🔥 enum-plus 3.0：介绍一个天花板级的前端枚举库

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

🎉 v3.0 发布了！

这是一个重大的里程碑版本升级，带来了很多令人兴奋的功能和改进。请查看发行公告了解包含哪些变化。如果你认为这个项目有帮助，请在 GitHub 上给它一个 ⭐️星标。

简介

enum-plus 是一个增强版的枚举类库，完全兼容原生enum的用法，是原生枚举的直接替代品。支持为枚举项添加显示名称，以及添加自定义元数据字段。可以用枚举直接生成下拉框、多选框、菜单、选项卡等各种 UI 控件，对前端工程师非常实用。

为枚举增加了很多扩展方法，支持对枚举项数组的遍历和各种数据转换。你可以把数值转换为多种语言的枚举名称，因为它支持国际化，这在 UI 回显业务数据时非常有用。

这是一个轻量级、零依赖、100% TypeScript 实现的工具库，适用于任何前端框架，包括无框架的纯原生应用。

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

特性

完全兼容原生 enum 的用法
支持number、string等多种数据类型
枚举项支持设置显示名称
支持国际化，可与任何 i18n 库集成
快速将值转换为显示名称，在 UI 回显时非常有用
枚举项支持扩展元数据字段，可以作为静态配置系统使用
支持插件体系，可以通过安装插件扩展枚举功能
支持数据类型约束，提高代码的类型安全性^* TypeScript*^
枚举可以生成下拉框等 UI 组件，支持 Ant Design、Element Plus、Material-UI 等多种组件库
支持 Web浏览器、Node.js、React Native、Taro、小程序等多种环境
支持服务端渲染 (SSR)
兼容任何前端开发框架，支持无框架的纯原生项目
面向 TypeScript 设计，具有良好的类型推导和代码补全能力
零依赖项
轻量（gzip压缩后仅2KB+）

安装

npm 安装

bash 复制代码

npm install enum-plus

浏览器中运行

html 复制代码

<!-- 兼容 ES2020 的现代版本 -->
<script src="https://cdn.jsdelivr.net/npm/enum-plus/umd/enum-plus.min.js"></script>
<!-- 兼容 ES2015 的早期版本 -->
<script src="https://cdn.jsdelivr.net/npm/enum-plus/umd/enum-plus-legacy.min.js"></script>

枚举定义

本节展示了使用 Enum 函数初始化枚举的多种方式，你可以根据不同的使用场景选择最合适的方法。

1. Key-Value 格式

js 复制代码

import { Enum } from 'enum-plus';

// Number 类型
const WeekEnum = Enum({
  Sunday: 0,
  Monday: 1,
});

WeekEnum.Monday; // 1

// String 类型
const WeekEnum2 = Enum({
  Sunday: 'Sun',
  Monday: 'Mon',
});

WeekEnum2.Monday; // 'Mon'

如果你的项目使用 TypeScript 且版本低于 5.0，那么建议你为 Enum 方法的参数添加 as const 类型断言，这样枚举值将保持原始的字面量值，而不会变成number、string类型。关于更多详情，请参考这里。

2. 标准格式（推荐）

为每个枚举项指定 value (枚举值) 和 label（显示名称）字段，这是最常用的格式，也是推荐的格式。这种格式允许你为每个枚举项设置显示名称，这些文本可以在 UI 组件中使用。关于为 label 字段启用本地化支持，请参考本地化章节。

js 复制代码

import { Enum } from 'enum-plus';

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

WeekEnum.Sunday; // 0
WeekEnum.items[0].key; // 'Sunday'
WeekEnum.items[0].label; // 星期日

3. 数组格式

数组格式在需要动态创建枚举时很有用，例如从 API 获取数据中动态创建一个枚举。你可以动态映射字段以适应各种不同的数据结构。请参考数组格式初始化，设置不同的字段映射章节，了解更多详情。

js 复制代码

import { Enum } from 'enum-plus';

const pets = [
  { value: 1, key: 'Dog', label: '可爱的小狗' },
  { value: 2, key: 'Cat', label: '萌萌的小猫' },
  { value: 3, key: 'Rabbit', label: '白白的小兔' },
];
const PetEnum = Enum(pets);

