Index Signatures: Propriedades Dinâmicas e Dicionários Tipados no TypeScript
No mundo real, nem sempre conhecemos os nomes exatos de todas as chaves de um objeto antecipadamente: dicionários, caches em memória, tabelas de tradução i18n e mapas de configuração exigem flexibilidade. Aprenda como dominar as Index Signatures no TypeScript para modelar propriedades dinâmicas com segurança estrita e evitar armadilhas de runtime.
📑 Índice do Conteúdo
1. O Que É uma Index Signature e Por Que Ela Existe
Uma Index Signature permite descrever o tipo dos valores de um objeto quando você não sabe de antemão os nomes de todas as propriedades que ele conterá, mas conhece o tipo da chave e o tipo do valor associado a ela.
A sintaxe utiliza colchetes com um nome de parâmetro representativo (como [chave: string] ou [index: number]) seguido pelo tipo do valor retornado:
// Definindo um mapa de contagem de acessos (Dicionário de números)
interface ContadorAcessos {
[url: string]: number;
}
const metricasDiarias: ContadorAcessos = {
"/home": 1420,
"/web-academy/typescript/": 890,
"/contato": 45
};
// Podemos adicionar novas chaves arbitrariamente, desde que o valor seja number:
metricasDiarias["/blog/artigo-ts"] = 312;
// ❌ Erro de compilação: TS2322: Type 'string' is not assignable to type 'number'.
metricasDiarias["/sobre"] = "duzentos";
2. A Regra de Ouro da Compatibilidade Estrutural
Quando você combina uma Index Signature com propriedades fixas pré-definidas na mesma interface, o TypeScript impõe uma regra matemática intransigente: o tipo de retorno da index signature deve ser abrangente o bastante para acolher todas as propriedades nomeadas.
Se uma propriedade explícita tiver um tipo incompatível com a assinatura de índice geral, o compilador rejeitará o contrato imediatamente:
// ❌ ERRO DE COMPILAÇÃO:
interface PerfilInvalido {
[chave: string]: string; // Declara que TODAS as chaves de texto devem ter valor string!
nome: string; // Válido: string é compatível com string.
// TS2411: Property 'idade' of type 'number' is not assignable to 'string' index type 'string'.
idade: number;
}
// ==========================================
// ✅ SOLUÇÃO 1: Usar Union Type na Index Signature
// ==========================================
interface PerfilFlexivel {
[chave: string]: string | number; // Agora aceita tanto texto quanto números!
nome: string;
idade: number;
}
// ==========================================
// ✅ SOLUÇÃO 2: Separar Propriedades Fixas do Dicionário Dinâmico
// ==========================================
interface PerfilSeparado {
nome: string;
idade: number;
metadadosCustomizados: Record<string, unknown>; // Dicionário isolado!
}
3. Dualidade de Índices: string versus number
No JavaScript, os objetos possuem uma peculiaridade histórica fundamental: se você indexar um objeto com um número (ex: obj[10]), o runtime automaticamente converte esse número para uma string (obj["10"]) antes de buscar a propriedade na memória.
Por conta dessa conversão implícita do JavaScript, o TypeScript exige que se uma interface contiver ambas as index signatures (numérica e de texto), o tipo retornado pelo índice numérico DEVE ser um subtipo do tipo retornado pelo índice de string:
class Animal {
especie: string = "Desconhecida";
}
class Cachorro extends Animal {
latir() {
console.log("Au au!");
}
}
// ✅ VÁLIDO: Cachorro é subtipo de Animal.
interface Zoologico {
[id: number]: Cachorro; // Mais específico (subtipo)
[nome: string]: Animal; // Mais abrangente (supertipo)
}
// ❌ ERRO: TS2413: 'number' index type 'Animal' is not assignable to 'string' index type 'Cachorro'.
interface ZooInvalido {
[id: number]: Animal;
[nome: string]: Cachorro;
}
4. O Perigo Oculto e a Flag noUncheckedIndexedAccess
Por padrão, nas configurações padrão do TypeScript, ao acessar qualquer chave de um objeto com index signature, o compilador assume otimisticamente que a propriedade sempre existe. Isso cria uma falsa sensação de segurança que pode derrubar sua aplicação em produção com o infame TypeError: Cannot read properties of undefined:
interface TabelaPrecos {
[produto: string]: number;
}
const precos: TabelaPrecos = {
notebook: 4500,
mouse: 120
};
// Com as configurações padrão do TS:
const valorTeclado = precos["teclado"];
// O compilador diz que valorTeclado é "number", mas em runtime ele é UNDEFINED!
console.log(valorTeclado.toFixed(2));
// 💥 TypeError em runtime: Cannot read properties of undefined (reading 'toFixed')!
Para eliminar essa vulnerabilidade fatal de arquitetura, o TypeScript introduziu no tsconfig.json a flag de rigor absoluto: "noUncheckedIndexedAccess": true.
Quando ativada, qualquer leitura em uma index signature tem seu tipo de retorno automaticamente afunilado para Tipo | undefined, obrigando você a realizar checagens defensivas:
// COM "noUncheckedIndexedAccess": true no tsconfig.json:
const valorTeclado = precos["teclado"]; // Tipo inferido: number | undefined!
// ❌ O compilador agora avisa e BLOQUEIA o erro antes do deploy:
// TS18048: 'valorTeclado' is possibly 'undefined'.
// valorTeclado.toFixed(2);
// ✅ Código defensivo profissional:
if (typeof valorTeclado === "number") {
console.log("Preço:", valorTeclado.toFixed(2));
} else {
console.warn("Produto não catalogado na tabela de preços.");
}
5. Modificador readonly em Index Signatures
Você também pode aplicar o modificador readonly a uma assinatura de índice para criar tabelas de lookup e dicionários de leitura estritamente congelados:
interface DicionarioImutavel {
readonly [termo: string]: string;
}
const traducoes: DicionarioImutavel = {
btn_salvar: "Save",
btn_cancelar: "Cancel"
};
// ❌ Erro de compilação: TS2542: Index signature in type 'DicionarioImutavel' only permits reading.
// traducoes["btn_salvar"] = "Salvar";
6. Index Signatures vs. Utilitário Record<K, V>
Muitas vezes você verá no código sênior o uso do utility type Record<Keys, Type>. Qual a relação dele com a Index Signature?
[key: string]: Vaceita qualquer string arbitrária e é implementado diretamente dentro de umainterface.Record<K, V>é mais flexível porque permite restringir as chaves a uniões literais exatas (ex:Record<'ativo' | 'inativo', number>), algo que uma Index Signature tradicional não permite na sintaxe padrão.
"noUncheckedIndexedAccess": true no arquivo tsconfig.json dos seus projetos corporativos. Ele transforma o TypeScript em um escudo de ferro contra acessos a chaves inexistentes em objetos de configuração e mapas de dados externos.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE