Definindo Assinaturas de Índice
Descreva objetos cujas chaves não são conhecidas antecipadamente.
Definindo Assinaturas de Índice é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 4 aulas no total.
Objetos com keys desconhecidas
Às vezes, você não sabe de antemão os nomes das propriedades — um dicionário de pontuações, um cache, uma tabela de consulta. A assinatura de índice do TypeScript permite descrever um objeto cujas keys são arbitrárias, mas cujos valores compartilham um mesmo tipo.
Sintaxe básica de assinatura de índice
Uma assinatura de índice é escrita como { [key: string]: number }. Isso significa que qualquer chave de cadeia de caracteres mapeia para um valor numérico. O nome key é apenas um label — você pode chamá-lo do que quiser.
type Scores = { [name: string]: number }
const game: Scores = { alice: 10, bob: 7 }
console.log(game.alice) // 10Adicionando keys dinamicamente
Como qualquer chave de cadeia de caracteres é permitida, você pode atribuir propriedades totalmente novas em tempo de execução sem que o TypeScript reclame. Esse é o objetivo principal de uma assinatura de índice.
type Scores = { [name: string]: number }
const game: Scores = {}
game.charlie = 5 // allowed
game["dave"] = 9 // also allowed
console.log(game.charlie + game.dave) // 14Acessando keys arbitrárias
Você pode ler qualquer chave, até mesmo uma que nunca foi definida. O sistema de tipos confia na assinatura, então o tipo do valor é number — mas, em tempo de execução, uma key missing é undefined. Tenha cuidado.
type Scores = { [name: string]: number }
const game: Scores = { alice: 10 }
const missing = game.zara // typed as number, but actually undefined
console.log(missing) // undefinedTodos os valores devem estar em conformidade
Cada propriedade do objeto deve corresponder ao tipo de valor da assinatura. Você não pode misturar um valor numérico em um dicionário cujos valores são cadeias de caracteres.
type Labels = { [key: string]: string }
const ok: Labels = { id: "a1", role: "admin" }
// const bad: Labels = { id: "a1", count: 5 } // Error: 5 not a stringAssinaturas de índice em interfaces
A mesma sintaxe funciona dentro de uma interface. Isso é comum para descrever objetos de configuração ou mapas de respostas de uma API.
interface Dictionary {
[word: string]: string
}
const defs: Dictionary = {
cat: "a small animal",
ts: "a typed superset of JavaScript",
}
console.log(defs.ts)Os tipos de valor podem ser qualquer coisa
A parte dos valores não se limita aos tipos primitivos. Você pode mapear keys para matrizes, objetos ou uniões — qualquer estrutura de que seus dados precisem.
type Groups = { [team: string]: string[] }
const roster: Groups = {
red: ["ana", "leo"],
blue: ["sam"],
}
console.log(roster.red.length) // 2Iterando sobre objetos com assinatura de índice
Um laço for...in visita cada key dinâmica. Dentro do laço, o valor é tipado corretamente de acordo com a assinatura.
type Scores = { [name: string]: number }
const game: Scores = { alice: 10, bob: 7 }
for (const name in game) {
console.log(name + ": " + game[name])
}A lacuna de segurança de undefined
As assinaturas de índice ocultam o fato de que as consultas podem falhar. Habilitar noUncheckedIndexedAccess no tsconfig adiciona | undefined a cada acesso, obrigando você a lidar com keys ausentes.
// with noUncheckedIndexedAccess on:
type Scores = { [name: string]: number }
const game: Scores = { alice: 10 }
const v = game.bob // type: number | undefined
console.log(v ?? 0)Assinaturas de índice somente leitura
Prefixe a assinatura com readonly para impedir a escrita por qualquer chave. O dicionário se torna uma estrutura somente para consulta.
type Frozen = { readonly [key: string]: number }
const rates: Frozen = { usd: 1, eur: 1.1 }
// rates.usd = 2 // Error: read-only
console.log(rates.eur)Quando as assinaturas de índice são ideais
Utilize uma assinatura de índice quando o conjunto de keys for aberto e descoberto em tempo de execução: caches, contadores indexados por identificador e parâmetros de consulta analisados. Para um conjunto fixo e conhecido de keys, prefira propriedades explícitas ou 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) // 2Verificação rápida
Teste sua compreensão das assinaturas de índice.
Recapitulação
Você aprendeu que { [key: string]: T } descreve objetos com keys arbitrárias cujos valores compartilham o tipo T. As keys podem ser adicionadas dinamicamente, cada valor deve estar em conformidade com a assinatura e as consultas de keys ausentes resultam em undefined em tempo de execução. Utilize readonly para mapas imutáveis e habilite noUncheckedIndexedAccess para obter acessos mais seguros.
Perguntas Frequentes
A aula “Definindo Assinaturas de Índice” é grátis?
Sim — o texto completo de “Definindo Assinaturas de Índice” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 4 aulas no total.
O que vou aprender em “Definindo Assinaturas de Índice”?
Descreva objetos cujas chaves não são conhecidas antecipadamente. Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar TypeScript Academy?
Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.
Quanto tempo leva a aula “Definindo Assinaturas de Índice”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de TypeScript Academy?
Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Definindo Assinaturas de Índice
- Assinaturas de Índice de Texto versus Número
- Combinando Chaves Conhecidas e Dinâmicas
- Assinaturas de Índice versus Record