vitesse-yitisheng-web/docs/dict-system.md

字典系统使用指南

概述

字典系统是为了解决项目中数据字典不统一、硬编码问题而设计的统一管理方案。系统支持静态字典（本地定义）和动态字典（API获取），并提供了便捷的访问接口。

系统架构

字典系统由以下几个部分组成：

1. 工具类 (src/utils/dict.ts) - 提供静态字典数据和工具函数
2. Store (src/stores/dict.ts) - 管理动态字典数据，与现有Pinia架构集成
3. API服务 (src/service/api/dict.ts) - 提供动态字典获取接口
4. 组件示例 - 展示如何在组件中使用字典系统

使用方法

1. 在组件中使用字典

<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. 在模板中使用

<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. 静态字典工具函数

// 获取字典项列表
const items = getDictItems('professionalCategory')

// 获取字典标签
const label = getDictLabel('professionalCategory', 'science')

// 获取字典值
const value = getDictValue('professionalCategory', '理工类')

// 获取字典颜色
const color = getDictColor('professionalCategory', 'science')

// 获取字典项对象
const item = getDictItem('professionalCategory', 'science')

4. 动态字典管理

// 加载动态字典
await dictStore.loadDynamicDicts()

// 加载特定类型的动态字典
await dictStore.loadDynamicDicts(['dynamic_type1', 'dynamic_type2'])

// 手动设置动态字典
dictStore.setDynamicDict('custom_type', [
  { label: '自定义项1', value: 'custom1' },
  { label: '自定义项2', value: 'custom2' }
])

// 清空动态字典
dictStore.clearDynamicDicts()

字典数据结构

字典项接口定义：

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. 动态字典会覆盖同名的静态字典数据