Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Map — uma coleção de pares chave-valor

Map armazena chaves únicas de qualquer tipo juntamente com os valores associados. Permite ler e eliminar entradas, verificar se uma chave existe e iterar pela ordem de inserção.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

new Map()
new Map(iterable)
map.set(key, value)
map.get(key)
map.has(key)
map.delete(key)
map.clear()
map.size
for (const [key, value] of map) { /* ... */ }

Map é uma coleção integrada de pares chave-valor. Tanto as chaves como os valores podem ser qualquer valor JavaScript. Crie um mapa vazio com new Map() ou passe ao construtor um objeto iterável que contenha pares [key, value]. Chamá-lo sem new gera um TypeError.

set(key, value) adiciona ou atualiza uma entrada e devolve o mapa. get(key) lê o seu valor; se a chave não existir, devolve undefined. Como um valor armazenado também pode ser undefined, verifique a presença com has(key). A propriedade size indica o número de entradas, delete(key) devolve se uma entrada foi eliminada e clear() elimina todas as entradas.

A comparação de chaves segue SameValueZero: NaN corresponde a NaN, e +0 e -0 são a mesma chave. Os objetos são comparados pela identidade, não pelo conteúdo. Assim, dois objetos { id: 1 } criados separadamente são chaves diferentes.

A iteração com for...of produz pares pela ordem de inserção das chaves; keys(), values() e entries() devolvem os iteradores correspondentes. Atualizar um valor não altera a posição da entrada, mas eliminá-la e inseri-la novamente move-a para o fim. Para adicionar entradas, utilize set(key, value), não map[key] = value. A atribuição com parênteses retos atua sobre uma propriedade do objeto, não sobre uma entrada do mapa. Por exemplo, numa instância de Map não modificada, a atribuição map["size"] = value lança um TypeError em modo estrito e é ignorada fora desse modo, porque a propriedade herdada size tem um getter, mas não tem um setter.

Exemplos

const key = { id: 1 };
const map = new Map([["first", 1], [key, 2]]);
map.set("first", 3);
map.set(NaN, 4);
map.set(NaN, 5);

console.log(map.size);
console.log(map.get(key));
console.log(map.has({ id: 1 }));
console.log(map.get(NaN));
console.log(JSON.stringify([...map.values()]));

Resultado

3
2
false
5
[3,2,5]

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes