394 lines
9.4 KiB
Markdown
394 lines
9.4 KiB
Markdown
# Pinia 字典管理系统使用指南
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ API 接口 (getDictItemsByCode) │
|
||
│ /api/dict/items/code/{code} │
|
||
└──────────────┬──────────────────────┘
|
||
│
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Pinia Store (useDictStore) │
|
||
│ ✅ 自动缓存字典数据 │
|
||
│ ✅ 避免重复请求 │
|
||
│ ✅ 支持同步/异步访问 │
|
||
└──────────────┬──────────────────────┘
|
||
│
|
||
┌──────┴──────┐
|
||
↓ ↓
|
||
┌────────┐ ┌──────────────┐
|
||
│组件 │ │Composable │
|
||
│直接用 │ │useDict Hook │
|
||
└────────┘ └──────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 核心文件说明
|
||
|
||
### 1. **Store**: `src/stores/dict.js`
|
||
|
||
字典数据的全局管理器
|
||
|
||
**主要方法**：
|
||
```javascript
|
||
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`
|
||
|
||
集中管理所有字典编码
|
||
|
||
**使用示例**：
|
||
```javascript
|
||
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
|
||
|
||
**基础用法**：
|
||
```javascript
|
||
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`
|
||
|
||
```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`
|
||
|
||
```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
|
||
|
||
最简单的方式，自动处理加载：
|
||
|
||
```vue
|
||
<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`
|
||
|
||
```javascript
|
||
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')
|
||
```
|
||
|
||
---
|
||
|
||
## 字典数据结构
|
||
|
||
后端返回的字典数据结构：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"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. **使用常量而不是硬编码字符串**
|
||
```javascript
|
||
// ✅ 好
|
||
dictStore.getDictItems(DICT_CODES.USER_STATUS)
|
||
|
||
// ❌ 差
|
||
dictStore.getDictItems('user_status')
|
||
```
|
||
|
||
2. **在父组件加载，通过 props 传给子组件**
|
||
```javascript
|
||
// ✅ 父组件负责数据，子组件负责展示
|
||
// index.vue
|
||
const statusDict = await dictStore.getDictItems(DICT_CODES.USER_STATUS)
|
||
|
||
// UserEdit.vue
|
||
const props = defineProps({ statusDict: Array })
|
||
```
|
||
|
||
3. **用 Composable 简化组件逻辑**
|
||
```javascript
|
||
// ✅ 一行代码搞定
|
||
const { user_statusDict, loading } = useUserStatusDict()
|
||
```
|
||
|
||
4. **预加载常用字典**
|
||
```javascript
|
||
// ✅ 应用启动时预加载，避免页面初始化时加载
|
||
await dictStore.preloadDicts([...])
|
||
```
|
||
|
||
### ❌ DON'T
|
||
|
||
1. **不要在多个地方重复加载同一个字典**
|
||
```javascript
|
||
// ❌ 糟糕：重复加载
|
||
// 页面A
|
||
const dict1 = await dictStore.getDictItems('user_status')
|
||
|
||
// 页面B（Store 会自动缓存，但代码看起来重复）
|
||
const dict2 = await dictStore.getDictItems('user_status')
|
||
```
|
||
|
||
2. **不要忘记处理加载状态**
|
||
```javascript
|
||
// ❌ 可能展示空白
|
||
const { statusDict } = useUserStatusDict()
|
||
|
||
// ✅ 处理加载状态
|
||
const { statusDict, loading } = useUserStatusDict()
|
||
if (loading) { /* 显示加载中 */ }
|
||
```
|
||
|
||
3. **不要混用不同的字典访问方式**
|
||
```javascript
|
||
// ❌ 混乱
|
||
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：状态选项为空
|
||
|
||
**原因**：字典未加载
|
||
**解决**：
|
||
```javascript
|
||
// ❌ 错误：字典还未加载
|
||
const statusDict = dictStore.getDictItemsSync('user_status') // 返回 []
|
||
|
||
// ✅ 正确：等待异步加载完成
|
||
const statusDict = await dictStore.getDictItems('user_status')
|
||
```
|
||
|
||
### 问题2：重复加载字典
|
||
|
||
**原因**：没有使用 Store 的缓存
|
||
**解决**：
|
||
```javascript
|
||
// 所有调用都会自动使用缓存，只请求一次
|
||
await dictStore.getDictItems('user_status') // 首次：发送请求
|
||
await dictStore.getDictItems('user_status') // 第二次：返回缓存
|
||
```
|
||
|
||
### 问题3：字典显示不对
|
||
|
||
**原因**：value 类型不匹配（如 1 vs "1"）
|
||
**解决**：
|
||
```javascript
|
||
// 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` - 导入字典库
|
||
|