TypeScript Academy · 课时

定义索引签名

Q: 「定义索引签名」这节课中我会学到什么？

描述键名事先未知的对象。 你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

描述键名事先未知的对象。

第 1 / 4 课13 个步骤

定义索引签名 是 CoddyKit 上的免费 TypeScript Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 TypeScript Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 TypeScript Academy 课程共包含 4 节课。

具有未知 keys 的对象

有时您无法预先知道属性名称——例如分数的字典、缓存或查找表。TypeScript 的索引签名可以描述这样一种对象：其 keys 可以是任意值，但值共享同一种类型。

索引签名的基本语法

索引签名写作 { [key: string]: number }。它表示：任意字符串键都会映射到一个数字值。key 这个名称只是一个 label——您可以将它命名为任何名称。

type Scores = { [name: string]: number }

const game: Scores = { alice: 10, bob: 7 }
console.log(game.alice) // 10

动态添加 keys

由于允许使用每个字符串键，您可以在运行时为对象赋予全新的属性，而不会收到 TypeScript 的报错。这正是索引签名的用途。

type Scores = { [name: string]: number }

const game: Scores = {}
game.charlie = 5     // allowed
game["dave"] = 9     // also allowed
console.log(game.charlie + game.dave) // 14

访问任意键

您可以读取任意键，即使该键从未被设置过。类型系统信任这个签名，因此值的类型是 number——但在运行时，missing 键的值会是 undefined。请务必小心。

type Scores = { [name: string]: number }

const game: Scores = { alice: 10 }
const missing = game.zara // typed as number, but actually undefined
console.log(missing) // undefined

所有值都必须符合要求

对象中的每个属性都必须符合索引签名的值类型。您不能在字符串值字典中混入数字值。

type Labels = { [key: string]: string }

const ok: Labels = { id: "a1", role: "admin" }
// const bad: Labels = { id: "a1", count: 5 } // Error: 5 not a string

接口中的索引签名

相同的语法也可以在 interface 中使用。这常用于描述配置对象，或来自应用程序接口的响应映射。

interface Dictionary {
  [word: string]: string
}

const defs: Dictionary = {
  cat: "a small animal",
  ts: "a typed superset of JavaScript",
}
console.log(defs.ts)

值类型可以是任意类型

值这一侧并不局限于基本类型。您可以将 keys 映射到数组、对象或联合类型——只要符合您的数据需求即可。

type Groups = { [team: string]: string[] }

const roster: Groups = {
  red: ["ana", "leo"],
  blue: ["sam"],
}
console.log(roster.red.length) // 2

遍历索引签名对象

for...in 循环会访问每个动态键。在循环内部，值会根据索引签名获得正确的类型。

type Scores = { [name: string]: number }
const game: Scores = { alice: 10, bob: 7 }

for (const name in game) {
  console.log(name + ": " + game[name])
}

未定义值的安全缺口

索引签名掩盖了查找可能失败这一事实。在 tsconfig 中启用 noUncheckedIndexedAccess 后，每次访问的类型都会增加 | undefined，从而迫使您处理 missing keys。

// with noUncheckedIndexedAccess on:
type Scores = { [name: string]: number }
const game: Scores = { alice: 10 }
const v = game.bob // type: number | undefined
console.log(v ?? 0)

只读索引签名

在签名前加上 readonly，即可禁止通过任何键进行写入。这样，字典就变成了只能查找的结构。

type Frozen = { readonly [key: string]: number }

const rates: Frozen = { usd: 1, eur: 1.1 }
// rates.usd = 2 // Error: read-only
console.log(rates.eur)

索引签名的适用场景

当 keys 的集合没有固定边界，并且要在运行时发现时，索引签名非常适合：例如缓存、以标识符为键的计数器、解析后的查询参数。对于固定且已知的 keys 集合，建议使用显式属性或 Record。

type Counter = { [event: string]: number }
const clicks: Counter = {}
function track(e: string) { clicks[e] = (clicks[e] ?? 0) + 1 }
track("open"); track("open")
console.log(clicks.open) // 2

快速检查

测试您对索引签名的理解。

在交互式课程中回答

回顾

您学到了，{ [key: string]: T } 描述的是这样一种对象：具有任意 keys，且所有值共享类型 T。您可以动态添加 keys，每个值都必须符合签名，而 missing keys 的查找结果在运行时是 undefined。对于不可变映射，请使用 readonly；为了进行更安全的访问，请启用 noUncheckedIndexedAccess。

免费开始

用 AI 导师学习 TypeScript — 免费

在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。

课程: 101
课程: 352

免费开始学习查看完整课程

常见问题解答

「定义索引签名」课时是免费的吗？

是的 — 「定义索引签名」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 TypeScript Academy 课程的其余内容，请升级到 CoddyKit PRO。 TypeScript Academy 课程共包含 4 节课。

「定义索引签名」这节课中我会学到什么？

描述键名事先未知的对象。你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 TypeScript Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 TypeScript Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「定义索引签名」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 TypeScript Academy 课中编写并运行代码吗？

能。每节 TypeScript Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 TypeScript Academy