{"_id":"@enum-plus/plugin-react","_rev":"4-7bed205536732a17742d04b17e33f523","name":"@enum-plus/plugin-react","dist-tags":{"latest":"1.0.0","beta":"1.0.0-beta.2"},"versions":{"1.0.0-beta.0":{"name":"@enum-plus/plugin-react","version":"1.0.0-beta.0","keywords":["enum","enumeration","enum-plus","plugin","typescript","react","localization","globalization","internationalization","front-end","node.js","ssr"],"author":{"url":"Leo","name":"李凤宝","email":"shijistar@gmail.com"},"license":"MIT","_id":"@enum-plus/plugin-react@1.0.0-beta.0","maintainers":[{"name":"shijistars","email":"shijistar@hotmail.com"}],"homepage":"https://github.com/shijistar/enum-plus","bugs":{"url":"https://github.com/shijistar/enum-plus/issues"},"dist":{"shasum":"aae6ec4fff3dd3281230f13f5823cb7040ae4c20","tarball":"https://registry.npmjs.org/@enum-plus/plugin-react/-/plugin-react-1.0.0-beta.0.tgz","fileCount":4,"integrity":"sha512-setIBPRHxwVIn+M/g59bQVOF5JrxgwQZwD+yfWz8kaTG4BqXj+YY+9b8zFmkuF/OgJzNC86YlLNOpNjx6kNFqA==","signatures":[{"sig":"MEYCIQDcmaPDQkLjDxh9A39ucrZ1ty9YTw+94Ir6uaH23wW2jgIhALe18qvhdALtEmp6TVQKZrrMD3n/7Nm/Zsy0rSptGpDF","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18861},"main":"lib/index.js","types":"lib/index.d.ts","module":"es/index.js","gitHead":"e30efb1050107e78144d457485f75d66439c52f2","scripts":{"test":"jest","build":"run-p build:es build:es-legacy build:lib","ts2lib":"tsc -p tsconfig.lib.json","build:es":"father build","build:lib":"run-s ts2lib task:copy-lib","test-legacy":"jest -c jest-legacy.config.js","test:browser":"npm run test:browser:bundle && playwright test","task:copy-lib":"tsx ../../scripts/copy-lib.ts","prepublishOnly":"npm run build && npm run test","build:es-legacy":"cross-env LEGACY=1 father build","test:browser:ui":"npm run test:browser:bundle && playwright test --ui","test:browser:debug":"npm run test:browser:bundle && playwright test --debug","test:browser:bundle":"node scripts/browser-test-bundle.js"},"_npmUser":{"name":"shijistars","email":"shijistar@hotmail.com"},"repository":{"url":"git+https://github.com/shijistar/enum-plus.git","type":"git"},"_npmVersion":"10.9.2","description":"A plugin for enum-plus that provides React components and hooks for enum handling","directories":{},"sideEffects":false,"_nodeVersion":"22.13.1","publishConfig":{"registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"packageManager":"npm@10.9.2","devDependencies":{"react":"^19.1.1","react-is":"^18.3.1","react-dom":"^19.1.1","@types/react":"^19.1.13","react-i18next":"^15.7.3","@testing-library/react":"^16.3.0","jest-environment-jsdom":"^30.1.2"},"peerDependencies":{"react":">=16.8.0","i18next":">=8.4.0","enum-plus":"^3.0.0-0","react-i18next":">=10.0.0"},"peerDependenciesMeta":{"i18next":{"optional":true},"react-i18next":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/plugin-react_1.0.0-beta.0_1759499955027_0.32413038034884223","host":"s3://npm-registry-packages-npm-production"}},"1.0.0-beta.1":{"name":"@enum-plus/plugin-react","version":"1.0.0-beta.1","keywords":["enum","enumeration","enum-plus","plugin","typescript","react","localization","globalization","internationalization","front-end","node.js","ssr"],"author":{"url":"Leo","name":"李凤宝","email":"shijistar@gmail.com"},"license":"MIT","_id":"@enum-plus/plugin-react@1.0.0-beta.1","maintainers":[{"name":"shijistars","email":"shijistar@hotmail.com"}],"homepage":"https://github.com/shijistar/enum-plus","bugs":{"url":"https://github.com/shijistar/enum-plus/issues"},"dist":{"shasum":"24151f47c5e51e4abeacb5332b18cdffcfd7a4be","tarball":"https://registry.npmjs.org/@enum-plus/plugin-react/-/plugin-react-1.0.0-beta.1.tgz","fileCount":67,"integrity":"sha512-26KnIijq8QkaWKohrs/o+KQDVDi6TieQCatGj5cazbRy5OShvetnuQ7g+RT0OuRDGCpt/8g8kX1wxqPKXl0XMw==","signatures":[{"sig":"MEUCIQD9H/DDpIl16l6uACNwNSAjQ7MvJZXYDja8Em0zwZ2IZgIgPEc7P7vEAQYVxmzJgr0HlsQoMVmzgh9n4m9Y0RWscXQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":191920},"main":"lib/index.js","types":"lib/index.d.ts","module":"es/index.js","gitHead":"12ca2afc0d1b87ea17e7a603e57e35d956a5daf2","scripts":{"test":"jest","build":"run-p build:es build:es-legacy build:lib","ts2lib":"tsc -p tsconfig.lib.json","build:es":"father build","build:lib":"run-s ts2lib task:copy-lib","test-legacy":"jest -c jest-legacy.config.js","test:browser":"npm run test:browser:bundle && playwright test","task:copy-lib":"tsx ../../scripts/copy-lib.ts","prepublishOnly":"npm run build && npm run test","build:es-legacy":"cross-env LEGACY=1 father build","test:browser:ui":"npm run test:browser:bundle && playwright test --ui","test:browser:debug":"npm run test:browser:bundle && playwright test --debug","test:browser:bundle":"node scripts/browser-test-bundle.js"},"_npmUser":{"name":"shijistars","email":"shijistar@hotmail.com"},"repository":{"url":"git+https://github.com/shijistar/enum-plus.git","type":"git"},"_npmVersion":"10.9.2","description":"A plugin for enum-plus that provides React components and hooks for enum handling","directories":{},"sideEffects":false,"_nodeVersion":"22.13.1","publishConfig":{"registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"packageManager":"npm@10.9.2","readmeFilename":"README.zh-CN.md","devDependencies":{"react":"^19.1.1","react-is":"^18.3.1","react-dom":"^19.1.1","@types/react":"^19.1.13","react-i18next":"^15.7.3","@testing-library/react":"^16.3.0","jest-environment-jsdom":"^30.1.2"},"peerDependencies":{"react":">=16.8.0","i18next":">=8.4.0","enum-plus":"^3.0.0-0","react-i18next":">=10.0.0"},"peerDependenciesMeta":{"i18next":{"optional":true},"react-i18next":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/plugin-react_1.0.0-beta.1_1759503545348_0.5063951941346845","host":"s3://npm-registry-packages-npm-production"}},"1.0.0-beta.2":{"name":"@enum-plus/plugin-react","version":"1.0.0-beta.2","keywords":["enum","enumeration","enum-plus","plugin","typescript","react","localization","globalization","internationalization","front-end","node.js","ssr"],"author":{"url":"Leo","name":"李凤宝","email":"shijistar@gmail.com"},"license":"MIT","_id":"@enum-plus/plugin-react@1.0.0-beta.2","maintainers":[{"name":"shijistars","email":"shijistar@hotmail.com"}],"homepage":"https://github.com/shijistar/enum-plus","bugs":{"url":"https://github.com/shijistar/enum-plus/issues"},"dist":{"shasum":"cc5bcbe97f030ec29c84d92adede9d91a0264c09","tarball":"https://registry.npmjs.org/@enum-plus/plugin-react/-/plugin-react-1.0.0-beta.2.tgz","fileCount":67,"integrity":"sha512-IYvQxfG59S7ulaezwmeFD3Yl02pR5o0onKw5y8LaC48u0mZPty2IQhNWL1zkoqnpONn2zkpQ5NGnnNRrI3dISg==","signatures":[{"sig":"MEUCIHiOKa7BzkaCW6y0kD9WQXpDF9mAq1ZUk++0+C1W4uEGAiEA17+ZaSiLkncBJkra04+I7CbUzuyOZcoHcwsVl+/0tXw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":190709},"main":"lib/index.js","types":"lib/index.d.ts","module":"es/index.js","gitHead":"696bfd0b25a9b30a4edf650c71a74c0aeac487c4","scripts":{"test":"jest","build":"run-p build:es build:es-legacy build:lib","ts2lib":"tsc -p tsconfig.lib.json","build:es":"father build","build:lib":"run-s ts2lib task:copy-lib","test-legacy":"jest -c jest-legacy.config.js","test:browser":"npm run test:browser:bundle && playwright test","task:copy-lib":"tsx ../../scripts/copy-lib.ts","prepublishOnly":"npm run build && npm run test","build:es-legacy":"cross-env LEGACY=1 father build","test:browser:ui":"npm run test:browser:bundle && playwright test --ui","test:browser:debug":"npm run test:browser:bundle && playwright test --debug","test:browser:bundle":"node scripts/browser-test-bundle.js"},"_npmUser":{"name":"shijistars","email":"shijistar@hotmail.com"},"repository":{"url":"git+https://github.com/shijistar/enum-plus.git","type":"git"},"_npmVersion":"10.9.2","description":"A plugin for enum-plus that provides React components and hooks for enum handling","directories":{},"sideEffects":false,"_nodeVersion":"22.13.1","publishConfig":{"registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"packageManager":"npm@10.9.2","readmeFilename":"README.zh-CN.md","devDependencies":{"react":"^19.1.1","react-is":"^18.3.1","react-dom":"^19.1.1","@types/react":"^19.1.13","react-i18next":"^15.7.3","@testing-library/react":"^16.3.0","jest-environment-jsdom":"^30.1.2"},"peerDependencies":{"react":">=16.8.0","i18next":">=8.4.0","enum-plus":"^3.0.0-0","react-i18next":">=10.0.0"},"peerDependenciesMeta":{"i18next":{"optional":true},"react-i18next":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/plugin-react_1.0.0-beta.2_1759505601358_0.09787140649964243","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@enum-plus/plugin-react","version":"1.0.0","description":"A plugin for enum-plus that provides React components and hooks for enum handling","keywords":["enum","enumeration","enum-plus","plugin","typescript","react","localization","globalization","internationalization","front-end","node.js","ssr"],"homepage":"https://github.com/shijistar/enum-plus","bugs":{"url":"https://github.com/shijistar/enum-plus/issues"},"repository":{"type":"git","url":"git+https://github.com/shijistar/enum-plus.git"},"license":"MIT","author":{"name":"李凤宝","email":"shijistar@gmail.com","url":"Leo"},"sideEffects":false,"main":"lib/index.js","module":"es/index.js","types":"lib/index.d.ts","scripts":{"build":"run-p build:es build:es-legacy build:lib","build:es":"father build","build:es-legacy":"cross-env LEGACY=1 father build","build:lib":"run-s ts2lib task:copy-lib","prepublishOnly":"npm run build && npm run test","task:copy-lib":"tsx ../../scripts/copy-lib.ts","test":"jest","test-legacy":"jest -c jest-legacy.config.js","test:browser":"npm run test:browser:bundle && playwright test","test:browser:bundle":"node scripts/browser-test-bundle.js","test:browser:debug":"npm run test:browser:bundle && playwright test --debug","test:browser:ui":"npm run test:browser:bundle && playwright test --ui","ts2lib":"tsc -p tsconfig.lib.json"},"devDependencies":{"@testing-library/react":"^16.3.0","@types/react":"^19.1.13","jest-environment-jsdom":"^30.1.2","react":"^19.1.1","react-dom":"^19.1.1","react-i18next":"^15.7.3","react-is":"^18.3.1"},"peerDependencies":{"enum-plus":"^3.0.0","i18next":">=8.4.0","react":">=16.8.0","react-i18next":">=10.0.0"},"peerDependenciesMeta":{"i18next":{"optional":true},"react-i18next":{"optional":true}},"packageManager":"npm@10.9.2","publishConfig":{"registry":"https://registry.npmjs.org/"},"_id":"@enum-plus/plugin-react@1.0.0","gitHead":"b48571af53cac04a3ccdf217001620c967005d75","_nodeVersion":"22.13.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-fO8oIf7e0M55kPOSL3GbYTLw/1z2gxFjow5KJPTfpFavwgq/CaGsBljWMQLj5oJusu28IxUMgVNKQHjELuyZqw==","shasum":"824b6bae28d66741a50c4560fa94548f0667c464","tarball":"https://registry.npmjs.org/@enum-plus/plugin-react/-/plugin-react-1.0.0.tgz","fileCount":67,"unpackedSize":191680,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAbaqDZsfaybOrYuoq0TyurJ9ZU9BG9eF6iIrvRwfw/0AiAKEGefYKVulmY1ATxUA6V6uFXuRWU331VJGsn5Djv/EQ=="}]},"_npmUser":{"name":"shijistars","email":"shijistar@hotmail.com"},"directories":{},"maintainers":[{"name":"shijistars","email":"shijistar@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/plugin-react_1.0.0_1759669994392_0.05776893387821125"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-03T13:59:14.968Z","modified":"2025-10-05T13:13:14.777Z","1.0.0-beta.0":"2025-10-03T13:59:15.200Z","1.0.0-beta.1":"2025-10-03T14:59:05.531Z","1.0.0-beta.2":"2025-10-03T15:33:21.559Z","1.0.0":"2025-10-05T13:13:14.596Z"},"bugs":{"url":"https://github.com/shijistar/enum-plus/issues"},"author":{"name":"李凤宝","email":"shijistar@gmail.com","url":"Leo"},"license":"MIT","homepage":"https://github.com/shijistar/enum-plus","keywords":["enum","enumeration","enum-plus","plugin","typescript","react","localization","globalization","internationalization","front-end","node.js","ssr"],"repository":{"type":"git","url":"git+https://github.com/shijistar/enum-plus.git"},"description":"A plugin for enum-plus that provides React components and hooks for enum handling","maintainers":[{"name":"shijistars","email":"shijistar@hotmail.com"}],"readme":"<!-- markdownlint-disable MD001 MD009 MD033 MD041 -->\n\n[English](./README.md) | [中文](./README.zh-CN.md) | [CHANGELOG](./CHANGELOG.md)\n\n# enum-plus for React\n\n## 简介\n\n`@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 自动更新，无需刷新页面。\n\n它与 `@enum-plus/plugin-i18next` 插件的区别在于：\n\n#### **@enum-plus/plugin-i18next**\n\n- 适用于任何 JavaScript 项目，返回的标签是字符串类型，适合在各种主流框架中使用。\n- 可以直接用于文本搜索等场景，例如，`Array.includes` 方法可以用于检查标签是否包含某个子字符串，或者绑定到Select等UI组件，搜索功能可以正常工作。\n- 缺点是无法监听语言变化，当语言变化时，需要手动重新渲染组件。\n\n#### **@enum-plus/plugin-react**\n\n- 专为 React 应用设计，返回的标签是 React 组件，可以直接在 JSX 中使用。\n- 监听语言变化，当语言变化时，组件会自动重新渲染，无需刷新页面或手动干预。\n- 由于返回值不是字符串类型，因此无法直接用于文本搜索等场景。例如，`Array.includes` 方法无法用于检查标签是否包含某个子字符串，或者绑定到Select等UI组件，可能搜索功能会失效。为了解决这个问题，建议使用 `@enum-plus/i18next` 中提供的 [isMatch](#-ismatch) 或 [isMatchCaseSensitive](#-ismatchcasesensitive) 方法。\n\n## 安装\n\n```bash\nnpm install @enum-plus/plugin-react\n```\n\n在应用程序的入口文件中，导入 `@enum-plus/plugin-react` 插件并安装：\n\n- 如果你使用 `i18next`：\n\n```js\nimport { i18nextPlugin } from '@enum-plus/plugin-react';\nimport { Enum } from 'enum-plus';\n\nEnum.install(i18nextPlugin);\n```\n\n- 如果你使用 `react-i18next`：\n\n```js\nimport { reactI18nextPlugin } from '@enum-plus/plugin-react';\nimport { Enum } from 'enum-plus';\n\nEnum.install(reactI18nextPlugin);\n```\n\n## 插件选项\n\n安装插件时，可以传入一个配置对象，用于设置插件的全局选项：\n\n- **i18nextPlugin**\n\n```ts\nEnum.install(i18nextPlugin, {\n  localize: {\n    // 设置 i18next 实例，如果有必要，默认为全局的 i18next 实例\n    instance: i18next,\n    // 传递给 i18next.t 方法的默认选项\n    tOptions: {\n      // 设置命名空间\n      ns: 'my-namespace',\n      // 设置返回值的默认值\n      defaultValue: '-',\n      // 其它 i18next.t 方法支持的选项\n      // 请参考 https://www.i18next.com/translation-function/essentials#overview-options\n    },\n    defaultSearchField: 'label', // 设置 isMatch 和 isMatchCaseSensitive 方法中用于搜索的字段，默认为 'label'\n  },\n});\n```\n\n- **reactI18nextPlugin**\n\n```ts\nEnum.install(reactI18nextPlugin, {\n  localize: {\n    // 设置 react-i18next 的 useTranslation 钩子选项\n    useTranslationOptions: {\n      // 设置命名空间\n      ns: 'my-namespace',\n      // 其它 useTranslation 方法支持的选项\n      // 请参考 https://react.i18next.com/latest/usetranslation-hook#usetranslation-params\n    },\n    // 传递给 i18next.t 方法的默认选项\n    tOptions: {\n      // 设置返回值的默认值\n      defaultValue: '-',\n      // 其它 i18next.t 方法支持的选项\n      // 请参考 https://www.i18next.com/translation-function/essentials#overview-options\n    },\n  },\n});\n```\n\n`tOptions` 还支持函数形式，以便动态生成选项，甚至可以直接返回最终的翻译文本，两个插件均适用：\n\n```ts\n// 使用函数形式动态生成 tOptions\nEnum.install(i18nextPlugin, {\n  localize: {\n    tOptions: (key, instance) => {\n      if (key === 'week.sunday') {\n        return { ns: 'my-namespace' };\n      }\n      return { ns: 'translation' }; // 默认命名空间\n    },\n  },\n});\n\n// 直接返回翻译文本\nEnum.install(i18nextPlugin, {\n  localize: {\n    tOptions: (key, instance) => {\n      if (key === 'week.sunday') {\n        return '周日'; // 直接返回翻译文本\n      }\n      return instance.t(key); // 其它情况返回默认翻译\n    },\n  },\n});\n```\n\n你甚至可以在 `tOptions` 中直接返回一个字符串，作为最终的翻译文本，以完全控制 `localize` 方法的行为。\n\n```ts\nEnum.install(i18nextPlugin, {\n  localize: {\n    tOptions: (key, instance) => {\n      if (key === 'week.sunday') {\n        return '周日'; // 直接返回翻译文本\n      }\n      return instance.t(key); // 其它情况返回默认翻译\n    },\n  },\n});\n```\n\n## 用法\n\n### 枚举标签响应语言的变化\n\n可以通过在枚举定义中使用本地化键，来实现枚举标签的国际化。\n\n```js\nimport { Enum } from 'enum-plus';\n\nconst WeekEnum = Enum(\n  {\n    Monday: { value: 1, label: 'week.monday' },\n    Tuesday: { value: 2, label: 'week.tuesday' },\n  },\n  {\n    name: 'weekDays.name', // 枚举类型名称，可选\n  }\n);\n\nWeekEnum.label(1); // Monday - ReactElement\nWeekEnum.name; // Week - ReactElement\n\ni18next.changeLanguage('zh-CN');\nWeekEnum.label(1); // 星期一 - ReactElement\nWeekEnum.name; // 星期 - ReactElement\n```\n\n从枚举生成的UI组件，当语言变化时，标签会自动更新：\n\n```tsx\nimport { Button, Select } from 'antd';\nimport { changeLanguage } from 'i18next';\n\n<Select options={WeekEnum.items} defaultValue={WeekEnum.Monday} />;\n// 选中并显示: Monday\n\n<Button onClick={() => changeLanguage('zh-CN')}>切换语言</Button>;\n\n// 切换语言后，选中项的文本会自动更新为: 星期一\n```\n\n### 下拉框搜索\n\n由于枚举的 `label` 已经变成了组件实例，而不是字符串类型，故无法直接用于文本搜索。可以使用 `isMatch` 或 `isMatchCaseSensitive` 方法来实现对枚举项的过滤。\n\n```tsx\nimport { Select } from 'antd';\n\n<Select options={WeekEnum.items} filterOption={WeekEnum.isMatch} />;\n```\n\n## 其它API\n\n### 💎 isMatch\n\n<sup>**_\\[方法]_**</sup> &nbsp; `isMatch(searchText: string, item: EnumItem): boolean`\n\n`isMatch` 方法用于根据搜索文本过滤枚举项，支持对枚举项的 `label` 进行模糊匹配，且忽略大小写。\n\n> 此方法仅适用于`Enum.localize`返回非字符串的情况。例如，Enum.localize 在React框架下返回一个组件，以便能在切换语言后实时更新UI。在这种情况下，无法对枚举项的`label`进行字符串匹配，可以考虑使用此方法过滤枚举项。\n\n- 下拉框搜索\n\n```tsx\nimport { Select } from 'antd';\n\n<Select options={WeekEnum.items} filterOption={WeekEnum.isMatch} />;\n```\n\n- 常规过滤的用法\n\n```js\nWeekEnum.items.filter((item) => WeekEnum.isMatch('Mon', item)); // 过滤出 label 中包含 'Mon' 的枚举项\n```\n\n### 💎 isMatchCaseSensitive\n\n<sup>**_\\[方法]_**</sup> &nbsp; `isMatchCaseSensitive(searchText: string, item: EnumItem): boolean`\n\n`isMatchCaseSensitive` 方法用于根据搜索文本过滤枚举项，支持对枚举项的 `label` 进行模糊匹配，且区分大小写。\n\n> 此方法仅适用于`Enum.localize`返回非字符串的情况。例如，Enum.localize 在React框架下返回一个组件，以便能在切换语言后实时更新UI。在这种情况下，无法对枚举项的`label`进行字符串匹配，可以考虑使用此方法过滤枚举项。\n\n- 下拉框搜索\n\n```tsx\nimport { Select } from 'antd';\n\n<Select options={WeekEnum.items} filterOption={WeekEnum.isMatchCaseSensitive} />;\n```\n\n- 常规过滤用法\n\n```js\nWeekEnum.items.filter((item) => WeekEnum.isMatch('mon', item)); // 过滤出 label 中包含 'mon' 的枚举项 (区分大小写)\n```\n","readmeFilename":"README.zh-CN.md"}