Динамические ключи объекта и 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 signature | Record<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.