567 lines
17 KiB
Markdown
567 lines
17 KiB
Markdown
# 公共组件库
|
||
|
||
:::tip 说明
|
||
项目提供丰富的公共组件，位于 `ui/src/components/` 目录，基于 AntDesign Vue 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。组件通过 `src/plugins/` 中的 `setupCustomComponents` 全局注册，任何页面直接使用，无需单独 import。
|
||
:::
|
||
|
||
## 组件总览
|
||
|
||
| 组件 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| BasicTable | `components/Table/` | 表格（列定义、分页、操作列、全屏、密度、斑马纹） |
|
||
| TableAction | `components/Table/` | 操作列按钮组（权限控制、下拉折叠） |
|
||
| BasicForm | `components/Form/` | 表单（schemas 配置化、动态渲染、折叠展开） |
|
||
| BasicModal | `components/Modal/` | 弹窗（拖拽、全屏、自定义按钮） |
|
||
| BasicUpload | `components/Upload/` | 文件/图片上传（卡片/列表、限制数量、预览） |
|
||
| Editor | `components/Editor/` | 富文本编辑器（基于 wangeditor） |
|
||
| CropperImage | `components/Cropper/` | 图片裁剪（圆形/矩形、实时预览） |
|
||
| QrCode | `components/Qrcode/` | 二维码生成（canvas/img、内嵌 logo） |
|
||
| ChinaArea | `components/ChinaArea/` | 省市区级联（懒加载、二/三级联动） |
|
||
| Icon | `components/icon/` | 图标（支持 AntDesign 图标 + SVG 图标） |
|
||
| BasicSelect | `components/Select/` | 增强下拉（远程请求、本地缓存） |
|
||
| CountTo | `components/CountTo/` | 数字动画（前缀/后缀、千分位、缓动曲线） |
|
||
| Password | `components/Password/` | 密码强度（强度指示器、重复确认、复杂度校验） |
|
||
| PageWrapper | `components/Page/` | 页面容器（标题卡片、固定底部） |
|
||
| Authority | `components/Authority/` | 权限容器（按权限码控制子元素渲染） |
|
||
| LockScreen | `components/Lockscreen/` | 锁屏组件 |
|
||
| ImpExcel | `components/Excel/` | Excel 导入/导出 |
|
||
| AppProvider | `components/Application/` | 应用提供者（全局配置注入） |
|
||
| Websocket | `components/Websocket/` | WebSocket 连接 |
|
||
| importFile | `components/importFile/` | 通用文件导入 |
|
||
| numberInput | `components/numberInput/` | 数字输入框 |
|
||
| Region | `components/Region/` | 区域选择 |
|
||
| pagination | `components/pagination/` | 分页组件 |
|
||
|
||
---
|
||
|
||
## BasicTable 表格
|
||
|
||
表格组件是使用频率最高的组件，基于 `a-table` + `a-pagination` 封装，详见 [BasicTable 表格](/zh/volume4/frontend/table) 章节。
|
||
|
||
### Props
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `columns` | `BasicColumn[]` | `[]`（必填） | 列定义 |
|
||
| `request` | `Function` | `null` | 数据请求函数，自动管理分页和 loading |
|
||
| `dataSource` | `Function \| Array` | `[]` | 数据源（与 request 二选一） |
|
||
| `title` | `string` | `null` | 表格标题 |
|
||
| `titleTooltip` | `string` | `null` | 标题提示 |
|
||
| `pagination` | `Object \| Boolean` | `{}` | 分页配置，`false` 隐藏分页 |
|
||
| `rowKey` | `string \| Function` | `undefined` | 行数据的唯一标识 |
|
||
| `border` | `Boolean` | `false` | 是否显示边框 |
|
||
| `size` | `string` | `'default'` | 表格尺寸：`small` / `middle` / `default` |
|
||
| `maxHeight` | `Number` | - | 最大高度 |
|
||
| `canResize` | `Boolean` | `true` | 是否自适应窗口高度 |
|
||
| `resizeHeightOffset` | `Number` | `0` | 高度偏移量 |
|
||
| `showTableSetting` | `Boolean` | `true` | 是否显示工具栏 |
|
||
| `tableSetting` | `TableSetting` | 见下方 | 工具栏配置 |
|
||
| `scroll` | `Object` | - | 滚动配置（`x` / `y`） |
|
||
| `rowSelection` | `Object` | - | 多选配置 |
|
||
| `virtualScroll` | `Boolean` | `false` | 是否启用虚拟滚动（大数据量优化） |
|
||
|
||
### tableSetting 工具栏配置
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `redo` | `Boolean` | `true` | 刷新按钮 |
|
||
| `size` | `Boolean` | `true` | 密度切换 |
|
||
| `setting` | `Boolean` | `true` | 列设置 |
|
||
| `fullscreen` | `Boolean` | `true` | 全屏切换 |
|
||
| `striped` | `Boolean` | `true` | 斑马纹开关 |
|
||
|
||
### BasicColumn 列定义
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `title` | `string` | 列标题 |
|
||
| `dataIndex` | `string` | 字段名 |
|
||
| `key` | `string` | 列唯一标识 |
|
||
| `width` | `number` | 列宽 |
|
||
| `align` | `string` | 对齐方式 |
|
||
| `fixed` | `string` | 固定列：`left` / `right` |
|
||
| `customRender` | `Function` | 自定义渲染函数 `({ text, record, index, column }) => VNode` |
|
||
| `ellipsis` | `boolean` | 超出省略（tooltip） |
|
||
| `auth` | `string[]` | 权限编码，控制列是否显示 |
|
||
| `ifShow` | `boolean \| Function` | 业务控制是否显示 |
|
||
|
||
### Events
|
||
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `fetch-success` | `(data, result)` | 数据请求成功 |
|
||
| `fetch-error` | `(error)` | 数据请求失败 |
|
||
| `columns-change` | `(columns)` | 列设置变化 |
|
||
|
||
### Slots
|
||
|
||
| 插槽 | 说明 |
|
||
|------|------|
|
||
| `tableTitle` | 表格标题左侧区域（常放添加按钮） |
|
||
| `toolbar` | 工具栏右侧区域 |
|
||
| `bodyCell` | 自定义单元格渲染（操作列） |
|
||
|
||
### Expose 方法
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `reload(opt?)` | 刷新表格（保留分页） |
|
||
| `restReload(opt?)` | 重置到第一页并刷新 |
|
||
| `getDataSource()` | 获取当前数据 |
|
||
| `setTableData(data)` | 设置表格数据 |
|
||
| `updateTableData(index, record)` | 更新指定行 |
|
||
| `getColumns()` | 获取列配置 |
|
||
| `setColumns(columns)` | 设置列配置 |
|
||
| `redoHeight()` | 重新计算高度 |
|
||
|
||
### 基础用法
|
||
|
||
```vue
|
||
<template>
|
||
<BasicTable :columns="columns" :request="loadDataTable" ref="tableRef">
|
||
<template #tableTitle>
|
||
<a-space>
|
||
<a-button v-perm="['sys:level:add']" type="primary" @click="handleAdd">
|
||
<template #icon><PlusOutlined /></template>
|
||
新增
|
||
</a-button>
|
||
</a-space>
|
||
</template>
|
||
<template #bodyCell="{ column, record }">
|
||
<template v-if="column.key === 'action'">
|
||
<a-space>
|
||
<a-button type="primary" @click="handleEdit(record.id)" v-perm="['sys:level:update']">编辑</a-button>
|
||
<a-button type="primary" danger @click="handleDelete(record.id)" v-perm="['sys:level:delete']">删除</a-button>
|
||
</a-space>
|
||
</template>
|
||
</template>
|
||
</BasicTable>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { PlusOutlined } from '@ant-design/icons-vue';
|
||
|
||
const columns = [
|
||
{ title: '名称', dataIndex: 'name', width: 200 },
|
||
{ title: '状态', dataIndex: 'status', width: 100 },
|
||
{ title: '创建时间', dataIndex: 'createTime', width: 180 },
|
||
{ title: '操作', dataIndex: 'action', key: 'action', fixed: 'right', width: 200 },
|
||
];
|
||
|
||
async function loadDataTable({ page, pageSize }) {
|
||
const res = await getListApi({ pageNo: page, pageSize });
|
||
return { data: res.data, count: res.count };
|
||
}
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
## BasicForm 表单
|
||
|
||
表单组件通过 schemas 配置化定义表单字段，支持动态渲染、折叠展开，详见 [BasicForm 表单](/zh/volume4/frontend/form) 章节。
|
||
|
||
### Props
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `schemas` | `FormSchema[]` | `[]` | 表单字段配置 |
|
||
| `model` | `Object` | - | 表单数据对象 |
|
||
| `rules` | `FormRules` | - | 表单验证规则 |
|
||
| `layout` | `string` | `'vertical'` | 布局方式 |
|
||
| `labelCol` | `Object` | - | 标签栅格配置 |
|
||
| `size` | `string` | `'default'` | 表单尺寸 |
|
||
| `isFull` | `Boolean` | `true` | 组件是否 100% 宽度 |
|
||
| `showActionButtonGroup` | `Boolean` | `true` | 显示操作按钮组 |
|
||
| `showSubmitButton` | `Boolean` | `true` | 显示查询按钮 |
|
||
| `showResetButton` | `Boolean` | `true` | 显示重置按钮 |
|
||
| `submitButtonText` | `string` | `'查询'` | 查询按钮文字 |
|
||
| `resetButtonText` | `string` | `'重置'` | 重置按钮文字 |
|
||
| `rowProps` | `Object` | - | 行栅格配置（gutter 等） |
|
||
| `colProps` | `Object` | - | 列栅格配置（span 等） |
|
||
|
||
### FormSchema 字段配置
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `name` | `string` | 字段名（必填） |
|
||
| `label` | `string` | 标签文字 |
|
||
| `component` | `ComponentType` | 渲染组件：`Input` / `Select` / `DatePicker` 等 |
|
||
| `componentProps` | `object` | 组件属性 |
|
||
| `defaultValue` | `any` | 默认值 |
|
||
| `rules` | `object \| object[]` | 字段校验规则 |
|
||
| `slot` | `string` | 自定义插槽名 |
|
||
| `hidden` | `boolean \| Function` | 是否隐藏 |
|
||
| `colProps` | `Object` | 栅格配置 |
|
||
| `labelMessage` | `string` | 标签提示信息 |
|
||
| `suffix` | `string` | 后缀插槽名 |
|
||
|
||
### Events
|
||
|
||
| 事件 | 说明 |
|
||
|------|------|
|
||
| `submit` | 点击查询按钮 |
|
||
| `reset` | 点击重置按钮 |
|
||
|
||
### Expose 方法
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `setFieldsValue(values)` | 设置字段值 |
|
||
| `getFieldsValue()` | 获取所有字段值 |
|
||
| `resetFields()` | 重置字段 |
|
||
| `validate()` | 校验表单 |
|
||
| `clearValidate(name?)` | 清除校验 |
|
||
| `setProps(formProps)` | 设置属性 |
|
||
| `setSchema(schemaProps)` | 动态修改 schema |
|
||
|
||
### 基础用法
|
||
|
||
```vue
|
||
<template>
|
||
<BasicForm @register="registerForm" @submit="handleSearch" @reset="handleReset" />
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
const [registerForm] = useForm({
|
||
schemas: [
|
||
{
|
||
name: 'name',
|
||
label: '名称',
|
||
component: 'Input',
|
||
componentProps: { placeholder: '请输入名称' },
|
||
},
|
||
{
|
||
name: 'status',
|
||
label: '状态',
|
||
component: 'Select',
|
||
componentProps: {
|
||
options: [
|
||
{ label: '启用', value: 1 },
|
||
{ label: '禁用', value: 0 },
|
||
],
|
||
},
|
||
},
|
||
],
|
||
});
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
## BasicModal 弹窗
|
||
|
||
弹窗组件基于 `a-modal` 封装，支持拖拽、自定义按钮，详见 [Modal 弹窗](/zh/volume4/frontend/modal) 章节。
|
||
|
||
### Props
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `title` | `string` | `''` | 弹窗标题 |
|
||
| `width` | `Number` | `446` | 弹窗宽度 |
|
||
| `draggable` | `Boolean` | `true` | 是否可拖拽 |
|
||
| `hideFooter` | `Boolean` | `false` | 隐藏底部按钮 |
|
||
| `okText` | `string` | `'确认'` | 确认按钮文字 |
|
||
| `cancelText` | `string` | `'取消'` | 取消按钮文字 |
|
||
|
||
### Events
|
||
|
||
| 事件 | 说明 |
|
||
|------|------|
|
||
| `ok` | 点击确认 |
|
||
| `cancel` | 点击取消 |
|
||
| `register` | 弹窗注册回调 |
|
||
|
||
### Expose 方法
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `setProps(props)` | 设置弹窗属性 |
|
||
| `openModal()` | 打开弹窗 |
|
||
| `closeModal()` | 关闭弹窗 |
|
||
|
||
### 基础用法
|
||
|
||
```vue
|
||
<template>
|
||
<BasicModal title="编辑用户" :width="600" @register="registerModal" @ok="handleSubmit">
|
||
<BasicForm @register="registerForm" />
|
||
</BasicModal>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
const [registerModal, { openModal, closeModal, setProps }] = useModal();
|
||
|
||
function handleEdit(record) {
|
||
setProps({ title: '编辑用户' });
|
||
openModal();
|
||
nextTick(() => {
|
||
setFieldsValue(record);
|
||
});
|
||
}
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
## BasicUpload 上传
|
||
|
||
文件/图片上传组件，支持卡片/列表模式、数量限制、图片预览。
|
||
|
||
### Props
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `listType` | `string` | `'picture-card'` | 展示类型：`picture-card` / `text` / `picture` |
|
||
| `limit` | `Number` | `Infinity` | 最大上传数量 |
|
||
| `maxSize` | `Number` | `2` | 文件大小上限（MB） |
|
||
| `accept` | `string` | - | 接受的文件类型 |
|
||
| `list` | `Ifiles[]` | `[]` | 已上传文件列表 |
|
||
| `circle` | `Boolean` | `false` | 圆形裁剪 |
|
||
| `uploadTitle` | `string` | `'上传图片'` | 列表模式按钮文字 |
|
||
| `helpText` | `string` | `''` | 帮助提示文字 |
|
||
|
||
### Events
|
||
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `uploadChange` | `(fileList)` | 上传/删除变化 |
|
||
| `delete` | `(fileList)` | 删除文件 |
|
||
|
||
### 基础用法
|
||
|
||
```vue
|
||
<!-- 单图上传 -->
|
||
<Upload v-model="formData.cover" :limit="1" accept="image/*" />
|
||
|
||
<!-- 多图上传 -->
|
||
<Upload :list="formData.images" :limit="5" @uploadChange="handleImageChange" />
|
||
|
||
<!-- 文件上传 -->
|
||
<Upload list-type="text" accept=".pdf,.doc,.docx" uploadTitle="上传附件" />
|
||
```
|
||
|
||
---
|
||
|
||
## Editor 富文本编辑器
|
||
|
||
基于 [wangeditor](https://www.wangeditor.cn/) 封装，支持图片/视频上传、工具栏配置。
|
||
|
||
### Props
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `getHtml` | `string` | - | 双向绑定（HTML 内容） |
|
||
| `getText` | `string` | - | 双向绑定（纯文本） |
|
||
| `height` | `string` | `'310'` | 编辑器高度 |
|
||
| `width` | `string` | `'auto'` | 编辑器宽度 |
|
||
| `mode` | `string` | `'default'` | 模式：`default` / `simple` |
|
||
| `disable` | `Boolean` | `false` | 是否禁用 |
|
||
| `placeholder` | `string` | `'请输入内容...'` | 占位文字 |
|
||
|
||
### 基础用法
|
||
|
||
```vue
|
||
<template>
|
||
<Editor v-model:getHtml="formData.content" height="400px" />
|
||
</template>
|
||
```
|
||
|
||
:::warning 注意
|
||
编辑器内部自动处理图片上传，上传接口由 `uploadFileUrl` 配置。后端图片迁移和 XSS 清洗由 Service 层的 `rich_text_fields` 声明自动处理。
|
||
:::
|
||
|
||
---
|
||
|
||
## CropperImage 图片裁剪
|
||
|
||
基于 [cropperjs](https://github.com/fengyuanchen/cropperjs) 封装，支持圆形/矩形裁剪、实时预览。
|
||
|
||
### 基础用法
|
||
|
||
```vue
|
||
<template>
|
||
<CropperImage
|
||
:src="formData.avatar"
|
||
:circled="true"
|
||
height="300px"
|
||
@cropend="handleCropend"
|
||
/>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
function handleCropend({ imgBase64, imgInfo }) {
|
||
formData.value.avatar = imgBase64;
|
||
}
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
## BasicSelect 增强下拉
|
||
|
||
远程数据下拉选择器，支持请求函数和本地缓存。
|
||
|
||
### 基础用法
|
||
|
||
```vue
|
||
<template>
|
||
<BasicSelect
|
||
v-model="formData.deptId"
|
||
:request="getDeptOptions"
|
||
:cache="true"
|
||
cacheKey="dept-options"
|
||
placeholder="请选择部门"
|
||
/>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
async function getDeptOptions() {
|
||
const res = await getDeptListApi();
|
||
return res.data.map(item => ({ label: item.name, value: item.id }));
|
||
}
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
## PageWrapper 页面容器
|
||
|
||
页面容器组件，提供标题卡片和固定底部区域。
|
||
|
||
### 基础用法
|
||
|
||
```vue
|
||
<template>
|
||
<PageWrapper title="用户管理" content="管理系统用户信息">
|
||
<BasicTable :columns="columns" :request="loadData" />
|
||
|
||
<template #leftFooter>
|
||
<a-button @click="handleCancel">取消</a-button>
|
||
</template>
|
||
<template #rightFooter>
|
||
<a-button type="primary" @click="handleSubmit">提交</a-button>
|
||
</template>
|
||
</PageWrapper>
|
||
</template>
|
||
```
|
||
|
||
---
|
||
|
||
## Authority 权限容器
|
||
|
||
按权限码控制子元素是否渲染，类似 `v-perm` 指令的组件形式。
|
||
|
||
### 基础用法
|
||
|
||
```vue
|
||
<template>
|
||
<Authority :value="['sys:user:add']">
|
||
<a-button type="primary">新增用户</a-button>
|
||
</Authority>
|
||
</template>
|
||
```
|
||
|
||
:::tip v-perm 指令
|
||
除了 `Authority` 组件，项目还提供 `v-perm` 指令，功能相同但更简洁：
|
||
```vue
|
||
<a-button v-perm="['sys:user:add']">新增用户</a-button>
|
||
```
|
||
:::
|
||
|
||
---
|
||
|
||
## Icon 图标
|
||
|
||
统一图标组件，支持 AntDesign 图标和 SVG 图标。
|
||
|
||
### 基础用法
|
||
|
||
```vue
|
||
<template>
|
||
<!-- AntDesign 图标 -->
|
||
<PlusOutlined />
|
||
<DeleteOutlined />
|
||
<EditOutlined />
|
||
<!-- SVG 图标 -->
|
||
<Icon name="svg-icon-user" />
|
||
</template>
|
||
```
|
||
|
||
---
|
||
|
||
## ImpExcel Excel 导入/导出
|
||
|
||
Excel 文件导入和导出组件。
|
||
|
||
### 导出函数
|
||
|
||
```typescript
|
||
import { jsonToSheetXlsx, aoaToSheetXlsx } from '@/components/Excel';
|
||
|
||
// JSON 数据导出
|
||
jsonToSheetXlsx({
|
||
data: [{ name: '张三', age: 25 }],
|
||
header: { name: '姓名', age: '年龄' },
|
||
filename: '用户列表.xlsx',
|
||
});
|
||
|
||
// 二维数组导出
|
||
aoaToSheetXlsx({
|
||
data: [['姓名', '年龄'], ['张三', 25]],
|
||
filename: '用户列表.xlsx',
|
||
});
|
||
```
|
||
|
||
### 导入组件
|
||
|
||
```vue
|
||
<template>
|
||
<ImpExcel @success="handleImportSuccess" />
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
function handleImportSuccess(data) {
|
||
// data: 导入的表格数据
|
||
console.log(data);
|
||
}
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
## 全局注册
|
||
|
||
所有组件在 `src/plugins/setupCustomComponents.ts` 中通过 `setupCustomComponents` 全局注册：
|
||
|
||
```typescript
|
||
// main.ts
|
||
import { setupCustomComponents } from '/@/plugins';
|
||
|
||
setupCustomComponents(app); // 注册所有自定义组件
|
||
```
|
||
|
||
全局注册后，任何组件中直接使用，无需单独 import。
|
||
|
||
---
|
||
|
||
## 权限控制体系
|
||
|
||
项目提供三种权限控制方式，覆盖不同场景：
|
||
|
||
| 方式 | 语法 | 适用场景 |
|
||
|------|------|----------|
|
||
| `v-perm` 指令 | `v-perm="['sys:user:add']"` | 按钮级权限，最常用 |
|
||
| `Authority` 组件 | `<Authority :value="['sys:user:add']">` | 容器级权限，控制多个元素 |
|
||
| `auth` 列属性 | `{ auth: ['sys:user:delete'] }` | TableAction 操作列权限 |
|
||
|
||
:::warning 注意
|
||
`v-perm` 和 `Authority` 的权限码必须与后端 `@permission_required("sys:xxx:xxx")` 一致。用户 ID 1（admin）拥有所有权限。
|
||
:::
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
公共组件库基于 AntDesign Vue 二次封装，核心三件套 BasicTable（表格）、BasicForm（表单）、BasicModal（弹窗）覆盖列表页标准场景。辅以 Upload、Editor、Cropper 等业务组件，以及 Authority、v-perm 权限体系。通过全局注册，任何页面直接使用，无需单独 import。优先使用公共组件，避免重复开发。
|