You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This section shows the various ways to initialize enums using the `Enum` function. Understanding these different initialization formats allows you to choose the most convenient approach for your specific use case.
137
137
138
-
### 1. Simple Key-Value Format
138
+
### 1. Key-Value Format
139
139
140
140
The simplest format is a direct mapping of keys to values. This is similar to the native enum format.
141
141
@@ -179,7 +179,7 @@ WeekEnum.label(0); // I love Sunday
179
179
180
180
### 3. Label-Only Format
181
181
182
-
This is useful when you want to use the key as the value.
182
+
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.
183
183
184
184
```js
185
185
import { Enum } from'enum-plus';
@@ -190,12 +190,15 @@ const WeekEnum = Enum({
190
190
});
191
191
192
192
WeekEnum.Sunday; // 'Sunday'
193
-
WeekEnum.label('Sunday'); // I love Sunday
193
+
WeekEnum.items[0].key; // 'Sunday'
194
+
WeekEnum.items[0].label; // I love Sunday
194
195
```
195
196
196
197
### 4. Array Format
197
198
198
-
The array format is useful when you need to create enums dynamically, such as from API data. This allows for flexibility in [Custom Field Mapping](#-custom-field-mapping-in-array-format-initialization) to adapt to different data structures.
199
+
The array format is useful when you need to create enums with dynamic data, for example the data from an API.
200
+
201
+
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.
Gets the display name of an enum item based on a certain value or key. If localization has been set up, the localized text will be returned.
372
+
Gets the display name of an enum item according to its value or key. If [localization](#localization) has been enabled, the localized text will be returned.
370
373
371
374
```js
372
375
WeekEnum.label(1); // Monday
@@ -379,7 +382,7 @@ WeekEnum.label('Monday'); // Monday, here is label, not key
Get the key of an enum item based on the enum value, if the key is not found, return `undefined`.
385
+
Find the key of an enum item by its value. It's also known as [reverse mapping](https://www.typescriptlang.org/docs/handbook/enums.html#reverse-mappings). If not found, `undefined` is returned.
383
386
384
387
```js
385
388
WeekEnum.key(1); // Monday (here is key, not label)
@@ -393,11 +396,11 @@ WeekEnum.key(1); // Monday (here is key, not label)
393
396
<br/>
394
397
<sup>**_\[F^2]_**</sup> `raw(keyOrValue: V | K): T[K]`
395
398
396
-
The `raw` method is used to return the original initialization object of the enum collection, which is the object used to create the enum.
399
+
The `raw` method has two overloads. The first one is to return the original initialization object of the whole enum collection, i.e. the first parameter of the `Enum` method.
397
400
398
-
The second overload method is used to return the original initialization object of a single enum item.
401
+
The second one is to return the original initialization object of a single enum item, i.e. the sub-object of the corresponding field in the first parameter of the `Enum` method.
399
402
400
-
The main purpose of the `raw` method is to get the extended custom fields of the enum items. Unlimited number of custom fields are allowed.
403
+
The main purpose of the `raw` method is to get the extended custom fields of the enum items.
> Tips: If you want to access the metadata fields of a known enum item, using `enum.named.XXX.raw` is a good option, for example: `WeekEnum.named.Sunday.raw.happy`.
Display name for Enum types. When creating an enum, you can assign it a display name using the optional `name` parameter. This name can be either a plain string or a localization key to support internationalized text. Please refer to the [Localization](#localization) section for more details.
471
-
472
-
> Usually Enums are used to generate dropdown menus in forms, or show item text in table cells. The display name of the enum type often serves as the form field label or table caption. By utilizing the `name` property, you can centralize the management of both the enum type's display name and its items' labels, simplifying maintenance and ensuring consistency across your application.
475
+
The display name of the whole enum collection. It's optional and can be set as the second parameter of the `Enum` method. This name can be either a plain string or a localization key to support internationalized text. Please refer to the [Localization](#localization) section for more details.
473
476
474
477
```js
475
478
constWeekEnum=Enum(
476
479
{
477
-
Sunday: { value:0, label:'Sunday', happy:true },
478
-
Monday: { value:1, label:'Monday', happy:false },
480
+
Sunday: { value:0, label:'Sunday' },
481
+
Monday: { value:1, label:'Monday' },
479
482
},
480
483
{
481
-
name:'i18n.enums.week', // A localization key
484
+
name:'i18n.enums.week', // A regular string or localization key
482
485
}
483
486
);
484
487
485
-
WeekEnum.name; // Week
486
-
WeekEnum.label(0); // Sunday
487
-
WeekEnum.label(1); // Monday
488
+
WeekEnum.name; // Week or 周, depending on the current language setting
488
489
```
489
490
491
+
> Enums are usually used to generate dropdown menus in forms, or show item text in table cells. The display name of the enum type often serves as the form field label or table caption. By utilizing the `name` property, you can centralize the management of both the enum type's display name and its items' labels, simplifying maintenance and ensuring consistency across your application.
In TypeScript, provides a union type containing all enum values, enabling precise type constraints for variables and component properties. This replaces broad primitive types like `number`or `string` with exact value sets, preventing invalid assignments while enhancing both code readability and compile-time type safety.
499
+
In TypeScript, provides a union type containing all enum values. It's usually used for type constraints on variables and method parameters, or used in component properties.
497
500
498
-
```typescript
499
-
typeWeekValues=typeofWeekEnum.valueType; // 0 | 1
501
+
```ts
502
+
const weekValue:typeofWeekEnum.valueType=1;
503
+
504
+
function setToday(day:typeofWeekEnum.valueType) {
505
+
// ...
506
+
}
500
507
501
-
const weekValue:typeofWeekEnum.valueType=1; // ✅ Type correct, 1 is a valid week enum value
502
-
const weeks: (typeofWeekEnum.valueType)[] = [0, 1]; // ✅ Type correct, 0 and 1 are valid week enum values
503
-
const badWeekValue:typeofWeekEnum.valueType=8; // ❌ Type error, 8 is not a valid week enum value
504
-
const badWeeks: (typeofWeekEnum.valueType)[] = [0, 8]; // ❌ Type error, 8 is not a valid week enum value
<MyComponentday="Monday"/>; // ❌ Type error, "Monday" is not a number
732
+
<MyComponentday={8} />; // ❌ Error, 8 is not a valid enum value
733
+
```
734
+
710
735
---
711
736
712
737
#### 💡 Support Metadata Fields That Can Serve as a Static Configuration System
@@ -1320,6 +1345,6 @@ Thanks to the high flexibility of [Plugin System](#plugin-system), it is quite e
1320
1345
1321
1346
If you find a security issue, please follow the [Security Policy](SECURITY.md) to report it responsibly.
1322
1347
1323
-
## Support & Star
1348
+
## Support
1324
1349
1325
-
**If you find this project useful, please consider giving it a [STAR](https://github.com/shijistar/enum-plus) ⭐️ on GitHub. It helps more people discover the project and encourages us to continue development.**
1350
+
If you find this project useful, please consider giving it a [STAR](https://github.com/shijistar/enum-plus) ⭐️ on GitHub. It helps more people discover the project and encourages us to continue development.
0 commit comments