Reader

进入官网

           像原生 enum 一样，但更强大！           

简介

enum-plus是一个增强版的枚举类库，完全兼容原生enum的基本用法，同时支持扩展显示文本、绑定到 UI 组件以及提供丰富的扩展方法，是原生enum的一个直接替代品。它是一个轻量级、零依赖、100% TypeScript 实现的工具，适用于多种前端框架，并支持本地化。

枚举项列表可以用来一键生成下拉框、复选框等组件，可以轻松遍历枚举项数组，获取某个枚举值的显示文本，判断某个值是否存在等。支持本地化，可以根据当前语言环境返回对应的文本，轻松满足国际化的需求。

还有哪些令人兴奋的特性呢？请继续探索吧！或者不妨先看下这个使用视频。

特性

• 兼容原生 enum 的用法
• 支持number、string等多种数据类型
• 支持枚举项扩展显示文本
• 支持本地化显示文本，可以使用任意国际化类库
• 支持枚举值转换为显示文本，代码更简洁
• 枚举项支持扩展任意个自定义字段
• 支持将枚举绑定到 Ant Design、ElementPlus、Material-UI 或任意其它组件库，只要一行代码
• 支持 Node.js 环境，支持服务端渲染(SSR)
• 零依赖，纯原生 JavaScript，可以应用在任意前端框架中
• 100% TypeScript 实现，支持类型推断
• 超轻量 (gzip 压缩后仅 1KB+)

安装

npm install enum-plus

枚举定义

构造一个枚举，枚举值支持 number 和 string 两种类型

• 基础用法，与原生枚举用法基本一致

import { Enum } from 'enum-plus';

const Week = Enum({
  Sunday: 0,
  Monday: 1,
} as const);

Week.Monday; // 1

• 【推荐】包含 Key、Value，以及显示文本

import { Enum } from 'enum-plus';

const Week = Enum({
  Sunday: { value: 0, label: '星期日' },
  Monday: { value: 1, label: '星期一' },
} as const);

Week.Sunday; // 0
Week.label(1); // 星期一

• 支持动态数据构建枚举

有时候我们需要使用接口返回的数据，动态创建一个枚举，这时可以采用数组的方式来初始化枚举

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);

• 支持原生枚举初始化，相当于为原生枚举扩展一些方法

import { Enum } from 'enum-plus';

enum init {
  Sunday = 0,
  Monday,
  Tuesday,
  Wednesday,
  Thursday,
  Friday,
  Saturday,
}

const Week = Enum(init);
Week.Sunday; // 0
Week.Monday; // 1
Week.Saturday; // 6
Week.label('Sunday'); // Sunday

API

💎   拾取枚举值       

像原生enum一样，直接拾取一个枚举值

Week.Sunday; // 0
Week.Monday; // 1

💎   items       

获取一个包含全部枚举项的只读数组，可以方便地遍历枚举项。由于符合 Ant Design 组件的数据规范，因此支持将枚举一键转换成下拉框、复选框等组件，只需要一行代码！

💎   keys       

获取一个包含全部枚举项Key的只读数组

💎   label       

  根据某个枚举值或枚举 Key，获取该枚举项的显示文本。如果设置了本地化，则会返回本地化后的文本。

Week.label(1); // 星期一
Week.label('Monday'); // 星期一

💎   key       

  根据枚举值获取该枚举项的 Key，如果不存在则返回undefined

Week.key(1); // 'Monday'

💎   has       

判断某个枚举项（值或 Key）是否存在

Week.has(1); // true
Week.has('Sunday'); // true
Week.has(9); // false
Week.has('Birthday'); // false

💎   toSelect       

toSelect与items相似，都是返回一个包含全部枚举项的数组。区别是，toSelect返回的元素只包含label和value两个字段，同时，toSelect方法支持在数组头部插入一个可自定义的默认元素，一般用于下拉框等组件的默认选项

💎   toMenu       

生成一个对象数组，可以绑定给 Ant Design 的Menu、Dropdown等组件

import { Menu } from 'antd';

<Menu items={Week.toMenu()} />;

数据数据格式为：

[
  { key: 0, label: '星期日' },
  { key: 1, label: '星期一' },
];

💎   toFilter       

生成一个对象数组，可以直接传递给 Ant Design Table 组件的列配置，在表头中显示一个下拉筛选框，用来过滤表格数据

数据数据格式为：

[
  { text: '星期日', value: 0 },
  { text: '星期一', value: 1 },
];

💎   toValueMap       

生成一个符合 Ant Design Pro 规范的枚举集合对象，可以传递给 ProFormField、ProTable 等组件。

数据格式为：

{
  0: { text: '星期日' },
  1: { text: '星期一' },
}

💎   raw       

^{方法重载^1   raw(): Record<K, T[K]>
方法重载^2   raw(keyOrValue: V | K): T[K]}

第一个重载方法，返回枚举集合的初始化对象，即用来初始化 Enum 原始 init 对象。

第二个重载方法，用来处理单个枚举项，根据获取单个枚举项的原始初始化对象。

