从Vue2迁到Vue3，最先让我破防的不是响应式API，也不是Teleport，而是全局过滤器被移除了。以前项目里性别、订单状态、审批节点这类字段，全靠Vue2里那句{{ status | dictLabel('orderStatus') }}一把梭。迁到Vue3之后这行代码直接报错，因为Vue3明确不再支持全局filter。我去翻了一圈社区的替代方案，有的说用函数替代，有的说用computed加工，还有人说干脆挂到window上……挂window那个我是真不敢用。
后来在几个后台管理项目里反复折腾，慢慢沉淀出一套在Vue3里引入和使用字典的比较稳的做法。今天就把这套方案完整拆开讲清楚：字典在业务里到底是什么、数据从哪来、怎么封装成组合式函数，以及在表格、下拉框、标签渲染这些实际场景里怎么用。文章里的代码都是可以直接抄走的级别，同时我会把每个关键决策背后的原因讲清楚，这样不管你是刚转Vue3的新手，还是已经在项目里挣扎过的老手，都能从中拿到点东西。
1. 先说清楚：业务里的"字典"到底指什么
1.1 字典不是Map，是"值到显示文本"的映射约定
数据结构里的字典，指的是键值对集合，比如{ key: value }。但业务开发里说的字典，含义更具体：它是一组枚举值和显示文本的对应关系。比如数据库里用户表存的是status = 2，页面上要显示的是"已通过"；再比如后端返回gender = 1，前端要渲染"男"。这个"把数字翻译成人话"的数据集合，就是字典。
用SQL理解更直观。没有字典表的时候，你写SQL可能这样：
SELECT CASE WHEN status = 1 THEN '待审核' WHEN status = 2 THEN '已通过' WHEN status = 3 THEN '已拒绝' END AS status_text FROM orders;前端拿到的是一个已经翻译好的字符串。这是早期"后端翻译、前端直接显示"的做法。但很快你会发现这条路走不通：表格既要显示文本，又要根据状态给标签颜色；下拉框要遍历所有选项；搜索条件又要复用同一组枚举。如果每次都是后端拼好的文本，前端反而失去灵活性，所以慢慢演变成后端只返回原始值（如1、2），前端统一维护一套字典来做翻译。
1.2 一套字典方案要解决哪几个问题
我自己在做字典方案时，先列了需求清单，主要包括这几件事：
- 定义：在某个地方把
value和label的关系声明出来，组内其他人容易找到、容易改； - 引入：页面有用到时就拿得到，不用每个组件都重复 import 一大堆常量；
- 翻译：给定一个字典类型和一个值，能快速拿到展示文本；
- 渲染：表格里显示文本，下拉框里生成选项，状态标签要带颜色；
- 兜底：字典里查不到的值，不能直接白屏或者报错，要有合理显示。
带着这份清单去看市面上的封装方案，你会发现很多方案都只解决了"翻译"这一件事，后面几项没人管。这就是为什么我最后选择自己封装一个useDict组合式函数，而不是简单地依赖某个 UI 库自带的字典功能。
2. 字典数据从哪来：本地静态和远程接口怎么选
2.1 静态字典：适合"改动跟着前端发布"的场景
字典的第一种来源是直接在前端代码里定义。我一般归类为静态字典，典型的例子是性别、证件类型、用户类型这种几乎不会变、而且是产品层固定语义的数据。
直接在src/dict/user.ts文件里写：
// src/dict/user.ts export interface DictItem { label: string value: string | number color?: string } export const userTypeDict: DictItem[] = [ { value: 1, label: '普通用户' }, { value: 2, label: '商家用户' }, { value: 3, label: '管理员' } ] export const genderDict: DictItem[] = [ { value: 0, label: '未知' }, { value: 1, label: '男' }, { value: 2, label: '女' } ]静态字典的优点很直接：类型安全、不依赖网络、打包时可被 tree-shaking。你定义的是 TypeScript 对象，IDE 能自动提示，编译期就能发现明显拼写错误。而且它不依赖后端接口，页面加载不需要等网络请求。缺点是如果字典值需要运营后台动态修改，比如增加一种新的订单状态，那就得发版改代码，节奏太慢。
2.2 接口字典：适合"运营需求频繁变化"的场景
第二种来源是后端接口返回的字典数据。数据库里通常会有一张sys_dict表，后台管理页面可以增删改字典项，前端启动时或者首次需要用的时候去请求接口拿数据。
接口返回格式一般长这样：
[ { "value": 1, "label": "待付款", "color": "warning" }, { "value": 2, "label": "待发货", "color": "primary" }, { "value": 3, "label": "已完成", "color": "success" } ]这种情况下字典的引入方式就不是import一个文件了，而是封装一个字典请求函数，按需加载。接口字典的优势是灵活，运营可以直接在后台维护字典，前端不用每次发版，同时权限系统可以控制不同用户能看到哪些字典。代价是引入了异步逻辑，组件渲染时要考虑"数据还没回来"的状态，后面第 3 节和第 6 节我会重点讲这个坑。
2.3 我的建议：混合使用，不要让一种方案包办所有
在我自己的项目里，字典方案从来不是二选一，而是混合的。原则是：
- 前端写死更好维护的、低频变化的，用静态字典；
- 业务运营需要随时调整、或者不同用户看到不同选项的，用接口字典。
比如用户性别、证件类型、颜色主题这种，用静态字典；订单状态、审批流程节点、积分等级规则这种，用接口字典。做这种区分不是为了炫技，而是让团队维护时少一点心智负担：静态字典改起来要发版，那就把发版成本高的数据推给接口；接口字典排查问题时要多一环网络链路，那就把实际上不会变的字段留在本地。
3. 核心封装：useDict 组合式函数的设计与实现
3.1 为什么Vue3里不推荐继续用"函数挂在全局"的老思路
Vue2时代，很多项目用Vue.filter或者Vue.prototype.$dictLabel来全局处理字典。Vue3里 filter 被移除了，Vue.prototype变成了app.config.globalProperties。于是很多人把字典函数挂到全局globalProperties上，组件里这么用：
const app = createApp(App) app.config.globalProperties.$dictLabel = (type, value) => { ... }模板里是能用了，但代价很明显：没有类型提示、不便于按需加载、测试困难。而且全局对象里塞的函数会随着项目变大而无限膨胀，组件里隐式依赖一个"外面定义"的$dictLabel，代码的可读性很差。更关键的是，这种方式没办法处理"字典数据是异步获取的"这类复杂场景——函数挂全局只能同步返回结果，异步数据只能存在别处再手动触发变更，坑非常多。
3.2 组合式函数为什么是更合适的答案
Vue3 的 Composition API 给了更优雅的答案：把一组"字典状态"和"字典方法"打包成一个组合式函数，组件里需要时就调用，不需要就不引入。这样既没有全局污染，又天然适配异步逻辑，同时还能利用 TypeScript 做类型约束。
我先说设计目标。我希望在组件里以极简的方式使用：
const dict = useDict({ orderStatus: { url: '/api/dict/order-status' }, userType: { data: userTypeDict } })然后模板里能直接翻译和渲染：
<el-tag :type="dict.getDictColor('orderStatus', row.status)"> {{ dict.getDictLabel('orderStatus', row.status) }} </el-tag>用户在useDict里传入一个配置对象，配置的每一项要么是带data的静态字典，要么是带url的远程字典。函数内部统一把数据加载逻辑、缓存逻辑、翻译逻辑封装好，对外暴露一个包含字典数据和翻译方法的对象。这个 API 形态友好，后续扩展字段也容易。
3.3 完整实现：一个可用的 useDict
下面这段代码是我在项目里使用的一个精简版实现，注释里标注了关键设计：
// src/composables/useDict.ts import { shallowReactive, ref } from 'vue' interface DictItem { label: string value: string | number color?: string [key: string]: unknown } interface DictMeta { /** 静态字典：直接传数组 */ data?: DictItem[] /** 远程字典：传接口地址，默认 GET 请求 */ url?: string /** 自定义请求函数，优先级高于 url */ fetcher?: () => Promise<DictItem[]> } // 全局共享的字典缓存，避免多个页面重复请求同一个接口 const store = shallowReactive<Record<string, DictItem[]>>({}) const pendingMap = new Map<string, Promise<DictItem[]>>() async function loadRemoteDict(key: string, meta: DictMeta): Promise<DictItem[]> { // 命中缓存直接返回 if (store[key]?.length) { return store[key] } // 同一时刻对同一个字典的并发请求，只发一次 if (pendingMap.has(key)) { return pendingMap.get(key)! } const load = async (): Promise<DictItem[]> => { let list: DictItem[] = [] if (meta.data) { list = [...meta.data] } else if (meta.fetcher) { list = await meta.fetcher() } else if (meta.url) { const res = await fetch(meta.url) const json = await res.json() // 根据接口返回结构自行调整，比如 json.data || json.result list = Array.isArray(json) ? json : json?.data ?? [] } // 写入全局缓存 store[key] = list return list } const promise = load() pendingMap.set(key, promise) return promise.finally(() => { pendingMap.delete(key) }) } export function useDict(dictMap: Record<string, DictMeta>) { // 当前组件实例内的字典数据，也是响应式的 const data = shallowReactive<Record<string, DictItem[]>>({}) const ready = ref(false) async function loadAll() { const tasks = Object.entries(dictMap).map(async ([key, meta]) => { data[key] = await loadRemoteDict(key, meta) }) await Promise.all(tasks) ready.value = true } loadAll() function getDictItems(key: string): DictItem[] { return data[key] ?? [] } function getDictLabel(key: string, value: string | number | null | undefined): string { if (value === null || value === undefined || value === '') { return '-' } const item = getDictItems(key).find(it => String(it.value) === String(value)) return item ? item.label : String(value) } function getDictColor(key: string, value: string | number | null | undefined): string { if (value === null || value === undefined) return '' const item = getDictItems(key).find(it => String(it.value) === String(value)) return item?.color ?? '' } return { data, ready, getDictItems, getDictLabel, getDictColor } }这个实现里有几个细节值得单独说明：
- 用
shallowReactive而不是reactive，因为字典数据只做整体替换，不需要深度监听内部对象的属性变化，性能更好； pendingMap解决并发重复请求的问题，两个组件同时在 onMounted 里调同一个接口字典，只会发出一个请求；getDictLabel里用String()统一 value 类型，这是为了避免接口返回"1"而本地定义是数字1时匹配不上，后面第 6 节会展开讲；- 页面销毁后字典数据不会自动清空，因为全局 store 是模块级变量，这是有意为之，让字典在应用生命周期内只加载一次。
3.4 把 useDict 放入模块边界
封装完useDict后，我还建议在src/dict/index.ts里把项目所有字典的 key 统一管理起来，避免在组件里每次手写字符串 key：
// src/dict/index.ts export const DICT = { orderStatus: 'orderStatus', userType: 'userType', gender: 'gender' } as const这样组件里引入DICT.orderStatus，配合 TypeScript 的字符串字面量类型，能减少手写字符串导致的拼写错误——尤其当项目里字典 key 有二十几个的时候，这个习惯能省不少排查时间。
4. 在组件里落地的完整姿势
4.1 给卡片和表格列提供翻译能力
最常见的字典使用场景是列表页表格。假设订单列表接口返回的数据里，每个订单只有status: 2，页面要显示"已发货"。在 Vue3 中我通常这么写：
<script setup lang="ts"> import { useDict } from '@/composables/useDict' import { DICT } from '@/dict' const dict = useDict({ [DICT.orderStatus]: { url: '/api/dict/order-status' } }) </script> <template> <el-table :data="orderList"> <el-table-column label="订单状态"> <template #default="{ row }"> <el-tag :type="dict.getDictColor(DICT.orderStatus, row.status)"> {{ dict.getDictLabel(DICT.orderStatus, row.status) }} </el-tag> </template> </el-table-column> </el-table> </template>这里我故意不在<script setup>里解构dict，而是直接使用dict.getDictLabel。经验是：组合式函数返回的响应式对象如果直接解构，会导致响应式丢失；虽然dict对象本身不会被解构后丢失响应式（因为方法内部访问了data），但为了保持一致的编码习惯，我统一用dict.xxx的姿势，团队新人看了也不会踩坑。
4.2 下拉框和单选组：字典数据直接喂给选项
第二个高频场景是把字典映射为下拉框选项。不管是el-select、el-radio-group，还是原生select，本质都是把字典数组映射成{ label, value }结构。如果后端字段刚好和DictItem结构一致，可以直接用dict.getDictItems得到数组，然后给 UI 组件渲染：
<template> <el-form-item label="订单状态"> <el-select v-model="queryForm.status" clearable placeholder="请选择"> <el-option v-for="item in dict.getDictItems(DICT.orderStatus)" :key="item.value" :label="item.label" :value="item.value" /> </el-select> </el-form-item> </template>有个容易忽略的细节：el-select的value是严格相等比较的，如果你的字典 value 是数字1，但是接口筛选参数传的是字符串"1"，那回显时就会选不中。所以这里要么统一value类型，要么在接口传参前转成字符串，二选一，但要在团队规范里明确写出来。
4.3 标签颜色映射：不只翻译文本，还照顾视觉状态
字典里带上color字段后，可以同步驱动 UI 颜色。我自己常用的做法是：后端字典接口允许配置颜色，前端渲染时直接取color作为 UI 组件的类型参数。这样订单状态是 warning 橙色、成功是绿色，不需要每个页面单独写 v-if 去判断。
不过要留意不同 UI 组件库对颜色类型值的约定不一样，比如 某组件库的el-tag的 type 只能是success / info / warning / danger / primary，如果你的color字段填的是#ff5500，直接传进去会失效。我的处理方式是color字段按组件库规范定义成语义值，而不是十六进制颜色码；如果真的需要自定义色值，就在业务页面上再包一层style绑定，把字典里存的色值直接给到style.color。
4.4 详情页回显：异步字典的顺序问题
还有一个很容易翻车的场景是详情页。详情页从列表页跳转过来，通常只带了一个id和某个状态值，比如orderStatus: 3。页面加载时要根据这个值回显"已完成"。但字典接口是异步的，如果组件刚渲染时字典还没加载完，getDictLabel会先返回3，等字典到了之后才需要更新成"已完成"。
用我们前面封装的useDict不需要额外处理，因为data是响应式的，getDictLabel方法每次执行时读取的都是最新的data；只要模板里绑定的是dict.getDictLabel(...)而不是在初始化时把 label 存到一个普通变量里，字典加载完成后模板会自动更新。
5. 缓存、类型安全与刷新策略
5.1 全局缓存的边界：什么时候该清，什么时候不该清
我在useDict里把字典缓存放到了模块级变量store，这意味着整个应用生命周期内，同一个字典 key 只会被请求一次。这在大多数后台管理系统里是合理的：字典数据变化频率非常低，没有理由每次进页面都重新请求。
但要注意两个例外情况：
- 字典数据由当前用户自己修改（比如用户修改了自己的昵称，性别字段跟着改动）：这种场景要区分"全局字典"和"用户自身属性"，全局字典不需要清；
- 不同角色看到的字典内容不同（比如管理员能看到"删除"状态，普通用户看不到）：这种场景下，缓存不能简单按 key 共享，要把用户标识也拼进 key 里。
我之前在一个权限系统里就踩过第二个坑。A 角色请求的字典有 5 个选项，B 角色登录后因为同一个 key 命中了缓存，导致 B 看不到自己应有的选项。排查半天才发现是缓存 key 没有和角色信息绑定。所以建议：如果字典接口的后端逻辑会随着登录用户不同而返回不同内容，那么loadRemoteDict的缓存 key 要加上用户维度：
async function loadRemoteDict(key: string, meta: DictMeta) { const userId = getCurrentUser()?.id ?? '' const cacheKey = `${userId}:${key}` // ... }5.2 刷新策略：手动刷新就够了，不要搞自动轮询
有人可能会想加"自动刷新"，比如每隔 5 分钟重新拉一次字典接口。我的建议是：能不自动刷新就别自动刷新。字典接口请求量小还好，一旦接口字典多了，定时轮询会给网关造成无意义的压力。更关键的是，字典数据在页面渲染过程中被整体替换，容易引发表格重新渲染的闪烁。
实际项目里，我更倾向于给useDict增加一个refreshDict方法，在明确的业务操作后手动调用。比如字典管理页面里，管理员修改了一个状态名称，然后跳回业务页面，业务页面可以在onMounted里主动调一次刷新。
// 在 useDict 返回值里补充 async function refreshDict(key: string) { delete store[key] data[key] = await loadRemoteDict(key, dictMap[key]) }如果确实需要跨页面自动同步，我听过比较可靠的方案是用 WebSocket 推送字典变更事件，前端收到事件后按 key 清除局部缓存。定时器轮询是效率最低的做法，除非你的字典量小且后端没有推送能力，否则不建议。
5.3 类型安全：让 TypeScript 帮你兜住字典 key
前面提到把字典 key 集中到DICT常量里管理，这一步其实已经能防住大多数拼写错误。再进一步，可以用 TypeScript 的联合类型来约束getDictLabel的 key 参数：
export type DictKey = keyof typeof DICT export function useDict(dictMap: Record<string, DictMeta>) { function getDictLabel(key: DictKey, value: string | number | null | undefined): string { // ... } // ... }这样如果模板里把DICT.orderStatus拼写成DICT.orderStatue，IDE 会在编译阶段报错，而不是等到运行期才发现标签显示成了原始值。对于团队成员较多、词典数量较大的项目，这种保护非常值得加。
6. 几个容易翻车的细节：我的踩坑实录
6.1 value 类型不一致导致"翻译失败"
这是我在项目中遇到频率最高的坑，也是最容易被忽视的。后端接口返回的订单状态是字符串"2"，前端静态字典里定义的是数字2，运行期用全等比较自然匹配不上。我用String()统一转换后，问题迎刃而解。
但要注意一点：统一用String()转换之后，如果你的字典里有两个 value 分别是"01"和1，在String()比较下它们不是同一个值，不会冲突；但如果用宽松相等==，就会有两个匹配项，导致find只会取第一个，这是潜在的 bug。所以我倾向于在字典定义阶段就统一规范：要么全部用数字，要么全部用字符串，不混用。
6.2 异步字典未加载完成时的显示策略
字典接口有延迟，表格已经先渲染出来了，此时getDictLabel返回的是原始 value 如"3"，页面上一片数字，非常难看。我一开始的处理是让getDictLabel在字典未加载完时返回空字符串，结果页面变空白，用户更困惑。后来我调整为：未查到字典项时，直接展示原始值，并配合ready状态来控制是否显示字段。
更实用的做法是给表格外层加一个v-loading或者v-if，等字典ready后再渲染相关列。但如果你不想整页等待，也可以对"字典已加载但找不到对应项"的情况做一个兜底显示，比如灰色问号图标。老实说，大多数后台项目选择整页loading是最省心的。
6.3 全局字典对象被"无意"修改
模块级缓存的store对象是响应式且全局共享的，这在带来便利的同时也带来了一个隐患：组件里如果直接操作dict.data数组，比如不小心对data下的字典数组push了一项，所有页面都会受影响。我在代码评审里见过不止一次这种写法：
dict.data.orderStatus.push({ value: 99, label: '自定义' })这种代码的初衷通常是某个页面有个性化展示需求，结果污染了整个全局字典。我的建议是：对外暴露的getDictItems返回一个新数组副本，或者在内部冻结字典数据：
store[key] = Object.freeze(list)这样别人再想push就会在非生产环境直接报错，提醒他换正确的方式处理。
6.4 字典 label 找不到时不要返回 undefined
最后一个细节看起来小，但影响面很大：getDictLabel找不到对应项时，返回什么？如果返回undefined，在表格里渲染就是一个空单元格，用户完全不知道这个状态值意味着什么。我建议的默认策略是：查不到就返回原始 value，至少用户能看到一个非空值，知道这里有一个"未定义状态"的数据。如果项目里这种脏数据很多，可以再配合日志上报，把"找不到字典项的 key 和 value"反馈到监控平台，方便定位后端脏数据问题。
我在几个后台项目里跑下来最大的感受是：字典方案的核心不是代码怎么写，而是要提前想清楚你的字典数据从哪里来、变化频率多高、会不会按用户区分。方向和边界定清楚了，封装就是水到渠成的事。如果你正在老项目里用全局函数迁移字典逻辑，我建议你花一个下午改成useDict组合式函数，顺手把缓存和类型安全补齐，这个投入换来的长期收益非常值。最后再分享一个小习惯：每次新增一个字典的时候，顺手在DICT常量里登记一次，项目字典再多也不乱。
