MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/MDN-dev-survey

O método filter() cria um novo array com todos os elementos que passaram no teste implementado pela função fornecida.

function isBigEnough(value) {
  return value >= 10;
}

var filtered = [12, 5, 8, 130, 44].filter(isBigEnough);
// filtrado é [12, 130, 44]

Sintaxe

var newArray = arr.filter(callback[, thisArg])

Parâmetros

callback
Função é um predicado, para testar cada elemento do array. Returna true para manter o elemento, false caso contrário, recebendo três argumentos:
element

O elemento que está sendo processado no array.

index
O índice do elemento atual que está sendo processado no array.
array
O  filter do array foi chamado.
thisArg Optional
Opcional. Valor a ser usado como this durante a execução do callback.

Valor de retorno

Um novo array com os elementos que passaram no teste.

Descrição

filter() chama a função callback fornecida, uma vez para cada elemento do array, e constrói um novo array com todos os valores para os quais o callback retornou o valor true ou  um valor que seja convertido para true. O callback é chamado apenas para índices do array que possuem valores atribuídos; Ele não é invocado para índices que foram excluídos ou para aqueles que não tiveram valor atribuído. Elementos do array que não passaram no teste do callback são simplesmente ignorados, e não são incluídos no novo array.

callback é invocado com estes três argumentos:

  1. o valor do elemento
  2. o índice do elemento
  3. o objeto do array a ser preenchido

So o parâmetro thisArg for provido para o filter, ele será passado para o callback quando invocado, para ser usado como o valor do this. Caso contrário, será passado undefined como o valor de this. O valor do this finalmente observado pela função de callback é determinado de acordo com a regra que define o valor do this geralmente visto por uma função.

filter() não altera a array a partir da qual foi invocado.

O intervalo de elementos processados pela função filter() é definido antes da invocação do primeiro callback. Elementos que forem adicionados ao array depois que a invocação do filter() não serão visitados pelo callback. Se elementos existentes no array forem alterados ou deletados, o valor deles passado para o callback será o valor que eles tenham quando o  filter() visitá-los; Elementos que forem deletados não são visitados..

Examples

Example: Filtering out all small values

Os exemplos a seguir usa filter() para criar um array filtrado cujo todos os elementos com valores menores que 10 foram removidos.

function isBigEnough(value) {
  return value >= 10;
}
var filtered = [12, 5, 8, 130, 44].filter(isBigEnough);
// filtered is [12, 130, 44]

Example: Filtrando entradas inválidas para JSON

O exemplo a seguir usa filter() para criar um json filtrado com todos seus elementos diferentes de zero, e id numérido.

var arr = [
  { id: 15 },
  { id: -1 },
  { id: 0 },
  { id: 3 },
  { id: 12.2 },
  { },
  { id: null },
  { id: NaN },
  { id: 'undefined' }
];

var invalidEntries = 0;

function filterByID(obj) {
  if ('id' in obj && typeof(obj.id) === 'number' && !isNaN(obj.id)) {
    return true;
  } else {
    invalidEntries++;
    return false;
  }
}

var arrByID = arr.filter(filterByID);

console.log('Filtered Array\n', arrByID); 
// [{ id: 15 }, { id: -1 }, { id: 0 }, { id: 3 }, { id: 12.2 }]

console.log('Number of Invalid Entries = ', invalidEntries); 
// 4

Polyfill

filter() foi adicionado ao padrão ECMA-262 na 5ª edição; assim como pode não estar presente em todas as implementações do padrão. Você pode trabalhar com isso adicionando o seguinte código no início de seus scripts, permitindo o uso do filter() na implementação ECMA-262 que não tem suporte nativo. Esse algoritmo é exatamente aquele especificado na 5ª edição do ECMA-262, assumindo que fn.call veja o valor original de Function.prototype.call(), e que Array.prototype.push() tenha seu valor original.

if (!Array.prototype.filter) {
  Array.prototype.filter = function(fun/*, thisArg*/) {
    'use strict';

    if (this === void 0 || this === null) {
      throw new TypeError();
    }

    var t = Object(this);
    var len = t.length >>> 0;
    if (typeof fun !== 'function') {
      throw new TypeError();
    }

    var res = [];
    var thisArg = arguments.length >= 2 ? arguments[1] : void 0;
    for (var i = 0; i < len; i++) {
      if (i in t) {
        var val = t[i];

        // NOTE: Technically this should Object.defineProperty at
        //       the next index, as push can be affected by
        //       properties on Object.prototype and Array.prototype.
        //       But that method's new, and collisions should be
        //       rare, so use the more-compatible alternative.
        if (fun.call(thisArg, val, i, t)) {
          res.push(val);
        }
      }
    }

    return res;
  };
}

Especificações

Especificação Status Comentário
ECMAScript 5.1 (ECMA-262)
The definition of 'Array.prototype.filter' in that specification.
Standard Definição inicial. Implementada no JavaScript 1.6.
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Array.prototype.filter' in that specification.
Standard  

Compatibilidade de Browser

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Suporte Básico (Yes) 1.5 (1.8) 9 (Yes) (Yes)
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Suporte Básico (Yes) (Yes) 1.0 (1.8) (Yes) (Yes) (Yes)

Veja também

Etiquetas do documento e colaboradores

 Colaboradores desta página: alexandresn, erikvinicius5, lotharthesavior, felipecaputo
 Última atualização por: alexandresn,