re:re:actable
Урок 033 минуты чтения

Динамические ключи объекта и index signature

На этой странице
Кратко

Если ключи объекта заранее неизвестны, используют index signature: { [key: string]: number } — любой строковый ключ со значением number. Ту же задачу решает Record<string, number>, а для известного набора ключей — Record<"a" | "b", number> или mapped types. Доступ по несуществующему ключу TypeScript по умолчанию считает безопасным — флаг noUncheckedIndexedAccess добавляет | undefined.

Вопрос

Как описать объект с динамическими ключами? Что такое index signature в интерфейсе и чем она отличается от Record?

Index signature

interface Scores {
  [studentName: string]: number;
}
 
const scores: Scores = {};
scores["Анна"] = 95;
scores.Иван = 87;
scores["Мария"] = "отлично"; // ошибка: значение должно быть number

Тип ключа может быть string, number, symbol, template literal или union этих типов:

interface Headers {
  [header: `x-${string}`]: string;
}
 
const h: Headers = { "x-request-id": "123" };

Совмещение с обычными полями

interface Translations {
  locale: string;               // обязано совпадать с типом index signature
  [key: string]: string;
}
 
interface Config {
  version: number;              // ошибка: number не совместим с string
  [key: string]: string;
}

Все явные поля должны быть совместимы с типом значения index signature. Решение — union: [key: string]: string | number.

Record

type Prices = Record<string, number>;               // = { [key: string]: number }
type StatusLabels = Record<"idle" | "done", string>; // ровно два обязательных ключа
 
const labels: StatusLabels = {
  idle: "Ожидание",
  done: "Готово",
  // пропустить ключ — ошибка, добавить лишний — тоже
};
Index signatureRecord<K, V>
Синтаксисв интерфейсе или типеutility-тип
Явные поля рядомможночерез пересечение
Конечный набор ключейнетда, если K — union литералов
Имя параметра ключадля документации ([userId: string])нет

Безопасный доступ

const prices: Record<string, number> = { tea: 120 };
 
const coffee = prices["coffee"];  // тип number, но в runtime undefined!
coffee.toFixed(2);                // упадет

С noUncheckedIndexedAccess: true тип станет number | undefined и потребует проверки. Для словарей с произвольными ключами также удобна Map<string, number>: map.get() возвращает V | undefined.

Ключи из другого типа

type User = { id: number; name: string };
 
type UserFlags = { [K in keyof User]: boolean }; // mapped type: { id: boolean; name: boolean }
 
function getField<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

Что важно помнить

  • {} и object не являются словарями: для произвольных ключей нужен Record или index signature.
  • Ключи объекта в runtime — строки: [key: number] описывает доступ obj[1], но Object.keys вернет строки.
  • Слишком общий Record<string, any> убивает пользу типов — указывайте тип значений.
  • satisfies Record<Status, string> проверяет, что все ключи на месте, и сохраняет литеральные типы значений.

Мини-шпаргалка

  • { [key: string]: T } — index signature.
  • Record<string, T> — то же, Record<"a" | "b", T> — точные ключи.
  • Явные поля должны быть совместимы с index signature.
  • noUncheckedIndexedAccess добавляет | undefined.
  • Для динамических словарей — Map.

Документация

TypeScript Handbook: Index Signatures, TypeScript: Record, TypeScript: noUncheckedIndexedAccess.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам