0Pricing
TypeScript Academy · Lección

Definición de firmas de índice

Describa objetos cuyas claves no se conocen de antemano.

Definición de firmas de índice es una lección gratuita de TypeScript Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de TypeScript Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de TypeScript Academy incluye 4 lecciones en total.

Objetos con claves desconocidas

A veces no se conocen de antemano los nombres de las propiedades: un diccionario de puntuaciones, una caché o una tabla de búsqueda. La signatura de índice de TypeScript permite describir un objeto cuyas claves son arbitrarias, pero cuyos valores comparten un mismo tipo.

Sintaxis básica de una signatura de índice

Una signatura de índice se escribe como { [key: string]: number }. Indica que cualquier clave de tipo string se asocia con un valor de tipo number. El nombre key es solo una etiqueta: puede llamarlo como quiera.

type Scores = { [name: string]: number }

const game: Scores = { alice: 10, bob: 7 }
console.log(game.alice) // 10

Adición dinámica de claves

Como se permite cualquier clave de tipo string, puede asignar propiedades completamente nuevas en tiempo de ejecución sin que TypeScript muestre errores. Este es precisamente el objetivo de una signatura 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) // 14

Acceso a claves arbitrarias

Puede leer cualquier clave, incluso una que nunca se haya establecido. El sistema de tipos confía en la signatura, por lo que el tipo del valor es number; pero, en tiempo de ejecución, una clave inexistente tiene el valor undefined. Tenga cuidado.

type Scores = { [name: string]: number }

const game: Scores = { alice: 10 }
const missing = game.zara // typed as number, but actually undefined
console.log(missing) // undefined

Todos los valores deben cumplir el tipo

Todas las propiedades del objeto deben coincidir con el tipo de valor de la signatura. No puede mezclar un valor numérico en un diccionario cuyos valores son cadenas.

type Labels = { [key: string]: string }

const ok: Labels = { id: "a1", role: "admin" }
// const bad: Labels = { id: "a1", count: 5 } // Error: 5 not a string

Signaturas de índice en interfaces

La misma sintaxis funciona dentro de una interface. Es habitual utilizarla para describir objetos de configuración o mapas de respuestas de una API.

interface Dictionary {
  [word: string]: string
}

const defs: Dictionary = {
  cat: "a small animal",
  ts: "a typed superset of JavaScript",
}
console.log(defs.ts)

Los tipos de valor pueden ser cualesquiera

La parte del valor no se limita a los tipos primitivos. Puede asociar las claves con arrays, objetos o uniones, según lo que necesiten sus datos.

type Groups = { [team: string]: string[] }

const roster: Groups = {
  red: ["ana", "leo"],
  blue: ["sam"],
}
console.log(roster.red.length) // 2

Iteración de objetos con signaturas de índice

Un bucle for...in recorre cada clave dinámica. Dentro del bucle, el valor tiene correctamente el tipo definido por la signatura.

type Scores = { [name: string]: number }
const game: Scores = { alice: 10, bob: 7 }

for (const name in game) {
  console.log(name + ": " + game[name])
}

La brecha de seguridad relacionada con undefined

Las signaturas de índice ocultan el hecho de que las búsquedas pueden fallar. Activar noUncheckedIndexedAccess en tsconfig añade | undefined a cada acceso y le obliga a gestionar las claves inexistentes.

// with noUncheckedIndexedAccess on:
type Scores = { [name: string]: number }
const game: Scores = { alice: 10 }
const v = game.bob // type: number | undefined
console.log(v ?? 0)

Signaturas de índice de solo lectura

Anteponer readonly a la signatura impide escribir a través de cualquier clave. El diccionario se convierte en una estructura de solo 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)

Cuándo resultan útiles las signaturas de índice

Utilice una signatura de índice cuando el conjunto de claves sea abierto y se descubra en tiempo de ejecución: cachés, contadores indexados por id o parámetros de consulta analizados. Para un conjunto fijo de claves conocidas, prefiera propiedades explícitas o 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) // 2

Comprobación rápida

Compruebe cuánto ha entendido sobre las signaturas de índice.

Resumen

Ha aprendido que { [key: string]: T } describe objetos con claves arbitrarias cuyos valores comparten el tipo T. Puede añadir claves dinámicamente, todos los valores deben cumplir la signatura y las búsquedas de claves inexistentes devuelven undefined en tiempo de ejecución. Utilice readonly para los mapas inmutables y active noUncheckedIndexedAccess para acceder de forma más segura.

Preguntas frecuentes

¿La lección «Definición de firmas de índice» es gratis?

Sí — el texto completo de «Definición de firmas de índice» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de TypeScript Academy, actualiza a CoddyKit PRO. El curso de TypeScript Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Definición de firmas de índice»?

Describa objetos cuyas claves no se conocen de antemano. Practicas TypeScript Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar TypeScript Academy?

No se requiere experiencia previa. TypeScript Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «Definición de firmas de índice»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de TypeScript Academy?

Sí. Cada lección de TypeScript Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Definición de firmas de índice
  2. Firmas de índice de tipo string frente a number
  3. Combinación de claves conocidas y dinámicas
  4. Firmas de índice frente a Record
← Volver a TypeScript Academy