yunzer_go/pc/docs/pinia-dict-guide.md

Pinia 字典管理系统使用指南

系统架构

┌─────────────────────────────────────┐
│     API 接口 (getDictItemsByCode)   │
│         /api/dict/items/code/{code} │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│   Pinia Store (useDictStore)        │
│  ✅ 自动缓存字典数据                 │
│  ✅ 避免重复请求                    │
│  ✅ 支持同步/异步访问                │
└──────────────┬──────────────────────┘
               │
        ┌──────┴──────┐
        ↓             ↓
    ┌────────┐  ┌──────────────┐
    │组件    │  │Composable    │
    │直接用  │  │useDict Hook  │
    └────────┘  └──────────────┘

---

核心文件说明

1. Store: src/stores/dict.js

字典数据的全局管理器

主要方法：

import { useDictStore } from '@/stores/dict'

const dictStore = useDictStore()

// ✅ 异步获取字典（推荐）
const items = await dictStore.getDictItems('user_status')

// ✅ 同步获取字典（已缓存时）
const items = dictStore.getDictItemsSync('user_status')

// ✅ 获取字典值对应的标签
const label = dictStore.getDictLabel('user_status', 1)

// ✅ 预加载多个字典
await dictStore.preloadDicts(['user_status', 'user_role'])

// ✅ 清空缓存
dictStore.clearCache('user_status')

---

2. 常量: src/constants/dictCodes.js

集中管理所有字典编码

使用示例：

import { DICT_CODES } from '@/constants/dictCodes'

// 好处：避免硬编码，IDE 有自动完成
const items = await dictStore.getDictItems(DICT_CODES.USER_STATUS)

// 所有可用的编码：
DICT_CODES.USER_STATUS      // 用户状态
DICT_CODES.USER_GENDER      // 用户性别
DICT_CODES.USER_ROLE        // 用户角色
DICT_CODES.DEPT_STATUS      // 部门状态
DICT_CODES.POSITION_STATUS  // 职位状态
// ... 更多编码

---

3. Composable: src/composables/useDict.js

简化在组件中使用字典的 Hook

基础用法：

import { useDictionary, useUserStatusDict } from '@/composables/useDict'
import { DICT_CODES } from '@/constants/dictCodes'

// 方式1：使用常量
const { statusDict, loading } = useDictionary(DICT_CODES.USER_STATUS)

// 方式2：使用字符串
const { dicts, loading } = useDictionary('user_status')

// 方式3：使用特化 Hook（推荐）
const { user_statusDict, loading } = useUserStatusDict()

---

使用场景

场景1：在列表页加载字典

文件: src/views/system/users/index.vue

<script setup>
import { useDictStore } from '@/stores/dict'
import { ref, onMounted } from 'vue'

const dictStore = useDictStore()
const statusDict = ref([])

const fetchStatusDict = async () => {
  statusDict.value = await dictStore.getDictItems('user_status')
}

onMounted(async () => {
  await fetchStatusDict()
})
</script>

<template>
  <!-- 传给子组件 -->
  <UserEditDialog :status-dict="statusDict" />
</template>

---

场景2：在编辑对话框使用字典

文件: src/views/system/users/components/UserEdit.vue

<template>
  <!-- 状态选择 -->
  <el-form-item label="状态">
    <el-select v-model="form.status">
      <el-option 
        v-for="item in statusDict"
        :key="item.dict_value"
        :label="item.dict_label"
        :value="item.dict_value"
      />
    </el-select>
  </el-form-item>
</template>

<script setup>
const props = defineProps({
  statusDict: {
    type: Array,
    default: () => [],
  },
})
</script>

---

场景3：快速使用 Composable Hook

最简单的方式，自动处理加载：

<template>
  <div>
    <p v-if="loading">加载中...</p>
    <el-select v-else v-model="status">
      <el-option 
        v-for="item in user_statusDict"
        :key="item.dict_value"
        :label="item.dict_label"
        :value="item.dict_value"
      />
    </el-select>
  </div>
</template>

<script setup>
import { useUserStatusDict } from '@/composables/useDict'
import { ref } from 'vue'

const status = ref('active')
const { user_statusDict, loading } = useUserStatusDict()
</script>

---

场景4：预加载应用启动时需要的字典

文件: src/main.js

import { createApp } from 'vue'
import { createPinia } from 'pinia'
import { useDictStore } from '@/stores/dict'
import { DICT_CODES } from '@/constants/dictCodes'

const app = createApp(App)
const pinia = createPinia()

app.use(pinia)

