Assinaturas de Índice de Texto versus Número
Entenda as regras e particularidades das chaves numéricas.
Assinaturas de Índice de Texto versus Número é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 2 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.
Dois tipos de keys de índice
O TypeScript aceita assinaturas de índice de cadeia de caracteres e de número. Elas têm aparência semelhante, mas se comportam de maneira diferente por causa de como o JavaScript realmente armazena as keys dos objetos.
Uma assinatura de índice numérico
Uma assinatura de índice numérico { [i: number]: T } descreve objetos indexados por posição numérica — naturalmente, matrizes e estruturas semelhantes a matrizes.
type NumberList = { [index: number]: string }
const names: NumberList = { 0: "ana", 1: "leo" }
console.log(names[0]) // anaJS converte keys numéricas em cadeias de caracteres
Aqui está o fato principal: as keys de objetos JavaScript são sempre cadeias de caracteres. Quando você escreve obj[0], o mecanismo na verdade armazena a chave como a cadeia de caracteres "0". O TypeScript modela essa realidade.
const obj: Record<string, string> = {}
obj[1] = "one"
console.log(obj["1"]) // one — same key!
console.log(Object.keys(obj)) // ["1"]A regra de compatibilidade
Como uma chave numérica é, na verdade, uma cadeia de caracteres internamente, o TypeScript impõe uma regra: quando um objeto tem ambas as assinaturas de índice numérico e de cadeia de caracteres, o tipo de valor do índice numérico deve ser atribuível ao tipo de valor do índice de cadeia de caracteres.
interface Mixed {
[key: string]: string
[index: number]: string // must match the string value type
}
const m: Mixed = { 0: "a", name: "b" }
console.log(m[0], m.name)Por que essa regra existe
Se obj[0] e obj["0"] forem o mesmo espaço, o tipo do valor não pode ser numérico em um caso e uma cadeia de caracteres no outro. Portanto, o valor do índice numérico deve ser um subtipo do valor do índice de cadeia de caracteres para manter a consistência.
// This is an ERROR:
// interface Bad {
// [key: string]: string
// [index: number]: number // number not assignable to string
// }Indexadas por número: matrizes
As matrizes são o tipo canônico indexado por número. O tipo integrado Array<T> efetivamente tem uma assinatura de índice numérico, e é por isso que arr[i] retorna T.
const nums: number[] = [10, 20, 30]
const first: number = nums[0]
console.log(first + nums[2]) // 40As tuplas também são indexadas por número
As tuplas se baseiam na indexação numérica, mas fixam posições específicas em tipos específicos. O acesso numérico fora do intervalo recorre à união dos tipos dos elementos ou é sinalizado.
const pair: [string, number] = ["age", 30]
const label: string = pair[0]
const value: number = pair[1]
console.log(label + ": " + value)O índice de cadeia permite ambos os acessos
Um objeto com uma assinatura de índice de cadeia de caracteres também aceita acessos com aparência numérica, porque o número é primeiro convertido em uma key de cadeia de caracteres.
type Bag = { [key: string]: number }
const b: Bag = {}
b[5] = 100 // stored as key "5"
console.log(b["5"]) // 100O índice numérico não aceita cadeias de caracteres
O inverso não é verdadeiro. Um objeto tipado apenas com uma assinatura de índice numérico rejeita keys de cadeia de caracteres em tempo de compilação, embora o JS tecnicamente permitisse esse acesso.
type OnlyNumbers = { [i: number]: string }
const o: OnlyNumbers = { 0: "x" }
// o.name = "y" // Error: property name not on number-indexed type
console.log(o[0])Escolhendo entre elas
Utilize um índice de número para dados semelhantes a sequências e baseados em posição (listas, tuplas). Utilize um índice de cadeia de caracteres para consultas por nome (dicionários, caches). Em caso de dúvida, a cadeia de caracteres é a opção mais geral.
type Positions = { [i: number]: { x: number; y: number } }
type ByName = { [name: string]: { x: number; y: number } }
const p: Positions = { 0: { x: 1, y: 2 } }
console.log(p[0].x)Objeto Mixed prático
Você pode combinar ambas as assinaturas quando um tipo de valor funcionar para as duas — útil para contêineres esparsos semelhantes a matrizes que também expõem posições nomeadas.
interface Flexible {
[key: string]: number
[index: number]: number
}
const f: Flexible = { 0: 1, total: 99 }
console.log(f[0] + f.total) // 100Verificação rápida
Teste sua compreensão das assinaturas de índice de cadeia de caracteres e numéricas.
Recapitulação
As assinaturas de índice de cadeia de caracteres e numéricas diferem porque o JS armazena todas as keys como cadeias de caracteres, convertendo números em keys de cadeia de caracteres. Quando ambas existem, o tipo de valor do índice numérico deve ser atribuível ao tipo de valor do índice de cadeia de caracteres. A indexação numérica modela matrizes e tuplas; a indexação por cadeia de caracteres modela dicionários. Objetos indexados por cadeia de caracteres aceitam acesso numérico, mas objetos indexados por número rejeitam keys de cadeia de caracteres em tempo de compilação.
Perguntas Frequentes
A aula “Assinaturas de Índice de Texto versus Número” é grátis?
Sim — o texto completo de “Assinaturas de Índice de Texto versus Número” é 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 “Assinaturas de Índice de Texto versus Número”?
Entenda as regras e particularidades das chaves numéricas. 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 2 de 4.
Quanto tempo leva a aula “Assinaturas de Índice de Texto versus Número”?
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