PetEnum.Dog; // 1
PetEnum.label(1); // 可爱的小狗

4. 原生枚举格式

如果你已经有一个原生的枚举，你可以直接传递给Enum函数，它会自动转换为增强版的枚举，这样可以借用原生枚举的枚举值自动递增特性

ts 复制代码

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

API

💎 拾取枚举值

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

js 复制代码

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

💎 named

一个聚合了所有枚举项的只读对象，可以通过key来快速访问某个枚举项对象。

js 复制代码

WeekEnum.named.Monday; // { key: 'Monday', value: 1, label: '星期一' }

💎 items

获取一个包含全部枚举项的只读数组，可以方便地遍历枚举项。

js 复制代码

WeekEnum.items; // [ { value: 0, label: '星期日', key: 'Sunday' }, { value: 1, label: '星期一', key: 'Monday' }, ... ]

💎 values

获取一个包含全部枚举项value的数组

js 复制代码

WeekEnum.values; // [0, 1, 2, 3, 4, 5, 6]

💎 labels

获取一个包含全部枚举项label的数组

js 复制代码

WeekEnum.labels; // ['星期日', '星期一', ... '星期五', '星期六']

💎 keys

获取一个包含全部枚举项key的数组

js 复制代码

WeekEnum.keys; // ['Sunday', 'Monday', ... 'Friday', 'Saturday']

💎 meta

获取一个包含全部枚举项自定义字段的聚合对象，键是字段名，值是该字段的所有枚举项值的数组，这样可以在不遍历枚举项的情况下访问自定义字段。

js 复制代码

const ColorEnum = Enum({
  Red: { value: 1, label: '红色', hex: '#FF0000' },
  Green: { value: 2, label: '绿色', hex: '#00FF00' },
  Blue: { value: 3, label: '蓝色', hex: '#0000FF' },
});
ColorEnum.meta.hex; // ['#FF0000', '#00FF00', '#0000FF']

顺便一提，你可以通过 named 和 raw 属性快速访问单个枚举项的自定义字段

js 复制代码

ColorEnum.named.Red.raw.hex; // '#FF0000'

💎 has ^方法

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

js 复制代码

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

💎 findBy ^方法

根据指定字段和字段值，获取枚举项对象，如果不存在则返回undefined

字段名支持：key、value、label或元数据字段

js 复制代码

ColorEnum.findBy('value', 1); // { key: 'Red', value: 1, label: '红色', hex: '#FF0000' }
ColorEnum.findBy('key', 'Red'); // { key: 'Red', value: 1, label: '红色', hex: '#FF0000' }
ColorEnum.findBy('hex', '#FF0000'); // { key: 'Red', value: 1, label: '红色', hex: '#FF0000' }

💎 label ^方法

根据某个枚举值或枚举 key，获取该枚举项的显示名称。如果启用了本地化，则会返回当前语言的内容。

js 复制代码

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

💎 key ^方法

根据枚举值获取该枚举项的key，这也被称为反向映射。如果不存在则返回undefined

js 复制代码

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

💎 toList ^方法

将枚举转换为一个默认包含value和label字段的数组，或者通过options参数自定义字段名。

js 复制代码

WeekEnum.toList();
// [
//   { value: 0, label: '星期日' },
//   { value: 1, label: '星期一' },
//   ...
//   { value: 6, label: '星期六' }
// ]
WeekEnum.toList({ valueField: 'id', labelField: 'name' });
// [
//   { id: 0, name: '星期日' },
//   { id: 1, name: '星期一' },
//   ...
//   { id: 6, name: '星期六' }
// ]

💎 toMap ^方法

js 复制代码

WeekEnum.toMap();
// {
//   "0": '星期日',
//   "1": '星期一',
//   ...
//   "6": '星期六'
// }
WeekEnum.toMap({ keySelector: 'key', valueSelector: 'value' });
// {
//   "Sunday": 0,
//   "Monday": 1,
//   ...
//   "Saturday": 6
// }

💎 raw ^方法

raw方法有两种重载形式。第一种是返回整个枚举集合的原始初始化对象，即Enum方法的第一个参数。

