TypeScript 中如何用 Record 和 Partial 定义对象键类型

在 TypeScript 中，对象类型的定义是日常开发的基础工作之一。当对象的键和值呈现出明显规律时，借助内置工具类型可以显著减少重复声明，让类型表达更精确、更易维护。Record和Partial是两个非常实用的工具类型，前者用于构造键值对集合，后者用于将属性变为可选。本文将分别介绍它们的基础用法，并重点说明如何将两者组合起来解决实际开发中的“固定键集合但允许部分缺失”这一常见需求。

一、Record 工具类型的基础用法

Record是 TypeScript 内置的一个映射类型，它接收两个类型参数：第一个参数Keys表示对象允许出现的键集合，第二个参数Type表示这些键对应的值的类型。使用Record可以快速构造出一个对象类型，该对象的键必须属于Keys，且每个键对应的值类型都是Type。这种定义方式特别适合键集合固定、值类型统一的场景，例如权限映射、状态字典、配置表等。

假设我们需要为系统定义一组角色权限，角色只有admin、editor、viewer三种，每个角色用一个布尔值表示是否拥有某种权限。如果手动声明对象类型，需要逐个写出所有键，代码会显得冗长。使用Record则可以将键的联合类型和值的类型一次性声明，不仅代码更简洁，而且当角色集合发生变化时，只需要修改联合类型即可。

// 定义角色类型的联合类型
type Role = 'admin' | 'editor' | 'viewer';

// 使用 Record 定义权限对象类型，键为 Role，值为 boolean
type RolePermission = Record<Role, boolean>;

// 符合类型的对象示例
const permissions: RolePermission = {
  admin: true,
  editor: true,
  viewer: false
};

作为对比，如果不使用Record，等价的类型声明会重复列举每一个键，当键的数量增多时，维护成本会明显上升。下面的代码展示了手动写法，虽然功能相同，但冗余度更高。

// 不使用 Record 的等价写法，冗余度高
type RolePermissionManual = {
  admin: boolean;
  editor: boolean;
  viewer: boolean;
};

通过上述比较可以看出，Record的核心价值在于用一个小规模的联合类型来约束对象的所有键，使类型定义与数据规则保持一致。需要注意的是，Keys必须是string、number或symbol的子类型，实际项目中最常见的是字符串联合类型。

二、Partial 工具类型的基础用法

Partial同样是一个内置工具类型，它的作用是将传入类型中的所有属性都变为可选属性。所谓可选属性，就是该属性可以存在，也可以不存在；如果存在，其值类型必须与原始类型一致。这个特性非常适合处理“部分更新”“可选配置”“初始化空对象”等场景，避免为同一数据结构维护完整版和可选版两套类型。

以用户信息为例，假设系统中定义了完整的用户信息类型，包含姓名、年龄、邮箱和地址四个字段。在用户编辑个人资料时，往往不需要一次性提交所有字段，可能只修改其中一部分。如果仍然使用完整类型，未修改的字段也必须提供，否则类型检查会报错。此时使用Partial生成一个所有字段都可选的类型，就能让对象只包含实际发生变化的字段。

// 完整的用户信息类型
type UserInfo = {
  name: string;
  age: number;
  email: string;
  address: string;
};

// 使用 Partial 生成所有属性可选的类型
type PartialUserInfo = Partial<UserInfo>;

// 只需要更新部分字段，符合 PartialUserInfo 类型
const updateInfo: PartialUserInfo = {
  name: '张三',
  age: 25
};

可以看到，变量updateInfo只提供了name和age两个属性，缺少email和address依然能够通过类型检查，这正是Partial带来的灵活性。需要注意的是，Partial只会将第一层属性变为可选，如果属性本身是嵌套对象，其内部属性不会自动变为可选；如果需要深层可选，可以自定义递归工具类型，但大多数业务场景中第一层可选已经足够。

三、Record 和 Partial 的组合使用

在实际项目中，有一类需求会同时涉及“固定键集合”和“键可以缺失”两个条件。例如某个缓存对象，键只能是预先定义的几个，如'user'、'post'、'comment'，值类型为缓存数据结构，但缓存中可能暂时没有某些键的数据。如果直接使用Record，就必须把所有键都初始化；而只用Partial又无法限制键名。将两者组合起来，就能同时满足“键集合固定”和“键可以缺失”两个条件：

type CacheKey = 'user' | 'post' | 'comment';

type CacheValue = {
  data: string;
  expireTime: number;
};

// 先限定键集合，再让所有键变为可选
type Cache = Partial<Record<CacheKey, CacheValue>>;

const cache: Cache = {
  user: { data: '用户数据', expireTime: 1712345678 },
  post: { data: '帖子数据', expireTime: 1712345688 }
  // comment 键可以完全省略
};

上面的cache对象只包含user和post，缺少comment依然合法，因为Partial把Record生成的所有键都变成了可选。这样一来，在访问不存在的键时，TypeScript 会提醒结果可能为undefined，从而强制开发者进行空值判断，避免运行时错误。

需要注意的是，Partial和Record的组合顺序不同，得到的类型含义也不同。下面这种写法表示“每个键都必须存在，但值内部的属性可以缺失”：

type RequiredKeyCache = Record<CacheKey, Partial<CacheValue>>;

const cache2: RequiredKeyCache = {
  user: { data: '用户数据' },        // expireTime 可省略
  post: { expireTime: 1712345688 }, // data 可省略
  comment: {}                        // 必须存在 comment 键，值可以为空对象
};

可以看到，Partial<Record<K, V>>解决的是“键可缺失”的问题，而Record<K, Partial<V>>解决的是“值内部可选”的问题。实际项目中应根据具体场景选择：缓存、按需加载等适合前者；配置项、表单初始值等每个键都需要出现、但值内容可能不完整时适合后者。

四、总结

TypeScript 内置的Partial、Record等工具类型本身并不复杂，但通过合理组合，可以精准描述许多真实业务中的数据结构。面对一个类型需求时，可以先明确“键是否需要固定”“键是否可能缺失”“值内部是否可能不完整”三个问题，然后选择相应的工具类型进行叠加：

• 键固定且必填：Record<Keys, Value>
• 键固定但可缺失：Partial<Record<Keys, Value>>
• 键固定且必填，但值内部可选：Record<Keys, Partial<Value>>
• 键不固定、值统一：可使用索引签名或Record<string, Value>

在实际编码中，不必一上来就定义大量重复类型，多利用这些内置工具类型，可以让类型定义更简洁、更贴近业务语义，同时减少维护成本。希望通过本文的介绍，能帮助你在项目中更灵活地运用Partial和Record，写出更健壮、更易读的 TypeScript 代码。

TypeScriptRecordPartial对象类型工具类型修改时间：2026-08-15 13:59:32