企业官网建设流程全解析

• 文档
• 教程

类型索引（Type Indexing）是 TypeScript 类型系统中用于描述“键事先未知、结构却必须受控”的对象的基石能力。本文以《The Concise TypeScript Book》中 type-indexing.md 为核心，完整讲解索引签名（Index Signature）的语法、string/number/symbol 三种键类型的行为差异、与泛型及Record工具类型的组合方式，并结合本仓库的同系列章节（index-signatures.md、type-manipulation.md、others.md）进行源码级纵深扩充。读完你将能够：为任意键数量的对象声明安全类型、通过Type[Key]提取属性类型、用模板字符串模式索引签名限定键的形态，以及在字典、配置表、JSON 树等实战场景中正确选用类型索引。

什么是类型索引（Type Indexing）

在 TypeScript 中，普通对象类型的每个属性都必须显式声明，例如：

type Config = { host: string; port: number; };

但如果对象的键在编写代码时无法预知——比如一张以任意字符串为键的字典、以用户 ID 为键的映射表、或来自外部数据的动态配置——显式声明就无能为力了。此时需要类型索引（Type Indexing）：它指的是"定义一类可以被事先未知的键所索引的类型"的能力，通过**索引签名（Index Signature）**为那些没有被显式声明的属性指定统一类型。

仓库中的原始文档给出了最经典的定义与示例（type-indexing.md）：

type Dictionary<T> = { [key: string]: T; }; const myDict: Dictionary<string> = { a: 'a', b: 'b' }; console.log(myDict['a']); // Retorna a

逐行拆解这段代码：

• [key: string]是索引签名的语法：方括号内先写一个任意取名的键变量（这里是key），后跟它的类型string，表示"该类型允许出现任意数量的、以字符串为键的属性"；
• : T声明这些动态键的属性值类型统一为泛型参数T；
• Dictionary<string>实例化后，myDict中的每个属性都必须是string类型，因此{ a: 'a', b: 'b' }合法，而{ a: 1 }会在编译期报错；
• 运行时访问与普通对象完全一致：myDict['a']输出a。

这里Dictionary<T>是"泛型 + 类型索引"结合的典型形态：泛型负责让字典的值类型可复用，索引签名负责让键的数量不受限制。两者叠加，就得到了 TypeScript 世界中最常用的"通用字典"建模工具。

索引签名的键类型：string、number 与 symbol

并非只有string可以作为索引签名。依据仓库 index-signatures.md 的说明，TypeScript 支持三种键类型：string、number和symbol：

type K = { [name: string | number]: string; }; const k: K = { x: 'x', 1: 'b' }; console.log(k['x']); console.log(k[1]); console.log(k['1']); // Mesmo resultado que k[1]

这段示例有三个值得注意的细节：

1. 索引签名键可以声明为联合类型：[name: string | number]表示对象的键可以是字符串也可以是数字，对应的属性值统一为string；
2. 数字键会被 JavaScript 自动转换为字符串键：如 index-signatures.md 所强调，JavaScript 对象键本质都是字符串（或 Symbol），因此k[1]、k['1']访问的是同一个属性，返回值完全相同；
3. symbol是第三种合法键类型：从 TypeScript 4.4 开始，索引签名支持symbol，通常与模板字符串模式结合使用（见下文）。

这种"键类型即约束"的机制，源于 JavaScript 运行时的对象语义：属性访问最终都会走字符串键或 Symbol 键路径。TypeScript 只是把这种动态行为提升到了类型层面，让编译器可以在键未知的情况下依然校验值类型。

数字索引 vs 字符串索引的常见误区

正因为数字键会被转成字符串，实践中要避免一个经典误判——以为"数字索引"会限制键必须是整数。实际上：

type Lookup = { [index: number]: string; }; const table: Lookup = { 0: 'zero', 1: 'one' };

[index: number]允许的键范围与[key: string]基本等价（因为1和'1'指向同一属性），区别主要在于语义表达：数字索引通常用于描述"类数组/以位置为键"的数据，字符串索引用于描述一般字典。理解 JavaScript 的自动转换行为，才能避免写出假设数字键与字符串键互相隔离的错误代码。

用泛型 + 索引签名实现可复用的字典工具

类型索引最强的用法之一，是把它封装进泛型类型里反复使用。除了原始文档中的Dictionary<T>，TypeScript 标准库还内置了等价的工具类型Record<K, T>，仓库 type-manipulation.md 给出了它的实战用法：

type Product = { name: string; price: number; }; const products: Record<string, Product> = { apple: { name: 'Apple', price: 0.5 }, banana: { name: 'Banana', price: 0.25 }, }; console.log(products.apple); // { name: 'Apple', price: 0.5 }

Record<K, T>本质就是{ [k in K]: T }的映射类型封装：K限定键的集合（可以是string、number或字面量联合类型），T限定值的类型。与手写索引签名相比，Record<K, T>的优势是：

• 意图更明确，代码更简洁；
• K可以是任意键集合，包括有限的字面量联合类型，从而兼具"枚举键"与"统一值类型"两种约束；
• 与泛型组合时无需再自建Dictionary<T>这样的工具。

值得注意的是，索引签名描述的是"键集合无限"的对象，而Record<K, T>在K为有限联合时描述的是"键集合确定"的对象，二者适用场景不同：

索引访问类型（Indexed Access Types）：Type[Key]