第二种是返回单个枚举项的原始初始化对象，即Enum方法的第一个参数中对应字段的子对象。

这个方法主要作用是，用来获取枚举项的自定义字段。

js 复制代码

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

WeekEnum.raw(0).happy; // true
WeekEnum.raw(0); // { value: 0, label: '星期日', happy: true }
WeekEnum.raw('Monday'); // { value: 1, label: '星期一', happy: false }
WeekEnum.raw(); // { Sunday: { value: 0, label: '星期日', happy: true }, Monday: { value: 1, label: '星期一', happy: false } }

温馨提示：如果要获取某个已知枚举项的元数据字段，使用enum.named.XXX.raw 是一个不错的选择。

💎 name

获取整个枚举集合的显示名称。可以在创建枚举时，通过传入一个可选的 name 参数来为枚举类型命名。这个名称可以是一个普通字符串，也可以是一个本地化键值，以支持国际化文本。请参考本地化章节，了解更多详情。

js 复制代码

const WeekEnum = Enum(
  {
    Sunday: { value: 0, label: '星期日' },
    Monday: { value: 1, label: '星期一' },
  },
  {
    name: 'i18n.enums.week', // 可以普通字符串或者一个本地化键值
  }
);

WeekEnum.name; // Week 或 周，取决于当前语言

在 UI 组件中，枚举通常用来作为数据源，生成下拉框表单项，或在表格单元格中显示枚举成员文本。而对应的表单项标签或列标题就是枚举类型的名称。通过使用name，我们可以集中管理枚举名称，和枚举成员的名称，也更方便使用。

⚡️ valueType ^TypeScript Only^

在 TypeScript 中，提供了一个包含所有枚举值的联合类型，用于缩小变量或组件属性的数据类型。这种类型替代了像 number 或 string 这样宽泛的原始类型，使用精确的值集合，防止无效赋值，同时提高代码可读性和编译时类型安全性。

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

ts 复制代码

const weekValue: typeof WeekEnum.valueType = 1;

function setToday(day: typeof WeekEnum.valueType) {
  // ...
}

const MyComponent = (props: { day: typeof WeekEnum.valueType }) => {
  // ...
};

静态方法

💎 Enum.isEnum ^方法

判断一个对象是否是一个由Enum函数创建的枚举对象

js 复制代码

Enum.isEnum(WeekEnum); // true
Enum.isEnum({}); // false

💎 Enum.localize ^方法

设置全局的本地化函数，用来处理枚举类型名称和枚举项显示名称的本地化。请参考本地化章节，了解更多详情。

js 复制代码

import i18n from 'i18next';

Enum.localize = (key) => i18n.t(key);

💎 Enum.extends ^方法

为所有枚举对象添加全局扩展方法，请参考全局扩展章节，了解更多详情。

js 复制代码

Enum.extends({
  sayHello() {
    return `你好，EnumPlus!`;
  },
});

💎 Enum.install ^方法

安装一个插件，插件可以为所有枚举添加新的功能。请参考插件系统章节，了解更多详情。

js 复制代码

import i18nextPlugin from '@enum-plus/plugin-i18next';

Enum.install(i18nextPlugin);

应用案例

💡 基础用法，消除魔法数字

js 复制代码

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

if (today === WeekEnum.Sunday) {
  // 今天是星期天，享受你的一天吧！
} else if (today === WeekEnum.Monday) {
  // 哦不，又是星期一了...
}

💡 检查是否一个有效的枚举值

js 复制代码

if (WeekEnum.has(value)) {
  // 是一个有效的枚举值，可以安全使用
} else {
  // 抛出异常或使用默认值
}

💡 检查是否一个枚举对象

ts 复制代码

let values: number[] | undefined;
if (Enum.isEnum(data)) {
  values = data.values;
} else if (Array.isArray(data)) {
  values = data;
} else {
  // 非法输入，抛出异常或使用默认值
}

💡 生成 UI 组件

以 React + Ant Design 为例，更多 UI 组件的案例请参考支持多种前端框架章节

jsx 复制代码

import { Menu, Select, Table } from 'antd';
import { ProFormCheckbox, ProFormSelect } from '@ant-design/pro-components';

