# UI公共组件使用手册
## 1. Pagination 分页组件
Pagination 是一个基于 Element Plus 的分页组件封装，提供了丰富的功能和灵活的配置选项。
### 1.1 核心功能
- 自定义页面大小选择
- 响应式设计（移动端适配）
- 自动滚动到顶部
- 支持多种布局配置
- 事件回调机制
### 1.2 基本使用
```vue
```
### 1.3 高级配置
#### 1.3.1 自定义页面大小
```vue
```
#### 1.3.2 自定义布局
```vue
```
#### 1.3.3 禁用自动滚动
```vue
```
### 1.4 响应式设计
组件会根据屏幕宽度自动调整页码按钮的数量：
- 大屏幕（≥992px）：显示7个页码按钮
- 小屏幕（<992px）：显示5个页码按钮
## 2. GlobalTable 全局表格组件
GlobalTable 是一个功能强大的表格组件，基于 Element Plus Table 封装，提供了丰富的功能和灵活的配置选项。
### 2.1 核心功能
- 数据加载与分页
- 排序与筛选
- 行选择与点击事件
- 行展开与树形结构
- 自定义列与表头
- 表格浮动表头
- 字段动态配置
- 性能优化（虚拟滚动、缓存等）
### 2.2 基本使用
```vue
编辑
删除
```
### 2.3 高级配置
#### 2.3.1 树形表格
```vue
```
#### 2.3.2 自定义排序
```vue
```
#### 2.3.3 表格汇总
```vue
```
#### 2.3.4 动态字段配置
```vue
```
通过配置 `field-type`，GlobalTable 会自动从后端获取字段配置，并根据用户设置动态显示/隐藏列。
### 2.4 性能优化
#### 2.4.1 浮动表头
当表格内容较长时，滚动时表头会固定在顶部：
```vue
```
#### 2.4.2 虚拟滚动
对于大数据量表格，可以启用虚拟滚动：
```vue
```
### 2.5 常用方法
```vue
```
## 3. 字典树运用
字典树是系统中用于管理和展示字典数据的机制，包括字典数据的获取、缓存和展示。
### 3.1 核心功能
- 字典数据缓存
- 多字典类型同时获取
- 字典标签展示
- 字典值转换
### 3.2 字典数据获取
使用 `useDict` hook 获取字典数据：
```vue
```
### 3.3 字典数据展示
使用 `DictTag` 组件展示字典标签：
```vue
```
### 3.4 字典数据转换
使用工具函数转换字典值：
```vue
```
### 3.5 字典数据缓存
字典数据会自动缓存到 Vuex 的 `dictStore` 中，避免重复请求：
```javascript
// 手动获取字典数据
import useDictStore from '@/hooks/store/useDictStore'
// 获取字典数据
const statusDict = useDictStore.getDict('sys_status')
// 手动设置字典数据
useDictStore.setDict('sys_status', dictData)
// 清除字典数据
useDictStore.removeDict('sys_status')
// 清除所有字典数据
useDictStore.cleanDict()
```
## 4. 权限控制
系统提供了基于指令的权限控制机制，使用 `v-hasPerm` 和 `v-hasPermi` 指令动态显示/隐藏元素。
### 4.1 核心功能
- 单个权限控制（v-hasPerm）
- 多个权限控制（v-hasPermi）
- 基于用户权限动态判断
- 无权限时自动隐藏元素
### 4.2 权限指令使用
#### 4.2.1 v-hasPerm 单个权限控制
```vue
新增用户
```
当用户拥有 `user:add` 权限时，按钮会显示；否则会隐藏。
#### 4.2.2 v-hasPermi 多个权限控制
```vue
批量操作
```
当用户拥有 `user:edit` 或 `user:delete` 权限时，按钮会显示；否则会隐藏。
### 4.3 权限控制原理
权限控制的核心逻辑在 `permission.js` 中实现：
```javascript
export const hasPerm = {
install: (app) => {
app.directive('hasPerm', {
mounted(el, binding) {
const permissions = store.state.permissionStore.permission;
const value = binding.value;
const flag = permissions.has(value);
if (!flag) {
el.parentNode.removeChild(el);
}
}
});
}
};
```
### 4.4 权限数据来源
用户权限数据从后端 API 获取，并存储在 Vuex 的 `permissionStore` 中：
```javascript
// 从后端获取权限数据
avoid axios.get('/api/admin/api/v1/menus/route').then(res => {
// 存储权限数据
store.dispatch("permissionStore/setPermission", res.data.data[0].meta.permissions);
});
```
### 4.5 高级使用场景
#### 4.5.1 权限控制在表格操作列
```vue
编辑
删除
```
#### 4.5.2 权限控制在表单字段
```vue
```
#### 4.5.3 权限控制在菜单
```vue
{{ menu.name }}
```
## 5. 其他公共组件
### 5.1 SvgIcon 图标组件
```vue
```
### 5.2 FileUpload 文件上传组件
```vue
```
### 5.3 Editor 富文本组件
```vue
```
### 5.4 RightToolbar 表格工具栏组件
```vue
新增
删除
```
## 6. 最佳实践
### 6.1 组件组合使用
**表格 + 分页 + 字典 + 权限**：
```vue
新增用户
批量删除
编辑
删除
```
### 6.2 性能优化建议
1. **表格性能优化**：
- 对于大数据量表格，使用 `height` 属性启用虚拟滚动
- 合理设置 `scrollbar-always-on` 属性
- 使用 `stripe` 和 `border` 属性时注意性能影响
2. **字典数据优化**：
- 尽量在组件初始化时获取所有需要的字典类型
- 避免在循环中频繁调用 `selectDictLabel` 函数
3. **权限控制优化**：
- 避免在大量重复元素上使用权限指令
- 可以在父组件层面进行权限判断，减少指令使用
### 6.3 代码规范建议
1. **组件命名**：
- 使用 PascalCase 命名组件
- 组件文件使用 kebab-case 命名
2. **Props 定义**：
- 明确 Props 类型和默认值
- 使用 v-model 实现双向绑定
3. **事件处理**：
- 使用明确的事件名称
- 避免在模板中编写复杂的事件处理逻辑
4. **代码结构**：
- 合理组织组件代码结构
- 使用 setup script 语法
- 避免组件过大，合理拆分组件
---
**文档版本**：1.0
**更新日期**：2023-07-01
**编写人员**：Wimoor UI 开发团队