这个方法主要作用是，用来获取枚举项的自定义字段，支持无限扩展字段

const Week = Enum({
  Sunday: { value: 0, label: '星期日', happy: true },
  Monday: { value: 1, label: '星期一', happy: false },
} as const);

Week.raw(0).happy // true
Week.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这种过于宽泛的类型，提高代码的可读性和类型安全性

const weekValue: typeof Week.valueType = 1;
const weeks: (typeof Week.valueType)[] = [0, 1];
type WeekValues = typeof Week.valueType; // 0 | 1

注意，这只是一个 TypeScript 类型，只能用来约束类型，不可在运行时调用，运行时调用会抛出异常

用法

• 基本用法，与原生枚举用法一致

const Week = Enum({
  Sunday: { value: 0, label: '星期日' },
  Monday: { value: 1, label: '星期一' },
} as const);

Week.Sunday; // 0
Week.Monday; // 1

• 支持为枚举项添加 Jsdoc 注释，代码提示更友好

在代码编辑器中，将光标悬停在枚举项上，即可显示关于该枚举项的详细 Jsdoc 注释，而不必再转到枚举定义处查看

const Week = Enum({
  /** 星期日 */
  Sunday: { value: 0, label: '星期日' },
  /** 星期一 */
  Monday: { value: 1, label: '星期一' },
} as const);

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); // true
Week.items.some(item => item.value === 1); // true
1 instanceof Week; // true

• 支持遍历枚举项数组，但不可修改

