更新记录

1.0.0（2026-08-21） 下载此版本

• 初始版本
• 封装 GET /core/mobile/system/dict，数据存于 Pinia store（id wc-dict）
• 对外 5 个模块级函数（import 后 await 即用）：
  • getDictAll() —— 全量字典数据
  • getDictList(code) —— 整个字典的数据项列表
  • getDictItem(code, value) —— 按值查单条
  • getDictLabel(code, value) / getDictColor(code, value) —— 单条的 label / color
• 缓存规则：store 有走缓存，没有走接口后写入再返回；force = true 跳过缓存强制走接口
• value 做 String() 归一化比较，传数字也能命中字符串值
• 依赖 wc-request ^2.0.0（fetch 开启 dedupe：同一字典并发请求在飞时自动合并）、pinia ^2.2.2

平台兼容性

uni-app(5.24)

uni-app x(5.24)

wc-dict

数据字典封装，基于 [wc-request]（/core/mobile/system/dict 接口），数据存于 Pinia store。

安装前置

1. 先安装 wc-request（本模块依赖它发请求）
2. 项目需已安装并启用 [Pinia]（npm 依赖 pinia），App 启动时配置：

// main.ts
import * as Pinia from 'pinia'
import { setBaseURL } from "@/uni_modules/wc-request/commons/request"

export function createApp() {
  setBaseURL("https://api.example.com")

  const app = createSSRApp(App)
  app.use(Pinia.createPinia())
  return {
    app,
    Pinia, // uni-app 约定：必须将 Pinia 一并返回（小程序 / App 端需要）
  }
}

使用（就一种姿势：import 函数，await）

5 个函数，全部返回 Promise，任何地方（onMounted / 事件回调 / 工具函数）直接 await：

import { getDictLabel, getDictList } from "@/uni_modules/wc-dict/commons"

// 组件里
onMounted(async () => {
  const label = await getDictLabel("gender", "2")        // "女"
  const items = await getDictList("upload_mode")          // [{ label: "本地存储", ... }, ...]
})

// 任何地方
const color = await getDictColor("gender", "2")           // "#ff4500"

末位可选参数 force = true：跳过缓存强制走接口（结果同时刷新缓存）：

const fresh = await getDictList("upload_mode", true)

缓存规则（所有函数一致）

Pinia 里有 → 直接走缓存返回；没有 → 请求接口 → 写入 Pinia → 返回。

• 同一字典第二次查询起，不再发请求
• 字典不存在 → 写入空数组，不再反复请求
• 请求失败 → 不写缓存（下次查询自然重试），RequestError 原样上抛；默认 toast 继承 wc-request
• 需要最新数据 → 传 force: true

数据结构

interface DictItem {
  id: number
  type_id: number
  label: string   // 展示文案，如 "女"
  value: string   // 恒为字符串，如 "2"（getDictItem 等传数字 2 也能命中）
  color: string   // 如 "#ff4500"
  code: string    // 所属字典 code
  sort: number
}

直接访问 store（可选）

getDictXxx 就是从 store 转发的，一般不用直接碰 store；需要响应式读全部数据时可以：

import { useDictStore } from "@/uni_modules/wc-dict/commons"

const store = useDictStore()
store.dictMap.gender   // 响应式，已加载的字典列表

范围说明

刻意不包含（保持简单）：

• 并发去重（在 wc-request：dedupe: true，本模块已启用）
• 组合式函数、UI 组件
• store 持久化、TTL 过期
• token 注入与刷新（wc-request 范畴）