Vue+TypeScript 枚举（Enum）的使用规范

发布于：2025-06-18 ⋅ 阅读:(17) ⋅ 点赞:(0)

在 TypeScript 中，枚举（Enum）的命名应遵循以下规范，这些规范结合了 TypeScript 官方建议和行业最佳实践：

枚举命名规范（TypeScript/Vue 项目）

  1. 基本命名规则：

    • 使用 PascalCase（大驼峰式） 命名枚举类型

    • 枚举成员使用 UPPER_SNAKE_CASE（全大写+下划线）

    • 避免使用复数形式（枚举表示一组相关常量，不是集合）

typescript

复制

下载

// ✅ 正确示例
export enum UserStatus {
  ACTIVE = "ACTIVE",
  INACTIVE = "INACTIVE",
  PENDING_VERIFICATION = "PENDING_VERIFICATION"
}

export enum HttpStatusCode {
  OK = 200,
  BAD_REQUEST = 400,
  NOT_FOUND = 404
}

  1. 语义化命名原则：

    • 使用名词+状态/类型的组合

    • 包含明确的上下文信息

    • 避免通用名称（如 Status, Type）

typescript

复制

下载

// ✅ 推荐（包含上下文）
export enum OrderPaymentStatus {
  UNPAID = "UNPAID",
  PARTIALLY_PAID = "PARTIALLY_PAID",
  PAID = "PAID",
  REFUNDED = "REFUNDED"
}

// ❌ 避免（过于通用）
export enum Status {
  ACTIVE = 1,
  DISABLED = 0
}

  1. 项目中的最佳实践：

    • 统一前缀（可选）：对相关枚举使用相同前缀

    • 文件组织：将枚举放在 /src/enums/ 目录

    • 导出规范：使用命名导出（非默认导出）

typescript

复制

下载

// /src/enums/user.enum.ts
export enum UserRole {
  ADMIN = "ADMIN",
  EDITOR = "EDITOR",
  VIEWER = "VIEWER"
}

export enum UserAccountType {
  STANDARD = "STANDARD",
  PREMIUM = "PREMIUM",
  ENTERPRISE = "ENTERPRISE"
}

  1. Vue 组件中的使用规范：

    • 在 <script setup> 中直接导入

    • 模板中使用带命名空间的枚举值

vue

复制

下载

<script setup lang="ts">
import { UserRole } from '@/enums/user.enum'

const currentRole = UserRole.ADMIN
</script>

<template>
  <div v-if="currentRole === UserRole.ADMIN">
    <!-- 管理员内容 -->
  </div>
</template>

  1. 字符串 vs 数字枚举：

    • 优先使用 字符串枚举（更好的可读性和调试体验）

    • 数字枚举仅用于性能关键场景或位运算

typescript

复制

下载

// ✅ 字符串枚举（推荐）
export enum Direction {
  UP = "UP",
  DOWN = "DOWN",
  LEFT = "LEFT",
  RIGHT = "RIGHT"
}

// ⚠️ 数字枚举（特定场景使用）
export enum FilePermission {
  READ = 1,       // 0001
  WRITE = 2,      // 0010
  EXECUTE = 4     // 0100
}

  1. 常量枚举注意事项：

    • 使用 const enum 仅适用于性能敏感场景

    • 会完全移除运行时代码，影响调试

typescript

复制

下载

// ❌ 常规项目慎用（无法在运行时访问）
const enum SecretCodes {
  KEY1 = 0xABC,
  KEY2 = 0xDEF
}

// ✅ 普通枚举更安全
export enum ApiKeys {
  CLIENT_ID = "AK_123456",
  SECRET = "SK_789012"
}

命名禁忌

  1. 避免的行为：

    typescript

    复制

    下载

    // ❌ 混合大小写
enum badNaming {
  mixedCase = 1  // 避免
}

// ❌ 单数形式表示集合
enum Color {
  RED, GREEN, BLUE  // 应命名为 Colors?
}

// ❌ 动词命名
enum ProcessData {  // 枚举应是状态描述
  START, STOP       // 而非动作
}

  2. 不要重复前缀：

    typescript

    复制

    下载

    // ❌ 冗余前缀
enum UserUserRole {  // User 重复
  USER_ADMIN,
  USER_EDITOR
}

// ✅ 简洁命名
enum UserRole {
  ADMIN,
  EDITOR
}

项目一致性建议

  1. 在项目中建立 enums 目录集中管理

  2. 添加 ESLint 规则强制枚举命名规范：

    json

    复制

    下载

    // .eslintrc.json
{
  "rules": {
    "@typescript-eslint/naming-convention": [
      "error",
      {
        "selector": "enum",
        "format": ["PascalCase"],
        "prefix": ["Enum"] // 可选前缀
      },
      {
        "selector": "enumMember",
        "format": ["UPPER_CASE"]
      }
    ]
  }
}

遵循这些规范能显著提升代码可读性和维护性，尤其在团队协作的 Vue+TypeScript 项目中。

在 Vue 3 + TypeScript 项目中，enums 目录的常规结构通常遵循模块化和可维护性原则。以下是典型的组织结构和最佳实践：

标准目录结构示例

text

复制

下载

