JavaScript / TypeScript / 系统课时

声明索引签名

声明索引签名

当对象的键来自用户名称、商品编号或配置项时,无法逐个写出属性名。索引签名可以统一约束这些动态键的值类型,同时要求已知属性也遵守同一访问规则。

学习目标

  • 为字符串动态键声明索引签名
  • 协调固定属性与动态属性的值类型
  • 判断何时改用 Record 或嵌套对象

索引签名控制什么

字符串索引签名的基本形式是 [key: string]: ValueType,表示通过任意字符串键读取到的值都必须符合 ValueType。参数名只用于说明含义,不参与类型检查,因此可以写成 name、sku 或 key。

对象中的已知属性也能通过字符串访问,所以它们的类型必须兼容索引签名。例如 [key: string]: number 存在时,passingScore 也必须是 number。否则同一个属性会同时得到两种互相矛盾的类型。

完整示例与结果

下面用索引签名表示一个成绩表,其中学生姓名是动态键,passingScore 是已知属性。代码可保存为 index-signature.ts。

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();

运行命令:

bash
npx --yes tsx index-signature.ts

预期输出:

text
passing=Alice,Chen
Alice=88

索引签名只提供编译期约束,不保证某个动态键在运行时一定存在。启用 noUncheckedIndexedAccess 后,读取未知键会得到 number | undefined,调用方应先判断或使用空值合并运算符提供默认值。

冲突修复与使用边界

下面的声明无法通过检查,因为 count 也属于字符串键,但它的 number 类型不满足索引签名要求的 string。

ts
// 片段示例:依赖 TypeScript 编译器展示类型错误。
interface InvalidDictionary {
  [key: string]: string;
  count: number;
}

一种修复方式是把索引值扩展为 string | number,但此后每次动态读取都需要缩小联合类型。若固定字段与动态字段语义不同,更清晰的做法是把动态部分放入独立属性。

ts
interface ProductCatalog {
  title: string;
  stock: Record<string, number>;
}

这种结构让 title 保持精确的 string 类型,同时把库存键值集中到 stock 中。需要禁止写入时,可使用 readonly [key: string]: ValueType,但它只限制通过该类型引用进行赋值,不会自动冻结运行时对象。

Record<string, number> 常用于表达字符串键到数字值的映射,效果与简单字符串索引签名接近。键集合有限时,Record<"draft" | "published", number> 更合适,因为它会要求两个键都存在,并拒绝未声明的键。

JavaScript 会把普通对象的数字键转换为字符串。若同时声明数字和字符串索引签名,数字索引对应的值类型必须能赋给字符串索引的值类型。对于来自接口响应或文件的未知数据,仍需在运行时校验,不能只依赖类型断言。

本课总结

  • 索引签名统一约束未知键对应的值类型
  • 已知属性的类型必须兼容同一索引签名
  • 固定字段与动态字段语义不同时,优先使用嵌套对象或 Record

下一课预告

下一课将继续进入对象建模,关注如何用类封装实例状态与行为,并区分类型约束和运行时实现。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

声明索引签名

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通