Array.prototype.map()

Baseline Widely available

This feature is well established and works across many devices and browser versions. Its been available across browsers since julho de 2015.

Learn more
See full compatibility

Experimente

const array1 = [1, 4, 9, 16];

// Pass a function to map
const map1 = array1.map((x) => x * 2);

console.log(map1);
// Expected output: Array [2, 8, 18, 32]

Resumo

O mtodo map() invoca a funo callback passada por argumento para cada elemento do Array e devolve um novo Array como resultado.

Sintaxe

arr.map(callback[, thisArg])

Parmetros

callback

Funo cujo retorno produz o elemento do novo Array. Recebe trs argumentos:

valorAtual: O valor do elemento original do Array de origem.
indice: O ndice do elemento atual que est sendo processado no array.
array: O Array de origem.

thisArg

Opcional. Valor a ser utilizado como o this no momento da execuo da funo callback.

O mtodo map chama a funo callback recebida por parmetro para cada elemento do Array original, em ordem, e constri um novo array com base nos retornos de cada chamada. A funo callback chamada apenas para os elementos do array original que tiverem valores atribudos; os elementos que estiverem como undefined, que tiverem sido removidos ou os que nunca tiveram valores atribudos no sero considerados.

A funo callback chamada com trs argumentos: o valor do elemento corrente, o ndice do elemento corrente e o array original que est sendo percorrido.

Se o parametro thisArg foi passado para o mtodo map, ele ser repassado para a funo callback no momento da invocao para ser utilizado como o this. Caso contrrio, o valor undefined ser repassado para uso como o this. O valor do this a ser repassado para o callback deve respeitar as regras para determinar como o this acessado por uma funo (em ingls).

O mtodo map no modifica o array original. No entanto, a funo callback invocada por ele pode faz-lo.

A lista de elementos que sero processados pelo map montada antes da primeira invocao funo callback. Se um elemento for acrescentado ao array original aps a chamada ao map, ele no ser visvel para o callback. Se os elementos existentes forem modificados, os valores que sero repassados sero os do momento em que o mtodo map invocar o callback. Elementos removidos no sero visitados.

Exemplos

Exemplo: Mapeando um array de nmeros para um array de razes quadradas

O cdigo a seguir mapeia um array de nmeros e cria um novo array contendo o valor da raiz quadrada de cada nmero do primeiro array.

var numbers = [1, 4, 9];
var roots = numbers.map(Math.sqrt);
// roots  [1, 2, 3], numbers ainda  [1, 4, 9]

Exemplo: Mapeando um array de nmeros usando uma funo `callback` que contm um argumento

O cdigo a seguir mostrar como o mtodo map funciona quando a funo callback possui apenas um argumento. Esse argumento ser automaticamente atribudo para cada elemento do array conforme o map itera sobre o array original.

var numbers = [1, 4, 9];
var doubles = numbers.map(function (num) {
  return num * 2;
});
// doubles  agora [2, 8, 18]. numbers ainda  [1, 4, 9]

Exemplo: usando `map` genericamente

Esse exemplo demonstra como usar o map em um String para recuperar a representao em ASCII de cada caracter em um array de bytes:

var map = Array.prototype.map;
var a = map.call("Hello World", function (x) {
  return x.charCodeAt(0);
});
// a agora vale [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]

Exemplo: usando `map` genericamente com `querySelectorAll`

Esse exemplo demonstra como iterar sobre uma coleo de objetos recuperada atravs de querySelectorAll. Nesse caso, vamos pegar todos os options selecionados na tela e imprimir no console:

var elems = document.querySelectorAll("select option:checked");
var values = [].map.call(elems, function (obj) {
  return obj.value;
});

Exemplo: Usando `map` para inverter uma string

var str = "12345";
[].map
  .call(str, function (x) {
    return x;
  })
  .reverse()
  .join("");

// Output: '54321'
// Bonus: utilize '===' para verificar se a string original e a nova string so palndromos

Exemplo: Caso de uso mais complexo

(inspirado nesse post) (em ingls)

