O método find()
retorna o valor do primeiro elemento do array que satisfizer a função de teste provida. Caso contrario, undefined
é retornado.
O código-fonte desse exemplo interativo está em um repositório do GitHub. Se você quiser contribuir para o projeto de exemplos interativos, clone https://github.com/mdn/interactive-examples e nos envie um pull request.
Veja também o método findIndex()
, que retorna o índice do elemento encontrado no array ao invés do seu valor.
Se você precisa encontrar a posição de um elemento ou se um elemento existe em um array, use Array.prototype.indexOf()
ou Array.prototype.includes()
.
Sintaxe
arr.find(callback(element[, index[, array]])[, thisArg])
Parâmetros
callback
- Função executada a cada iteração do array, recebendo três argumentos:
element
- O elemento atual que está sendo processado no array.
index
Optional- O índice do elemento atualmente sendo processado no array.
array
Optional- O array sobre o qual
find
foi chamado.
thisArg
Optional- Opcional. Objeto usado como
this
quando executando ocallback
.
Valor retornado
O valor do primeiro elemento do array que satisfaz a função de teste fornecida; caso contrário, undefined
.
Descrição
O método find
executa a função callback
uma vez para cada elemento presente no array até que encontre um onde callback
retorne o valor true. Se o elemento é encontrado, find
retorna imediatamente o valor deste elemento. Caso contrário, find
retorna undefined
. O callback
é acionado para todos os índices do array de 0
a tamanho-1
, não apenas para aqueles que possuem valores atribuídos. Sendo assim, ele pode ser menos eficiente para arrays esparços que métodos que só visitam índices que tenham valor atribuído.
O callback
é acionado com três argumentos: o valor do elemento, o índice do elemento e o objeto do Array que está sendo cruzado.
Se um parâmetro thisArg
é provido ao find
, ele será usado como o this
para cada acionamento do callback
. Se não for provido, então undefined
é usado.
O find
não altera a array à qual foi acionado.
O conjunto dos elementos processados por find
é definido antes do primeiro acionamento do callback
. Elementos que são anexados à array após o início da chamada ao find
não serão visitados pelo callback
. Se um elemento existente ainda não visitado da array for alterado pelo callback
, o valor passado ao callback
quando o visitar será o valor no momento que find
visita o índice daquele elemento; elementos excluídos ainda são visitados.
Exemplos
Encontrar um objeto em um array por uma de suas propriedades
const inventory = [ {name: 'maças', quantity: 2}, {name: 'bananas', quantity: 0}, {name: 'cerejas', quantity: 5} ]; function isCherries(fruit) { return fruit.name === 'cerejas'; } console.log(inventory.find(isCherries)); // { name: 'cerejas', quantity: 5 }
Utilizando arrow function ES2015
const inventory = [ {name: 'maças', quantity: 2}, {name: 'bananas', quantity: 0}, {name: 'cerejas', quantity: 5} ]; const result = inventory.find( fruit => fruit.name === 'cerejas' ); console.log(result) // { name: 'cerejas', quantity: 5 }
Encontrar um número primo em uma array
O exemplo a seguir encontra um elemento dentro da array que é número primo (ou retorna undefined
se não houverem números primos).
function isPrime(element, index, array) { var start = 2; while (start <= Math.sqrt(element)) { if (element % start++ < 1) { return false; } } return element > 1; } console.log([4, 6, 8, 12].find(isPrime)); // undefined, not found console.log([4, 5, 8, 12].find(isPrime)); // 5
Polyfill
Este método foi adicionado à especificação do ECMAScript 2015 e pode não estar disponível em todas as implementações do JavaScript. Entretanto, você pode fazer um polyfill para o Array.prototype.find
com o trecho de código abaixo:
if (!Array.prototype.find) { Array.prototype.find = function(predicate) { if (this === null) { throw new TypeError('Array.prototype.find called on null or undefined'); } if (typeof predicate !== 'function') { throw new TypeError('predicate must be a function'); } var list = Object(this); var length = list.length >>> 0; var thisArg = arguments[1]; var value; for (var i = 0; i < length; i++) { value = list[i]; if (predicate.call(thisArg, value, i, list)) { return value; } } return undefined; }; }
Especificações
Especificação | Status | Comentário |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Array.prototype.find' in that specification. |
Padrão | Definição inicial. |
Compatibilidade do Navegador
Funcionalidade | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Suporte básico | 45.0 | 25.0 (25.0) | Não suportado | Não suportado | 7.1 |
Funcionalidade | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Suporte básico | Não suportado | Não suportado | 25.0 (25.0) | Não suportado | Não suportado | 8.0 |