Definiowanie sygnatur indeksów
Opisuj obiekty, których klucze nie są znane z wyprzedzeniem
Definiowanie sygnatur indeksów to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej TypeScript Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs TypeScript Academy zawiera 4 lekcji w sumie.
Obiekty z nieznanymi kluczami
Czasami nazwy właściwości nie są znane z góry — może to być słownik wyników, pamięć podręczna albo tabela wyszukiwania. Sygnatura indeksu TypeScript pozwala opisać obiekt, którego klucze są dowolne, ale wszystkie wartości mają jeden typ.
Podstawowa składnia sygnatury indeksu
Sygnaturę indeksu zapisuje się jako { [key: string]: number }. Oznacza to, że każdy klucz typu string wskazuje wartość typu number. Nazwa key jest tylko etykietą — można ją zastąpić dowolną nazwą.
type Scores = { [name: string]: number }
const game: Scores = { alice: 10, bob: 7 }
console.log(game.alice) // 10Dynamiczne dodawanie kluczy
Ponieważ dozwolony jest każdy klucz typu string, w czasie działania programu można przypisywać zupełnie nowe właściwości bez zgłaszania błędu przez TypeScript. To właśnie jest główny cel sygnatury indeksu.
type Scores = { [name: string]: number }
const game: Scores = {}
game.charlie = 5 // allowed
game["dave"] = 9 // also allowed
console.log(game.charlie + game.dave) // 14Dostęp do dowolnych kluczy
Można odczytać dowolny klucz, nawet taki, który nigdy nie został ustawiony. System typów ufa sygnaturze, więc typ wartości to number — jednak w czasie działania programu brakujący klucz ma wartość undefined. Należy zachować ostrożność.
type Scores = { [name: string]: number }
const game: Scores = { alice: 10 }
const missing = game.zara // typed as number, but actually undefined
console.log(missing) // undefinedWszystkie wartości muszą być zgodne
Każda właściwość obiektu musi odpowiadać typowi wartości określonemu w sygnaturze. Nie można umieścić wartości typu number w słowniku, którego wartości są typu string.
type Labels = { [key: string]: string }
const ok: Labels = { id: "a1", role: "admin" }
// const bad: Labels = { id: "a1", count: 5 } // Error: 5 not a stringSygnatury indeksu w interfejsach
Ta sama składnia działa wewnątrz konstrukcji interface. Jest to często stosowane do opisywania obiektów konfiguracyjnych lub map odpowiedzi z API.
interface Dictionary {
[word: string]: string
}
const defs: Dictionary = {
cat: "a small animal",
ts: "a typed superset of JavaScript",
}
console.log(defs.ts)Typy wartości mogą być dowolne
Typ wartości nie jest ograniczony do typów prostych. Klucze można mapować na tablice, obiekty lub typy unii — zależnie od potrzeb danych.
type Groups = { [team: string]: string[] }
const roster: Groups = {
red: ["ana", "leo"],
blue: ["sam"],
}
console.log(roster.red.length) // 2Iterowanie po obiektach z sygnaturą indeksu
Pętla for...in odwiedza każdy dynamiczny klucz. Wewnątrz pętli wartość ma prawidłowy typ zgodny z sygnaturą.
type Scores = { [name: string]: number }
const game: Scores = { alice: 10, bob: 7 }
for (const name in game) {
console.log(name + ": " + game[name])
}Luka bezpieczeństwa związana z undefined
Sygnatury indeksu ukrywają fakt, że wyszukiwanie może się nie powieść. Włączenie noUncheckedIndexedAccess w tsconfig dodaje | undefined do każdego dostępu, wymuszając obsługę brakujących kluczy.
// with noUncheckedIndexedAccess on:
type Scores = { [name: string]: number }
const game: Scores = { alice: 10 }
const v = game.bob // type: number | undefined
console.log(v ?? 0)Sygnatury indeksu tylko do odczytu
Dodanie prefiksu readonly do sygnatury uniemożliwia zapis przez dowolny klucz. Słownik staje się strukturą przeznaczoną wyłącznie do wyszukiwania.
type Frozen = { readonly [key: string]: number }
const rates: Frozen = { usd: 1, eur: 1.1 }
// rates.usd = 2 // Error: read-only
console.log(rates.eur)Kiedy sygnatury indeksu są przydatne
Po sygnaturę indeksu warto sięgać, gdy zbiór kluczy jest otwarty i jest ustalany w czasie działania programu: w przypadku pamięci podręcznych, liczników indeksowanych identyfikatorami czy przeanalizowanych parametrów zapytania. Dla stałego, znanego zbioru kluczy lepiej użyć jawnych właściwości lub 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) // 2Szybki test
Sprawdź swoją znajomość sygnatur indeksu.
Podsumowanie
Dowiedziałeś się, że { [key: string]: T } opisuje obiekty z dowolnymi kluczami, których wartości mają wspólny typ T. Klucze można dodawać dynamicznie, każda wartość musi być zgodna z sygnaturą, a wyszukiwanie brakujących kluczy zwraca w czasie działania programu undefined. Używaj readonly dla niezmiennych map i włącz noUncheckedIndexedAccess, aby uzyskać bezpieczniejszy dostęp.
Ucz się TypeScript dzięki korepetycjom AI — za darmo
Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.
- Kursy
- 101
- Lekcje
- 352
Często zadawane pytania
Czy lekcja „Definiowanie sygnatur indeksów” jest bezpłatna?
Tak — pełny tekst „Definiowanie sygnatur indeksów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu TypeScript Academy, przejdź na CoddyKit PRO. Kurs TypeScript Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Definiowanie sygnatur indeksów”?
Opisuj obiekty, których klucze nie są znane z wyprzedzeniem Ćwiczysz TypeScript Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć TypeScript Academy?
Nie wymagamy żadnego doświadczenia. TypeScript Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.
Ile czasu zajmuje lekcja „Definiowanie sygnatur indeksów”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji TypeScript Academy?
Tak. Każda lekcja TypeScript Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Definiowanie sygnatur indeksów
- Sygnatury indeksów string i number
- Łączenie znanych i dynamicznych kluczy
- Sygnatury indeksów a Record