TypeScript Enum (枚举) 详解：类型安全与代码可读性的利器
在软件开发中，我们经常需要定义一组固定的、相关的常量。例如，一年四季、一周七天、用户状态（在线、离线、忙碌）、请求状态（成功、失败、处理中）等。在没有特定语言结构的情况下，我们通常会使用硬编码的数字或字符串来表示这些状态。这样做虽然简单，但存在明显的问题：
- 可读性差:
if (status === 1)不如if (status === UserStatus.Online)直观。数字1本身没有意义，需要查阅文档或代码才能知道它代表什么。 - 易错: 不小心输入了
if (status === 2)而2并没有被定义为有效状态，代码在编译时可能不会报错，运行时才可能出现问题。 - 维护困难: 如果需要修改某个状态的值（例如，将在线状态从
1改为10），需要在代码中查找并替换所有使用了这个硬编码值的地方，容易遗漏。
为了解决这些问题，许多编程语言都引入了枚举（Enum）类型。TypeScript 作为 JavaScript 的超集，也提供了强大的枚举支持，它不仅提供了命名常量的好处，还与 TypeScript 的类型系统深度集成，提供了额外的类型安全保障。
本文将详细探讨 TypeScript 中的枚举类型，包括其基本用法、不同类型的枚举、编译后的行为、高级特性以及最佳实践，帮助你充分理解并有效地在项目中利用枚举。
1. 什么是 Enum？
在 TypeScript 中，enum 关键字用于声明一个枚举类型。枚举允许我们定义一组命名的常量。默认情况下，枚举的成员是数字值，从 0 开始自动递增。
一个最简单的数字枚举示例：
“`typescript
enum Direction {
Up,
Down,
Left,
Right
}
let direction1: Direction = Direction.Up;
console.log(direction1); // 输出: 0
let direction2: Direction = Direction.Right;
console.log(direction2); // 输出: 3
“`
在这个例子中，Direction 是一个枚举类型，它有四个成员：Up, Down, Left, Right。TypeScript 编译器会默认给这些成员赋值：Up 是 0，Down 是 1，Left 是 2，Right 是 3。
使用枚举的成员时，我们通过 枚举名.成员名 的方式访问，这比直接使用数字 0 或 3 更具描述性，大大提高了代码的可读性。
2. 为什么使用 Enum？
正如引言中提到的问题，使用枚举的主要好处包括：
- 提高可读性: 使用有意义的名称代替魔法数字或字符串。
- 增强类型安全: 枚举是一种类型，你可以限制变量只能赋值为枚举中的某个成员，避免使用无效的值。TypeScript 编译器会在编译阶段检查类型，减少运行时错误。
- 简化维护: 如果需要修改枚举成员的值，只需在枚举定义处修改一次，所有使用该成员的地方都会自动引用新值（如果是数字或字符串枚举），或者在编译时直接内联（如果是
const枚举）。 - 意图明确: 枚举清晰地表达了一组相关的常量集合，使得代码结构更清晰。
3. 数字枚举 (Numeric Enums)
数字枚举是 TypeScript 枚举的默认类型。
3.1 默认赋值与自动递增
如前所示，如果第一个成员没有显式赋值，它将获得值 0。后续成员会从前一个成员的值开始自动递增 1。
typescript
enum Status {
Loading, // 0
Success, // 1
Error // 2
}
3.2 显式赋值
你也可以为枚举成员显式指定数字值。如果没有为后续成员赋值，它们将从前一个显式赋值的成员值开始自动递增。
“`typescript
enum HttpStatusCode {
OK = 200,
BadRequest = 400,
Unauthorized, // 401 (从 400 递增 1)
NotFound = 404,
InternalServerError // 405 (从 404 递增 1)
}
console.log(HttpStatusCode.OK); // 200
console.log(HttpStatusCode.Unauthorized); // 401
console.log(HttpStatusCode.InternalServerError); // 405
“`
你可以为 所有 成员显式赋值，甚至可以不按顺序：
typescript
enum Numbers {
One = 1,
Ten = 10,
Five = 5
}
3.3 数字枚举的编译输出与反向映射 (Reverse Mapping)
数字枚举的一个有趣特性是它在编译到 JavaScript 后，会生成一个对象，并且支持反向映射。这意味着你可以通过成员的名称获取其值，也可以通过成员的值获取其名称（作为字符串）。
考虑以下数字枚举：
“`typescript
enum Role {
Admin, // 0
Editor, // 1
Viewer // 2
}
let myRole: Role = Role.Editor; // myRole 的值是 1
console.log(myRole); // 1
let roleName: string = Role[1]; // 通过值 1 获取名称
console.log(roleName); // “Editor”
console.log(Role[Role.Admin]); // Role[0] -> “Admin”
“`
编译后的 JavaScript 代码大致如下：
javascript
var Role;
(function (Role) {
Role[Role["Admin"] = 0] = "Admin";
Role[Role["Editor"] = 1] = "Editor";
Role[Role["Viewer"] = 2] = "Viewer";
})(Role || (Role = {}));
这段代码创建了一个名为 Role 的对象。观察赋值语句 Role[Role["Admin"] = 0] = "Admin";：
1. Role["Admin"] = 0：将 Admin 作为键，0 作为值存入 Role 对象。
2. Role[0] = "Admin"：将 0 作为键，"Admin" 作为值存入 Role 对象。
这就是实现反向映射的机制。这个对象在运行时是存在的。
反向映射的注意事项：
- 反向映射只适用于数字枚举成员。
- 如果多个枚举成员具有相同的数字值，反向映射只会保留最后一个定义的值到名称的映射。例如：
typescript
enum StatusMap {
Active = 1,
Enabled = 1, // 相同的值
Disabled = 0
}
console.log(StatusMap[1]); // 输出 "Enabled" (最后一个定义为 1 的成员)
console.log(StatusMap[0]); // 输出 "Disabled"
console.log(StatusMap.Active); // 输出 1
console.log(StatusMap.Enabled); // 输出 1
3.4 计算成员 (Computed Members)
数字枚举的成员也可以是计算得出的值，但需要注意：
- 计算成员后面的所有成员必须显式赋值。
- 计算成员在运行时才会被求值。
“`typescript
function getA(): number {
return 1;
}
enum EnumWithComputed {
A = getA(), // 计算成员
B = 2, // 必须显式赋值
C // Error: Enum member must have initializer
}
enum EnumWithComputedFixed {
A = getA(), // 计算成员
B = 2,
C = 3 // 显式赋值，或者基于前面的计算成员继续显式赋值
}
“`
使用计算成员相对较少，因为它引入了运行时的不确定性，并且对后续成员的定义有限制。
4. 字符串枚举 (String Enums)
字符串枚举是 TypeScript 1.8 版本引入的。在这种枚举中，每个成员的值都必须是字符串字面量，并且必须显式赋值。
“`typescript
enum FileState {
Open = “OPEN”,
Closed = “CLOSED”,
Archived = “ARCHIVED”
}
let currentState: FileState = FileState.Open;
console.log(currentState); // 输出: “OPEN”
// 字符串枚举不能进行反向映射
// console.log(FileState[“OPEN”]); // Error 或 undefined (取决于编译设置和访问方式)
“`
4.1 字符串枚举的优点
- 更好的可读性: 运行时看到的是有意义的字符串值，而不是数字，这在调试和日志记录时非常有帮助。
- 无反向映射: 由于没有数字到名称的反向映射，生成的 JavaScript 代码通常比数字枚举更简洁，运行时开销更小。
- 类型安全: 仍然提供了严格的类型检查。
4.2 字符串枚举的编译输出
字符串枚举编译后的 JavaScript 代码只生成一个包含键值对的简单对象，没有反向映射：
typescript
enum FileState {
Open = "OPEN",
Closed = "CLOSED",
Archived = "ARCHIVED"
}
编译后大致如下：
javascript
var FileState;
(function (FileState) {
FileState["Open"] = "OPEN";
FileState["Closed"] = "CLOSED";
FileState["Archived"] = "ARCHIVED";
})(FileState || (FileState = {}));
这比数字枚举的输出更简洁。
5. 异构枚举 (Heterogeneous Enums)
异构枚举是同时包含数字和字符串成员的枚举。
“`typescript
enum Mixed {
No = 0,
Yes = “YES”
}
console.log(Mixed.No); // 0
console.log(Mixed.Yes); // “YES”
console.log(Mixed[0]); // “No” (数字成员有反向映射)
// console.log(Mixed[“YES”]); // undefined (字符串成员没有反向映射)
“`
尽管 TypeScript 支持异构枚举，但强烈不推荐使用它。它结合了数字和字符串枚举的一些行为，可能导致混淆和意外的结果。在实际开发中，通常应该只使用纯数字枚举或纯字符串枚举。
6. Const 枚举 (Const Enums)
const enum 是 TypeScript 枚举的一个特殊变体，它在编译时被完全移除，枚举成员的值被直接内联到使用它的地方。
“`typescript
const enum LogLevel {
Info, // 0
Warn, // 1
Error // 2
}
let level: LogLevel = LogLevel.Info;
if (level === LogLevel.Warn) {
// …
}
console.log(LogLevel.Error);
“`
编译后的 JavaScript 代码：
“`javascript
var level = 0 / LogLevel.Info /; // 值被直接替换了
if (level === 1 / LogLevel.Warn /) {
// …
}
console.log(2 / LogLevel.Error /); // 值被直接替换了
“`
6.1 Const 枚举的优点
- 性能优化: 由于没有生成额外的运行时对象，减少了 JavaScript 代码量，加载更快，内存占用更少。
- 更好的 tree shaking: 因为值被内联，打包工具更容易判断哪些代码是死代码并移除，进一步优化包体积。
6.2 Const 枚举的缺点
- 无运行时对象: 无法在运行时访问枚举对象本身（例如，
LogLevel变量在编译后不存在）。这意味着你不能进行反向映射 (LogLevel[0])，也不能迭代枚举成员 (Object.keys(LogLevel))。 - 限制: 只能使用常量表达式作为成员的初始化器。计算成员是不允许的，除非是字面量枚举成员。
6.3 何时使用 Const 枚举？
当你确定你只在编译时需要枚举成员的值，而不需要在运行时访问枚举对象本身或进行反向映射时，const enum 是一个非常好的选择。例如，用于条件判断、赋值或作为函数参数的字面量类型。
7. Ambient 枚举 (Ambient Enums)
环境枚举通常用于声明已经存在于 JavaScript 代码中的枚举类型，而无需 TypeScript 重新生成代码。它们主要出现在 .d.ts 声明文件中。
“`typescript
// 假设你的项目依赖了一个 JS 库，其中有一个全局变量叫做 ExistingState
// 并且它是一个包含 Active 和 Inactive 属性的对象
// 在你的 .d.ts 文件中可以这样声明：
declare enum ExistingState {
Active,
Inactive
}
// 在你的 TypeScript 代码中就可以直接使用 ExistingState 并获得类型提示
let state: ExistingState = ExistingState.Active;
“`
Ambient 枚举在使用时与普通枚举类似，但它们不会生成任何 JavaScript 代码。它们只用于提供类型信息给 TypeScript 编译器。
8. 枚举作为类型
枚举本身可以作为类型注解使用，强制变量只能被赋值为该枚举的成员。
“`typescript
enum UserStatus {
Pending,
Active,
Deactivated
}
let currentUserStatus: UserStatus = UserStatus.Active;
// 以下赋值会报错
// currentUserStatus = 100; // Error: Type ‘100’ is not assignable to type ‘UserStatus’.
// currentUserStatus = “Active”; // Error: Type ‘”Active”‘ is not assignable to type ‘UserStatus’.
“`
你也可以使用枚举成员作为更精细的类型。例如，UserStatus.Active 类型实际上就是其值（对于数字枚举是数字，对于字符串枚举是字符串字面量类型）。
“`typescript
type ActiveStatus = UserStatus.Active; // ActiveStatus 的类型是 1
let status1: ActiveStatus = UserStatus.Active; // OK
// let status2: ActiveStatus = UserStatus.Pending; // Error: Type ‘UserStatus.Pending’ is not assignable to type ‘UserStatus.Active’.
“`
9. 枚举与键类型 (keyof typeof)
在处理非 const 枚举时，你可以使用 keyof typeof 来获取枚举成员的名称作为字符串字面量联合类型。
“`typescript
enum Color {
Red = “#FF0000”,
Green = “#00FF00”,
Blue = “#0000FF”
}
// 获取枚举的所有 key (成员名称) 的联合类型
type ColorName = keyof typeof Color; // “Red” | “Green” | “Blue”
function getColorValue(name: ColorName): string {
return Color[name];
}
console.log(getColorValue(“Red”)); // “#FF0000”
// console.log(getColorValue(“Yellow”)); // Error: Argument of type ‘”Yellow”‘ is not assignable to parameter of type “Red” | “Green” | “Blue”.
“`
对于数字枚举，keyof typeof EnumName 会包含数字键和字符串键（因为反向映射）。
“`typescript
enum NumericStatus {
Success = 200,
Error = 500
}
type NumericStatusKey = keyof typeof NumericStatus;
// NumericStatusKey 的类型是 “Success” | “Error” | “200” | “500”
// 包含名称和值的字符串表示
“`
这通常在需要根据枚举名称（字符串）在运行时查找值时非常有用。注意，const enum 不能使用 keyof typeof EnumName 的方式来获取运行时字符串键，因为它在编译时不存在。
10. 枚举的运行时迭代
对于非 const 枚举（数字枚举或字符串枚举），它们在运行时是存在的对象，因此可以对其进行迭代。
10.1 迭代字符串枚举
字符串枚举对象只包含成员名称到值的映射，迭代比较直接。
“`typescript
enum Fruit {
Apple = “APPLE”,
Banana = “BANANA”,
Orange = “ORANGE”
}
console.log(“— Iterating String Enum —“);
for (const key in Fruit) {
// 使用 hasOwnProperty 确保只遍历自身的属性
if (Object.prototype.hasOwnProperty.call(Fruit, key)) {
const value = Fruit[key as keyof typeof Fruit]; // 确保 key 是有效的键
console.log(${key}: ${value});
}
}
// 输出:
// Apple: APPLE
// Banana: BANANA
// Orange: ORANGE
“`
或者使用 Object.keys() 或 Object.values() 或 Object.entries()：
typescript
console.log(Object.keys(Fruit)); // ["Apple", "Banana", "Orange"]
console.log(Object.values(Fruit)); // ["APPLE", "BANANA", "ORANGE"]
console.log(Object.entries(Fruit)); // [["Apple", "APPLE"], ["Banana", "BANANA"], ["Orange", "ORANGE"]]
10.2 迭代数字枚举
迭代数字枚举时需要小心，因为其对象包含了正向映射（名称到值）和反向映射（值到名称）。
“`typescript
enum NumericEnum {
A, // 0
B, // 1
C // 2
}
console.log(“— Iterating Numeric Enum —“);
for (const key in NumericEnum) {
if (Object.prototype.hasOwnProperty.call(NumericEnum, key)) {
const value = NumericEnum[key as keyof typeof NumericEnum];
console.log(${key}: ${value});
}
}
// 输出:
// 0: A
// 1: B
// 2: C
// A: 0
// B: 1
// C: 2
“`
可以看到，迭代包含了数字键和字符串键。通常我们只希望获取成员的名称或值列表。
-
获取成员名称列表:
typescript
const enumNames = Object.keys(NumericEnum).filter(key => isNaN(Number(key)));
console.log(enumNames); // ["A", "B", "C"]
这里通过判断键是否能转换为数字来过滤掉反向映射的数字键。 -
获取成员值列表:
“`typescript
const enumValues = Object.values(NumericEnum).filter(value => typeof value === ‘number’);
console.log(enumValues); // [0, 1, 2]// 或者使用 Object.keys().map()
const enumValuesAlt = Object.keys(NumericEnum)
.filter(key => isNaN(Number(key))) // 先过滤出名称
.map(key => NumericEnum[key as keyof typeof NumericEnum]); // 再通过名称获取值
console.log(enumValuesAlt); // [0, 1, 2]
“`
迭代非 const 枚举的能力在某些场景下很有用，例如在下拉菜单中显示所有可能的枚举值。
11. 枚举的编译细节与体积考量
前面已经简要提到了不同类型枚举的编译输出，这里再总结一下，并考虑对项目体积的影响。
- 数字枚举: 生成 IIFE (Immediately Invoked Function Expression) 包装的对象，包含正向和反向映射。运行时存在，有一定开销。
- 字符串枚举: 生成 IIFE 包装的对象，只包含正向映射。运行时存在，开销比数字枚举略小。
- Const 枚举: 在编译时被完全内联。不生成运行时代码，对项目体积贡献最小，性能最好。
选择哪种枚举类型，需要权衡可读性、类型安全、运行时访问需求以及对项目体积和性能的影响。如果只需要编译时的常量，const enum 通常是首选。如果需要在运行时根据值查找名称（反向映射）或者需要迭代枚举成员，则必须使用非 const 的数字或字符串枚举。如果需要运行时可见的字符串值（方便调试），则字符串枚举是好的选择。
12. 与替代方案的比较
在某些情况下，枚举的功能也可以通过其他 TypeScript 特性来实现。了解这些替代方案有助于你做出最佳选择。
12.1 字符串字面量联合类型 (String Literal Union Types)
对于一组固定的字符串值，可以使用联合类型代替字符串枚举。
“`typescript
// 使用枚举
enum StatusEnum {
Active = “ACTIVE”,
Inactive = “INACTIVE”
}
let status1: StatusEnum = StatusEnum.Active;
// 使用字面量联合类型
type StatusLiteral = “ACTIVE” | “INACTIVE”;
let status2: StatusLiteral = “ACTIVE”;
“`
比较:
- 类型安全: 两者都提供了强大的类型安全，限制变量只能使用预定义的值。
- 可读性/代码组织: 枚举通常更适合表示一组相关的常量集合，提供一个命名空间 (
StatusEnum.Active)。字面量联合类型更简洁，但在常量较多时可能显得冗长。 - 运行时存在: 字面量联合类型是纯类型概念，在编译后的 JavaScript 中完全不存在。枚举（非
const）在运行时存在。 -
值访问: 枚举成员可以通过
Enum.MemberName访问其值。字面量联合类型本身不是值，你通常需要配合const对象来存储这些值以便在运行时访问：“`typescript
const StatusValues = {
Active: “ACTIVE”,
Inactive: “INACTIVE”
} as const; // as const 确保属性是字面量类型且对象是只读的type StatusLiteralFromObject = typeof StatusValues[keyof typeof StatusValues]; // “ACTIVE” | “INACTIVE”
let status3: StatusLiteralFromObject = StatusValues.Active; // 或者直接 “ACTIVE”
“`
这种方式结合了字面量联合类型的类型安全和对象的运行时可访问性。 -
反向查找: 字面量联合类型本身不支持反向查找。使用
const对象时，可以通过遍历对象实现类似功能。
结论: 当你需要一组在运行时可访问、有命名空间的相关常量，并且可能需要根据名称获取值时，枚举是一个好选择。如果只是需要限制变量的值为某个字符串集合，并且不需要在运行时通过名称访问，或者愿意使用 const 对象作为值源，字面量联合类型可能更简洁。
12.2 使用 const 对象
使用 const 对象和 as const 断言是另一种替代方案，特别是与字面量联合类型结合使用时。
“`typescript
const Colors = {
Red: “#FF0000”,
Green: “#00FF00”,
Blue: “#0000FF”
} as const;
type ColorType = typeof Colors[keyof typeof Colors]; // “#FF0000” | “#00FF00” | “#0000FF”
type ColorNameType = keyof typeof Colors; // “Red” | “Green” | “Blue”
let color: ColorType = Colors.Red; // 或者直接 “#FF0000”
let colorName: ColorNameType = “Red”;
console.log(Colors.Green); // “#00FF00”
“`
比较:
- 类型安全: 结合
typeof和keyof可以达到与枚举相同的类型安全。 - 运行时存在:
const对象在运行时存在，可以通过Object.keys/values/entries迭代。 - 编译输出: 生成简单的 JavaScript 对象，通常比非
const枚举更简洁，但不如const enum直接内联。 - 反向查找: 不像数字枚举那样自动提供反向查找，需要手动实现（例如，通过遍历对象）。
- 语法: 比枚举定义稍微繁琐一些（需要定义对象、
as const、可能的type别名）。
结论: 当你需要在运行时访问常量、需要迭代，并且偏好更接近普通 JavaScript 对象的结构时，const 对象是一个有力的替代品。它提供了与字符串枚举相似的优点，并且与标准 JavaScript 对象更一致。然而，对于纯粹的编译时常量且无需运行时访问，const enum 仍是最优解。对于需要反向查找的数字常量集，数字枚举是原生支持且最方便的。
13. 最佳实践
- 选择合适的类型:
- 如果成员值本身就是有意义的数字（如 HTTP 状态码），或者你需要反向映射功能，使用数字枚举。
- 如果成员值是字符串，且希望在运行时看到有意义的字符串（便于调试/日志），或者不需要反向映射，使用字符串枚举。
- 如果只需要在编译时使用枚举成员的值作为常量（如条件判断、赋值），且不需要运行时访问枚举对象，使用
const enum以获得更好的性能和更小的代码体积。
- 避免异构枚举: 尽量只使用纯数字或纯字符串枚举。
- 命名约定: 枚举名称通常使用单数形式（如
Color而不是Colors），首字母大写（PascalCase）。枚举成员名称也通常使用首字母大写（PascalCase），或全大写（Upper_Snake_Case/AllCaps）如果它们是纯粹的、不变的常量。遵循团队或社区的约定。 - 显式赋值: 对于字符串枚举，必须显式赋值。对于数字枚举，如果从 0 开始递增符合你的意图，可以省略第一个赋值，但如果不是从 0 开始或有中断，请务必显式赋值。
- 文档注释: 为枚举及其成员添加 JSDoc 注释，说明其用途和每个成员的含义，提高代码的可维护性。
typescript
/**
* 表示用户在系统中的状态。
*/
enum UserState {
/** 用户已注册但未激活。 */
Pending = "PENDING",
/** 用户已激活，可以正常使用。 */
Active = "ACTIVE",
/** 用户已被暂停或禁用。 */
Suspended = "SUSPENDED"
}
14. 总结
TypeScript 中的枚举是一个强大且灵活的特性，用于定义一组相关的命名常量。它通过提供比硬编码数字或字符串更好的可读性、类型安全和可维护性，显著提升代码质量。
我们深入探讨了不同类型的枚举：
- 数字枚举: 默认类型，支持自动递增和反向映射，但在运行时有对象开销。
- 字符串枚举: 必须显式赋值字符串，提供更好的运行时可读性，没有反向映射，运行时开销相对较小。
- 异构枚举: 不推荐使用。
- Const 枚举: 编译时内联，无运行时开销，性能最优，但无法在运行时访问对象或进行反向映射。
- Ambient 枚举: 用于声明现有 JavaScript 代码中的枚举，不生成新代码。
了解每种枚举类型的特点、编译输出和适用场景，是正确选择和使用枚举的关键。同时，我们也比较了枚举与字面量联合类型和 const 对象等替代方案，帮助你在不同场景下做出明智的技术决策。
通过遵循最佳实践，你可以有效地在 TypeScript 项目中利用枚举，编写出更清晰、更安全、更易于维护的代码。无论是表示状态、类型、模式还是任何固定集合的常量，枚举都是一个值得优先考虑的工具。