enum-plus
Version:
A drop-in replacement for native enum. Like native enum but much better!
150 lines (118 loc) • 10.3 kB
Markdown
<!-- markdownlint-disable MD001 MD009 MD033 MD041 -->
[English](./README.md) | [中文](./README.zh-CN.md) | [CHANGELOG](./CHANGELOG.md)
<p align="center">
<a href="https://github.com/shijistar/enum-plus" target="blank">
<img src="https://cdn.jsdelivr.net/gh/shijistar/enum-plus@v3.2.1/public/enum-plus.svg" width="240" alt="enum-plus" />
</a>
</p>
<p align="center">
<strong>用法像原生 enum 一样，但更强大！</strong>
</p>
<p align="center">
<strong>一个业务字典管理解决方案，不可或缺的前端基础设施。</strong>
</p>
<br/>
[](https://www.npmjs.com/package/enum-plus)
[](https://www.npmjs.com/package/enum-plus?activeTab=code)
[](https://www.npmjs.com/package/enum-plus)
[](https://deepwiki.com/shijistar/enum-plus)
[](https://app.codecov.io/gh/shijistar/enum-plus)
**支持平台**
[](https://www.npmjs.com/package/enum-plus)
[](https://github.com/shijistar/enum-plus)
[](https://reactnative.dev)
[](https://developers.weixin.qq.com/miniprogram/dev/framework)
[](https://taro.zone/)
[介绍](http://localhost:6006/?path=/docs/introduce--docs&globals=locale:zh-CN) • [快速上手](http://localhost:6006/?path=/docs/get-started--docs&globals=locale:zh-CN) • [API文档](http://localhost:6006/?path=/docs/api-reference--docs&globals=locale:zh-CN) • [全局配置](https://shijistar.github.io/enum-plus/?path=/docs/global-configuration--docs&globals=locale:zh-CN) • [典型用法](https://shijistar.github.io/enum-plus/?path=/docs/user-stories--docs&globals=locale:zh-CN) • [插件系统](https://shijistar.github.io/enum-plus/?path=/docs/plugin-system--docs&globals=locale:zh-CN) • [本地化](https://shijistar.github.io/enum-plus/?path=/docs/localization--docs&globals=locale:zh-CN) • [全局扩展](https://shijistar.github.io/enum-plus/?path=/docs/extensibility--docs&globals=locale:zh-CN) • [最佳实践](https://shijistar.github.io/enum-plus/?path=/docs/best-practices--docs&globals=locale:zh-CN) • [兼容性](https://shijistar.github.io/enum-plus/?path=/docs/compatibility--docs&globals=locale:zh-CN) • [常见问题](https://shijistar.github.io/enum-plus/?path=/docs/faq--docs&globals=locale:zh-CN) • [查看完整API文档](./README-FULL.zh-CN.md)
## 为什么使用 enum-plus
原生 enum 很适合表达常量，但真实业务的运行时需求往往更多：
- 用户友好的显示名称
- 扩展颜色、图标、权限等元数据
- 渲染下拉框、复选框、菜单、表格筛选等 UI 组件
- 枚举值转换标签文本
- 渲染颜色徽章
- 国际化
- 枚举元数据查找
- 枚举值校验
`enum-plus` 保留了直观的枚举式使用体验，并把这些运行时能力收敛到同一个对象里。
这是一套完整的前端业务字典解决方案，更像是一个轻量级的数据源，通常被用作前端公共基础设施。
<p align="center">
<a href="https://cdn.jsdelivr.net/gh/shijistar/enum-plus@v3.2.1/public/usage-screenshot-high-v3.mp4" target="_blank">
<img src="https://cdn.jsdelivr.net/gh/shijistar/enum-plus@v3.2.1/public/usage-screenshot-v3.gif" width="500" alt="usage video" />
</a>
</p>
<p align="center">
<sup><em>↑ 点击图片查看高清视频 ↑</em></sup>
</p>
> 💡 想看看 enum-plus 能做什么，以及如何能提高前端开发效率？[查看完整 Demo](https://shijistar.github.io/enum-plus/?path=/story/demo-full-demo--playground&globals=locale:zh-CN)
## 特性
- 完全兼容原生 `enum` 的用法
- 支持`number`、`string`等多种数据类型
- 枚举项支持设置显示名称
- 支持国际化，可与任何 i18n 库集成
- 快速将值转换为显示名称，在 UI 回显时非常有用
- 枚举项支持扩展元数据字段，可以作为静态配置系统使用
- 支持插件体系，可以通过安装插件扩展枚举功能
- 支持数据类型约束，提高代码的类型安全性<sup>_ TypeScript_</sup>
- 枚举可以生成下拉框等 UI 组件，支持 [Ant Design](https://ant-design.antgroup.com/components/overview-cn)、[Element Plus](https://element-plus.org/zh-CN/component/select.html)、[Material-UI](https://mui.com/material-ui) 等多种组件库
- 支持 Web浏览器、Node.js、React Native、Taro、小程序等多种环境
- 支持服务端渲染 (SSR)
- 兼容任何前端开发框架，支持无框架的纯原生项目
- 面向 TypeScript 设计，具有良好的类型推导和代码补全能力
- 零依赖项
- 轻量（gzip压缩后仅2KB+）
## 安装
```bash
npm install enum-plus
```
## 快速示例
```ts
import { Enum } from 'enum-plus';
const StatusEnum = Enum({
Draft: { value: 1, label: '草稿', color: 'default' },
Review: { value: 2, label: '审核中', color: 'processing' },
Published: { value: 3, label: '已发布', color: 'success' },
});
StatusEnum.Review; // 2
StatusEnum.label(2); // '审核中'
StatusEnum.has(2); // true
StatusEnum.keys; // ['Draft', 'Review', 'Published']
StatusEnum.values; // [1, 2, 3]
StatusEnum.labels; // ['草稿', '审核中', '已发布']
StatusEnum.items; // [{ key: 'Draft', value: 1, label: '草稿', color: 'default' }, ...]
StatusEnum.named.Draft; // { key: 'Draft', value: 1, label: '草稿', color: 'default' }
StatusEnum.item(1); // { key: 'Draft', value: 1, label: '草稿', color: 'default' }
StatusEnum.meta; // { color: [ 'default', 'processing', 'success' ] }
StatusEnum.findBy('color', 'success'); // { key: 'Published', value: 3, label: '已发布', color: 'success' }
StatusEnum.toList({ valueField: 'id', labelField: 'name' }); // [{ id: 1, name: '草稿' }, ...]
StatusEnum.toMap({ keySelector: 'key', valueSelector: 'value' }); // { Draft: 1, Review: 2, Published: 3 }
```
## 国际化
```ts
import i18nPlugin from '@enum-plus/plugin-i18next';
import { Enum } from 'enum-plus';
Enum.install(i18nPlugin);
const StatusEnum = Enum({
Draft: { value: 1, label: 'locales.enums.statusEnum.draft' },
Review: { value: 2, label: 'locales.enums.statusEnum.review' },
Published: { value: 3, label: 'locales.enums.statusEnum.published' },
});
StatusEnum.labels; // ['Draft', 'In Review', 'Published'] 或者 ['草稿', '审核中', '已发布']
StatusEnum.label(2); // 'In Review' 或者 '审核中'
StatusEnum.named.Review.label; // 'In Review' 或者 '审核中'
```
## 插件生态
- [@enum-plus/plugin-react](./packages/plugin-react/README.zh-CN.md)
- [@enum-plus/plugin-react-i18next](./packages/plugin-react-i18next/README.zh-CN.md)
- [@enum-plus/plugin-i18next](./packages/plugin-i18next/README.zh-CN.md)
- [@enum-plus/plugin-i18next-vue](./packages/plugin-i18next-vue/README.zh-CN.md)
- [@enum-plus/plugin-vue-i18n](./packages/plugin-vue-i18n/README.zh-CN.md)
- [@enum-plus/plugin-next-international](./packages/plugin-next-international/README.zh-CN.md)
- [@enum-plus/plugin-antd](./packages/plugin-antd/README.zh-CN.md)
## 支持
如果这个项目对你有帮助，请给它一个 GitHub [星标 ⭐️](https://github.com/shijistar/enum-plus)，这将鼓励我们继续开发和维护这个项目。