TypeScript 中如何限制对象键名的取值范围

作者：小括号时间：2026-10-24 11:24:10浏览：644

本文详解在 TypeScript 中限制对象键名取值范围的两种核心方法。首先介绍使用枚举（Enum）定义键名，确保数据纯粹性；其次探讨利用 const assertions 结合 typeof 和 keyof 生成联合类型，实现更灵活的键名约束。文章对比了不同方案的语义化程度及编辑器支持情况，帮助开发者选择最佳实践。

在使用 TypeScript 开发时，充分利用其类型系统来约束代码的各个细节是常见需求，其中自然也包括对对象键名（key）的限制。

例如，假设我们需要构建一个对象来存储各个年级的学生姓名，其基础类型定义可能如下所示。


type Students = Record<string, string[]>;

对应的数据实例通常表现为标准的键值对结构。


const students: Students = {
  Freshman: ["David", "John"],
  sophomore: [],
  Junior: ["Lily"],
  Senior: ["Tom"],
};

利用枚举限制对象键名

上述类型定义存在一个潜在问题：年级实际上是有限且固定的几种取值，但对象允许任意添加属性，这导致数据结构不够严谨。

为了解决这个问题，我们可以引入枚举（Enum）来明确列出所有合法的键名取值。


export enum Grade {
  Freshman,
  sophomore,
  Junior,
  Senior,
}

接下来，将对象的键名类型约束为上述枚举类型即可。


- type Students = Record<string, string[]>;
+ type Students = Record<Grade, string[]>;

此时，数据的书写方式需要配合枚举的使用进行调整。


const students: Students = {
  [Grade.Freshman]: ["David", "John"],
  [Grade.sophomore]: [],
  [Grade.Junior]: ["Lily"],
  [Grade.Senior]: ["Tom"],
  // ❌ Object literal may only specify known properties, and 'blah' does not exist in type 'Students'.ts(2322)
  blah: ["some one"],
};

通过这种方式，我们成功限制了对象键名的范围。如果尝试添加枚举中未定义的键名，TypeScript 编译器会报错，从而保证数据的纯粹性。

优化枚举值的语义化

然而，上述方案仍有改进空间。因为默认枚举值是从 0 开始的数字，直接作为键名使用时语义不够清晰，这在访问对象属性时尤为明显。

利用枚举限制对象键名

我们可以修正枚举定义，使用更具语义的文本字符串作为枚举值。


export enum Grade {
  Freshman = "Freshman",
  sophomore = "sophomore",
  Junior = "Junior",
  Senior = "Senior",
}

修改后，使用该枚举访问属性时，得到的将是清晰的字符串而非无意义的数字。

利用枚举限制对象键名

如果项目需要，枚举值甚至可以使用中文。


export enum Grade {
  Freshman = "大一萌新",
  sophomore = "大二学弟",
  Junior = "大三学妹",
  Senior = "大四老司机",
}

在实际使用中，这种方式同样没有任何问题。

利用枚举限制对象键名

处理可选键值

前面的类型定义还有一个局限：它要求对象必须包含枚举中的所有键。例如，sophomore 这个年级可能没有学生，此时不写该键会报错。


// ❌ Property 'sophomore' is missing in type '{ Freshman: string[]; Junior: string[]; Senior: string[]; }' but required in type 'Students'.ts(2741)
const students: Students = {
  [Grade.Freshman]: ["David", "John"],
  // [Grade.sophomore]: [],
  [Grade.Junior]: ["Lily"],
  [Grade.Senior]: ["Tom"],
};

因此，我们可以将类型优化为可选状态。


type Students = Partial<Record<Grade, string[]>>;

假设这些可选值并非通过枚举定义，而是来源于一个普通数组。


const grades = ["Freshman", "sophomore", "Junior", "Senior"];

这意味着我们需要从数组中提取值，形成一个联合类型（Union Type）。

首先，利用 const assertions 将数组转换为元组（Tuple）类型，以保留具体的字符串值。


const grades = <const>["Freshman", "sophomore", "Junior", "Senior"];

接着，利用 typeof 操作符和查找类型（Lookup Types）特性，提取出最终的联合类型。


// 实际为 type Keys = "Freshman" | "sophomore" | "Junior" | "Senior"
type Keys = typeof grades[number];

最终的数据类型和实例定义如下所示。


type Students = Partial<Record<Keys, string[]>>;

const students: Students = {
  Freshman: ["David", "John"],
  Junior: ["Lily"],
  Senior: ["Tom"],
};

需要注意的是，在这种形式下，对象的 key 与原数组中的元素在语法层面并没有直接关联，这意味着编辑器的“跳转定义”功能可能不可用。

利用枚举限制对象键名

为了充分发挥 TypeScript 的优势，尽量保持代码间的逻辑关联是更好的实践。因此，对于这种仅具备类型约束而无法建立实际关联的操作，通常不建议采用。