JavaScript / TypeScript / 系统课时
声明索引签名
声明索引签名
当对象的键来自用户名称、商品编号或配置项时,无法逐个写出属性名。索引签名可以统一约束这些动态键的值类型,同时要求已知属性也遵守同一访问规则。
学习目标
- 为字符串动态键声明索引签名
- 协调固定属性与动态属性的值类型
- 判断何时改用
Record或嵌套对象
索引签名控制什么
字符串索引签名的基本形式是 [key: string]: ValueType,表示通过任意字符串键读取到的值都必须符合 ValueType。参数名只用于说明含义,不参与类型检查,因此可以写成 name、sku 或 key。
对象中的已知属性也能通过字符串访问,所以它们的类型必须兼容索引签名。例如 [key: string]: number 存在时,passingScore 也必须是 number。否则同一个属性会同时得到两种互相矛盾的类型。
完整示例与结果
下面用索引签名表示一个成绩表,其中学生姓名是动态键,passingScore 是已知属性。代码可保存为 index-signature.ts。
interface ScoreBoard {
[studentName: string]: number;
passingScore: number;
}
function findPassedStudents(board: ScoreBoard): string[] {
const { passingScore, ...studentScores } = board;
return Object.entries(studentScores)
.filter(([, score]) => score >= passingScore)
.map(([name]) => name);
}
function main(): void {
const scores: ScoreBoard = {
passingScore: 60,
Alice: 88,
Bob: 55,
Chen: 92,
};
console.log(`passing=${findPassedStudents(scores).join(",")}`);
console.log(`Alice=${scores["Alice"]}`);
}
main();运行命令:
npx --yes tsx index-signature.ts预期输出:
passing=Alice,Chen
Alice=88索引签名只提供编译期约束,不保证某个动态键在运行时一定存在。启用 noUncheckedIndexedAccess 后,读取未知键会得到 number | undefined,调用方应先判断或使用空值合并运算符提供默认值。
冲突修复与使用边界
下面的声明无法通过检查,因为 count 也属于字符串键,但它的 number 类型不满足索引签名要求的 string。
// 片段示例:依赖 TypeScript 编译器展示类型错误。
interface InvalidDictionary {
[key: string]: string;
count: number;
}一种修复方式是把索引值扩展为 string | number,但此后每次动态读取都需要缩小联合类型。若固定字段与动态字段语义不同,更清晰的做法是把动态部分放入独立属性。
interface ProductCatalog {
title: string;
stock: Record<string, number>;
}这种结构让 title 保持精确的 string 类型,同时把库存键值集中到 stock 中。需要禁止写入时,可使用 readonly [key: string]: ValueType,但它只限制通过该类型引用进行赋值,不会自动冻结运行时对象。
Record<string, number> 常用于表达字符串键到数字值的映射,效果与简单字符串索引签名接近。键集合有限时,Record<"draft" | "published", number> 更合适,因为它会要求两个键都存在,并拒绝未声明的键。
JavaScript 会把普通对象的数字键转换为字符串。若同时声明数字和字符串索引签名,数字索引对应的值类型必须能赋给字符串索引的值类型。对于来自接口响应或文件的未知数据,仍需在运行时校验,不能只依赖类型断言。
本课总结
- 索引签名统一约束未知键对应的值类型
- 已知属性的类型必须兼容同一索引签名
- 固定字段与动态字段语义不同时,优先使用嵌套对象或
Record
下一课预告
下一课将继续进入对象建模,关注如何用类封装实例状态与行为,并区分类型约束和运行时实现。