Week.items.length; // 2
Week.items.map((item) => item.value); // [0, 1]，✅ 可遍历
Week.items.forEach((item) => {}); // ✅ 可遍历
for (let item of Week.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'); // 星期一

• 枚举值转换为Key

Week.key(1); // 'Monday'
Week.key(Week.Monday); // 'Monday'
Week.key(9); // undefined, 不存在此枚举项

• 添加扩展字段，不限数量

const Week = Enum({
  Sunday: { value: 0, label: '星期日', active: true, disabled: false },
  Monday: { value: 1, label: '星期一', active: false, disabled: true },
} as const);
Week.raw(0).active // true
Week.raw(Week.Sunday).active // true
Week.raw('Sunday').active // true

🔥   转换成 UI 组件

• 生成 Select 下拉框

  • Ant Design | Arco Design Select

  import { Select } from 'antd';
  
  <Select options={Week.items} />;
  

  • Material-UI Select

  import { MenuItem, Select } from '@mui/material';
  
  <Select>
    {Week.items.map((item) => (
      <MenuItem key={item.value} value={item.value}>
        {item.label}
      </MenuItem>
    ))}
  </Select>;
  

  • Kendo UI Select

  import { DropDownList } from '@progress/kendo-react-dropdowns';
  
  <DropDownList data={Week.items} textField="label" dataItemKey="value" />;
  

  • ElementPlus Select

  <el-select>
    <el-option v-for="item in Week.items" v-bind="item" />
  </el-select>
  

  • Ant Design Vue | Arc Design Select

  <a-select :options="Week.items" />
  

  • Vuetify Select

  <v-select :items="Week.items" item-title="label" />
  

  • Angular Material Select

  <mat-select>
    <mat-option *ngFor="let item of Week.items" [value]="item.value">{{ item.label }}</mat-option>
  </mat-select>
  

  • NG-ZORRO Select

  <nz-select>
    <nz-option *ngFor="let item of Week.items" [nzValue]="item.value">{{ item.label }}</nz-option>
  </nz-select>
  

• 生成下拉菜单

toMenu方法可以为 Ant Design Menu、Dropdown 等组件生成数据源，格式为：{ key: number|string, label: string } []

import { Menu } from 'antd';

<Menu items={Week.toMenu()} />;

• 生成表格列筛选

toFilter方法可以生成一个对象数组，为表格绑定列筛选功能，列头中显示一个下拉筛选框，用来过滤表格数据。对象结构遵循 Ant Design 的数据规范，格式为：{ text: string, value: number|string } []

import { Table } from 'antd';

const columns = [
  {
    title: 'week',
    dataIndex: 'week',
    filters: Week.toFilter(),
  },
];
// 在表头中显示下拉筛选项
<Table columns={columns} />;

• 支持 Ant Design Pro 组件生成

toValueMap方法可以为 Ant Design Pro 的ProFormFields、ProTable等组件生成数据源，这是一个类似 Map 的数据结构，格式为：{ [key: number|string]: { text: string } }

import { ProFormSelect, ProFormCheckbox, ProFormRadio, ProFormTreeSelect } from '@ant-design/pro-components';

<ProFormSelect valueEnum={Week.toValueMap()} />; // 下拉框
<ProFormCheckbox valueEnum={Week.toValueMap()} />; // 复选框
<ProFormRadio.Group valueEnum={Week.toValueMap()} />; // 单选框
<ProFormTreeSelect valueEnum={Week.toValueMap()} />; // 树选择

• 枚举合并（或者扩展枚举）

const myWeek = Enum({
  ...Week.raw(),
  Friday: { value: 5, label: '星期五' },
  Saturday: { value: 6, label: '星期六' },
});

• 使用枚举值序列来缩小 number 取值范围   ^{[TypeScript ONLY]}

使用 valueType 类型约束，可以将数据类型从宽泛的number或string类型缩小为有限的枚举值序列，这不但能减少错误赋值的可能性，还能提高代码的可读性

const weekValue: number = 8; // 👎 任意数字都可以赋值给周枚举，即使错误的
const weekName: string = 'Birthday'; // 👎 任意字符串都可以赋值给周枚举，即使错误的

const goodWeekValue: typeof Week.valueType = 1; // ✅ 类型正确，1 是一个有效的枚举值
const goodWeekName: typeof Week.keyType = 'Monday'; // ✅ 类型正确，'Monday' 是一个有效的枚举名

const badWeekValue: typeof Week.valueType = 8; // ❌ 类型报错，8 不是一个有效的枚举值
const badWeekName: typeof Week.keyType = 'Birthday'; // ❌ 类型报错，'Birthday' 不是一个有效的枚举值

type FooProps = {
  value?: typeof Week.valueType; // 👍 组件属性类型约束，可以防止错误赋值，还能智能提示取值范围
  names?: (typeof Week.keyType)[]; // 👍 组件属性类型约束，可以防止错误赋值，还能智能提示取值范围
};

本地化

enum-plus 本身不提供国际化功能，但支持通过设置 localize 可选自定义方法来实现本地化文本。你可以在项目内声明一个本地化方法，把输入的枚举label转换成对应的本地化文本。你需要自己维护语言，并且在 localize 方法中针对当前语言返回对应的文本。如果可能的话，强烈建议你使用一个流行的国际化库，比如 i18next

下面是一个简单的示例。请注意，第一种方式其实并不是很好，因为它不够灵活，仅用于演示基本功能，请考虑使用第二种及后面的示例

import { Enum } from 'enum-plus';
import i18next from 'i18next';
import Localize from './Localize';

let lang = 'zh-CN';
const setLang = (l: string) => {
  lang = l;
};

// 👎 这不是一个好例子，仅供演示，请采用后面其它的方式
const sillyLocalize = (content: string) => {
  if (lang === 'zh-CN') {
    switch (content) {
      case 'enum-plus.options.all':
        return '全部';
      case 'week.sunday':
        return '星期日';
      case 'week.monday':
        return '星期一';
      default:
        return content;
    }
  } else {
    switch (content) {
      case 'enum-plus.options.all':
        return 'All';
      case 'week.sunday':
        return 'Sunday';
      case 'week.monday':
        return 'Monday';
      default:
        return content;
    }
  }
};
// 👍 建议使用 i18next 或其他国际化库
const i18nLocalize = (content: string | undefined) => i18next.t(content);
// 👍 或者封装成一个基础组件
const componentLocalize = (content: string | undefined) => <Localize value={content} />;

const Week = Enum(
  {
    Sunday: { value: 0, label: 'week.sunday' },
    Monday: { value: 1, label: 'week.monday' },
  } as const,
  {
    localize: sillyLocalize,
    // localize: i18nLocalize, // 👍 推荐使用i18类库
    // localize: componentLocalize, // 👍 推荐使用组件形式
  }
);
setLang('zh-CN');
Week.label(1); // 星期一
setLang('en-US');
Week.label(1); // Monday

每个枚举类型都这样设置可能比较繁琐，你也可以通过 Enum.localize 方法来全局设置。如果静态设置和初始化选项两者同时存在，则枚举类型的初始化选项方式优先级更高。

Enum.localize = sillyLocalize;

全局扩展

Enum已经提供了一些常用的方法，但如果这些方法还不能满足你的需求，你可以通过 Enum.extend 方法来添加自定义扩展函数。这些扩展方法将会被添加到所有的枚举类型上，即便是在扩展之前已经创建的枚举类型，也会立即生效

Enum.extend({
  toMySelect(this: ReturnType<typeof Enum>) {
    return this.items.map((item) => ({ value: item.value, title: item.label }));
  },
  reversedItems(this: ReturnType<typeof Enum>) {
    return this.items.reverse();
  },
});

Week.toMySelect(); // [{ value: 0, title: '星期日' }, { value: 1, title: '星期一' }]

兼容性

• 对于浏览器环境，enum-plus 提供了良好的兼容性支持

  • 如果使用现代打包工具（例如 Webpack 5+、Vite、Rollup 等），支持解析 package.json 中的 exports 字段，enum-plus 输出 EcmaScript 版本为 ES2020。另外，如果你希望进一步兼容更低版本的浏览器，你可以在构建时使用 @babel/preset-env 来转换成更低版本的语法

  • 如果是旧版的打包工具（例如 Webpack 4），enum-plus 会自动降级，输出 EcmaScript 版本为 ES2016。

• 对于 Node.js 环境，enum-plus 最低向下兼容到 EcmaScript ES2016，对应 Node.js 版本为 v7.x。

意犹未尽，还期待更多？不妨移步 enum-plus 官网，你可以发现更多的高级使用技巧。相信我，一定会让你感觉相见恨晚！