const App = () => {
  return (
    <>
      <Select options={WeekEnum.items} />
      <Menu items={WeekEnum.toMenu()} />
      <Table columns={[{ filters: WeekEnum.toFilter() }]} />
      <ProFormSelect valueEnum={WeekEnum.toValueMap()} />
      <ProFormCheckbox valueEnum={WeekEnum.toValueMap()} />
    </>
  );
};

需要安装 @enum-plus/plugin-antd 插件

💡 枚举名称/标签支持国际化

可以支持多语言环境，将label字段设置为一个本地化键值，根据当前语言环境显示对应的文本。请参考本地化章节，了解更多详情。

js 复制代码

WeekEnum.label(1); // Monday 或 星期一，取决于当前语言环境
WeekEnum.named.Monday.label; // Monday 或 星期一，取决于当前语言环境
WeekEnum.name; // Week 或 周，取决于当前语言环境

💡 约束数据类型 (仅 TypeScript)

这是一个 TypeScript 特有的特性，可以使用 valueType 约束变量、方法参数或组件属性的类型，防止无效赋值，提高代码的类型安全性。

变量

ts 复制代码

type WeekValues = typeof WeekEnum.valueType; // 0 | 1 | ... | 5 | 6

const weekValue: WeekValues = 1; // ✅ 正确，1 是一个有效的周枚举值
const weeks: WeekValues[] = [0, 1]; // ✅ 正确，0 和 1 是有效的周枚举值

const badWeekValue1: WeekValues = 'Weekend'; // ❌ 类型错误，"Weekend" 不是数字
const badWeekValue2: WeekValues = 8; // ❌ 错误，8 不是一个有效的周枚举值
const badWeeks: WeekValues[] = [0, 8]; // ❌ 错误，8 不是一个有效的周枚举值

方法参数

ts 复制代码

function setDay(day: typeof WeekEnum.valueType) {
  // day 的类型被约束为 0 | 1 | ... | 5 | 6
}

setDay(1); // ✅ 正确
setDay('Monday'); // ❌ 类型错误，'Monday' 不是数字
setDay(8); // ❌ 错误，8 不是一个有效的枚举值

组件属性

ts 复制代码

type MyComponentProps = {
  day: typeof WeekEnum.valueType; // 0 | 1 | ... | 5 | 6
};
const MyComponent = (props: MyComponentProps) => {
  return <div>今天是 {WeekEnum.label(props.day)}</div>;
};

<MyComponent day={1} />; // ✅ 类型正确
<MyComponent day="Monday" />; // ❌ 类型错误
<MyComponent day={8} />; // ❌ 错误，8 不是一个有效的枚举值

💡 添加元数据字段，可以作为静态配置系统使用

js 复制代码

const ColorEnum = Enum({
  Red: { value: 1, hex: '#FF0000', icon: '🔥' },
  Green: { value: 2, hex: '#00FF00', icon: '🍏' },
  Blue: { value: 3, hex: '#0000FF', icon: '🔵' },
});

ColorEnum.values; // [1, 2, 3]
ColorEnum.keys; // ['Red', 'Green', 'Blue']
ColorEnum.meta.hex; // ['#FF0000', '#00FF00', '#0000FF']
ColorEnum.meta.icon; // ['🔥', '🍏', '🔵']
ColorEnum.named.Red.raw.hex; // '#FF0000'
ColorEnum.named.Red.raw.icon; // '🔥'

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

js 复制代码

Array.isArray(WeekEnum.items); // true
WeekEnum.items.push({ value: 2, label: '星期二' }); // ❌ 不可修改
WeekEnum.items.splice(0, 1); // ❌ 不可修改
WeekEnum.items[0].label = 'foo'; // ❌ 不可修改

💡 枚举组合（合并）

js 复制代码

const PrimaryColorEnum = Enum({
  Red: { value: 1, hex: '#FF0000' },
  Green: { value: 2, hex: '#00FF00' },
  Blue: { value: 3, hex: '#0000FF' },
});
const SecondaryColorEnum = Enum({
  Yellow: { value: 4, hex: '#FFFF00' },
  Cyan: { value: 5, hex: '#00FFFF' },
  Magenta: { value: 6, hex: '#FF00FF' },
});
const AllColorEnum = Enum({
  ...PrimaryColorEnum.raw(),
  ...SecondaryColorEnum.raw(),
});

