JavaScript / TypeScript / 系统课时
索引签名
索引签名
本课解决对象键名在编写代码时无法全部预先列出的问题。索引签名可以约束动态属性的键和值类型,适合库存表、计数器和按标识符索引的数据集合。
学习目标
- 使用字符串索引签名描述动态属性
- 理解显式属性与索引值类型的兼容要求
- 判断何时改用
Record或更精确的键联合
声明动态键
字符串索引签名写作 [key: string]: ValueType。它表示任意字符串属性都必须具有指定值类型,而不是表示对象一定拥有所有字符串键。
例如 { [sku: string]: number } 允许任意 SKU 作为属性名,但每个库存值都必须是数字。
主示例
// 允许任意 SKU,但数量必须保持数值类型
type Inventory = {
[sku: string]: number;
};
function totalStock(inventory: Inventory): number {
return Object.values(inventory).reduce(
(total, quantity) => total + quantity,
0
);
}
const inventory: Inventory = {
"sku-1001": 8,
"sku-1002": 5,
"sku-1003": 2
};
console.log(totalStock(inventory));预期输出:
15如果某个属性值写成字符串,例如 "sku-1001": "8",类型检查会失败,因为它不符合索引签名规定的 number。
关键边界
对象同时声明固定属性和字符串索引签名时,固定属性的类型也必须能赋给索引值类型。例如 { [name: string]: number; total: number } 合法,而把 total 改为字符串会产生冲突。
当键集合已知时,优先使用 Record 和字面量联合。例如 type ServiceUrls = Record<"dev" | "test" | "prod", string> 会要求三个环境键全部存在,并拒绝其他键。
若项目开启 noUncheckedIndexedAccess,读取未知动态键时会得到包含 undefined 的类型,调用方需要先判断该键是否真的存在。
缺键与输入校验
库存对象可能没有某个 SKU,索引签名不会自动补出零库存。先把读取结果保存在局部变量,再用空值判断决定是按零处理还是报“未知商品”;不要把不存在与实际库存为零混为一谈。开启 noUncheckedIndexedAccess 后,这条运行时边界也能体现在类型检查里。
有限键的 Record 要求已知键完整,但“拒绝其他键”主要体现为新鲜对象字面量的多余属性检查,并不意味着运行时对象永远没有额外字段。来自接口的库存应先校验每个数量是有限数、是否允许负数,再交给 totalStock;TypeScript 类型不会自动校验 JSON。
验证时保留三个对照:当前数据总量为 15,空对象总量为 0,把某个数量改为字符串应出现编译错误。业务若允许缺失值,应在类型里表达 undefined,而不是在计算失败后用断言压掉报错。需要频繁增删任意外部键时,也可评估 Map,避免普通对象原型键带来的歧义。
独立验证
使用 TypeScript 5.9.3 和 Node.js 22 检查本节。库存示例应得到总量 15;再把输入替换为空对象,确认得到 0。将库存量临时改成字符串,应在编译阶段被拒绝。把主示例保存为独立目录的 main.ts,执行 npx tsc main.ts --strict --target ES2022 --module commonjs --outDir dist,预期退出码为 0;再执行 node dist/main.js 核对上述结果。说明性片段按其上下文编译,练习目录保持 CommonJS 模块约定。