Esta página foi traduzida do inglês pela comunidade.Saiba mais e junte-se à comunidade MDN Web Docs.
Map
Baseline Widely available *
This feature is well established and works across many devices and browser versions. It’s been available across browsers since julho de 2015.
* Some parts of this feature may have varying levels of support.
O objetoMap contém pares de chave-valor e lembra a ordem original da inserção das chaves. Qualquer valor (objetos evalores primitivos) podem ser usados como chave ou valor.
Experimente
const map1 = new Map();map1.set("a", 1);map1.set("b", 2);map1.set("c", 3);console.log(map1.get("a"));// Expected output: 1map1.set("a", 97);console.log(map1.get("a"));// Expected output: 97console.log(map1.size);// Expected output: 3map1.delete("b");console.log(map1.size);// Expected output: 2Descrição
Um objetoMap itera seus elementos na order da inserção - um loopfor...of retorna um array de[key, value] para cada iteração
Igualdade de chaves
A igualdade de chaves é baseada no algoritimo
sameValueZero.O
NaNé considerado o mesmo que oNaN(apesar deNaN !== NaN) e todos os outros valores são considerados de acordo com a semântica do operador===.Na especificação atual do ECMAScript,
-0e+0são considerados iguais, embora não tenha sido nos esboços anteriores. Veja"Equivalência de valor entre -0 e 0" emCompatibilidade com navegadores para mais detalhes;
Objetos vs. Maps
UmObject é similar oMap - ambos permitem que valores sejam definidos a chaves, retornar esses valores, remover as chaves, e detectar se algo está armazenado na chave. Por esta razão (e porque não existem outras alternativas construídas), oObjeto tem sido usado comoMap historicamente.
Porém, existem diferenças importantes que fazem oMap ser preferido em alguns casos:
| Map | Objeto | |
|---|---|---|
| Chaves acidentais | OMap não contém nenhuma chave por padrão. Ele só contém o que é definido explicitamente nele. | Um Nota: Apartir do ES5, isso pode ser ignorado com o |
| Tipos das chaves | As chaves doMap podem ser qualquer valor (incluindo funções, objetos, ou qualquer outro tipo primitivo). | A chave de umObjeto deve ser umaString ou umSymbol. |
| Ordem das chaves | As chaves dentro do | Embora as chaves de um A ordem foi definida primeiramente para suas próprias propriedades apenas no ECMAScript 2015; no ECMAScript 2020 a ordem definida é por propriedades herdadas também. Veja oOrdinaryOwnPropertyKeys e numerateObjectProperties operações de especificações abstraídas. Mas note que nenhum mecanismo iteratodas as propriedades do objeto; cada um dos vários mecanismos incluem diferentes subconjuntos de propriedades. ( |
Tamanho | O número de items dentro de umMap é facilmente retornado pela propriedadesize | O número de items dentro de umObjeto deve ser determinado manualmente |
| Iteração | UmMap éiterável, então ele pode ser diretamente iterável | O Nota:
|
| Performance | Perfoma melhor em cenários envolvendo adições e remoções frequentes em pares chave-valor. | Não é otimizado para adições e remoções frequentes de pares chave-valor. |
| Serialização e análise sintática | Não há suporte nativo para a serialização ou análise sintática. (Mas você pode construir sua própria serialização e conversão para o | Suporte nativo para serialização de Suporte nativo para conversão de JSON para |
Definindo propriedades no objeto
Definir propriedades no objeto também funciona em objetosMap, e pode causar um confusão considerável.
Portanto, isso aparenta funcionar de certa forma:
const wrongMap = new Map();wrongMap["bla"] = "blaa";wrongMap["bla2"] = "blaaa2";console.log(wrongMap); // Map { bla: 'blaa', bla2: 'blaaa2' }Mas esse jeito de definir propriedades não interage com a estrura de dados doMap. Dessa forma é usada a implementação genérica do objeto. O valor 'bla' não é armazenado noMap para queries. Outras operaçãoes nos dados irão falhar.
wrongMap.has("bla"); // falsewrongMap.delete("bla"); // falseconsole.log(wrongMap); // Map { bla: 'blaa', bla2: 'blaaa2' }A maneira correta para armazenar dados dentro doMap é através doset(key,value)
const contacts = new Map();contacts.set("Jessie", { phone: "213-555-1234", address: "123 N 1st Ave" });contacts.has("Jessie"); // truecontacts.get("Hilary"); // undefinedcontacts.set("Hilary", { phone: "617-555-4321", address: "321 S 2nd St" });contacts.get("Jessie"); // {phone: "213-555-1234", address: "123 N 1st Ave"}contacts.delete("Raymond"); // falsecontacts.delete("Jessie"); // trueconsole.log(contacts.size); // 1Construtor
Map()Cria um novo objeto
Map.
propriedades estáticas
get Map[@@species]A função do construtor que é usada para criar apartir de objetos.
propriedades da instância
Map.prototype.sizeRetorna o número de pares chave/valor no objeto
Map.
Métodos da instância
Map.prototype.clear()Remove todos os pares chave/valor do objeto
Map.Map.prototype.delete(key)Retorna
truese o elemento no objetoMapexistia e tenha sido removido, oufalsese o elemento não existia.Map.prototype.has(key)irá retornarfalseapós isso.Map.prototype.get(key)Retorna o valor associado à chave, ou
undefinedse não há nada.Map.prototype.has(key)Retorna uma asserção booleana se o valor tenha sido associado à chave no objeto
Mapou não.Map.prototype.set(key,value)Define o
valorpara achaveno objetoMap. Retorna o objetoMap
Métodos iterativos
Map.prototype[@@iterator]()Retorna um novo objeto iterador que contèmum array de
[chave, valor]para cada elemento do objetoMapna ordem em que foram inseridos.Map.prototype.keys()Retorna um novo objeto iterador que contèm aschaves de cada elemento do objeto
Mapna ordem em que foram inseridos.Map.prototype.values()Retorna um novo objeto iterador que contém osvalores para cada elemento do objeto
Mapna ordem em que foram inseridos.Map.prototype.entries()Retorna um novo objeto iterador que contèmum array de
[chave, valor]para cada elemento no objetoMapna ordem em que foram inseridos.Map.prototype.forEach(callbackFn[,thisArg])Invoca o
callbackFnuma vez para cada par chave-valor presente no objetoMap, na ordem em que foram inseridos. Se um parâmetrothisArgé provido para oforEach, será usado o valor dethispara cada callback.
Exemplos
Usando o objeto Map
const myMap = new Map();const keyString = "a string";const keyObj = {};const keyFunc = function () {};// setting the valuesmyMap.set(keyString, "value associated with 'a string'");myMap.set(keyObj, "value associated with keyObj");myMap.set(keyFunc, "value associated with keyFunc");myMap.size; // 3// getting the valuesmyMap.get(keyString); // "valor associado a 'a string'"myMap.get(keyObj); // "valor associado a keyObj"myMap.get(keyFunc); // "valor associado a keyFunc"myMap.get("a string"); // "valor associado a 'a string'"// porque keyString === 'a string'myMap.get({}); // undefined, porque keyObj !== {}myMap.get(function () {}); // undefined, porque keyFunc !== function () {}Usando NaN como chaves de Map
NaN também pode ser usado como chave. Apesar de todo oNaN não ser igual a ele mesmo (NaN !== NaN), o exemplo a seguir funciona porque não é possível distinguir umNaN de outros.
const myMap = new Map();myMap.set(NaN, "not a number");myMap.get(NaN);// "not a number"const otherNaN = Number("foo");myMap.get(otherNaN);// "not a number"Iterando o Map com for..of
Maps podem ser iterados usando um loopfor..of:
const myMap = new Map();myMap.set(0, "zero");myMap.set(1, "one");for (const [key, value] of myMap) { console.log(key + " = " + value);}// 0 = zero// 1 = umfor (const key of myMap.keys()) { console.log(key);}// 0// 1for (const value of myMap.values()) { console.log(value);}// zero// onefor (const [key, value] of myMap.entries()) { console.log(key + " = " + value);}// 0 = zero// 1 = oneIterando o Map com forEach()
Maps podem ser iterados usando ométodoforEach():
myMap.forEach(function (value, key) { console.log(key + " = " + value);});// 0 = zero// 1 = umRelação com Arrays
const kvArray = [ ["key1", "value1"], ["key2", "value2"],];// Use o construtor padrão do Map para transformar um array 2D chave-valor em um mapconst myMap = new Map(kvArray);myMap.get("key1"); // retorna "value1"// Use o Array.from() para transformar um map em um Array bidimensional de chaves e valoresconsole.log(Array.from(myMap)); // Irá exibir para você o mesmo Array como um Array chave-valor// Uma forma sucinta de fazer o mesmo, utilizando a sintaxe spreadconsole.log([...myMap]);// Ou use os iteradores keys() ou values(), e os converta para um arrayconsole.log(Array.from(myMap.keys())); // ["key1", "key2"]Clonando e mesclando Maps
Assim comoArrays, o map também pode ser clonado:
const original = new Map([[1, "um"]]);const clone = new Map(original);console.log(clone.get(1)); // umconsole.log(original === clone); // false (Útil para comparações superficiais)Nota:Tenha em mente queo dado em si não é clonado.
Maps podem ser mesclados, mantendo as chaves únicas:
const first = new Map([ [1, "one"], [2, "two"], [3, "three"],]);const second = new Map([ [1, "uno"], [2, "dos"],]);// Mescla dois maps. A última chave a se repetir vence.// O operador spread essenciamente converte um Map para um Arrayconst merged = new Map([...first, ...second]);console.log(merged.get(1)); // unoconsole.log(merged.get(2)); // dosconsole.log(merged.get(3)); // threeMaps podem ser mesclados com array também:
const first = new Map([ [1, "one"], [2, "two"], [3, "three"],]);const second = new Map([ [1, "uno"], [2, "dos"],]);// Mescla maps com um array. A última chave a se repetir vence.const merged = new Map([...first, ...second, [1, "eins"]]);console.log(merged.get(1)); // einsconsole.log(merged.get(2)); // dosconsole.log(merged.get(3)); // threeEspecificações
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-map-objects |