TypeScript 中如何定义具有可选键的嵌套映射类型

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

TypeScript 中如何定义具有可选键的嵌套映射类型

2025-11-22

浏览次数：次

返回列表

typescript 中如何定义具有可选键的嵌套映射类型

本文探讨了在 TypeScript 中定义具有可选键的嵌套对象类型的方法。当需要创建一个对象，其键值来源于预定义的类型集合，但并非所有可能的键都必须存在时，传统的映射类型会导致编译错误。通过引入 TypeScript 的映射修饰符 `?`，我们可以轻松地将这些键标记为可选，从而实现更灵活和健壮的类型定义。

在 TypeScript 的类型系统中，我们经常需要定义那些结构复杂、键值具有特定约束的对象。一种常见的场景是，我们希望对象的键来源于一个预定义的字符串字面量类型集合，并且可能存在嵌套结构。然而，默认情况下，使用映射类型（Mapped Types）创建的属性都是必需的。当实际对象只包含部分键时，就会导致类型检查错误。

问题背景与初始尝试

假设我们定义了两组常量，分别代表不同的类型集合：

export const ABC = {
  A: 'A',
  B: 'B',
  C: 'C',
} as const;

export const DEF = {
  D: 'D',
  E: 'E',
  F: 'F',
} as const;

// 提取字面量类型
export type AbcTypes = (typeof ABC)[keyof typeof ABC]; // 'A' | 'B' | 'C'
export type DefTypes = (typeof DEF)[keyof typeof DEF]; // 'D' | 'E' | 'F'

我们的目标是创建一个字典类型的对象 MyNewDictionary，它的第一层键必须是 AbcTypes 中的值，第二层键必须是 DefTypes 中的值，并且最内层包含 onClick 和 onCancel 方法。关键在于，我们不希望强制要求对象中包含所有可能的 AbcTypes 和 DefTypes 组合。

初次尝试的类型定义可能如下所示：

type MyNewDictionary = {
  [pKey in AbcTypes]: { // pKey 必须是 AbcTypes 中的一个
    [eKey in DefTypes]: { // eKey 必须是 DefTypes 中的一个
      onClick: () => void;
      onCancel: () => void;
    }
  }
};

当我们尝试创建一个 MyNewDictionary 类型的实际对象，但只包含部分键时，TypeScript 编译器会报错：

const dictionary: MyNewDictionary = {
  [ABC.A]: {
    [DEF.D]: {
      onClick: () => null,
      onCancel: () => null,
    }
  }
};
// 错误信息示例：
// Type '{ D: { onClick: () => null; onCancel: () => null; }; }'
// is missing the following properties from type '{ D: { onClick: () => void; onCancel: () => void; }; E: { onClick: () => void; onCancel: () => void; }; F: { onClick: () => void; onCancel: () => void; }; }'
// with properties 'E', and 'F'.

这个错误表明，尽管我们只指定了 ABC.A 下的 DEF.D，但由于 MyNewDictionary 的定义方式，TypeScript 期望 ABC.A 属性下必须包含 DEF.D、DEF.E 和 DEF.F 所有子属性。同样，如果只定义了 ABC.A，也会期望 ABC.B 和 ABC.C 也存在。

Avatar AI

AI成像模型，可以从你的照片中生成逼真的4K头像

92 查看详情 Avatar AI

解决方案：映射修饰符 ?

TypeScript 提供了映射修饰符（Mapping Modifiers）来控制映射类型中属性的可选性或只读性。其中，? 修饰符用于将属性标记为可选。

要解决上述问题，我们只需要在映射类型中的键后面添加 ?，表示该属性是可选的。对于嵌套结构，我们需要在每一层需要可选的映射键后面都添加 ?。

type MyNewDictionary = {
  [pKey in AbcTypes]?: { // 使 pKey (例如 'A', 'B', 'C') 成为可选属性
    [eKey in DefTypes]?: { // 使 eKey (例如 'D', 'E', 'F') 成为可选属性
      onClick: () => void;
      onCancel: () => void;
    }
  }
};

通过添加 ? 修饰符，我们修改了 MyNewDictionary 的行为：

[pKey in AbcTypes]? 表示 MyNewDictionary 可以包含 AbcTypes 中的任意键，但不需要包含所有键。如果某个 pKey 不存在，也是合法的。
对于每个 pKey 对应的对象 { [eKey in DefTypes]?: ... }，其内部的 [eKey in DefTypes]? 同样表示该对象可以包含 DefTypes 中的任意键，但不需要包含所有键。

现在，使用这个修正后的类型定义，我们可以灵活地创建 dictionary 对象，只包含我们需要的特定组合，而不会引发类型错误：

const dictionary: MyNewDictionary = {
  [ABC.A]: {
    [DEF.D]: {
      onClick: () => null,
      onCancel: () => null,
    }
  },
  [ABC.C]: { // 也可以只定义 ABC.C
    [DEF.F]: {
      onClick: () => console.log('C.F click'),
      onCancel: () => console.log('C.F cancel'),
    }
  }
};

// 甚至可以是一个空对象，如果没有任何键被定义
const emptyDictionary: MyNewDictionary = {};

// 也可以只定义一个顶层键，其内部为空对象（因为内层键也是可选的）
const partialDictionary: MyNewDictionary = {
    [ABC.B]: {}
};

console.log(dictionary);
console.log(emptyDictionary);
console.log(partialDictionary);

注意事项与总结

嵌套可选性： 当处理嵌套的映射类型时，如果希望内部属性也是可选的，必须在每一层映射键后都使用 ? 修饰符。Partial 实用类型只能对顶层属性起作用，对于深层嵌套的属性，需要手动应用可选修饰符或递归地使用 Partial。
其他映射修饰符： 除了 ? (可选) 之外，TypeScript 还支持 readonly (只读) 修饰符。这些修饰符也可以与 + 或 - 符号结合使用，例如 +? 明确添加可选性，-? 明确移除可选性（使属性变为必需）。默认的 ? 行为等同于 +?。
类型安全与灵活性： 映射修饰符提供了一种强大的机制，可以在保持类型安全的同时，为对象结构提供极大的灵活性，特别适用于配置对象、API 响应处理等场景，这些场景中数据结构可能不总是完整的。