解释 TypeScript 中的枚举（enum），如何使用枚举定义一组常量？

news2025/3/18 6:28:54

枚举（Enum） 是 TypeScript 中用于定义一组具名常量的核心类型，通过语义化的命名提升代码可读性，同时利用类型检查减少低级错误。

以下从定义方式、使用建议、注意事项三方面深入解析。

一、枚举的定义方式

1. 数字枚举

特性：默认从 0 开始自增，支持手动赋值，支持反向映射（通过值获取键）

// 定义用户状态枚举
enum UserStatus {
  New,       // 0
  Active,    // 1
  Blocked,   // 2
  Deleted = 404 // 手动赋值
}

// 使用示例
const currentStatus: UserStatus = UserStatus.Active;
console.log(currentStatus); // 输出: 1
console.log(UserStatus[1]); // 反向映射输出: "Active"

2. 字符串枚举

特性：每个成员必须显式初始化，无反向映射，适用于需明确语义的场景

// 定义 API 端点枚举
enum ApiEndpoint {
  Login = "/api/login",
  UserInfo = "/api/user",
  Logout = "/api/logout"
}

// 使用示例
fetch(ApiEndpoint.Login) // 发起登录请求
  .then(response => { /*...*/ });

3. 异构枚举（混合类型）

慎用：混合数字和字符串成员，易导致维护问题

enum MixedEnum {
  A = 1,
  B = "B_VALUE",
  C = 2 // 允许但容易引发混乱
}

4. 常量枚举

特性：编译后完全移除，直接内联值，适用于性能敏感场景

const enum Direction {
  Up = "UP",
  Down = "DOWN"
}

// 编译后 Direction 消失，直接替换为 "UP"/"DOWN"
console.log(Direction.Up); // 输出: "UP"

二、使用建议

1. 优先字符串枚举

理由：避免数字枚举的“魔法值”问题，明确语义且无副作用

// 推荐：字符串枚举明确表示错误类型
enum ErrorType {
  Timeout = "TimeoutError",
  Network = "NetworkError"
}

// 不推荐：数字枚举需额外注释说明
enum LegacyError {
  Timeout, // 0-超时错误
  Network  // 1-网络错误
}

2. 避免数字枚举的陷阱

问题：隐式自增可能导致意外覆盖

enum Problematic {
  A = 2,
  B,    // 3（预期外）
  C = 1,
  D     // 2（覆盖 A）
}

3. 合理使用常量枚举

场景：高频访问且无需反射的常量，如状态码

const enum HttpCode {
  OK = 200,
  NotFound = 404
}

if (response.status === HttpCode.OK) { 
  // 编译后直接替换为数字
}

4. 避免过度使用枚举

替代方案：对象常量或联合类型

// 简单键值对场景用对象
const ROLES = {
  Admin: "admin",
  User: "user"
} as const;

// 有限集合用联合类型
type LogLevel = "debug" | "info" | "error";

三、注意事项

1. 初始化顺序依赖

问题：前置成员未初始化会导致引用错误

enum Cycle {
  A = B, // Error: B 未定义
  B = 1
}

2. 运行时存在性

常量枚举：编译后消失，无法通过 Object.keys() 遍历

// 常规枚举可遍历
console.log(Object.keys(UserStatus)); // ["0", "1", "2", "404", "New", ...]

// 常量枚举在运行时不存在
console.log(Direction.Up); // 有效
console.log(Direction);    // 编译错误

3. 模块化导出规范

建议：统一导出方式避免混乱

// 正确：显式导出
export enum Color { Red = "#FF0000" }

// 正确：统一通过 constants 模块管理
export const enum Sizes { Small = "S" }

4. 避免循环引用

陷阱：跨文件枚举相互引用导致未定义

// file1.ts
import { SecondEnum } from "./file2";
export enum FirstEnum { A = SecondEnum.B }

// file2.ts
import { FirstEnum } from "./file1";
export enum SecondEnum { B = FirstEnum.A } // 循环依赖报错