💡 枚举项支持 JSDoc 注释，启用代码智能提示

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

js 复制代码

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

WeekEnum.Monday; // 将光标悬浮在 Monday 上

可以看到，当光标悬浮在枚举项上时，可以同时显示枚举值和枚举项的介绍。无需跳转离开当前光标位置，去查看枚举的定义，这在阅读代码时非常方便。

💡 支持多种前端框架

Enum.items 可以直接作为组件的数据源（以 Select 组件为例）

React相关框架

Ant Design | Arco Design Select

tsx 复制代码

import { Select } from 'antd';

<Select options={WeekEnum.items} />;

Material-UI Select

tsx 复制代码

import { MenuItem, Select } from '@mui/material';

<Select>
  {WeekEnum.items.map((item) => (
    <MenuItem key={item.value} value={item.value}>
      {item.label}
    </MenuItem>
  ))}
</Select>;

Kendo UI Select

tsx 复制代码

import { DropDownList } from '@progress/kendo-react-dropdowns';

<DropDownList data={WeekEnum.items} textField="label" dataItemKey="value" />;

Vue相关框架

Element Plus Select

html 复制代码

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

Ant Design Vue | Arco Design Select

html 复制代码

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

Vuetify Select

html 复制代码

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

Angular相关框架

Angular Material Select

html 复制代码

<mat-select>
  @for (item of WeekEnum.items; track item.value) {
  <mat-option [value]="item.value">{{ item.label }}</mat-option>
  }
</mat-select>

NG-ZORRO Select

jsx 复制代码

<nz-select>
  @for (item of WeekEnum.items; track item.value) {
    <nz-option [nzValue]="item.value">{{ item.label }}</nz-option>
  }
</nz-select>

插件系统

enum-plus 提供了一个插件系统，允许你为枚举添加额外的功能。插件可以为所有枚举实例添加新的方法或属性，极大地扩展了枚举的功能。你可以选择性地安装需要的插件，而不是将所有功能都打包在一起，从而保持核心库的轻量和高效。

ts 复制代码

import antdPlugin from '@enum-plus/plugin-antd';
import { Enum } from 'enum-plus';

Enum.install(antdPlugin);

当你安装一个插件后，插件会为所有枚举实例添加新的方法或属性。例如，安装了 @enum-plus/plugin-antd 插件后，你可以使用 enum.toSelect 方法使用枚举生成一个 Select 组件。

你还可以设置插件的可选配置选项，以定制插件的行为，关于插件的配置选项，请参考各个插件的文档。

ts 复制代码

import antdPlugin from '@enum-plus/plugin-antd';
import { Enum } from 'enum-plus';

Enum.install(antdPlugin, {
  toSelect: {
    valueField: 'id', // 设置 toSelect 方法生成的数据对象中，关于值的字段名
    labelField: 'name', // 设置 toSelect 方法生成的数据对象中，关于枚举名称的字段名
  },
});

插件生态

目前我们已经开发并发布了以下插件，你可以根据需要选择安装：

@enum-plus/plugin-antd：面向 Ant Design 的功能扩展，包括 enum.toSelect、enum.toMenu、enum.toFilter 和 enum.toValueMap。通过这些方法，可以直接将枚举绑定到对应的 Ant Design 组件上，极大地简化了代码。
@enum-plus/plugin-i18next：集成 i18next 并实现枚举标签的国际化。
@enum-plus/plugin-react-i18next：自动适配 react-i18next 以让枚举支持国际化。
@enum-plus/plugin-react：React 集成，包括支持 Enum.localize 返回 React 组件，以及监听语言变化以自动重新渲染组件。
@enum-plus/plugin-i18next-vue：集成 i18next-vue 并实现枚举标签的国际化，支持切换语言后自动更新UI。
@enum-plus/plugin-vue-i18n：集成 vue-i18n 并实现枚举标签的国际化，支持切换语言后自动更新UI。

