O método find() retorna o valor do primeiro elemento do array que satisfaça a função de teste fornecida. Caso contrário o valor undefined é retornado.

Ver também o método findIndex() , o qual retorna o index de um elemento encontrado num array, em alternativa do seu valor.

É possível obter a posição de um elemento ou verificar a sua existência num array, através da função Array.prototype.indexOf() ou Array.prototype.includes().

Sintaxe

arr.find(callback[, thisArg])

Parâmetros

callback
Função a executar em cada elemento do array, utilizando três argumentos:
element
O elemento a ser processado no array.
indexOptional
O index do elemento a ser processado no array.
arrayOptional
O array no qual o método find foi chamado.
thisArg Optional
Objeto para usar como this ao executar a callback.

Valor de retorno

Um valor do array caso um elemento passe no teste; caso contrário, undefined.

Descrição

O métodofind executa a callback uma vez para cada index do array até ser encontrado um no qual a callback retorna o valor true. Caso um elemento seja encontrado, o método find retorna imediatamente o seu valor. Caso contrário, o método find retorna undefined. A função de callback é invocada para cada index do array do 0 ao length - 1 e é invocada para todos os indexes, não apenas nos que tem valor. Isto pode significar que é menos eficiente para o um array com muitos elementos sem valor (sparse array) do que outros métodos que visitam apenas os elementos com valor.

A função de callback é invocada com 3 parâmetros: o valor do elemento, o index do elemento, e o Array no qual é executado.

Se o parâmetro thisArg for disponibilizado ao método find, este será usado como this para cada invocação da callback. Caso contrário, será usado o valor undefined.

O método find não altera o array no qual é invocado.

A quantidade de elementos processados pelo método find é definida antes da invocação da callback. Os elementos adicionados ao array após o método find ter iniciado não serão visitados pela callback. Se um elemento existente e não visitado, for alterado pela callback, o seu valor que foi passado para a callback será o valor a ser avaliado pelo método find; Os elementos eliminados após o inicio do método find também serão visitados.

Exemplos

Encontrar um objeto num array através de uma das suas propriedades

var inventory = [
    {name: 'apples', quantity: 2},
    {name: 'bananas', quantity: 0},
    {name: 'cherries', quantity: 5}
];

function isCherries(fruit) { 
    return fruit.name === 'cherries';
}

console.log(inventory.find(isCherries)); 
// { name: 'cherries', quantity: 5 }

Encontrar um número primo num array

O seguinte exemplo encontra um elemento no array que seja um número primo (caso não exista, retorna undefined ).

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

O seguinte exemplo, apresenta como os elementos não existentes e eliminados são visitados e o seu valor passado para a callback será o seu valor quando visitado.

// Declare array with no element at index 2, 3 and 4
var a = [0,1,,,,5,6];

// Shows all indexes, not just those that have been assigned values
a.find(function(value, index) {
  console.log('Visited index ' + index + ' with value ' + value); 
});

// Shows all indexes, including deleted
a.find(function(value, index) {

  // Delete element 5 on first iteration
  if (index == 0) {
    console.log('Deleting a[5] with value ' + a[5]);
    delete a[5];
  }
  // Element 5 is still visited even though deleted
  console.log('Visited index ' + index + ' with value ' + value); 
});

Polyfill

Este método foi adicionado ao ECMAScript 2015 Language Specification e pode não estar disponível em todas as implementações de JavaScript. É possível desenvolver o polyfill do método find com o seguinte código:

// https://tc39.github.io/ecma262/#sec-array.prototype.find
if (!Array.prototype.find) {
  Object.defineProperty(Array.prototype, 'find', {
    value: function(predicate) {
     // 1. Let O be ? ToObject(this value).
      if (this == null) {
        throw new TypeError('"this" is null or not defined');
      }

      var o = Object(this);

      // 2. Let len be ? ToLength(? Get(O, "length")).
      var len = o.length >>> 0;

      // 3. If IsCallable(predicate) is false, throw a TypeError exception.
      if (typeof predicate !== 'function') {
        throw new TypeError('predicate must be a function');
      }

      // 4. If thisArg was supplied, let T be thisArg; else let T be undefined.
      var thisArg = arguments[1];

      // 5. Let k be 0.
      var k = 0;

      // 6. Repeat, while k < len
      while (k < len) {
        // a. Let Pk be ! ToString(k).
        // b. Let kValue be ? Get(O, Pk).
        // c. Let testResult be ToBoolean(? Call(predicate, T, « kValue, k, O »)).
        // d. If testResult is true, return kValue.
        var kValue = o[k];
        if (predicate.call(thisArg, kValue, k, o)) {
          return kValue;
        }
        // e. Increase k by 1.
        k++;
      }

      // 7. Return undefined.
      return undefined;
    }
  });
}

É melhor não utilizar o polyfill Array.prototype para motores JavaScript obsoletos que não suportem métodos Object.defineProperty, uma vez que, não é possível torna-los não-enumeráveis.

Especificações

Especificação Estado Comentário
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Array.prototype.find' in that specification.
Standard Initial definition.
ECMAScript Latest Draft (ECMA-262)
The definition of 'Array.prototype.find' in that specification.
Draft  

Compatibilidade de Browsers

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung InternetNode.js
Basic supportChrome Full support 45Edge Full support YesFirefox Full support 25IE No support NoOpera Full support 32Safari Full support 8WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 4Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support Yesnodejs Full support 4.0.0
Full support 4.0.0
Full support 0.12
Disabled
Disabled From version 0.12: this feature is behind the --harmony runtime flag.

Legend

Full support  
Full support
No support  
No support
User must explicitly enable this feature.
User must explicitly enable this feature.

Ver também

Etiquetas do documento e contribuidores

Contribuidores para esta página: JMoreira93
Última atualização por: JMoreira93,