入门指南
由于组件是基于 element-plus 进行拓展的，所以需要首先安装 element-plus，若项目已存在可忽略，无需指定特定版本（ps：涉及到element-plus组件的功能，你也只能用到你当前项目中的版本）。
快速使用
md
npm install element-plus已经存在 element-plus 后，再安装当前组件库。
md
npm install devecoui-plus
或者安装指定版本
npm install devecoui-plus@1.0.43 -E全部安装完成后在 src/main.js 中引用配置，示例如下：
ts
import {createApp} from 'vue';
import App from './App.vue';
import router from './router';
import ElementPlus from 'element-plus';
import 'element-plus/dist/index.css';//必须引入
import zhCn from 'element-plus/es/locale/lang/zh-cn';// 此处是element-plus汉化
import DevecouiPlus from "devecoui-plus";//必须引入
import 'devecoui-plus/dist/style.css';//必须引入
const app = createApp(App);
app.use(createPinia());
app.use(router);
app.use(ElementPlus, {locale: zhCn});
app.use(DevecouiPlus);//必须引入
app.mount('#app');至此你就愉快的使用了，需要更精准的控制请阅读完下方内容，完成进阶。
自定义全局配置
很多情况下，组件的默认配置或方法并不是你想要的，但是在每个组件上传参修改又会很麻烦，这个时候就可以用到全局参数配置 ，只需要配置一次，所有同类型组件会默认使用全局配置项。
第一步
在 src 目录下新建文件夹 config，如果已存在可忽略。
第二步
在 config 文件夹下新增文件 devecoui.fn.ts，内容如下：
ts
import type {DevSearchTableProps} from 'devecoui-plus'
/**
* DevSearchTable组件调用接口后处理返回的数据：默认情况下是取结果中的data内容。
* @param res - 调用接口后返回的完整数据（注：如果axios处理了结果数据res返回的是处理后的内容）。
* @param props - DevSearchTable组件的props。
* @param type- data表示要处理接口返回的列表数据，total表示要处理接口返回的总条数。
* @returns 默认返回值为接口回调data内容。
*/
function devSearchTableFieldsFn(res: any, props: DevSearchTableProps, type: 'data'): object[];
function devSearchTableFieldsFn(res: any, props: DevSearchTableProps, type: 'total'): number;
function devSearchTableFieldsFn(res: any, props: DevSearchTableProps, type: 'data' | 'total'): object[] | number {
const result = res.data;
if (type === 'data') {
if (props.isPagination) {
return result[props.dataKey || 'list'] as object[];
} else {
return result as object[];
}
}
if (type === 'total') {
if (props.isPagination) {
return result[props.totalKey || 'total'] * 1 || 0 as number;
} else {
return 0;
}
}
return [];
}
// ... 更多配置可参考下方全局默认配置
export const fnConfig = {
devSearchTableFieldsFn,
// ... 更多配置可参考下方全局默认配置
};第三步
在 config 文件夹下新增文件 devecoui.props.ts，内容如下：
ts
export const propsConfig = {
// 影响 dev-search-table 组件 和 dev-form-table 组件
elTableProps: {
rowKey: 'id',
border: true,
style: {width: '100%'},
headerCellStyle: {background:'#eff3f6', textAlign: 'center'},
},
// ... 更多配置可参考下方全局默认配置
};第四步
在 config 文件夹下新增文件 devecoui.config.ts，内容如下：
ts
import {stylesConfig} from './devecoui.props'
import {fnConfig} from './devecoui.fn'
export const defaultConfig = {
...propsConfig,
...fnConfig,
merge: false, // 默认情况下为false 具体功能请查看下方 merge配置
};第五步
在 src/main.js 中引入配置文件，需要将刚才的配置文件引入，并且修改devecoui组件注册代码，示例如下：
ts
import { defaultConfig } from '@/config/devecoui.config';// 加一句这个（引入配置文件）
app.use(DevecouiPlus, defaultConfig); // 修改这里全局默认配置
fnConfig 配置
ts
import type {DevSearchTableProps} from 'devecoui-plus'
/**
* DevSearchTable组件调用接口后处理返回的数据：默认情况下是取结果中的data内容。
* @param res - 调用接口后返回的完整数据（注：如果axios处理了结果数据res返回的是处理后的内容）。
* @param props - DevSearchTable组件的props。
* @param type- data表示要处理接口返回的列表数据，total表示要处理接口返回的总条数。
* @returns 默认返回值为接口回调data内容。
*/
function devSearchTableFieldsFn(res: any, props: DevSearchTableProps, type: 'data'): object[];
function devSearchTableFieldsFn(res: any, props: DevSearchTableProps, type: 'total'): number;
function devSearchTableFieldsFn(res: any, props: DevSearchTableProps, type: 'data' | 'total'): object[] | number {
const result = res.data;
if (type === 'data') {
if (props.isPagination) {
return result[props.dataKey || 'list'] as object[];
} else {
return result as object[];
}
}
if (type === 'total') {
if (props.isPagination) {
return result[props.totalKey || 'total'] * 1 || 0 as number;
} else {
return 0;
}
}
return [];
}
/**
* DevSelect组件调用接口后处理返回的数据：默认情况下是取结果中的data内容。
* @param res
* @returns 默认返回值为接口回调data内容。
*/
function devSelectFieldsFn(res: any) {
return res.data || []
}
/**
* DevSelectMutex组件调用接口后处理返回的数据：默认情况下是取结果中的data内容。
*/
function devSelectMutexFieldsFn(res: any) {
return res.data || []
}
/**
* DevCascaderMutex 组件调用接口后处理返回的数据：默认情况下是取结果中的data内容。
*/
function devCascaderMutexFieldsFn(res: any) {
return res.data || []
}
/**
* DevCascader 组件调用接口后处理返回的数据：默认情况下是取结果中的data内容。
*/
function devCascaderFieldsFn(res: any) {
return res.data || []
}
/**
* DevDownload组件调用接口后处理返回的数据：默认情况下是取结果中的data内容。
* @param res
*/
function devDownloadFieldsFn(res: any) {
return res || {}
}
/**
* DevUploadImage组件调用接口后处理返回的数据：默认情况下是取结果中的data内容。
*/
function devUploadImageFieldsFn(res: any) {
return res.data || ''
}
/**
* DevUploadImage组件调用接口入参处理
*/
function devUploadImageParamsFn(files: File, config: Record<string, any> = {}): FormData {
const formData = new FormData();
formData.append(config.fileKey, files);
return formData;
}
/**
* 向外部暴露的处理组件数据的方法。
*/
export const fnConfig = {
devSearchTableFieldsFn,
devSelectFieldsFn,
devSelectMutexFieldsFn,
devCascaderMutexFieldsFn,
devDownloadFieldsFn,
devCascaderFieldsFn,
devUploadImageFieldsFn,
devUploadImageParamsFn
};propsConfig 配置
ts
/**
* 向外部暴露的处理组件数据的方法。
*/
export const propsConfig = {
elTableProps: {
rowKey: 'id',
border: true,
style: {width: '100%'},
headerCellStyle: {background: '#eff3f6', textAlign: 'center'},
},
// 下拉选择框
elSelectProps: {
style: {width: '100%'},
clearable: true,
placeholder: '请选择',
tagType: 'primary'
},
elDatePickerProps: {
style: {width: '100%'},
type: 'datetimerange',
clearable: true,
placeholder: '请选择',
rangeSeparator: '至',
startPlaceholder: '开始时间',
endPlaceholder: '结束时间',
valueFormat: 'YYYY-MM-DD HH:mm:ss'
},
devSearchTablePaginationProps: {
layout: 'total, sizes, prev, pager, next',
pageSizes: [10, 20, 50, 100],
background: true
},
elFormProps: {},
elCascaderProps: {
tagType: 'primary',
clearable: true,
style: {width: '100%'},
props: {
emitPath: true,
multiple: false,
value: 'value',
label: 'label',
children: 'children',
disabled: 'disabled'
}
},
elTooltipProps: {
effect: "dark",
},
elInputProps: {
clearable: true, // 是否可清空
style: {width: '100%'},
placeholder: '请输入',
},
// 图片裁剪
devImageCropperProps: {
showViewer: true,// 是否裁剪结果显示预览
showCrosshair: true,// 是否显示裁剪框十字线
showSelectionGrid: true,// 是否显示裁剪框内栅栏
showShade: true, // 是否显示遮罩层
showCanvasGrid: false, // 是否显示Canvas组件的栅栏
outputType: ['blob', 'base64', 'file', 'url'], // 输出的裁剪结果类型
viewerAttrs: {
selection: '#dev_cropperSelection', // 预览组件关联的选择框ID
}, // 预览组件的属性
canvasAttrs: {
background: true, // 是否有背景
style: {width: '300px', height: '300px'},
}, // Canvas组件的属性
selectionAttrs: {
id: 'dev_cropperSelection',
"initial-coverage": 0.5, // 初始覆盖率
movable: true,
resizable: true,
width: '',
height: '',
x: '',
y: ''
},
canvasGridAttrs: {},
shadeAttrs: {
hidden: true
},
crosshairAttrs: {centered: true}, // 十字线组件的属性
selectionGridAttrs: {
covered: true,
role: "grid"
}, // 栅栏组件的属性
canvasHandleList: [{action: 'select', plain: true}], // Canvas中的操作按钮列表
selectionHandleList: [
{action: 'move', themeColor: 'rgba(255, 255, 255, 0.35)'},
{action: 'n-resize'},
{action: 'e-resize'},
{action: 's-resize'},
{action: 'w-resize'},
{action: 'ne-resize'},
{action: 'se-resize'},
{action: 'sw-resize'},
{action: 'nw-resize'},
], // Selection 中的操作按钮列表
},
// 文件选择
devFileSelectProps: {
buttonText: '选择文件',
},
devUploadImageProps:{
width: '150', // 图片容器宽度
height: '150', // 图片容器高度
borderRadius: '10', // 图片容器圆角
cropper: false, // 是否裁剪
sortable:false, // 是否支持排序
maxCount: 1, // 最大上传文件数Infinity
gap: '20', // 图片容器内边距,
fileKey: 'file', // 存储file的key值
elImageViewerAttrs:{},// 图片预览可以添加的属性
imageButtons:['edit', 'delete', 'look'], // 图片中可操作的按钮
imageOptionsSize:'20px',// 图片中可操作按钮大小
imageOptionsColor:'#fff',// 图片中可操作按钮颜色
chooseColor: '#d9d9d9', // 选择图片按钮边框颜色和icon颜色
chooseIconSize:'20px', // 选择图片按钮icon大小
cropperElDialogAttrs:{
title: '裁剪图片',
width: '800px',
top: '10vh',
closeOnClickModal: false,
closeOnPressEscape: false,
destroyOnClose: true,
style: {
borderRadius: '10px'
}
},
cropperDevImageCropperAttrs:{
canvasAttrs: {
background: true, // 是否有背景
style: {
width: '770px',
height: '400px'
}
}
}
}
};merge 配置
1.0.43 版本新增了 merge 新特性，此配置只针对 propsConfig 中属性合并。
在以往的版本中，当我们只想修改默认配置中的其中某一个小项的时候，需要对应的组件模块全部粘贴过来，以 elCascaderProps举例:
1.0.43 之前版本
如果我们想修改 props 中的 label 属性，需要把这段代码整体粘贴过来。
ts
elCascaderProps: {
tagType: 'primary',
clearable: true,
style: {width: '100%'},
props: {
emitPath: true,
multiple: false,
value: 'value',
label: 'name', // 把label 改成 name
children: 'children',
disabled: 'disabled'
}
}1.0.43 版本开始
当我们配置 merge 属性后就可以这样去修改
比如说我们只想修改，props 中的 label 属性，就不再需要全部粘贴过来，只需要这样组件库就会自行合并到默认配置项中去。
ts
elCascaderProps: {
props: {
label: 'name' // 把label 改成 name
}
}WARNING
但需注意，开启后只会递归合并 propsConfig 中属性为 object 类型的字段，其他类型无效。
如何配置 merge
我们只需要在 第四步 的操作中增加 merge 属性即可，具体操作如下
ts
import {stylesConfig} from './devecoui.props'
import {fnConfig} from './devecoui.fn'
export const defaultConfig = {
...propsConfig,
...fnConfig,
merge: true, // true代表开启合并，false就还是老版本的方案，默认情况下为false
};