hzdyjs/mobile/src/common/README-dict.md

移动端字典工具使用指南

📋 简介

为移动端（Vue 2.6.14 + uni-app 2.x）提供完整的字典数据获取和管理功能，与web端保持一致的API设计。

🚀 快速开始

1. 基础导入

import { useDict, getDict, getDictLabel } from '@/common/dict.js'

2. 在页面中使用

export default {
  data() {
    return {
      dictionaries: {},
      userInfo: {
        gender: '0',
        status: '1'
      }
    }
  },
  
  created() {
    this.loadDictionaries()
  },
  
  methods: {
    async loadDictionaries() {
      // 批量加载字典
      const dictManager = useDict('sys_user_sex', 'sys_normal_disable')
      
      // Vue 2响应式更新（必须设置）
      dictManager.setUpdateCallback((dictType, data) => {
        this.$set(this.dictionaries, dictType, data)
      })
    },
    
    // 获取字典标签显示
    getDictText(dictType, value) {
      const dictData = this.dictionaries[dictType] || []
      return getDictLabel(dictData, value)
    }
  }
}

3. 在模板中显示

<template>
  <view>
    <!-- 显示用户性别 -->
    <text>性别: {{ getDictText('sys_user_sex', userInfo.gender) }}</text>
    
    <!-- 显示用户状态 -->
    <text>状态: {{ getDictText('sys_normal_disable', userInfo.status) }}</text>
  </view>
</template>

📚 主要功能

功能	方法	说明
批量字典管理	useDict(...types)	推荐使用，支持多字典并发加载
单个字典获取	getDict(type, cache?)	获取单个字典数据
字典标签获取	getDictLabel(data, value)	根据值获取标签
字典值获取	getDictValue(data, label)	根据标签获取值
值存在检查	hasDictValue(data, value)	检查值是否存在
缓存刷新	refreshDict(types)	刷新指定字典缓存

🎯 使用场景

场景1: uview组件集成

// radio-group
<u-radio-group v-model="form.gender">
  <u-radio 
    v-for="item in dictionaries.sys_user_sex" 
    :key="item.value"
    :name="item.value"
  >
    {{ item.label }}
  </u-radio>
</u-radio-group>

// select组件
computed: {
  selectOptions() {
    return (this.dictionaries.sys_user_sex || []).map(item => ({
      value: item.value,
      label: item.label
    }))
  }
}

场景2: 表格数据转换

computed: {
  processedData() {
    return this.tableData.map(row => ({
      ...row,
      genderText: getDictLabel(this.dictionaries.sys_user_sex || [], row.gender),
      statusText: getDictLabel(this.dictionaries.sys_normal_disable || [], row.status)
    }))
  }
}

场景3: 单独获取字典

async methods: {
  async loadSingleDict() {
    try {
      const genderDict = await getDict('sys_user_sex')
      console.log('性别字典:', genderDict)
    } catch (error) {
      console.error('加载失败:', error)
    }
  }
}

⚡ 性能特性

• 智能缓存: 24小时有效期，自动管理
• 并发加载: 多字典同时请求，提升加载速度
• 响应式更新: 完美适配Vue 2响应式系统
• 错误处理: 完善的错误处理和兜底机制

🔧 高级用法

缓存管理

import { dictCache, refreshDict } from '@/common/dict.js'

// 清除指定缓存
dictCache.remove('sys_user_sex')

// 清除所有缓存
dictCache.clear()

// 刷新缓存
await refreshDict(['sys_user_sex', 'sys_normal_disable'])

错误处理

// 安全的字典获取（带默认值）
safeDictLabel(dictType, value, defaultLabel = '-') {
  try {
    const dictData = this.dictionaries[dictType] || []
    const label = getDictLabel(dictData, value)
    return label || defaultLabel
  } catch (error) {
    console.error(`获取字典失败 ${dictType}:${value}`, error)
    return defaultLabel
  }
}

📖 相关文件

• 核心实现: /mobile/src/common/dict.js
• 使用示例: /mobile/src/common/dict-usage-example.js
• 变更记录: /docs/变更管理/code-adjust-record-2025-01-27-移动端字典工具实现.md

⚠️ 重要提醒

Vue 2必须使用回调机制

// 错误：直接赋值不会触发响应式更新
this.dictionaries = dictManager.data

// 正确：使用回调确保响应式更新 ✅
dictManager.setUpdateCallback((dictType, data) => {
  this.$set(this.dictionaries, dictType, data)
})

兼容性

• ✅ Vue 2.6.14+
• ✅ uni-app 2.x
• ✅ H5 / 小程序 / App

🎯 最佳实践

1. 优先使用useDict: 支持并发加载，性能更好
2. 合理使用缓存: 频繁变动的字典设置useCache=false
3. 添加错误处理: 关键业务场景要有异常处理
4. 使用callback机制: Vue 2中必须使用setUpdateCallback

---

✨ 完成时间: 2025-01-27 20:15:00
👨‍💻 开发者: wuzilong
📱 适用版本: Vue 2.6.14 + uni-app 2.x