在长期维护中后台业务的过程中，我发现‘硬编码’的状态逻辑是导致代码劣化的主因。有了 local-dict 这个工具，不仅是为了简化模板中的条件判断，更是为了利用 TypeScript 的类型推导能力，为前端业务字典建立一套‘定义即类型，配置即驱动’的标准流，从而实现业务语义与工程逻辑的深度解耦。
在前端业务开发中，你是否经常被这种代码折磨：
- 满屏魔术数字：
if (status === 1)—— 这个1到底是谁？ - 反查 Label 靠手写：
list.find(i => i.val === v)?.label—— 逻辑重复，满屏undefined风险。 - 重构如排雷：后端改了个状态值，你得全项目搜索字符串，生怕漏改一处导致事故。
1. 为什么不直接用 enum？
很多同学问：用原生的enum或者const Object不行吗？看下对比就知道了：
| 对比项 | 原生 enum / Object | local-dict |
|---|---|---|
| Label 支持 | 需手动维护额外 Map | 定义即绑定，一行获取 |
| 扩展属性 | 难以挂载颜色、图标等 UI 属性 | 原生支持，且具备完整的 IDE 类型提示 |
| 类型推导 | 弱，需手动写断言 | 强类型约束，支持自动推导联合类型 |
| 运行时能力 | 转换 List 或反查逻辑繁琐 | 高度集成，提供标准化的 API 调用 |
2. 适用场景
- 业务状态字典：如订单状态、支付类型等。
- 枚举 + UI 映射：状态与颜色、图标、国际化 Key 绑定。
- 表单选项：快速生成 Select、Radio 的数据源。
- 中后台系统：对代码健壮性和可维护性要求极高的项目。
- 对 TS 类型质量有追求：不想在项目中到处写
as any。
3. 快速开始
1. 安装依赖
npm install local-dict2. 创建字典
import { createLocalDict } from 'local-dict'; const STATUS = createLocalDict({ SUCCESS: { label: '成功', value: 1, type: 'success' }, FAIL: { label: '失败', value: 2, type: 'danger' }, UNKNOWN: { label: '未知', value: -1, type: 'info' } });4. 用法
4.1 基础调用
// 获取原始 Value STATUS.SUCCESS.getValue(); // 1 // 获取展示 Label STATUS.SUCCESS.getLabel(); // '成功' // 获取条目在原始数组中的索引 STATUS.SUCCESS.getIndex(); // 0 // 将接口字段转换为中文 STATUS.getLabel4Value(status) // 具体label // 获取标准格式，适合 Select 或 Radio 组件。 STATUS.getList() // [{ label: '成功', value: 1, type: 'green' }, ...]4.2 包含判断与类型收窄
// 如果status被命中，则status的类型会缩小为 STATUS.SUCCESS.getValue() | STATUS.FAIL.getValue() if (STATUS.includes(status, [STATUS.SUCCESS.getValue(), STATUS.FAIL.getValue()])) { // TODO } else {}4.3 属性扩展：自定义业务字段
// 很多时候需要自定义字段，比如ui渲染为tag，每个状态对应不同的字体、背景颜色 // 获取 status 的的颜色 STATUS.getItemMap().get(status)?.type // success | danger | info | undefined5. 实操(diff)
- 根据 row.status 渲染标签, 不再写一堆 v-if 判断
<el-table> <el-table-column label="状态"> <template #default="{ row }"> - <el-tag v-if="row.status === 1" type="success">成功</el-tag> - <el-tag v-else-if="row.status === 2" type="danger">失败</el-tag> - <el-tag v-else type="info">未知</el-tag> + <el-tag :type="STATUS.getItemMap().get(row.status)?.type"> + {{ STATUS.getLabel4Value(row.status) }} + </el-tag> </template> </el-table-column> </el-table>- 获取列表渲染，适合 Select 或 Radio 组件的绑定数据
<el-select v-model="formData.status"> <el-option - v-for="item in options" + v-for="item in STATUS.getList()" :key="item.value" :label="item.label" :value="item.value"> </el-option> </el-select>- 操作按钮显隐
如果是多个状态都可以显示，不要使用 [STATUS.SUCCESS.getValue()].includes(row.status) 判断,需要使用STATUS.includes(row.status, [STATUS.SUCCESS.getValue()]), 因为 includes 类型收窄原因, 会导致 ts 报错
// 单个状态判断 <div> - <el-button v-if="row.status == 2" type="success">完成</el-button> + <el-button v-if="row.status == STATUS.SUCCESS.getValue()" type="success">完成</el-button> </div> // 多个状态判断 <div> - <el-button v-if="[1, 2].includes(row.status)" type="success">完成</el-button> + <el-button v-if="STATUS.includes(row.status, [STATUS.SUCCESS.getValue(), STATUS.FAIL.getValue()])" type="success">完成</el-button> </div>6. 扩展
如果需要在type/interface申明字段类型，直接通过字面量/string | number ... 的方式是不好维护的，local-dict这个版本还没有实现，可以通过下面DictValues来推断value的联合类型。
import type { DictInstance, DictValueOf } from 'local-dict' type DictValues<S> = S extends DictInstance<infer T> ? DictValueOf<T> : never; //用法： interface Vo { status: DictValues<typeof STATUS>; // 1 | 2 | -1 }