src/
├── enums/                   # 枚举根目录
│   ├── system/              # 系统级枚举
│   │   ├── http.enum.ts     # HTTP 状态码枚举
│   │   ├── error-codes.enum.ts
│   │   └── index.ts         # 统一导出
│   │
│   ├── business/            # 业务相关枚举
│   │   ├── order-status.enum.ts
│   │   ├── payment-method.enum.ts
│   │   └── index.ts
│   │
│   ├── user/                # 用户相关枚举
│   │   ├── user-role.enum.ts
│   │   ├── user-status.enum.ts
│   │   └── index.ts
│   │
│   ├── ui/                  # UI/组件相关枚举
│   │   ├── button-variant.enum.ts
│   │   ├── notification-type.enum.ts
│   │   └── index.ts
│   │
│   ├── shared/              # 跨模块通用枚举
│   │   ├── date-formats.enum.ts
│   │   ├── country-codes.enum.ts
│   │   └── index.ts
│   │
│   └── index.ts             # 总入口文件（可选）

关键实践说明

  1. 分类组织

    • 按功能域分组：系统、业务、用户、UI 等

    • 按模块分组：适合大型项目（如 auth/, order/, product/）

    • 通用共享枚举：放在 shared/ 目录

  2. 文件命名规范

    • 使用 *.enum.ts 后缀明确文件类型

    • 短横线命名：order-status.enum.ts

    • 枚举名与文件名一致（PascalCase）：

      typescript

      复制

      下载

      // order-status.enum.ts
export enum OrderStatus {
  PENDING = "PENDING",
  PROCESSING = "PROCESSING",
  SHIPPED = "SHIPPED"
}

  3. 索引文件（index.ts）
    每个子目录使用 index.ts 统一导出：

    typescript

    复制

    下载

    // system/index.ts
export * from './http.enum';
export * from './error-codes.enum';

  4. 总入口文件（可选）

    typescript

    复制

    下载

    // enums/index.ts
export * as SystemEnums from './system';
export * as BusinessEnums from './business';
export * as UserEnums from './user';

使用场景示例

组件中使用

vue

复制

下载

<script setup lang="ts">
// 按需导入（推荐）
import { OrderStatus } from '@/enums/business/order-status.enum';

// 通过索引文件导入
import { UserRole } from '@/enums/user';
</script>
统一导入方式

typescript

复制

下载

// 通过总入口导入（适合频繁使用的枚举）
import { SystemEnums, UserEnums } from '@/enums';

console.log(SystemEnums.HttpStatus.OK); // 200
console.log(UserEnums.UserRole.ADMIN);  // "ADMIN"

高级组织结构

方案 1：按业务模块划分（推荐）

text

复制

下载

enums/
├── order/
│   ├── status.enum.ts
│   ├── payment-type.enum.ts
│   └── index.ts
├── product/
│   ├── category.enum.ts
│   ├── availability.enum.ts
│   └── index.ts
└── auth/
    ├── permission.enum.ts
    └── index.ts
方案 2：按枚举类型划分

text

复制

下载

enums/
├── numeric/
│   ├── http-status.enum.ts
│   └── error-codes.enum.ts
├── string/
│   ├── user-roles.enum.ts
│   └── order-status.enum.ts
└── const/
    ├── ui-variants.enum.ts
    └── icon-types.enum.ts

最佳实践建议

  1. 单一职责原则

    • 每个文件只包含 1 个主要枚举（相关辅助枚举可共存）

    • 避免创建包含多个无关枚举的 "global.enum.ts"

  2. 树摇优化

    typescript

    复制

    下载

    // 避免默认导出（影响 tree-shaking）
// ❌ 不推荐
export default enum Status { ... }

// ✅ 推荐使用命名导出
export enum OrderStatus { ... }

  3. 常量枚举处理
    对于 const enum，创建单独目录或添加注释：

    typescript

    复制

    下载

    // system/const-enums/
// 或添加特殊后缀
export const enum CacheKeys {
  USER_PROFILE = "user_profile",
  APP_CONFIG = "app_config"
}

  4. 自动生成枚举
    如果使用 OpenAPI 等工具生成：

    text

    复制

    下载

    enums/
├── generated/  # 自动生成的枚举
│   ├── api-models.enum.ts
│   └── ...
└── manual/     # 手动维护的枚举
    ├── ui.enum.ts
    └── ...

典型文件示例

用户角色枚举 (enums/user/user-role.enum.ts)

typescript

复制

下载

export enum UserRole {
  /** 系统管理员 */
  ADMIN = "ADMIN",
  
  /** 内容编辑者 */
  EDITOR = "EDITOR",
  
  /** 普通查看用户 */
  VIEWER = "VIEWER",
  
  /** 访客（未登录用户） */
  GUEST = "GUEST"
}

// 类型导出（方便同时作为类型使用）
export type UserRoleType = `${UserRole}`;

HTTP 状态枚举 (enums/system/http.enum.ts)

typescript

复制

下载

export enum HttpStatus {
  OK = 200,
  CREATED = 201,
  BAD_REQUEST = 400,
  UNAUTHORIZED = 401,
  FORBIDDEN = 403,
  NOT_FOUND = 404,
  INTERNAL_SERVER_ERROR = 500
}

// 状态码描述映射
export const HttpStatusMessage: Record<HttpStatus, string> = {
  [HttpStatus.OK]: "请求成功",
  [HttpStatus.CREATED]: "资源创建成功",
  // ...其他描述
};

目录结构选择建议

项目规模 推荐结构 特点
小型项目 平铺结构 (enums/*.enum.ts) 简单直接，无需嵌套
中型项目 功能域分组 平衡查找效率和组织结构
大型项目 业务模块分组 与功能模块对齐，便于跨团队协作
对接后端API 混合结构（生成+手动） 分离自动生成和自定义枚举

这种组织方式确保：

  1. 快速定位枚举定义

  2. 避免命名冲突

  3. 支持按需加载

  4. 保持类型系统完整性

  5. 便于维护和扩展

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布