# @enum-plus/plugin-react 中文文档 规范地址：https://npmcn.com/package/%40enum-plus/plugin-react/ 版本：1\.0\.0 npm 元数据更新时间：2025-10-05T13:13:14.777Z 中文译文更新时间：2026-11-13T18:48:11.241Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40enum-plus/plugin-react 原文对照：https://npmcn.com/package/%40enum-plus/plugin-react/?lang=original 项目主页：https://github.com/shijistar/enum-plus 源码仓库：https://github.com/shijistar/enum-plus ## 关键信息（来自 npm 元数据） - 包体积（解压后）：192 kB，67 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：enum-plus ^3\.0\.0，i18next \>=8\.4\.0，react \>=16\.8\.0，react-i18next \>=10\.0\.0 - 首次发布：2025-10-03T13:59:14.968Z - 最新版本发布：2025-10-05T13:13:14.596Z - 近 30 天下载量：7271（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：4（近 12 个月 0 个） ## 中文简介 用于 enum- plus 的插件, 提供 enum 处理的 React 组件和钩子 ## 安装 ```sh npm install @enum-plus/plugin-react ``` 也可以使用：`pnpm add @enum-plus/plugin-react`、`yarn add @enum-plus/plugin-react`、`bun add @enum-plus/plugin-react` ## README [English](https://npmcn.com/package/%40enum-plus/plugin-react/README.md) | [中文](https://npmcn.com/package/%40enum-plus/plugin-react/README.zh-CN.md) | [CHANGELOG](https://npmcn.com/package/%40enum-plus/plugin-react/CHANGELOG.md) # enum-plus for React ## 简介 `@enum-plus/plugin-react` 是 [enum-plus](https://github.com/shijistar/enum-plus) 的一个插件，可以认为是[@enum-plus/plugin-i18next](https://github.com/shijistar/enum-plus/tree/main/packages/plugin-i18next) 插件的进阶版本。它提供了 [i18next](https://www.i18next.com/) 和 [react-i18next](https://react.i18next.com/getting-started) 两个版本的插件。插件允许你在枚举定义中使用 i18next 的本地化键，并动态显示为当前语言的翻译文本，使得在 React 应用中使用 i18next 变得更加简单和高效。支持切换语言后，UI 自动更新，无需刷新页面。 它与 `@enum-plus/plugin-i18next` 插件的区别在于： #### **@enum-plus/plugin-i18next** - 适用于任何 JavaScript 项目，返回的标签是字符串类型，适合在各种主流框架中使用。 - 可以直接用于文本搜索等场景，例如，`Array.includes` 方法可以用于检查标签是否包含某个子字符串，或者绑定到Select等UI组件，搜索功能可以正常工作。 - 缺点是无法监听语言变化，当语言变化时，需要手动重新渲染组件。 #### **@enum-plus/plugin-react** - 专为 React 应用设计，返回的标签是 React 组件，可以直接在 JSX 中使用。 - 监听语言变化，当语言变化时，组件会自动重新渲染，无需刷新页面或手动干预。 - 由于返回值不是字符串类型，因此无法直接用于文本搜索等场景。例如，`Array.includes` 方法无法用于检查标签是否包含某个子字符串，或者绑定到Select等UI组件，可能搜索功能会失效。为了解决这个问题，建议使用 `@enum-plus/i18next` 中提供的 [isMatch](https://npmcn.com/package/%40enum-plus/plugin-react/#readme--ismatch) 或 [isMatchCaseSensitive](https://npmcn.com/package/%40enum-plus/plugin-react/#readme--ismatchcasesensitive) 方法。 ## 安装 ```bash npm install @enum-plus/plugin-react ``` 在应用程序的入口文件中，导入 `@enum-plus/plugin-react` 插件并安装： - 如果你使用 `i18next`： ```js import { i18nextPlugin } from '@enum-plus/plugin-react'; import { Enum } from 'enum-plus'; Enum.install(i18nextPlugin); ``` - 如果你使用 `react-i18next`： ```js import { reactI18nextPlugin } from '@enum-plus/plugin-react'; import { Enum } from 'enum-plus'; Enum.install(reactI18nextPlugin); ``` ## 插件选项 安装插件时，可以传入一个配置对象，用于设置插件的全局选项： - **i18nextPlugin** ```ts Enum.install(i18nextPlugin, { localize: { // 设置 i18next 实例，如果有必要，默认为全局的 i18next 实例 instance: i18next, // 传递给 i18next.t 方法的默认选项 tOptions: { // 设置命名空间 ns: 'my-namespace', // 设置返回值的默认值 defaultValue: '-', // 其它 i18next.t 方法支持的选项 // 请参考 https://www.i18next.com/translation-function/essentials#overview-options }, defaultSearchField: 'label', // 设置 isMatch 和 isMatchCaseSensitive 方法中用于搜索的字段，默认为 'label' }, }); ``` - **reactI18nextPlugin** ```ts Enum.install(reactI18nextPlugin, { localize: { // 设置 react-i18next 的 useTranslation 钩子选项 useTranslationOptions: { // 设置命名空间 ns: 'my-namespace', // 其它 useTranslation 方法支持的选项 // 请参考 https://react.i18next.com/latest/usetranslation-hook#usetranslation-params }, // 传递给 i18next.t 方法的默认选项 tOptions: { // 设置返回值的默认值 defaultValue: '-', // 其它 i18next.t 方法支持的选项 // 请参考 https://www.i18next.com/translation-function/essentials#overview-options }, }, }); ``` `tOptions` 还支持函数形式，以便动态生成选项，甚至可以直接返回最终的翻译文本，两个插件均适用： ```ts // 使用函数形式动态生成 tOptions Enum.install(i18nextPlugin, { localize: { tOptions: (key, instance) => { if (key === 'week.sunday') { return { ns: 'my-namespace' }; } return { ns: 'translation' }; // 默认命名空间 }, }, }); // 直接返回翻译文本 Enum.install(i18nextPlugin, { localize: { tOptions: (key, instance) => { if (key === 'week.sunday') { return '周日'; // 直接返回翻译文本 } return instance.t(key); // 其它情况返回默认翻译 }, }, }); ``` 你甚至可以在 `tOptions` 中直接返回一个字符串，作为最终的翻译文本，以完全控制 `localize` 方法的行为。 ```ts Enum.install(i18nextPlugin, { localize: { tOptions: (key, instance) => { if (key === 'week.sunday') { return '周日'; // 直接返回翻译文本 } return instance.t(key); // 其它情况返回默认翻译 }, }, }); ``` ## 用法 ### 枚举标签响应语言的变化 可以通过在枚举定义中使用本地化键，来实现枚举标签的国际化。 ```js import { Enum } from 'enum-plus'; const WeekEnum = Enum( { Monday: { value: 1, label: 'week.monday' }, Tuesday: { value: 2, label: 'week.tuesday' }, }, { name: 'weekDays.name', // 枚举类型名称，可选 } ); WeekEnum.label(1); // Monday - ReactElement WeekEnum.name; // Week - ReactElement i18next.changeLanguage('zh-CN'); WeekEnum.label(1); // 星期一 - ReactElement WeekEnum.name; // 星期 - ReactElement ``` 从枚举生成的UI组件，当语言变化时，标签会自动更新： ```tsx import { Button, Select } from 'antd'; import { changeLanguage } from 'i18next'; ; ``` ## 其它API ### 💎 isMatch **_\[方法\]_**   `isMatch(searchText: string, item: EnumItem): boolean` `isMatch` 方法用于根据搜索文本过滤枚举项，支持对枚举项的 `label` 进行模糊匹配，且忽略大小写。 > 此方法仅适用于`Enum.localize`返回非字符串的情况。例如，Enum.localize 在React框架下返回一个组件，以便能在切换语言后实时更新UI。在这种情况下，无法对枚举项的`label`进行字符串匹配，可以考虑使用此方法过滤枚举项。 - 下拉框搜索 ```tsx import { Select } from 'antd'; ; ``` - 常规过滤用法 ```js WeekEnum.items.filter((item) => WeekEnum.isMatch('mon', item)); // 过滤出 label 中包含 'mon' 的枚举项 (区分大小写) ``` ## 常见问题 ### @enum-plus/plugin-react 是什么？ 用于 enum- plus 的插件, 提供 enum 处理的 React 组件和钩子 ### 如何安装 @enum-plus/plugin-react？ 在项目目录运行 npm install @enum-plus/plugin-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：enum-plus（^3\.0\.0）、react（\>=16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @enum-plus/plugin-react 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @enum-plus/plugin-react 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @enum-plus/plugin-react 可以商用吗？ @enum-plus/plugin-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @enum-plus/plugin-react 的下载量有多少？ 根据 npm 官方下载统计，@enum-plus/plugin-react 在 2026/10/14 – 2026/11/12 这 30 天内被下载 7,271 次，日均约 242 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @enum-plus/plugin-react 还在维护吗？ 最新版本 1\.0\.0 发布于 2025/10/05（1\.1 年前）；至今共发布 4 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/10/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。