uma prtica comum utilizar o callback com apenas um argumento (o elemento atual do array original). Algumas funes tambm so comumente utilizadas com um argumento, mesmo tendo argumentos adicionais opcionais. Esses hbitos podem resultar em comportamentos indesejado:

// Considere:
["1", "2", "3"].map(parseInt);
// Enquanto era de se esperar [1, 2, 3]
// O resultado atual  [1, NaN, NaN]

// parseInt  normalmente usado com apenas um argumento, mas ele possui dois.
// O primeiro  uma expresso, e o segundo o radical.
// Para a funo callback, o Array.prototype.map repassa 3 argumentos:
// o elemento corrente, o indice e o array original
// O terceiro argumento  ignorado pelo parseInt, mas o segundo no, o que certamente gerou o comportamento inesperado. Veja o post para maiores detalhes

function returnInt(element) {
  return parseInt(element, 10);
}

["1", "2", "3"].map(returnInt); // [1, 2, 3]
// O resultado atual  um array de nmeros (como esperado)

// Bonus: Um jeito mais simples de conseguir o mesmo resultado sem nenhuma "pegadinha do Malandro":
["1", "2", "3"].map(Number); // [1, 2, 3]

Polyfill

(veja definio em Polyfill)

O mtodo map foi introduzido ao padro ECMA-262 na sua 5 edio, o que significa que ele pode no estar presente em todas as implementaes desse padro. Voc pode contornar esse problema inserindo o cdigo a seguir no incio dos seus scripts, permitindo o uso do map mesmo que ele no esteja sendo suportado nativamente. Esse algoritmo exatamente o especificado no ECMA-262 5 edio, assumindo que Object, TypeError, e Array tenham seus valores originais, e que callback.call avalie para o valor original de Function.prototype.call.

// Production steps of ECMA-262, Edition 5, 15.4.4.19
// Reference: http://es5.github.io/#x15.4.4.19
if (!Array.prototype.map) {
  Array.prototype.map = function (callback, thisArg) {
    var T, A, k;

    if (this == null) {
      throw new TypeError(" this is null or not defined");
    }

    //  1. Let O be the result of calling ToObject passing the |this|
    //    value as the argument.
    var O = Object(this);

    // 2. Let lenValue be the result of calling the Get internal
    //    method of O with the argument "length".
    // 3. Let len be ToUint32(lenValue).
    var len = O.length >>> 0;

    // 4. If IsCallable(callback) is false, throw a TypeError exception.
    // See: http://es5.github.com/#x9.11
    if (typeof callback !== "function") {
      throw new TypeError(callback + " is not a function");
    }

    // 5. If thisArg was supplied, let T be thisArg; else let T be undefined.
    if (arguments.length > 1) {
      T = thisArg;
    }

    // 6. Let A be a new array created as if by the expression new Array(len)
    //    where Array is the standard built-in constructor with that name and
    //    len is the value of len.
    A = new Array(len);

    // 7. Let k be 0
    k = 0;

    // 8. Repeat, while k < len
    while (k < len) {
      var kValue, mappedValue;

      // a. Let Pk be ToString(k).
      //   This is implicit for LHS operands of the in operator
      // b. Let kPresent be the result of calling the HasProperty internal
      //    method of O with argument Pk.
      //   This step can be combined with c
      // c. If kPresent is true, then
      if (k in O) {
        // i. Let kValue be the result of calling the Get internal
        //    method of O with argument Pk.
        kValue = O[k];

        // ii. Let mappedValue be the result of calling the Call internal
        //     method of callback with T as the this value and argument
        //     list containing kValue, k, and O.
        mappedValue = callback.call(T, kValue, k, O);

        // iii. Call the DefineOwnProperty internal method of A with arguments
        // Pk, Property Descriptor
        // { Value: mappedValue,
        //   Writable: true,
        //   Enumerable: true,
        //   Configurable: true },
        // and false.

        // In browsers that support Object.defineProperty, use the following:
        // Object.defineProperty(A, k, {
        //   value: mappedValue,
        //   writable: true,
        //   enumerable: true,
        //   configurable: true
        // });

        // For best browser support, use the following:
        A[k] = mappedValue;
      }
      // d. Increase k by 1.
      k++;
    }

    // 9. return A
    return A;
  };
}