Vue 常用组件、Components、Hooks、Dict
# DictLabel 字典组件
数据字典组件,位于 src/components/Dict/src/useDict.ts (opens new window)
BasicTable 表格列已经内置 dictType 属性,自动完成 DictLabel 组件的渲染。
# 使用
<template>
<DictLabel :dictType="'sys_yes_no'" :dictValue="'1'" />
</template>
<script lang="ts" setup>
import { DictLabel } from '/@/components/Dict';
</script>
2
3
4
5
6
字典数据风格
指定的 dictType 数据来自后台字典管理,可给字典数据设置 CSS类名,完成以下内置字典样式:
- 标签风格:
tag pink、tag red、tag orange、tag green、tag cyan、tag blue、tag purple、 tag error、tag success、tag warning、tag processing、tag default 预览 (opens new window) v5.1.0 及之前版本:预览 (opens new window)
- 微章风格:
badge error、badge success、badge warning、badge processing 预览 (opens new window) v5.1.0 及之前版本:预览 (opens new window)
# 属性
属性 | 类型 | 默认值 | 说明 |
---|---|---|---|
dictType | string | - | 字典类型 |
dictValue | any | - | 字典数据 |
defaultValue | string | 未知 | 查询不到字典数据的时候,显示的默认值 |
icon | bool | true | 字典图标 |
# useDict
字典工具,位于 src/components/Dict/src/useDict.ts (opens new window) 内。
相关组件:DictLabel 字典组件
举例:
// 引入和初始字典方法
import { useDict } from '/@/components/Dict';
const { initDict, getDictList, getDictLabel } = useDict();
// 使用字典前必须先初始化下字典数据(参数为数组,支持一次性加载多个字典类型)
await initDict(['sys_yes_no']);
// 获取字典数据(参数:字典类型)
const dictList = getDictList('sys_yes_no');
console.log(dictList);
// 根据字典值获取字典标签(参数:字典类型,字典值,默认值)
const dictLabel = getDictLabel('sys_yes_no', '1', '未知');
console.log(dictLabel);
2
3
4
5
6
7
8
9
10
11
12
13
14
API:
// 初始化字典
async function initDict(dictTypes: string[] | Set<string> = [])
// 获取字典列表数据
function getDictList(dictType: string): Recordable[]
// 根据字段类型获取字典标签
function getDictLabel(dictType: string, value?: string, defaultValue = t('未知')): string
// 生成 Select 组件选项数据
async function initSelectOptions(optionsRef: Ref, dictType?: string)
// 生成 SelectTree 组件选项数据
async function initSelectTreeData(treeData: Ref, dictType: string, isListToTree: boolean)
2
3
4
5
6
7
8
9
10
11
12
13
14
# BasicDrawer 抽屉组件
对 Antdv 的 Drawer 抽屉 (opens new window) 组件进行封装扩展。 v5.1.0 及之前版本:Antdv 2.x Drawer 抽屉 (opens new window)
组件位于 src/components/Drawer (opens new window)
# 使用
定义弹窗内容:Drawer.vue
<template>
<!-- 注意 v-bind="$attrs" 不可缺,用于接受父组件的属性传值给 BasicDrawer 组件 -->
<BasicDrawer v-bind="$attrs" title="抽屉标题" width="50%"> 抽屉内容 </BasicDrawer>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { BasicDrawer } from '/@/components/Drawer';
export default defineComponent({
components: { BasicDrawer },
});
</script>
2
3
4
5
6
7
8
9
10
11
页面引用弹窗:
<template>
<div>
<Drawer @register="register" />
<a-button @click="openDrawer">打开</a-button>
</div>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { useDrawer } from '/@/components/Drawer';
import Drawer from './Drawer.vue';
export default defineComponent({
components: { Drawer },
setup() {
const [register, { openDrawer }] = useDrawer();
return {
register,
openDrawer,
};
},
});
</script>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# useDrawer
用于外部组件调用
const [register, { openDrawer, setDrawerProps }] = useDrawer();
register
register 用于注册 useDrawer
,如果需要使用 useDrawer
提供的 api,必须将 register
传入组件的 onRegister
。
原理其实很简单,就是 vue 的组件子传父通信,内部通过 emit("register",instance)
实现。
同时,独立出去的组件需要将 attrs
绑定到 Drawer 的上面。
<BasicDrawer v-bind="$attrs"> 抽屉内容 </BasicDrawer>
openDrawer
用于打开/关闭弹窗
// true/false: 打开关闭弹窗
// data: 传递到子组件的数据,useDrawerInner 接受
openDrawer(true, data);
2
3
closeDrawer
用于关闭弹窗
closeDrawer();
setDrawerProps
用于更改 drawer 的 props 参数因为 drawer 内容独立成组件,如果在外部页面需要更改 props 可能比较麻烦,所以提供 setDrawerProps 方便更改内部 drawer 的 props
setDrawerProps(props);
# useDrawerInner
用于独立的 Drawer 内部方法调用
<template>
<BasicDrawer v-bind="$attrs" @register="register" title="抽屉标题" width="50%">
抽屉内容
<a-button type="primary" @click="closeDrawer">关闭抽屉</a-button>
</BasicDrawer>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { BasicDrawer, useDrawerInner } from '/@/components/Drawer';
export default defineComponent({
components: { BasicDrawer },
setup() {
const [register, { closeDrawer }] = useDrawerInner();
return { register, closeDrawer };
},
});
</script>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
useDrawerInner用于操作独立组件
const [register, { closeDrawer, setDrawerProps }] = useDrawerInner(callback);
callback
type: (data:any)=>void
回调函数用于接收 openDrawer 第二个参数传递的值
useDrawerInner((data: any) => {
console.log(data);
});
2
3
closeDrawer
用于关闭抽屉
closeDrawer();
changeOkLoading
用于修改确认按钮的 loading 状态
// true or false
changeOkLoading(true);
2
changeLoading
用于修改 drawer 的 loading 状态
// true or false
changeLoading(true);
2
setDrawerProps
用于更改 drawer 的 props 参数因为 drawer 内容独立成组件,如果在外部页面需要更改 props 可能比较麻烦,所以提供setDrawerProps 方便更改内部 drawer 的 props
# 属性
温馨提醒
除以下参数外,官方文档内的 props 也都支持,具体可以参考 Antv Drawer 属性 (opens new window)
v5.1.0 及之前版本:Antdv 2.x Drawer 属性 (opens new window)
属性 | 类型 | 默认值 | 可选值 | 说明 |
---|---|---|---|---|
isDetail | boolean | false | - | 是否为详情模式(风格不同) |
loading | boolean | false | - | loading 状态 |
loadingText | string | `` | - | loading 文本 |
showDetailBack | boolean | true | - | isDetail=true 状态下是否显示返回按钮 |
closeFunc | () => Promise<boolean> | - | - | 自定义关闭函数,返回true 关闭,否则不关闭 |
showFooter | boolean | - | - | 是否显示底部 |
footerHeight | number | 60 | - | 底部区域高度 |
# 事件
事件 | 回调参数 | 说明 |
---|---|---|
close | (e)=>void | 点击关闭回调 |
visible-change | (visible:boolean)=>void | 弹窗打开关闭时触发 |
ok | (e)=>void | 点击确定回调 |
# 插槽
名称 | 说明 |
---|---|
footer | 底部区域(会替换掉默认的按钮) |
insertFooter | 关闭按钮的左边(不使用footer插槽时有效) |
centerFooter | 关闭按钮和确认按钮的中间(不使用footer插槽时有效) |
appendFooter | 确认按钮的右边(不使用footer插槽时有效) |
# BasicModal 弹窗组件
对 Antdv 的 Modal 弹窗 (opens new window) 组件进行封装扩展。 v5.1.0 及之前版本:Antdv 2.x Modal 弹窗 (opens new window)
扩展新增拖拽,全屏,自适应高度等功能。
组件位于 src/components/Modal (opens new window)
# 使用
定义弹窗内容:Modal.vue
<template>
<!-- 注意 v-bind="$attrs" 不可缺,用于接受父组件的属性传值给 BasicModal 组件 -->
<BasicModal v-bind="$attrs" title="弹窗标题" :helpMessage="['提示1', '提示2']">
弹窗内容
</BasicModal>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { BasicModal } from '/@/components/Modal';
export default defineComponent({
components: { BasicModal },
setup() {
return {};
},
});
</script>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
页面引用弹窗
<template>
<div class="px-10">
<Modal @register="register" />
<a-button @click="openModal">打开</a-button>
</div>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { useModal } from '/@/components/Modal';
import Modal from './Modal.vue';
export default defineComponent({
components: { Modal },
setup() {
const [register, { openModal }] = useModal();
return {
register,
openModal,
};
},
});
</script>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# useModal
用于外部组件调用
useModal 用于操作组件
const [register, { openModal, setModalProps }] = useModal();
register
register 用于注册 useModal
,如果需要使用 useModal
提供的 api,必须将 register
传入组件的 onRegister
。
原理其实很简单,就是 vue 的组件子传父通信,内部通过 emit("register",instance)
实现。
同时独立出去的组件需要将 attrs
绑定到 BasicModal
上面。
<template>
<BasicModal v-bind="$attrs"></BasicModal>
</template>
2
3
openModal
用于打开/关闭弹窗
// true/false: 打开关闭弹窗
// data: 传递到子组件的数据,useModalInner 接受
openModal(true, data);
2
3
closeModal
用于关闭弹窗
closeModal();
setModalProps
用于更改 modal 的 props 参数因为 modal 内容独立成组件,如果在外部页面需要更改 props 可能比较麻烦,所以提供 setModalProps 方便更改内部 modal 的 props
setModalProps(props);
# useModalInner
用于独立的 Modal 内部方法调用
<template>
<BasicModal
v-bind="$attrs"
@register="register"
title="弹窗标题"
:helpMessage="['提示1', '提示2']"
>
<a-button type="primary" @click="closeModal" class="mr-2">从内部关闭弹窗</a-button>
<a-button type="primary" @click="setModalProps">从内部修改title</a-button>
</BasicModal>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { BasicModal, useModalInner } from '/@/components/Modal';
export default defineComponent({
components: { BasicModal },
setup() {
const [register, { closeModal, setModalProps }] = useModalInner();
return {
register,
closeModal,
setModalProps: () => {
setModalProps({ title: '弹窗新标题(修改后)' });
},
};
},
});
</script>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
useModalInner用于操作独立组件
const [register, { closeModal, setModalProps }] = useModalInner(callback);
callback
type: (data:any)=>void
回调函数用于接收 openModal 第二个参数传递的值
useModalInner((data: any) => {
console.log(data);
});
2
3
closeModal
用于关闭弹窗
closeModal();
changeOkLoading
用于修改确认按钮的 loading 状态
changeOkLoading(true);
changeLoading
用于修改 modal 的 loading 状态
// true or false
changeLoading(true);
2
setModalProps
用于更改 modal 的 props 参数因为 modal 内容独立成组件,如果在外部页面需要更改 props 可能比较麻烦,所以提供 setModalProps 方便更改内部 modal 的 props
# 属性
提示
除以下参数外,组件库文档内的 props 也都支持,具体可以参考 Modal 属性 (opens new window)
v5.1.0 及之前版本:Antdv 2.x Modal 属性 (opens new window)
属性 | 类型 | 默认值 | 可选值 | 说明 |
---|---|---|---|---|
title | string | - | - | modal 标题 |
height | number | - | - | 固定 modal 的高度 |
minHeight | number | - | - | 设置 modal 的最小高度 |
draggable | boolean | true | true/false | 是否开启拖拽 |
useWrapper | boolean | true | true/false | 是否开启自适应高度,开启后会跟随屏幕变化自适应内容,并出现滚动条 |
wrapperFooterOffset | number | 0 | - | 开启是适应高度后,如果超过屏幕高度,底部和顶部会保持一样的间距,该参数可以用来缩小底部的间距 |
canFullscreen | boolean | true | true/false | 是否可以进行全屏 |
defaultFullscreen | boolean | false | true/false | 默认全屏 |
loading | boolean | false | true/false | loading 状态 |
loadingTip | string | - | - | loading 文本 |
showCancelBtn | boolean | true | true/false | 显示关闭按钮 |
showOkBtn | boolean | true | true/false | 显示确认按钮 |
helpMessage | string , string[] | - | - | 标题右侧提示文本 |
centered | boolean | false | true/false | 是否居中弹窗 |
cancelText | string | '关闭' | - | 关闭按钮文本 |
okText | string | '保存' | - | 确认按钮文本 |
closeFunc | () => Promise<boolean> | 关闭函数 | - | 关闭前执行,返回 true 则关闭,否则不关闭 |
# 事件
事件 | 回调参数 | 说明 |
---|---|---|
ok | function(e) | 点击确定回调 |
cancel | function(e) | 点击取消回调 |
visible-change | (visible:boolean)=>{} | 打开或者关闭触发 |
# 插槽
名称 | 说明 |
---|---|
footer | 底部区域(会替换掉默认的按钮) |
insertFooter | 关闭按钮的左边(不使用footer插槽时有效) |
centerFooter | 关闭按钮和确认按钮的中间(不使用footer插槽时有效) |
appendFooter | 确认按钮的右边(不使用footer插槽时有效) |
# Tree 树形组件
对 antv 的 Tree 树 (opens new window) 组件进行封装。 v5.1.0 及之前版本:Antdv 2.x Tree 树 (opens new window)
新增扩展拖拽,全屏,自适应高度等功能。
组件位于 src/components/Tree (opens new window)
# 使用
<template>
<BasicTree :treeData="treeData" :treeDataSimpleMode="false" />
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { BasicTree, TreeItem } from '/@/components/Tree';
// 这里演示 children 方式,同样支持 zTree 的 id pId 格式
const treeData: TreeItem[] = [
{
id: '1',
name: 'tree 1',
children: [
{ id: '1-1', name: 'tree 1-1' },
{ id: '1-2', name: 'tree 1-2' },
],
},
{
id: '2',
name: 'tree 2',
children: [
{ id: '2-1', name: 'tree 2-1' },
{ id: '2-2', name: 'tree 2-2' },
],
},
];
export default defineComponent({
components: { BasicTree },
setup() {
return { treeData };
},
});
</script>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 属性
温馨提醒
除以下参数外,官方文档内的 props 也都支持,具体可以参考 Tree 属性 (opens new window)
v5.1.0 及之前版本:Antdv 2.x Tree 属性 (opens new window)
属性 | 类型 | 默认值 | 说明 |
---|---|---|---|
treeData | TreeItem[] | - | 树组件数据 |
rightMenuList | ContextMenuItem[] | - | 右键菜单列表 |
checkedKeys | string[] | - | 勾选的节点 |
selectedKeys | string[] | - | 选中的节点 |
expandedKeys | string[] | - | 展开的节点 |
actionList | ActionItem[] | - | 鼠标移动上去右边操作按钮列表 |
title | string | - | 定制标题字符串 |
toolbar | boolean | - | 是否显示工具栏 |
search | boolean | - | 显示搜索框 |
clickRowToExpand | boolean | - | 是否在点击行时自动展开 |
beforeRightClick | (node, event)=>ContextMenuItem[] | - | 右键点击回调,可返回右键菜单列表数据来生成右键菜单 |
rightMenuList | ContextMenuItem[] | - | 右键菜单列表数据 |
defaultExpandLevel | string | number | - | 初次渲染后默认展开的层级 |
defaultExpandAll | boolean | false | 初次渲染后默认全部 |
searchValue(v-model) | string | - | 当前搜索词 |
treeDataSimpleMode | boolean | true | 是否ztree格式 { id, pId, name } |
注意
defaultExpandLevel
、defaultExpandAll
仅在初次渲染时生效。如果basicTree
是在创建完毕之后才设置的treeData
(如异步数据),需要在更新后自己调用basicTree
提供的expandAll
、filterByLevel
来执行展开
ActionItem
{
// 渲染的图标
render: (record: any) => any;
// 是否显示
show?: boolean | ((record: Recordable) => boolean);
}
2
3
4
5
6
ContextMenuItem
{
// 文本
label: string;
// 图标
icon?: string;
// 是否禁用
disabled?: boolean;
// 事件
handler?: (...arg) => any;
// 是否显示分隔线
divider?: boolean;
// 子级菜单数据
children?: ContextMenuItem[];
}
2
3
4
5
6
7
8
9
10
11
12
13
14
# 插槽
温馨提醒
官方文档内的 slot 都支持,具体可以参考 Antv Tree (opens new window)
v5.1.0 及之前版本:Antdv 2.x Tree 插槽 (opens new window)
# 方法
名称 | 回调参数 | 说明 |
---|---|---|
checkAll | (checkAll: boolean) => void | 选择所有 |
expandAll | (expandAll: boolean) => void | 展开或折叠所有 |
setExpandedKeys | (keys: Keys) => void | 设置展开节点 |
getExpandedKeys | () => Keys | 获取展开节点 |
setSelectedKeys | (keys: Keys) => void | 设置选中节点 |
getSelectedKeys | () => Keys | 获取选中节点 |
setCheckedKeys | (keys: CheckKeys) => void | 设置勾选节点 |
getCheckedKeys | () => CheckKeys | 获取勾选节点 |
filterByLevel | (level: number) => void | 显示指定等级 |
insertNodeByKey | (opt: InsertNodeParams) => void | 插入子节点到指定节点内 |
deleteNodeByKey | (key: string) => void | 根据 key 删除节点 |
updateNodeByKey | (key: string, node: Omit<TreeItem, 'key'>) => void | 根据 key 更新节点 |
setSearchValue | (value: string) => void | 设置当前搜索词 |
getSearchValue | () => string | 获取当前搜索词 |
# 更多常用组件
Basic 基础组件 (opens new window):BasicTitle 显示标题组件、BasicArrow 带动画的箭头组件、BasicHelp 帮助按钮组件
Page 页面相关组件 (opens new window):PageWrapper 包裹页面组件、PageFooter 页面底部工具栏
PopConfirmButton (opens new window):带有 PopConfirm 下拉菜单功能的按钮
CollapseContainer (opens new window):区域折叠卡片容器
ScrollContainer (opens new window):参考 element-ui 的 el-scrollbar 组件实现,滚动容器组件
LazyContainer (opens new window):延时加载/懒加载组件, 只在组件可见或者延迟一段时间才进行加载
WangEditor (opens new window):富文本编辑器,实例见 testData/form.vue
CodeEditor (opens new window):代码编辑器
JsonPreview (opens new window):json 数据预览组件
CountDown (opens new window):倒计时组件
ClickOutSide (opens new window):监听包裹的元素点击外部触发事件
CountTo (opens new window):数字动画组件,该组件对 vue-countTo (opens new window) 进行了重构,适配 vue3
Cropper (opens new window):图片裁剪组件
Description (opens new window):详情组件
FlowChart (opens new window):流程图组件,基于 didi/LogicFlow (opens new window) 的简单封装。详细配置请参考文档 FlowChart (opens new window)
Excel 组件 (opens new window):excel 导入导出操作,具体文档可以参考 XLSX 文档 (opens new window)
QrCode (opens new window):用于生成二维码的组件
Markdown (opens new window):基于 Vditor (opens new window) 的 MarkDown 编辑器
Loading (opens new window):加载框组件
Tinymce (opens new window):富文本组件
Time (opens new window):相对时间组件,刚刚,多少秒前,多少秒后等
StrengthMeter (opens new window):校验密码强度,密码等级
Verify (opens new window):拖拽校验组件、图片还原正方向校验组件
Transition (opens new window):页面/组件切换动画
VirtualScroll (opens new window):虚拟滚动组件(用于大量数据纯展示时使用)
ContextMenu (opens new window):函数式创建右键菜单组件
Loading (opens new window):函数式加载框组件
Preview (opens new window):函数式图片预览组件
Splitpanes (opens new window):窗口布局插件
VueGridLayout (opens new window):拖拽工具
Print.js (opens new window):网页打印工具