"类型索引"还有另一层含义：用索引从既有类型中"取出"某个属性的类型，语法是Type[Key]。仓库 type-manipulation.md 对此有专门讲解：

type Person = { name: string; age: number; }; type AgeType = Person['age']; // number

这里的Person['age']就是在类型层面执行"索引访问"，其结果就是属性age的类型number。该语法同样适用于元组，按位置取元素类型：

type MyTuple = [string, number, boolean]; type MyType = MyTuple[2]; // boolean

索引访问类型可以继续与泛型、索引签名组合，形成类型体操的常用套路：

type ValueType<T> = T[keyof T]; // 取出 T 中所有属性值类型的联合

其底层原理与索引签名同源：既然对象可以用string/number键索引取值，类型系统也允许用同样的索引语法从对象类型中取"值的类型"。理解这一点，就能把"运行时取值"与"编译期取类型"两套行为一一对应起来，这也是Record、Pick、Omit等工具类型的实现基础。

模板字符串模式索引签名：给键加上形态约束

从 TypeScript 4.4 起，索引签名支持模板字符串模式（Template String Pattern），允许把键约束在某种字符串形态之内。仓库 others.md 提供了完整示例：

const uniqueSymbol = Symbol('description'); type MyKeys = `key-${string}`; type MyObject = { [uniqueSymbol]: string; [key: MyKeys]: number; }; const obj: MyObject = { [uniqueSymbol]: 'Unique symbol key', 'key-a': 123, 'key-b': 456, }; console.log(obj[uniqueSymbol]); // Unique symbol key console.log(obj['key-a']); // 123 console.log(obj['key-b']); // 456

这段代码同时展示了 TypeScript 4.4 引入的两项能力：

1. 模板字符串模式索引签名：[key: \key-${string}`]只允许key-a、key-b这类以key-开头、后接任意字符串的键，值类型为number。若试图写入other: 1，编译器会报错——比裸[key: string]` 精确得多；
2. symbol索引签名：[uniqueSymbol]: string用具体 Symbol 作为键，与模板模式索引共存于同一类型中。这解决了"既要有限制的字符串键，又要特殊 Symbol 键"的建模需求。

这种"受限键"的类型索引，特别适合表示事件注册表、插件系统或带前缀的配置项——键的形态本身成为类型约束的一部分。

类型索引在递归类型与 JSON 建模中的应用

索引签名是构造递归类型的关键原料。仓库 others.md 中的 JSON 类型是最经典的例子：

type Json = string | number | boolean | null | Json[] | { [key: string]: Json }; const data: Json = { prop1: true, prop2: 'prop2', prop3: { prop4: [], }, };

{ [key: string]: Json }允许任意深度嵌套：每一层对象的键都是字符串，值仍是Json本身，从而以无限递归的方式覆盖了任意 JSON 结构。这正是类型索引之于树形/递归数据建模的意义——没有索引签名，就无法表达"结构未知但类型受控"的递归节点。

同文件中的Flatten<T>递归条件类型（others.md）也建立在这一思想之上：类型层面通过T extends Array<infer U>递归展开嵌套数组，与运行时递归遍历结构遥相呼应。

类型索引的边界与注意事项

索引签名与显式属性共存

索引签名与显式声明的属性可以写在同一类型中，但显式属性的类型必须是索引签名值类型的子类型：

type Dictionary = { [key: string]: string | number; // 索引值类型 fixed: number; // 显式属性，是 string | number 的子类型，合法 };

若显式属性类型超出索引值类型（例如fixed: boolean），编译器会报错，因为索引签名要求"所有未被声明键的属性"都满足统一类型。

弱类型检查与 unknown 索引

当对象类型只包含可选属性时，TypeScript 会将其判定为"弱类型"（Weak Type），拒绝赋入毫无重叠属性的对象。仓库 exploring-the-type-system.md 给出了绕过方式——向弱类型中添加unknown索引签名：

type Options = { [prop: string]: unknown; a?: string; b?: string; }; const fn = (options: Options) => undefined; fn({ c: 'c' }); // Valid

这里[prop: string]: unknown表示"允许任意未声明键，值类型为 unknown"，既保留了类型安全（访问未声明属性得到unknown，仍需收窄后才可使用），又绕过了弱类型检查的限制。

不要滥用索引签名

索引签名放宽了属性约束，代价是丧失了对具体属性的类型检查（拼写错误、多余属性都会被放过）。因此实践中应遵循：

• 结构已知的对象优先使用显式声明或字面量联合的Record；
• 只有键集合确实无限/未知时，才使用[key: string]索引签名；
• 需要进一步收窄键形态时，优先考虑模板字符串模式索引签名（TS 4.4+）。

小结

类型索引（Type Indexing）是 TypeScript 动态键建模的核心能力，贯穿字典类型、Record、索引访问类型、模板字符串模式索引签名与递归 JSON 类型等大量场景。掌握它需要同时理解三件事：索引签名[key: string]: T声明"未知键 + 统一值类型"；Type[Key]在类型层面按索引取属性类型；键类型（string/number/symbol）及数字键转字符串键的 JS 运行时行为决定了索引签名的实际语义。结合本仓库 type-indexing.md、index-signatures.md、type-manipulation.md 与 others.md 中的示例逐条验证，即可在真实项目中安全、精确地建模任意形态的动态对象。

• 文档
• 教程