TypeScript Academy · Урок

Определение индексных сигнатур

Описывайте объекты, ключи которых заранее неизвестны

Урок 1 из 413 шагов

«Определение индексных сигнатур» — бесплатный урок TypeScript Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения TypeScript Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс TypeScript Academy содержит 4 уроков всего.

Объекты с неизвестными ключами

Иногда имена свойств заранее неизвестны — например, это может быть словарь оценок, кэш или таблица поиска. Сигнатура индекса TypeScript позволяет описать объект, ключи которого могут быть любыми, но значения имеют один общий тип.

Базовый синтаксис сигнатуры индекса

Сигнатура индекса записывается так: { [key: string]: number }. Это означает: любой строковый ключ сопоставляется с числовым значением. Имя key — всего лишь метка, поэтому его можно назвать как угодно.

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

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

Динамическое добавление ключей

Поскольку разрешён любой строковый ключ, во время выполнения можно присваивать совершенно новые свойства, и 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, но во время выполнения отсутствующий ключ имеет значение 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)

Типы значений могут быть любыми

Тип значения не ограничивается примитивами. Можно сопоставлять ключи с массивами, объектами или объединениями типов — всем, что требуется вашим данным.

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])
}

Пробел в безопасности из-за отсутствующих значений

Сигнатуры индекса скрывают тот факт, что поиск может завершиться неудачей. Включение noUncheckedIndexedAccess в конфигурации TypeScript добавляет | undefined к каждому обращению, заставляя обрабатывать отсутствующие ключи.

// 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)

Когда сигнатуры индекса особенно полезны

Используйте сигнатуру индекса, когда набор ключей не ограничен и определяется во время выполнения: для кэшей, счётчиков с ключами-идентификаторами и разобранных параметров запроса. Для фиксированного, заранее известного набора ключей предпочитайте явные свойства или 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 } описывает объекты с произвольными ключами, значения которых имеют общий тип T. Ключи можно добавлять динамически, каждое значение должно соответствовать сигнатуре, а поиск отсутствующих ключей во время выполнения возвращает undefined. Используйте readonly для неизменяемых отображений и включайте noUncheckedIndexedAccess для более безопасного доступа.

Можно начать бесплатно

Изучай TypeScript с ИИ-репетитором — бесплатно

Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.

Курсы: 101
Уроки: 352

Начать учиться бесплатно Посмотреть полный курс

Часто задаваемые вопросы

Урок «Определение индексных сигнатур» бесплатный?

Да — полный текст урока «Определение индексных сигнатур» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс TypeScript Academy, подпишись на CoddyKit PRO. Курс TypeScript Academy содержит 4 уроков всего.

Чему я научусь в уроке «Определение индексных сигнатур»?

Описывайте объекты, ключи которых заранее неизвестны Ты практикуешь TypeScript Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать TypeScript Academy?

Предыдущий опыт не требуется. TypeScript Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Определение индексных сигнатур»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке TypeScript Academy?

Да. Каждый урок TypeScript Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Определение индексных сигнатур
Индексные сигнатуры строк и чисел
Объединение известных и динамических ключей
Индексные сигнатуры и Record

← Назад к TypeScript Academy