本教程旨在解决在 typescript 中定义对象类型时遇到的一个常见问题：如何确保对象的键来源于一个预定义的集合，但同时允许这些键是可选的，而非全部强制存在。文章将深入探讨如何结合使用映射类型（mapped types）和可选修饰符（?），以创建灵活且类型安全的对象结构，从而避免因缺少非必需属性而导致的编译错误。
在 TypeScript 开发中，我们经常需要定义具有特定结构的对象，其中对象的键值（key）必须限定在某个预设的枚举或字符串集合中。然而，一个常见的挑战是，我们可能不希望对象必须包含该集合中的所有键，而是允许它们是可选的。本文将详细介绍如何利用 TypeScript 的映射类型（Mapped Types）和可选修饰符（Mapping Modifiers）来优雅地解决这一问题。
定义基础类型集合
首先，我们定义两个常量对象，它们将作为我们对象键的来源。使用 as const 可以确保 TypeScript 推断出最窄的字面量类型，而不是宽泛的 string 类型。
export const ABC = {
A: 'A',
B: 'B',
C: 'C',
} as const;
export const DEF = {
D: 'D',
E: 'E',
F: 'F',
} as const;接下来，我们基于这些常量对象创建联合类型（Union Types），这些联合类型将精确地表示允许的键值。
export type AbcTypes = (typeof ABC)[keyof typeof ABC]; // 类型为 'A' | 'B' | 'C' export type DefTypes = (typeof DEF)[keyof typeof DEF]; // 类型为 'D' | 'E' | 'F'
AbcTypes 和 DefTypes 现在分别是 ABC 和 DEF 对象中所有值组成的字面量联合类型。
初始尝试与遇到的问题
我们的目标是创建一个字典类型 MyNewDictionary，它的第一层键来自 AbcTypes，第二层键来自 DefTypes。每个最内层对象都包含 onClick 和 onCancel 两个函数。
一种直观的定义方式是使用映射类型：
type MyNewDictionaryAttempt = {
[pKey in AbcTypes]: {
[eKey in DefTypes]: {
onClick: () => void;
onCancel: () => void;
}
}
};然而，当我们尝试创建一个 MyNewDictionaryAttempt 类型的对象实例，并且只赋值了部分键时，TypeScript 编译器会报错：
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
const dictionaryAttempt: MyNewDictionaryAttempt = {
[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; }; }'
*/这个错误表明，尽管我们只为 ABC.A 下的 DEF.D 属性赋了值，但 MyNewDictionaryAttempt 类型要求 ABC.A 下必须包含 DEF.E 和 DEF.F，同样，整个 dictionaryAttempt 对象也必须包含 ABC.B 和 ABC.C。这是因为默认情况下，映射类型会创建所有属性都为必需（mandatory）的新类型。
解决方案：使用可选修饰符 ?
要解决这个问题，我们需要引入 TypeScript 的映射修饰符（Mapping Modifiers）。具体来说，使用 ? 修饰符可以将映射类型生成的属性标记为可选（optional）。
我们将 MyNewDictionaryAttempt 类型修改为 MyNewDictionary，在每个映射类型的键后面添加 ?：
type MyNewDictionary = {
[pKey in AbcTypes]?: { // 外层键现在是可选的
[eKey in DefTypes]?: { // 内层键现在也是可选的
onClick: () => void;
onCancel: () => void;
}
}
};通过在 [pKey in AbcTypes] 和 [eKey in DefTypes] 后面分别添加 ?，我们告诉 TypeScript：
- MyNewDictionary 对象可以包含 AbcTypes 中的任意键，但不需要全部包含。
- 对于 AbcTypes 中的每个键（例如 ABC.A），其对应的值（一个对象）可以包含 DefTypes 中的任意键，但同样不需要全部包含。
现在，我们可以按照预期创建对象实例，只包含我们需要的属性，而不会引发编译错误：
const dictionary: MyNewDictionary = {
[ABC.A]: {
[DEF.D]: {
onClick: () => console.log('A.D clicked'),
onCancel: () => console.log('A.D cancelled'),
},
// DEF.E 和 DEF.F 在这里是可选的，可以不写
},
[ABC.C]: { // ABC.B 也是可选的，可以不写
[DEF.F]: {
onClick: () => console.log('C.F clicked'),
onCancel: () => console.log('C.F cancelled'),
}
}
};
// 尝试访问存在的属性
if (dictionary[ABC.A]?.[DEF.D]) {
dictionary[ABC.A][DEF.D]?.onClick(); // 输出: A.D clicked
}
// 尝试访问不存在的属性（类型安全地处理 undefined）
console.log(dictionary[ABC.B]?.D?.onClick); // 输出: undefined总结与注意事项
- 映射类型 (Mapped Types): 允许你基于现有类型创建新类型，通过遍历一个联合类型或字面量类型的所有成员来生成新的属性。语法是 {[Key in UnionType]: ValueType}。
- 可选修饰符 (?): 在映射类型中使用 ? ({[Key in UnionType]?: ValueType}) 可以将生成的属性标记为可选。这意味着在创建该类型的对象时，这些属性可以被省略。
- as const 的重要性: 使用 as const 确保 TypeScript 推断出最具体的字面量类型，这对于创建精确的联合类型（如 AbcTypes）至关重要，从而使映射类型能够正确地工作。
- 嵌套可选性: 当处理嵌套对象时，如果希望内层属性也是可选的，需要在内层映射类型中也使用 ? 修饰符。
- 其他映射修饰符: 除了 ? (可选)，还有 -? (必需)，readonly (只读)，和 -readonly (可写) 等修饰符，可以根据需求灵活组合使用。
通过掌握映射类型和可选修饰符，你可以在 TypeScript 中创建出更加灵活、健壮且类型安全的对象结构，有效管理复杂的配置或数据字典，同时避免不必要的强制性属性检查。