// 在应用启动后预加载常用字典
const dictStore = useDictStore()
await dictStore.preloadDicts([
  DICT_CODES.USER_STATUS,
  DICT_CODES.COMMON_STATUS,
  DICT_CODES.YES_NO,
])

app.mount('#app')

---

字典数据结构

后端返回的字典数据结构：

[
  {
    "dict_id": 1,
    "dict_value": "1",
    "dict_label": "启用",
    "dict_type": "user_status",
    "remarks": "用户启用状态",
    "remark": "用户启用状态"
  },
  {
    "dict_id": 2,
    "dict_value": "0",
    "dict_label": "禁用",
    "dict_type": "user_status",
    "remarks": "用户禁用状态",
    "remark": "用户禁用状态"
  }
]

关键字段：

• dict_value: 字典值（存储在数据库中）
• dict_label: 字典标签（显示给用户）
• dict_type: 字典类型编码（如 'user_status'）

---

最佳实践

✅ DO

1. 使用常量而不是硬编码字符串

   // ✅ 好
   dictStore.getDictItems(DICT_CODES.USER_STATUS)
   
   // ❌ 差
   dictStore.getDictItems('user_status')
   

2. 在父组件加载，通过 props 传给子组件

   // ✅ 父组件负责数据，子组件负责展示
   // index.vue
   const statusDict = await dictStore.getDictItems(DICT_CODES.USER_STATUS)
   
   // UserEdit.vue
   const props = defineProps({ statusDict: Array })
   

3. 用 Composable 简化组件逻辑

   // ✅ 一行代码搞定
   const { user_statusDict, loading } = useUserStatusDict()
   

4. 预加载常用字典

   // ✅ 应用启动时预加载，避免页面初始化时加载
   await dictStore.preloadDicts([...])
   

❌ DON'T

1. 不要在多个地方重复加载同一个字典

   // ❌ 糟糕：重复加载
   // 页面A
   const dict1 = await dictStore.getDictItems('user_status')
   
   // 页面B（Store 会自动缓存，但代码看起来重复）
   const dict2 = await dictStore.getDictItems('user_status')
   

2. 不要忘记处理加载状态

   // ❌ 可能展示空白
   const { statusDict } = useUserStatusDict()
   
   // ✅ 处理加载状态
   const { statusDict, loading } = useUserStatusDict()
   if (loading) { /* 显示加载中 */ }
   

3. 不要混用不同的字典访问方式

   // ❌ 混乱
   const dict1 = await dictStore.getDictItems('user_status')
   const dict2 = dictStore.getDictItemsSync('user_role')
   
   // ✅ 统一使用
   const dict1 = await dictStore.getDictItems('user_status')
   const dict2 = await dictStore.getDictItems('user_role')
   

---

性能优化建议

优化项	说明
缓存	Store 自动缓存，同一个字典只请求一次
预加载	在路由切换前预加载需要的字典
同步访问	已加载的字典可用 getDictItemsSync 同步获取
避免重复	不要在多个组件重复请求同一个字典

---

故障排查

问题1：状态选项为空

原因：字典未加载 解决：

// ❌ 错误：字典还未加载
const statusDict = dictStore.getDictItemsSync('user_status') // 返回 []

// ✅ 正确：等待异步加载完成
const statusDict = await dictStore.getDictItems('user_status')

问题2：重复加载字典

原因：没有使用 Store 的缓存 解决：

// 所有调用都会自动使用缓存，只请求一次
await dictStore.getDictItems('user_status') // 首次：发送请求
await dictStore.getDictItems('user_status') // 第二次：返回缓存

问题3：字典显示不对

原因：value 类型不匹配（如 1 vs "1"） 解决：

// Store 会自动处理类型匹配
const item = items.find(i => 
  String(i.dict_value) === String(value) || i.dict_value === value
)

---

集成检清表

• 创建 src/stores/dict.js - Store
• 创建 src/constants/dictCodes.js - 常量
• 创建 src/composables/useDict.js - Composable
• 在 index.vue 中导入 useDictStore
• 在 UserEdit.vue 中接收 statusDict props
• 测试字典加载和显示
• 验证缓存功能（打开浏览器 DevTools 检查 Network）
• 预加载常用字典（可选）

---

相关文件修改

已修改的文件：

• ✅ src/stores/dict.js - 新建
• ✅ src/constants/dictCodes.js - 新建
• ✅ src/composables/useDict.js - 新建
• ✅ src/views/system/users/index.vue - 使用 useDictStore
• ✅ src/views/system/users/components/UserEdit.vue - 导入字典库