162 lines
4.4 KiB
Markdown
162 lines
4.4 KiB
Markdown
# 字典系统使用指南
|
||
|
||
## 概述
|
||
|
||
字典系统是为了解决项目中数据字典不统一、硬编码问题而设计的统一管理方案。系统支持静态字典（本地定义）和动态字典（API获取），并提供了便捷的访问接口。
|
||
|
||
## 系统架构
|
||
|
||
字典系统由以下几个部分组成：
|
||
|
||
1. **工具类** (`src/utils/dict.ts`) - 提供静态字典数据和工具函数
|
||
2. **Store** (`src/stores/dict.ts`) - 管理动态字典数据，与现有Pinia架构集成
|
||
3. **API服务** (`src/service/api/dict.ts`) - 提供动态字典获取接口
|
||
4. **组件示例** - 展示如何在组件中使用字典系统
|
||
|
||
## 使用方法
|
||
|
||
### 1. 在组件中使用字典
|
||
|
||
```typescript
|
||
<script setup lang="ts">
|
||
import { useDictStore } from '~/stores/dict'
|
||
import { getDictLabel, getDictColor } from '~/utils/dict'
|
||
|
||
const dictStore = useDictStore()
|
||
|
||
// 获取字典项列表
|
||
const professionalCategoryItems = computed(() => dictStore.getDictItems('professionalCategory'))
|
||
|
||
// 获取字典项标签
|
||
const label = dictStore.getDictLabel('professionalCategory', 'science')
|
||
|
||
// 获取字典项颜色
|
||
const color = dictStore.getDictColor('educationalLevel', 'undergraduate')
|
||
</script>
|
||
```
|
||
|
||
### 2. 在模板中使用
|
||
|
||
```vue
|
||
<template>
|
||
<select v-model="selectedValue">
|
||
<option
|
||
v-for="item in dictStore.getDictItems('professionalCategory')"
|
||
:key="item.value"
|
||
:value="item.value"
|
||
>
|
||
{{ item.label }}
|
||
</option>
|
||
</select>
|
||
|
||
<!-- 显示标签 -->
|
||
<span>选中值: {{ dictStore.getDictLabel('professionalCategory', selectedValue) }}</span>
|
||
</template>
|
||
```
|
||
|
||
### 3. 静态字典工具函数
|
||
|
||
```typescript
|
||
// 获取字典项列表
|
||
const items = getDictItems('professionalCategory')
|
||
|
||
// 获取字典标签
|
||
const label = getDictLabel('professionalCategory', 'science')
|
||
|
||
// 获取字典值
|
||
const value = getDictValue('professionalCategory', '理工类')
|
||
|
||
// 获取字典颜色
|
||
const color = getDictColor('professionalCategory', 'science')
|
||
|
||
// 获取字典项对象
|
||
const item = getDictItem('professionalCategory', 'science')
|
||
```
|
||
|
||
### 4. 动态字典管理
|
||
|
||
```typescript
|
||
// 加载动态字典
|
||
await dictStore.loadDynamicDicts()
|
||
|
||
// 加载特定类型的动态字典
|
||
await dictStore.loadDynamicDicts(['dynamic_type1', 'dynamic_type2'])
|
||
|
||
// 手动设置动态字典
|
||
dictStore.setDynamicDict('custom_type', [
|
||
{ label: '自定义项1', value: 'custom1' },
|
||
{ label: '自定义项2', value: 'custom2' }
|
||
])
|
||
|
||
// 清空动态字典
|
||
dictStore.clearDynamicDicts()
|
||
```
|
||
|
||
## 字典数据结构
|
||
|
||
字典项接口定义：
|
||
|
||
```typescript
|
||
interface DictItem {
|
||
label: string // 显示标签
|
||
value: string | number // 实际值
|
||
disabled?: boolean // 是否禁用
|
||
color?: string // 颜色值
|
||
order?: number // 排序
|
||
[key: string]: any // 扩展属性
|
||
}
|
||
```
|
||
|
||
## 静态字典类型
|
||
|
||
目前系统已内置以下静态字典：
|
||
|
||
- `professionalCategory` - 专业类别
|
||
- `educationalLevel` - 学历层次
|
||
- `provinces` - 省份
|
||
- `subjectList` - 科目列表
|
||
- `gender` - 性别
|
||
- `status` - 状态
|
||
- `type` - 类型
|
||
|
||
## 动态字典API
|
||
|
||
动态字典通过API获取，支持以下接口：
|
||
|
||
- `GET /dict/list` - 获取字典列表
|
||
- `GET /dict/type/{type}` - 获取指定类型的字典
|
||
|
||
## 在现有组件中集成
|
||
|
||
以ScoreForm.vue为例，展示了如何将现有硬编码的选项替换为字典系统：
|
||
|
||
1. 导入字典Store
|
||
2. 使用computed属性获取字典项
|
||
3. 在模板中使用字典数据
|
||
|
||
## 扩展字典类型
|
||
|
||
如需添加新的静态字典类型：
|
||
|
||
1. 在 `src/utils/dict.ts` 中的 `staticDicts` 对象中添加新类型
|
||
2. 确保遵循 `DictItem[]` 的数据结构
|
||
|
||
如需添加新的动态字典类型：
|
||
|
||
1. 在后端API中提供相应的字典数据接口
|
||
2. 在前端调用 `dictStore.loadDynamicDicts()` 时指定类型
|
||
|
||
## 最佳实践
|
||
|
||
1. **优先使用字典系统** - 避免在代码中硬编码选项数据
|
||
2. **统一管理** - 所有字典数据通过字典系统统一管理
|
||
3. **性能优化** - 字典数据通常在应用初始化时加载一次，后续直接使用
|
||
4. **扩展性** - 支持静态和动态字典，满足不同业务场景需求
|
||
5. **类型安全** - 提供完整的TypeScript类型定义
|
||
|
||
## 注意事项
|
||
|
||
1. 动态字典加载失败时，系统会继续使用静态字典数据
|
||
2. 字典数据在应用生命周期内会被缓存，避免重复请求
|
||
3. 在组件中使用字典前，确保字典数据已加载完成
|
||
4. 动态字典会覆盖同名的静态字典数据 |