如果你没有找到需要的插件，或者你想开发自己的插件，请参阅插件开发指南。你可以在enum-plus官方仓库中开发新插件，也可以将你开发的插件发布到 npm 上，并把你的插件链接分享在这里。我们真诚地需要你的帮助，来丰富插件生态系统！

本地化

enum-plus 默认不内置国际化能力，因此枚举项的label字段将被视为普通字符串，直接返回原始文本。

为 enum-plus 添加本地化支持，最简单的方式是安装对应的 i18n插件，例如 @enum-plus/plugin-i18next，它会自动将 label 和 name 字段的值传递给 i18next 进行翻译。

bash 复制代码

npm install @enum-plus/plugin-i18next i18next

然后在项目入口文件中安装插件：

index.js

js 复制代码

import i18nextPlugin from '@enum-plus/plugin-i18next';
import { Enum } from 'enum-plus';

Enum.install(i18nextPlugin);

安装了插件后，枚举的 label 和 name 字段将自动通过 i18next 进行翻译。

js 复制代码

const WeekEnum = Enum(
  {
    Sunday: { value: 0, label: 'week.sunday' },
    Monday: { value: 1, label: 'week.monday' },
  },
  { name: 'weekDays.name' }
);
WeekEnum.label(1); // Monday 或 星期一，取决于当前语言环境
WeekEnum.named.Monday.label; // Monday 或 星期一，取决于当前语言环境
WeekEnum.name; // Week 或 周，取决于当前语言环境

此插件还支持自定义 i18next 选项，甚至允许完全控制 localize 方法，请参考插件文档，了解更多详情。

如果你需要切换语言后自动更新UI，这需要借助 React、Vue 或 Angular 等框架的能力，请考虑使用 @enum-plus/plugin-react 或 @enum-plus/plugin-vue 等插件。

全局扩展

Enum 提供了丰富的内置方法和属性，它们已经可以满足大多数常见的使用场景。如果这些还不够，你还可以使用 Enum.extends 扩展更多的自定义方法。这些扩展会全局应用于所有枚举实例，包括在扩展应用之前创建的实例，并且会立即生效，无需任何额外的设置。

my-enum-extension.ts

ts 复制代码

// 功能实现
Enum.extends({
  toMySelect() {
    return this.items.map((item) => ({ value: item.value, title: item.label }));
  },
  reversedItems() {
    return this.items.toReversed();
  },
});

// 类型声明，以获得更好的类型提示
declare module 'enum-plus/extension' {
  export interface EnumExtension<T, K, V> {
    toMySelect: () => { value: V; title: string }[];
    reversedItems: () => EnumItemClass<EnumItemInit<V>, K, V>[];
  }
}

index.ts

然后在项目的入口文件中导入这个文件：

ts 复制代码

import './my-enum-extension';

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

实际上，整个插件系统以及 Enum.install 在底层都是通过 Enum.extends 来实现的。

兼容性

enum-plus 设计之初就考虑了广泛的兼容性需求，可无缝运行于各类环境，包括现代浏览器、Node.js 以及多种构建工具。下面详细说明各环境的兼容性情况：

浏览器环境

现代打包工具 ：对于支持 exports 配置的打包工具（如 webpack 5+、vite、rollup），代码引入的是 es 目录，对应的 ECMAScript 版本是 ES2020。
旧版打包工具 ：对于不支持 exports 配置的旧版打包工具（如 webpack 4），代码引入的是 es-legacy 目录，对应的 ECMAScript 版本是 ES2015。
UMD版本 ：为了方便在浏览器中直接使用，或者在没有打包工具的静态项目中使用，enum-plus 还提供了 UMD 版本，存放在 umd 目录下。UMD 格式的文件可以通过 <script> 标签直接引入，通过 window.EnumPlus 获取类库内容。umd 目录提供了两种版本：
- enum-plus.min.js ：对应的 ECMAScript 版本是 ES2020，适用于现代浏览器
- enum-plus-legacy.min.js ：对应的 ECMAScript 版本是 ES2015，适用于旧版浏览器

Node.js 环境

在 Node.js 环境下，支持通过 require 或 import 语法引入 enum-plus。

require

对于所有支持 CommonJS 的 Node.js 版本，均可通过 require('enum-plus') 方式引入 enum-plus。代码引入的是 lib 目录，对应的 ECMAScript 版本是 ES2015 。Node.js版本最低可以向下兼容到 v7.x。
import

