enum-plus：前端福利！介绍一个天花板级的前端枚举库 （金石计划倒计时Ⅱ天，2篇原创推荐好文即可瓜分现金??）简介enum-plus是一个增强版的枚举类库，完全兼容原生enum的基本用法，同时支持扩展显示文本、绑定到 UI 组件以及提供丰富的扩展方法，是原生enum的一个直接替代品。它是一个轻量级、零依赖、100% TypeScript 实现的工具，适用于多种前端框架，并支持本地化。 枚举项列表可以用来一键生成下拉框、复选框等组件，可以轻松遍历枚举项数组，获取某个枚举值的显示文本，判断某个值是否存在等。支持本地化，可以根据当前语言环境返回对应的文本，轻松满足国际化的需求。 还有哪些令人兴奋的特性呢？请继续探索吧！或者不妨先看下这个使用视频。 特性完全兼容原生enum的用法支持number、string等多种数据类型增强的枚举项，支持自定义显示文本内置本地化能力，枚举项文本可实现国际化，可与任何 i18n 库集成支持枚举值转换为显示文本，代码更简洁可扩展设计，允许在枚举项上添加自定义字段支持将枚举绑定到Ant Design[1]、ElementPlus[2]、Material-UI[3]等 UI 库，一行代码枚举变下拉框支持 Node.js 环境，支持服务端渲染 (SSR)零依赖，纯原生 JavaScript，可用于任何前端框架100% TypeScript 实现，具有全面的类型推断能力轻量 (gzip 压缩后仅 2KB+)安装npm installenum-plus枚举定义本节展示了使用Enum函数初始化枚举的多种方式，你可以根据不同的使用场景选择最合适的方法 1. 基础格式，与原生枚举用法基本一致import { Enum }from'enum-plus'; constWeek=Enum({ Sunday:0, Monday:1,}asconst); Week.Monday;// 1?as const类型断言用于将枚举值变成字面量类型，类型更精确，否则它们将被作为number类型。如果你使用的是 JavaScript，请删除as const ?2. 标准格式（推荐）为每个枚举项指定value(枚举值) 和label（显示文本）字段，这是最常用的格式，也是推荐的格式。这种格式允许你为每个枚举项设置显示文本，这些文本可以在 UI 组件中使用 import { Enum }from'enum-plus'; constWeek=Enum({ Sunday: {value:0,label:'星期日'}, Monday: {value:1,label:'星期一'},}asconst); Week.Sunday;// 0Week.label(0);// 星期日3. 数组格式数组格式在需要动态创建枚举时很有用，例如从 API 获取数据中动态创建一个枚举。这种方式还允许自定义字段映射，这增加了灵活性，可以适配不同的数据格式 import { Enum } from'enum-plus'; const petTypes = await getPetsData();//[ { value:1, key:'dog', label:'狗'},// { value:2, key:'cat', label:'猫'},// { value:3, key:'rabbit', label:'兔子'} const PetTypes = Enum(petTypes);4. 原生枚举格式如果你已经有一个原生的枚举，你可以直接传递给Enum函数，它会自动转换为增强版的枚举，这样可以借用原生枚举的枚举值自动递增特性 import { Enum }from'enum-plus'; enuminit{ Sunday =0, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday,}constWeek = Enum(init); Week.Sunday;// 0Week.Monday;// 1Week.Saturday;// 6Week.label('Sunday');// SundayAPI??拾取枚举值像原生enum一样，直接拾取一个枚举值 Week.Sunday;// 0Week.Monday;// 1??items获取一个包含全部枚举项的只读数组，可以方便地遍历枚举项。由于符合Ant Design[5]组件的数据规范，因此支持将枚举一键转换成下拉框、复选框等组件，只需要一行代码！ ??keys获取一个包含全部枚举项Key的只读数组 ??label根据某个枚举值或枚举 Key，获取该枚举项的显示文本。如果设置了本地化，则会返回本地化后的文本。 Week.label(1);// 星期一Week.label('Monday');// 星期一??key根据枚举值获取该枚举项的 Key，如果不存在则返回undefined Week.key(1);//'Monday'??has判断某个枚举项（值或 Key）是否存在 Week.has(1);//trueWeek.has('Sunday');//trueWeek.has(9);//falseWeek.has('Birthday');//false??toSelecttoSelect与items相似，都是返回一个包含全部枚举项的数组。区别是，toSelect返回的元素只包含label和value两个字段，同时，toSelect方法支持在数组头部插入一个可自定义的默认元素，一般用于下拉框等组件的默认选项 ??toMenu生成一个对象数组，可以绑定给Ant Design[6]的Menu、Dropdown等组件 import{Menu}from'antd'; Menuitems={Week.toMenu()}/;数据数据格式为： [ {key:0,label:'星期日'}, {key:1,label:'星期一'},];??toFilter生成一个对象数组，可以直接传递给Ant Design[7]Table 组件的列配置，在表头中显示一个下拉筛选框，用来过滤表格数据 数据数据格式为： [ {text:'星期日',value:0}, {text:'星期一',value:1},];??toValueMap生成一个符合Ant Design Pro[8]规范的枚举集合对象，可以传递给ProFormField、ProTable等组件。 数据格式为： {0: { text:'星期日'},1: { text:'星期一'},}??raw「方法重载 ^1」 raw(): RecordK, T[K] 「方法重载 ^2」 raw(keyOrValue: V | K): T[K] 第一个重载方法，返回枚举集合的初始化对象，即用来初始化 Enum 原始 init 对象。 第二个重载方法，用来处理单个枚举项，根据获取单个枚举项的原始初始化对象。 这个方法主要作用是，用来获取枚举项的自定义字段，支持无限扩展字段 constWeek=Enum({ Sunday: {value:0,label:'星期日',happy:true}, Monday: {value:1,label:'星期一',happy:false},}asconst); Week.raw(0).happy// trueWeek.raw(0);// { value: 0, label: '星期日', happy: true }Week.raw('Monday');// { value: 1, label: '星期一', happy: false }Week.raw();// { Sunday: { value: 0, label: '星期日', happy: true }, Monday: { value: 1, label: '星期一', happy: false } }??valueType_「TypeScript ONLY」_在 TypeScript 中，提供了一个包含所有枚举值的联合类型，用于缩小变量或组件属性的数据类型。这种类型替代了像number或string这样宽泛的原始类型，使用精确的值集合，防止无效赋值，同时提高代码可读性和编译时类型安全性。 typeWeekValues=typeofWeek.valueType;// 0 | 1 constweekValue:typeofWeek.valueType=1;// ? 类型正确，1 是一个有效的周枚举值constweeks: (typeofWeek.valueType)[] = [0,1];// ? 类型正确，0 和 1 是有效的周枚举值constbadWeekValue:typeofWeek.valueType=8;// ? 类型错误，8 不是一个有效的周枚举值constbadWeeks: (typeofWeek.valueType)[] = [0,8];// ? 类型错误，8 不是一个有效的周枚举值?注意，这只是一个 TypeScript 类型，只能用来约束类型，不可在运行时调用，运行时调用会抛出异常 ?用法? 基本用法，与原生枚举用法一致constWeek=Enum({ Sunday: {value:0,label:'星期日'}, Monday: {value:1,label:'星期一'},}asconst); Week.Sunday;// 0Week.Monday;// 1? 支持为枚举项添加 Jsdoc 注释，代码提示更友好在代码编辑器中，将光标悬停在枚举项上，即可显示关于该枚举项的详细 Jsdoc 注释，而不必再转到枚举定义处查看 constWeek=Enum({/** 星期日 */ Sunday: {value:0,label:'星期日'},/** 星期一 */ Monday: {value:1,label:'星期一'},}asconst); Week.Monday;// 将光标悬浮在 Monday 上可以看到，不但提示了枚举项的释义，还有枚举项的值，无需跳转离开当前光标位置，在阅读代码时非常方便 ? 获取包含全部枚举项的数组Week.items; // 输出如下:// [// { value:0, label:'星期日', key:'Sunday', raw: { value:0, label:'星期日'} },// { value:1, label:'星期一', key:'Monday', raw: { value:1, label:'星期一'} }// ]? 获取第一个枚举值Week.items[0].value; //0? 检查一个值是否一个有效的枚举值Week.has(1);//trueWeek.items.some(item = item.value ===1);//true1instanceofWeek;//true? 支持遍历枚举项数组，但不可修改Week.items.length;// 2Week.items.map((item) =item.value);// [0, 1]，? 可遍历Week.items.forEach((item) =// ? 可遍历for(constitemofWeek.items) {// ? 可遍历}Week.items.push({value:2,label:'星期二'// ? 不可修改Week.items.splice(0,1);// ? 不可修改Week.items[0].label='foo';// ? 不可修改? 枚举值 (或 Key) 转换为显示文本Week.label(1);// 星期一，Week.label(Week.Monday);// 星期一Week.label('Monday');// 星期一? 枚举值转换为 KeyWeek.key(1);//'Monday'Week.key(Week.Monday);//'Monday'Week.key(9);//undefined, 不存在此枚举项? 添加扩展字段，不限数量constWeek=Enum({ Sunday: {value:0,label:'星期日',active:true,disabled:false}, Monday: {value:1,label:'星期一',active:false,disabled:true},}asconst); Week.raw(0).active// trueWeek.raw(Week.Sunday).active// trueWeek.raw('Sunday').active// true?? 转换成 UI 组件生成 Select 下拉框 Ant Design|Arco DesignSelectimport{Select}from'antd'; Selectoptions={Week.items}/;Material-UISelectimport{MenuItem,Select}from'@mui/material'; Select {Week.items.map((item) = ( MenuItemkey={item.value}value={item.value} {item.label} /MenuItem ))}/Select; Kendo UISelectimport{DropDownList}from'@progress/kendo-react-dropdowns'; DropDownListdata={Week.items}textField="label"dataItemKey="value"/;ElementPlusSelectel-selectel-optionv-for="item in Week.items"v-bind="item"//el-selectAnt Design Vue|Arc DesignSelecta-select:options="Week.items"/VuetifySelectv-select:items="Week.items"item-title="label"/Angular MaterialSelectmat-selectmat-option*ngFor="let item of Week.items"[value]="item.value"{{ item.label }}/mat-option/mat-selectNG-ZORROSelectnz-select nz-option*ngFor="let item of Week.items"[nzValue]="item.value"{{ item.label }}/nz-option/nz-select生成下拉菜单toMenu方法可以为Ant Design[19]Menu、Dropdown等组件生成数据源，格式为：{ key: number|string, label: string } [] import{Menu}from'antd'; Menuitems={Week.toMenu()}/;生成表格列筛选toFilter方法可以生成一个对象数组，为表格绑定列筛选功能，列头中显示一个下拉筛选框，用来过滤表格数据。对象结构遵循Ant Design[20]的数据规范，格式为：{ text: string, value: number|string } [] import{Table}from'antd'; constcolumns = [ { title:'week', dataIndex:'week', filters:Week.toFilter(), },];// 在表头中显示下拉筛选项Tablecolumns={columns}/;支持 Ant Design Pro 组件生成toValueMap方法可以为Ant Design Pro[21]的ProFormFields、ProTable等组件生成数据源，这是一个类似 Map 的数据结构，格式为：{ [key: number|string]: { text: string } } import{ProFormSelect,ProFormCheckbox,ProFormRadio,ProFormTreeSelect,ProTable}from'@ant-design/pro-components'; ProFormSelectvalueEnum={Week.toValueMap()}/;// 下拉框ProFormCheckboxvalueEnum={Week.toValueMap()}/;// 复选框ProFormRadio.GroupvalueEnum={Week.toValueMap()}/;// 单选框ProFormTreeSelectvalueEnum={Week.toValueMap()}/;// 树选择ProTablecolumns={[{dataIndex:'week',valueEnum:Week.toValueMap() }]} /;// ProTable? 枚举合并（或者扩展枚举）constmyWeek=Enum({ ...Week.raw(), Friday: {value:5,label:'星期五'}, Saturday: {value:6,label:'星期六'},});? 使用枚举值序列来缩小number取值范围 [TypeScript ONLY]使用valueType类型约束，可以将数据类型从宽泛的number或string类型缩小为有限的枚举值序列，这不但能减少错误赋值的可能性，还能提高代码的可读性 constweekValue:number=8;// ?? 任意数字都可以赋值给周枚举，即使错误的constweekName:string='Birthday';// ?? 任意字符串都可以赋值给周枚举，即使错误的 constgoodWeekValue:typeofWeek.valueType=1;// ? 类型正确，1 是一个有效的枚举值constgoodWeekName:typeofWeek.keyType='Monday';// ? 类型正确，'Monday' 是一个有效的枚举名 constbadWeekValue:typeofWeek.valueType=8;// ? 类型报错，8 不是一个有效的枚举值constbadWeekName:typeofWeek.keyType='Birthday';// ? 类型报错，'Birthday' 不是一个有效的枚举值 typeFooProps= { value?:typeofWeek.valueType;// ?? 组件属性类型约束，可以防止错误赋值，还能智能提示取值范围 names?: (typeofWeek.keyType)[];// ?? 组件属性类型约束，可以防止错误赋值，还能智能提示取值范围};本地化enum-plus本身不内置国际化能力，但支持通过localize可选参数传入一个自定义方法，来实现本地化文本的转化。这是一个非常灵活的方案，这使你能够实现自定义的本地化函数，根据当前的语言环境将枚举的label值转换为适当的翻译文本。语言状态管理仍由您自己负责，您的localize方法决定返回哪种本地化文本。对于生产环境的应用程序，我们强烈建议使用成熟的国际化库（如 i18next），而不是创建自定义解决方案。 以下是一个简单的示例，仅供参考。请注意，第一种方法由于缺乏灵活性，不建议在生产环境中使用，它仅用于演示基本概念。请考虑使用第二种及后面的示例。 import{Enum}from'enum-plus';importi18nextfrom'i18next';importLocalizefrom'./Localize'; letlang ='zh-CN';constsetLang= (l:string) = { lang = l;}; // ?? 这不是一个好例子，仅供演示，不建议生产环境使用constsillyLocalize= (content:string) = {if(lang ==='zh-CN') { switch(content) { case'enum-plus.options.all': return'全部'; case'week.sunday': return'星期日'; case'week.monday': return'星期一'; default: returncontent; } }else{ switch(content) { case'enum-plus.options.all': return'All'; case'week.sunday': return'Sunday'; case'week.monday': return'Monday'; default: returncontent; } }};// ?? 建议使用 i18next 或其他国际化库consti18nLocalize= (content:string|undefined) = i18next.t(content);// ?? 或者封装成一个基础组件constcomponentLocalize= (content:string|undefined) =Localizevalue={content}/; constWeek=Enum( { Sunday: {value:0,label:'week.sunday'}, Monday: {value:1,label:'week.monday'}, }asconst, { localize: sillyLocalize, // localize: i18nLocalize, // ?? 推荐使用i18类库 // localize: componentLocalize, // ?? 推荐使用组件形式 });setLang('zh-CN');Week.label(1);// 星期一setLang('en-US');Week.label(1);// Monday当然，每个枚举类型都这样设置可能比较繁琐，enum-plus提供了一种全局设置方案，可以通过Enum.localize全局方法，来全局设置本地化。如果两者同时存在，单个枚举的设置会覆盖全局设置。 Enum.localize= i18nLocalize;全局扩展虽然Enum提供了一套全面的内置方法，但如果这些还不能满足你的需求，你可以使用Enum.extendsAPI 扩展其功能，添加自定义方法。这些扩展会全局应用于所有枚举实例，包括在扩展应用之前创建的实例，并且会立即生效，无需任何其它设置。 Enum.extends({toMySelect(this: ReturnTypetypeofEnum) { returnthis.items.map((item) =({value: item.value,title: item.label },reversedItems(this: ReturnTypetypeofEnum) { returnthis.items.reverse(); },}); Week.toMySelect();// [{ value: 0, title: '星期日' }, { value: 1, title: '星期一' }]兼容性enum-plus 提供了完善的兼容性支持。 「浏览器环境」： core-js配置适当的@babel/preset-env和useBuiltIns设置其他替代的 polyfill 实现「现代打包工具」：对于支持exports[22]字段的打包工具（如 Webpack 5+、Vite、Rollup），enum-plus 的目标是「ES2020」。如果需要更广泛的浏览器支持，可以在构建过程中使用@babel/preset-env转译为更早期的语法。 「旧版打包工具」：对于不支持exports字段的工具（如 Webpack 4），enum-plus 会自动回退到main字段的入口点，其目标是「ES2016」。 「Polyfill 策略」：为了最小化包的体积，enum-plus 不包含任何 polyfill。如果需要支持旧版浏览器，可以引入以下内容： 「Node.js 兼容性」：enum-plus 需要至少「ES2016」的特性，兼容 Node.jsv7.x及以上版本。 意犹未尽，还期待更多？不妨移步Github 官网[23]，你可以发现更多的高级使用技巧。 相信我，一定会让你感觉相见恨晚！ 如果你喜欢这个项目，欢迎在 GitHub 上给项目点个 Star? —— 这是程序员表达喜爱的通用语言??～ 可以让更多开发者发现它！ 关注更多AI编程资讯请去AI Coding专区：https://juejin.cn/aicoding 点击"阅读原文"了解详情~ 阅读原文