Mozilla wants to hear from developers like you. http://www.surveygizmo.com/s3/2737536/440b74c45e94?a=mdn

Array.prototype.forEach()

Sumário

Execute uma dada função um vez por elemento do vetor.

Sintaxe

array.forEach(callback[, thisArg])

Parâmetros

callback
Função para executar cada elemento.
thisArg
Objeto para usar como this quando executando callback.

Descrição

forEach execute a fornecida callback uma vez para cada elemento da ordem com um valor atribuido. Ele não é invocado para índices que foram deletados ou que foram inicializados para  undefined.

callback é invocado com três argumentos:

  • o valor do elemento
  • o índice do elemento
  • a ordem que está sendo percorrida

Se um parâmetro thisArg é provido para forEach, será usado como o this valor para cada callback invocação como se callback.call(thisArg, element, index, array) fosse chamado. Se thisArg é undefined ou null, o valor this dentro da função depende se a função é em strict mode ou não (valor passado se em strict mode, objeto global se em non-strict mode).

O alcance dos elementos processados por forEach é determinado antes da primeira invocação do callback. Elementos que são anexados para a ordem depois do chamado para iniciar forEach não será visitado por callback. Se os elementos existentes na ordem forem modificados, ou deletados, seus valores passados para callback serão os valores no momento forEach visitá-los; elementos deletados não são visitados.

Exemplos

Imprimindo os conteúdos de uma ordem

Os códigos a seguir logam uma linha para cada elemento na ordem:

function logArrayElements(element, index, array) {
    console.log("a[" + index + "] = " + element);
}
[2, 5, 9].forEach(logArrayElements);
// logs:
// a[0] = 2
// a[1] = 5
// a[2] = 9

Função para cópia de um objeto

O código a seguir cria uma cópia para cada objeto dado. Há diferentes formas de criar uma cópia para um objeto. Esta é somente uma forma de explicar como  Array.prototype.forEach funciona. Ela usa um grupo de novas funções ECMAScript 5 Object.*

function copy(o){
  var copy = Object.create( Object.getPrototypeOf(o) );
  var propNames = Object.getOwnPropertyNames(o);

  propNames.forEach(function(name){
    var desc = Object.getOwnPropertyDescriptor(o, name);
    Object.defineProperty(copy, name, desc);
  });

  return copy;
}

var o1 = {a:1, b:2};
var o2 = copy(o1); // o2 looks like o1 now

Compatibilidade

forEach é uma adição recente para o ECMA-262 standard; assim sendo, pode não estar presente em outras implementações do standard. Você pode contornar isto pela inserção do código a seguir no começo de seus scripts, permitindo o uso de forEach em implementações que normalmente não possuem este suporte.

if ( !Array.prototype.forEach ) {
  Array.prototype.forEach = function(fn, scope) {
    for(var i = 0, len = this.length; i < len; ++i) {
      fn.call(scope, this[i], i, this);
    }
  };
}

Um algorítimo 100% verdadeiro para a 5ª Edição do ECMA-262, pode ser visto abaixo:

O algoritmo é exatamente o especificado na 5ª Edição da  ECMA-262, assumindo Object e TypeError possuem seus valores originais e avalia callback.call para o valor original de Function.prototype.call.

// Production steps of ECMA-262, Edition 5, 15.4.4.18
// Reference: http://es5.github.com/#x15.4.4.18
if ( !Array.prototype.forEach ) {

  Array.prototype.forEach = function forEach( callback, thisArg ) {

    var T, 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; // Hack to convert O.length to a UInt32

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

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

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

    // 7. Repeat, while k < len
    while( k < len ) {

      var kValue;

      // 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 ( Object.prototype.hasOwnProperty.call(O, k) ) {

        // i. Let kValue be the result of calling the Get internal method of O with argument Pk.
        kValue = O[ k ];

        // ii. Call the Call internal method of callback with T as the this value and
        // argument list containing kValue, k, and O.
        callback.call( T, kValue, k, O );
      }
      // d. Increase k by 1.
      k++;
    }
    // 8. return undefined
  };
}

Compatibilidade de Browser

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support (Yes) 1.5 9 (Yes) (Yes)
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? ? ? ? ?

Baseado em Kangax's compat tables

Veja também

Array.map

Etiquetas do documento e colaboradores

 Colaboradores desta página: deyvidyury, rafaelescrich, teoli, nah_luquiari
 Última atualização por: deyvidyury,