对于支持 ES Module 的 Node.js 现代版本（Node.js 14.13+），可以通过 import { Enum } from 'enum-plus' 方式引入 enum-plus。代码引入的是 es 目录，对应的 ECMAScript 版本是 ES2020。

最佳实践

在使用 enum-plus 创建和管理枚举时，遵循一些最佳实践可以帮助你编写更清晰、可维护的代码。以下是一些建议：

枚举类型命名： 采用 PascalCase 大驼峰命名法，并以 Enum 作为后缀，如 WeekEnum 、ColorEnum 等。
枚举成员命名： 使用 PascalCase 大驼峰命名法，如 Sunday 、Red 等。这种命名方式突显了枚举成员的静态与不可变性，并且在IDE智能提示中可以显示在顶部，而不是与其它方法名混在一起，更方便查看和拾取。
语义明确： 确保枚举和成员名称具有清晰的语义，良好的语义命名能够自解释代码意图，降低理解成本。
单一职责原则： 每个枚举类型应专注表达一组高内聚的相关常量，避免不同枚举类型之间的职责重叠。
提供JSDoc注释： 为每个枚举项添加 JSDoc 注释，说明其含义和用途。完善的JSDoc文档能在IDE中提供悬停提示，提升代码阅读体验。同样也建议为枚举类添加注释。
国际化架构： 建议从开始就搭建国际化架构，可集成本库提供的本地化机制。预先设计的国际化方案能够避免后期重构的高成本，并使应用更易于扩展到全球市场。

下面是一个示例，展示了如何结合上述最佳实践来定义一个枚举：

js 复制代码

/** 表示一周的枚举 */
const WeekEnum = Enum(
  {
    /** 星期日 */
    Sunday: { value: 0, label: 'enums.week.sunday' },
    /** 星期一 */
    Monday: { value: 1, label: 'enums.week.monday' },
    // ...
    /** 星期五 */
    Friday: { value: 5, label: 'enums.week.friday' },
    /** 星期六 */
    Saturday: { value: 6, label: 'enums.week.saturday' },
  },
  { name: 'enums.week.name' }
);

意犹未尽，还期待更多？不妨移步 Github官网，你可以发现更多的高级使用技巧。

相信我，一定会让你感觉相见恨晚！

如果你喜欢这个项目，欢迎在GitHub上给项目添加一个⭐️星标 ------ 这是程序员表达喜爱的通用语言😜～可以让更多开发者发现它！

🔥 enum-plus 3.0：介绍一个天花板级的前端枚举库

简介

特性

安装

枚举定义

1. Key-Value 格式

2. 标准格式（推荐）

3. 数组格式

4. 原生枚举格式

API

💎 拾取枚举值

💎 named

💎 items

💎 values

💎 labels

💎 keys

💎 meta

💎 has **方法**

💎 findBy **方法**

💎 label **方法**

💎 key **方法**

💎 toList **方法**

💎 toMap **方法**

💎 raw **方法**

💎 name

⚡️ valueType ^TypeScript Only^

静态方法

💎 Enum.isEnum **方法**

💎 Enum.localize **方法**

💎 Enum.extends **方法**

💎 Enum.install **方法**

应用案例

💡 基础用法，消除魔法数字

💡 检查是否一个有效的枚举值

💡 检查是否一个枚举对象

💡 生成 UI 组件

💡 枚举名称/标签支持国际化

💡 约束数据类型 (仅 TypeScript)

💡 添加元数据字段，可以作为静态配置系统使用

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

💡 枚举组合（合并）

💡 枚举项支持 JSDoc 注释，启用代码智能提示

💡 支持多种前端框架

插件系统

插件生态

本地化

全局扩展

兼容性

浏览器环境

Node.js 环境

最佳实践

💎 has ^方法

💎 findBy ^方法

💎 label ^方法

💎 key ^方法

💎 toList ^方法

💎 toMap ^方法

💎 raw ^方法

💎 Enum.isEnum ^方法

💎 Enum.localize ^方法

💎 Enum.extends ^方法

💎 Enum.install ^方法