docs(core): update README

shijistar · shijistar · commit 7eec20b7c091 · 2025-10-05T00:01:51.000+08:00
diff --git a/README.md b/README.md
@@ -74,7 +74,7 @@ What other exciting features are there? Please continue to explore! Or you can c
 - Compatible with any front-end development framework, including vanilla projects
 - TypeScript‑oriented, providing excellent type inference and code completion capabilities
 - Zero dependencies
-- Lightweight (2KB+ minzipped only)
+- Lightweight (min+gzip 2KB+ only)
 
 ## Installation
 
@@ -180,7 +180,7 @@ WeekEnum.items[0].label; // I love Sunday
 
 ### 3. Label-Only Format
 
-Create an enumeration that only provides the `key` and `label` fields. If the `value` field is omitted, it defaults to the same value as the key  field.
+Create an enumeration that only provides the `key` and `label` fields. If the `value` field is omitted, it defaults to the same value as the `key` field.
 
 ```js
 import { Enum } from 'enum-plus';
@@ -222,7 +222,7 @@ Create from native enums. It benefits from the native enum's `auto-incrementing`
 ```ts
 import { Enum } from 'enum-plus';
 
-enum init {
+enum WeekNative {
   Sunday = 0,
   Monday,
   Tuesday,
@@ -231,7 +231,7 @@ enum init {
   Friday,
   Saturday,
 }
-const WeekEnum = Enum(init);
+const WeekEnum = Enum(WeekNative);
 
 WeekEnum.Sunday; // 0
 WeekEnum.Monday; // 1
@@ -270,7 +270,7 @@ WeekEnum.named.Monday; // { key: 'Monday', value: 1, label: 'Monday' }
 Returns a read-only array of all enum items.
 
 ```js
-WeekEnum.items; // [ { value: 0, label: 'Sunday', key:  'Sunday' }, { value: 1, label: 'Monday', key: 'Monday' }, ... ]
+WeekEnum.items; // [ { value: 0, label: 'Sunday', key: 'Sunday' }, { value: 1, label: 'Monday', key: 'Monday' }, ... ]
 ```
 
 ---
@@ -326,7 +326,7 @@ const ColorEnum = Enum({
 ColorEnum.meta.hex; // ['#FF0000', '#00FF00', '#0000FF']
 ```
 
-Aditionally, you can quickly access custom fields of an enum item through the `named` and `raw` property.
+Additionally, you can quickly access custom fields of an enum item through the `named` and `raw` properties.
 
 ```js
 ColorEnum.named.Red.raw.hex; // '#FF0000'
@@ -359,8 +359,8 @@ The `field` parameter can be one of the built-in fields: `key`, `value`, `label`
 
 ```js
 ColorEnum.findBy('value', 1); // { key: 'Red', value: 1, label: 'Red', hex: '#FF0000' }
-WeekEnum.findBy('key', 'Red'); // { key: 'Red', value: 1, label: 'Red' }
-WeekEnum.findBy('hex', '#FF0000'); // { key: 'Red', value: 1, label: 'Red', hex: '#FF0000' }
+ColorEnum.findBy('key', 'Red'); // { key: 'Red', value: 1, label: 'Red', hex: '#FF0000' }
+ColorEnum.findBy('hex', '#FF0000'); // { key: 'Red', value: 1, label: 'Red', hex: '#FF0000' }
 ```
 
 > If you need to get the meta fields of a known enum item, it is recommended to use the `named` and `raw` property, for example: `ColorEnum.named.Red.raw.hex`.
@@ -431,15 +431,17 @@ Converts the enum items to an array of objects, each containing `value` and `lab
 ```js
 WeekEnum.toList();
 // [
+//   { value: 0, label: 'Sunday' },
 //   { value: 1, label: 'Monday' },
-//   { value: 2, label: 'Tuesday' },
 //   ...
+//   { value: 6, label: 'Saturday' }
 // ]
 WeekEnum.toList({ valueField: 'id', labelField: 'name' });
 // [
+//   { id: 0, name: 'Sunday' },
 //   { id: 1, name: 'Monday' },
-//   { id: 2, name: 'Tuesday' },
 //   ...
+//   { id: 6, name: 'Saturday' }
 // ]
 ```
 
@@ -456,15 +458,17 @@ Converts the enum items to a key-value map object, where the keys are the enum v
 ```js
 WeekEnum.toMap();
 // {
+//   "0": 'Sunday',
 //   "1": 'Monday',
-//   "2": 'Tuesday',
 //   ...
+//   "6": 'Saturday'
 // }
 WeekEnum.toMap({ keySelector: 'key', valueSelector: 'value' });
 // {
+//   "Sunday": 0,
 //   "Monday": 1,
-//   "Tuesday": 2,
 //   ...
+//   "Saturday": 6
 // }
 ```
 
@@ -682,7 +686,7 @@ const App = () => {
 
 ### 💡 Internationalization for Enum Names and Labels
 
-Internationalization support . Set the `label` field to a localization key, so that it displays the corresponding text based on the current language environment. Please refer to the [Localization](#localization) section for more details.
+Internationalization support. Set the `label` field to a localization key, so that it displays the corresponding text based on the current language environment. Please refer to the [Localization](#localization) section for more details.
 
 ```js
 WeekEnum.label(1); // Monday or 星期一, depending on the current locale
@@ -704,8 +708,8 @@ type WeekValues = typeof WeekEnum.valueType; // 0 | 1 | ... | 5 | 6
 const weekValue: WeekValues = 1; // ✅ Correct, 1 is a valid week enum value
 const weeks: WeekValues[] = [0, 1]; // ✅ Correct, 0 and 1 are valid week enum values
 
-const badWeekValue: WeekValues = "Weekend"; // ❌ Type error, "Weekend" is not a number
-const badWeekValue: WeekValues = 8; // ❌ Error, 8 is not a valid week enum value
+const badWeekValue1: WeekValues = 'Weekend'; // ❌ Type error, "Weekend" is not a number
+const badWeekValue2: WeekValues = 8; // ❌ Error, 8 is not a valid week enum value
 const badWeeks: WeekValues[] = [0, 8]; // ❌ Error, 8 is not a valid week enum value
 ```
 
@@ -812,7 +816,7 @@ const WeekEnum = Enum({
 WeekEnum.Monday; // Hover over Monday
 ```
 
-![jsdoc](./public/jsdoc-en.png)
+![JSDoc](./public/jsdoc-en.png)
 
 We can see that both the enumeration value and the description of the enumeration item can be displayed at the same time, when the cursor hovers over an enumeration item. There is no need to jump away from the current position in the code to check the definitions.
 
@@ -902,7 +906,7 @@ We can see that both the enumeration value and the description of the enumeratio
 
 ### 💡 Custom Field Mapping in Array Format Initialization
 
-In [4. Array Format](#4-array-format) section, we know that you can build an enum from dynamic data from the backend, but it is very likely that the field names of dynamic data are not `value`, `label`, `key`, but other field names. In this case, you can pass in a custom option to map these to other field names.
+In the [4. Array Format](#4-array-format) section, we know that enums can be created from dynamic data arrays. However, the field names in the real world may be different from the default `value`, `label`, and `key`. In such cases, you can pass in a custom option to map these to other field names.
 
 ```js
 import { Enum } from 'enum-plus';
@@ -1017,7 +1021,7 @@ This plugin also supports custom i18next options, and even allows complete contr
 
 If you need to automatically update the UI after switching languages, this requires the capabilities of frameworks like React, Vue, or Angular. Please consider using plugins such as [@enum-plus/plugin-react](https://github.com/shijistar/enum-plus/tree/main/packages/plugin-react) or [@enum-plus/plugin-vue](https://github.com/shijistar/enum-plus/tree/main/packages/plugin-vue).
 
-If you are using other internationalization libraries, such as `react-intl`, `vue-i18next`, or `ngx-translate`, you can integrate these libraries by overwritting the `Enum.localize` method.
+If you are using other internationalization libraries, such as `react-intl`, `vue-i18next`, or `ngx-translate`, you can integrate these libraries by overwriting the `Enum.localize` method.
 
 _my-extension.js_
 
@@ -1187,7 +1191,7 @@ When using `enum-plus`, following these best practices can help ensure consisten
 1. **Enum Type Naming:** Use `PascalCase` and append with the `Enum` suffix (e.g., _WeekEnum_, _ColorEnum_).
 2. **Enum Item Naming:** Use `PascalCase` for enum items (e.g., _WeekEnum.Sunday_, _ColorEnum.Red_). This naming style highlights the immutability and static nature of enum items, and ensures they appear at the top in IDE IntelliSense suggestions for easier selection.
 3. **Semantic Clarity:** Ensure enum and item names have clear semantics. Good semantic naming serves as self-documentation, making code intent explicit and reducing cognitive overhead.
-4. **Single Responsibility Principle:** Each enum type should represent a single, cohesive set of related constants. Avoiding overlapping responsibilities between different enum types.
+4. **Single Responsibility Principle:** Each enum type should represent a single, cohesive set of related constants. Avoid overlapping responsibilities between different enum types.
 5. **Provide JSDoc Comments:** Provide JSDoc comments for each enum item and the enum type itself, explaining their purpose and usage. Comprehensive documentation enables IDE hover tooltips and improves code readability and maintainability.
 6. **Internationalization Architecture:** Plan for internationalization from the outset by leveraging the library's [localization](#localization) features. A well-designed internationalization architecture minimizes future refactoring and facilitates global scalability.
 
@@ -1250,7 +1254,7 @@ In Node.js environments, you can import enum-plus using either `require` or `imp
 
 ### Why do I need this library? TypeScript already has the built-in enums
 
-TypeScript's built-in enum only provides the basic functionality of [Enumeration](https://en.wikipedia.org/wiki/Enumerated_type): eliminating magic numbers, and regulating control flow. However, as a front-end engineer, the needs for enumerations are not merely these. We also need:
+TypeScript's built-in enum only provides the basic functionality of [Enumeration](https://en.wikipedia.org/wiki/Enumerated_type): eliminating magic numbers and structuring control flow (e.g. with if / switch). However, as a front-end engineer, the needs for enumerations are not merely these. We also need:
 
 1. _Eliminate magic numbers_
 2. _Used in the `if` or `switch` statements for conditional branching_
@@ -1316,7 +1320,7 @@ const WeekEnum = Enum({
 
 As you can see, in earlier versions of TypeScript, you may need to use the `as const` type assertion. `as const` allows the enum values to remain their original literal values instead of being converted to `number` or `string` types. Meanwhile, the `enum.valueType` will remain as `0 | 1` instead of becoming `number`. This makes TypeScript's type checking more accurate and enhances code safety. Additionally, please check your `tsconfig.json` file to ensure that the `moduleResolution` option is set to `node` or `node10`, which prevents the type declaration files of `enum-plus` from being automatically switched to the version of 5.0+.
 
-If you are using JavaScript, you can leverage `jsdoc` to help the editor accurately recognize types.
+If you are using JavaScript, you can leverage `JSDoc` to help the editor accurately recognize types.
 
 ```js
 /** @type {{ Sunday: 0; Monday: 1 }} */
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -70,11 +70,11 @@
 - 支持数据类型约束，提高代码的类型安全性<sup>_&nbsp;&nbsp;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)
+- 支持服务端渲染 (SSR)
 - 兼容任何前端开发框架，支持无框架的纯原生项目
 - 面向 TypeScript 设计，具有良好的类型推导和代码补全能力
 - 零依赖项
-- 轻量（gzip压缩后仅 2KB+）
+- 轻量（gzip压缩后仅2KB+）
 
 ## 安装
 
@@ -197,9 +197,6 @@ WeekEnum.items[0].label; // 星期日
 
 数组格式在需要动态创建枚举时很有用，例如从 API 获取数据中动态创建一个枚举。
 
-<!-- You can use dynamic field mapping rules to adapt to various different data structures. Please refer to the [Custom Field Mapping](#-custom-field-mapping-in-array-format-initialization) section for more details. -->
-<!-- 英文翻译 -->
-
 你可以动态映射字段以适应各种不同的数据结构。请参考 [数组格式初始化，设置不同的字段映射](#数组格式初始化设置不同的字段映射) 章节，了解更多详情。
 
 ```js
@@ -208,7 +205,7 @@ import { Enum } from 'enum-plus';
 const pets = [
   { value: 1, key: 'Dog', label: '狗' },
   { value: 2, key: 'Cat', label: '猫' },
-  { value: 3, key: 'Rabbit', label: '兔子' },
+  { value: 3, key: 'Rabbit', label: '兔' },
 ];
 const PetEnum = Enum(pets);
 
@@ -223,7 +220,7 @@ PetEnum.label(1); // 狗
 ```ts
 import { Enum } from 'enum-plus';
 
-enum init {
+enum WeekNative {
   Sunday = 0,
   Monday,
   Tuesday,
@@ -232,7 +229,7 @@ enum init {
   Friday,
   Saturday,
 }
-const WeekEnum = Enum(init);
+const WeekEnum = Enum(WeekNative);
 
 WeekEnum.Sunday; // 0
 WeekEnum.Monday; // 1
@@ -320,9 +317,9 @@ WeekEnum.keys; // ['Sunday', 'Monday', ... 'Friday', 'Saturday']
 
 ```js
 const ColorEnum = Enum({
-  Red: { value: 1, label: 'Red', hex: '#FF0000' },
-  Green: { value: 2, label: 'Green', hex: '#00FF00' },
-  Blue: { value: 3, label: 'Blue', hex: '#0000FF' },
+  Red: { value: 1, label: '红色', hex: '#FF0000' },
+  Green: { value: 2, label: '绿色', hex: '#00FF00' },
+  Blue: { value: 3, label: '蓝色', hex: '#0000FF' },
 });
 ColorEnum.meta.hex; // ['#FF0000', '#00FF00', '#0000FF']
 ```
@@ -357,8 +354,9 @@ WeekEnum.has('Birthday'); // false
 字段名支持：`key`、`value`、`label`或元数据字段
 
 ```js
-WeekEnum.findBy('value', 1); // { key: 'Monday', value: 1, label: '星期一' }
-WeekEnum.findBy('key', 'Monday'); // { key: 'Monday', value: 1, label: '星期一' }
+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' }
 ```
 
 ---
@@ -427,15 +425,17 @@ WeekEnum.raw(); // { Sunday: { value: 0, label: '星期日', happy: true }, Mond
 ```js
 WeekEnum.toList();
 // [
+//   { value: 0, label: '星期日' },
 //   { value: 1, label: '星期一' },
-//   { value: 2, label: '星期二' },
 //   ...
+//   { value: 6, label: '星期六' }
 // ]
 WeekEnum.toList({ valueField: 'id', labelField: 'name' });
 // [
+//   { id: 0, name: '星期日' },
 //   { id: 1, name: '星期一' },
-//   { id: 2, name: '星期二' },
 //   ...
+//   { id: 6, name: '星期六' }
 // ]
 ```
 
@@ -452,15 +452,17 @@ WeekEnum.toList({ valueField: 'id', labelField: 'name' });
 ```js
 WeekEnum.toMap();
 // {
+//   "0": '星期日',
 //   "1": '星期一',
-//   "2": '星期二',
 //   ...
+//   "6": '星期六'
 // }
 WeekEnum.toMap({ keySelector: 'key', valueSelector: 'value' });
 // {
+//   "Sunday": 0,
 //   "Monday": 1,
-//   "Tuesday": 2,
 //   ...
+//   "Saturday": 6
 // }
 ```
 
@@ -697,8 +699,8 @@ type WeekValues = typeof WeekEnum.valueType; // 0 | 1 | ... | 5 | 6
 const weekValue: WeekValues = 1; // ✅ 正确，1 是一个有效的周枚举值
 const weeks: WeekValues[] = [0, 1]; // ✅ 正确，0 和 1 是有效的周枚举值
 
-const badWeekValue: WeekValues = "Weekend"; // ❌ 类型错误，"Weekend" 不是数字
-const badWeekValue: WeekValues = 8; // ❌ 错误，8 不是一个有效的周枚举值
+const badWeekValue1: WeekValues = 'Weekend'; // ❌ 类型错误，"Weekend" 不是数字
+const badWeekValue2: WeekValues = 8; // ❌ 错误，8 不是一个有效的周枚举值
 const badWeeks: WeekValues[] = [0, 8]; // ❌ 错误，8 不是一个有效的周枚举值
 ```
 
@@ -790,9 +792,9 @@ const AllColorEnum = Enum({
 
 ---
 
-### 💡 枚举项支持 Jsdoc 注释，启用代码智能提示
+### 💡 枚举项支持 JSDoc 注释，启用代码智能提示
 
-在代码编辑器中，将光标悬停在枚举项上，即可显示关于该枚举项的详细 Jsdoc 注释，而不必再转到枚举定义处查看。关于如何编写良好的代码，请参考 [最佳实践](./docs/best-practices.md) 章节。
+在代码编辑器中，将光标悬停在枚举项上，即可显示关于该枚举项的详细 JSDoc 注释，而不必再转到枚举定义处查看。关于如何编写良好的代码，请参考 [最佳实践](./docs/best-practices.md) 章节。
 
 ```js
 const WeekEnum = Enum({
@@ -805,7 +807,7 @@ const WeekEnum = Enum({
 WeekEnum.Monday; // 将光标悬浮在 Monday 上
 ```
 
-![jsdoc](./public/jsdoc-chs.png)
+![JSDoc](./public/jsdoc-chs.png)
 
 可以看到，当光标悬浮在枚举项上时，可以同时显示枚举值和枚举项的介绍。无需跳转离开当前光标位置，去查看枚举的定义，这在阅读代码时非常方便。
 
@@ -894,7 +896,7 @@ WeekEnum.Monday; // 将光标悬浮在 Monday 上
 
 ---
 
-### 💡 数组格式初始化，设置不同的字段映射
+### 💡 在数组初始化方式中，设置不同的字段映射
 
 在 [4. 数组格式](#4-数组格式) 章节中，介绍了可以通过后端动态数据来构建枚举，但是很可能动态数据的字段名并不是`value`、`label`、`key`，而是其它的字段名。这时你可以传入一个自定义选项，把这些映射到其它字段名上
 
@@ -1180,7 +1182,7 @@ WeekEnum[ITEMS].toList(); // 但可以通过 ITEMS 别名来访问它
 2. **枚举成员命名：** 使用 `PascalCase` 大驼峰命名法，如 _WeekEnum.Sunday_、_ColorEnum.Red_ 等。此命名方式突显了枚举成员的不可变性与静态特性，且在IDE智能提示中会在顶部显示，更方便拾取。
 3. **语义明确：** 确保枚举和成员名称具有清晰的语义，良好的语义命名能够自解释代码意图，降低理解成本。
 4. **单一职责原则：** 每个枚举类型应专注表达一组高内聚的相关常量，避免不同枚举类型之间的职责重叠。
-5. **提供JSDoc注释：** 为每个枚举项添加 Jsdoc 注释，说明其含义和用途。完善的JSDoc文档能在IDE中提供悬停提示，提升代码阅读体验。同样也建议为枚举类添加注释。
+5. **提供JSDoc注释：** 为每个枚举项添加 JSDoc 注释，说明其含义和用途。完善的JSDoc文档能在IDE中提供悬停提示，提升代码阅读体验。同样也建议为枚举类添加注释。
 6. **国际化架构：** 建议从开始就搭建国际化架构，可集成本库提供的 [本地化](#本地化) 机制。预先设计的国际化方案能够避免后期重构的高成本，并使应用更易于扩展到全球市场。
 
 下面是一个示例，展示了如何结合上述最佳实践来定义一个枚举：
@@ -1308,7 +1310,7 @@ const WeekEnum = Enum({
 
 可以看到，在较低版本的TypeScript中，你可能需要使用 `as const` 类型断言。`as const` 可以让枚举值保持原始的字面量值，而不会变成 `number`、`string` 类型，同时 `enum.valueType` 类型也会保持 `0 | 1`，而不会变成 `number` 类型。这让 TypeScript 的类型校验变得更准确，也可以提升代码的安全性。另外，请检查你的 `tsconfig.json` 文件，确保 `moduleResolution` 选项设置为 `node` 或 `node10`，避免 `enum-plus` 的类型声明文件被自动切换到 5.0+ 版本。
 
-如果你使用的是 JavaScript，那么你可以借助 `jsdoc` 来让编辑器精确识别类型。
+如果你使用的是 JavaScript，那么你可以借助 `JSDoc` 来让编辑器精确识别类型。
 
 ```js
 /** @type {{ Sunday: 0; Monday: 1 }} */
