path: root/files/pt-pt/web/javascript/reference/global_objects/array/find/index.html

---
title: Array.prototype.find()
slug: Web/JavaScript/Reference/Global_Objects/Array/find
tags:
  - Array
  - ECMAScript 2015
  - JavaScript
  - Method
  - polyfill
translation_of: Web/JavaScript/Reference/Global_Objects/Array/find
---
<div>{{JSRef}}</div>

<p>O método <code><strong>find()</strong></code> retorna o <strong>valor</strong> do primeiro elemento do array que satisfaça a função de teste fornecida. Caso contrário o valor {{jsxref("undefined")}} é retornado.</p>

<div>{{EmbedInteractiveExample("pages/js/array-find.html")}}</div>



<p>Ver também o método {{jsxref("Array.findIndex", "findIndex()")}} , o qual retorna o <strong>index</strong> de um elemento encontrado num array, em alternativa do seu valor.</p>

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

<h2 id="Sintaxe">Sintaxe</h2>

<pre class="syntaxbox"><var>arr</var>.find(<var>callback</var>[, <var>thisArg</var>])</pre>

<h3 id="Parâmetros">Parâmetros</h3>

<dl>
 <dt><code>callback</code></dt>
 <dd>Função a executar em cada elemento do array, utilizando três argumentos:
 <dl>
  <dt><code>element</code></dt>
  <dd>O elemento a ser processado no array.</dd>
  <dt><code>index</code>{{optional_inline}}</dt>
  <dd>O index do elemento a ser processado no array.</dd>
  <dt><code>array</code>{{optional_inline}}</dt>
  <dd>O array no qual o método <code>find</code> foi chamado.</dd>
 </dl>
 </dd>
 <dt><code>thisArg</code> <code>{{Optional_inline}}</code></dt>
 <dd>Objeto para usar como <code>this</code> ao executar a <code>callback</code>.</dd>
</dl>

<h3 id="Valor_de_retorno">Valor de retorno</h3>

<p>Um valor do array caso um elemento passe no teste; caso contrário, {{jsxref("undefined")}}.</p>

<h2 id="Descrição">Descrição</h2>

<p>O método<code>find</code> executa a <code>callback</code> uma vez para cada index do array até ser encontrado um no qual a <code>callback</code> retorna o valor true. Caso um elemento seja encontrado, o método <code>find</code> retorna imediatamente o seu valor. Caso contrário, o método <code>find</code> retorna {{jsxref("undefined")}}. A função de <code>callback</code> é invocada para cada index do array do <code>0</code> ao <code>length - 1</code> 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.</p>

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

<p>Se o parâmetro <code>thisArg</code> for disponibilizado ao método <code>find</code>, este será usado como <code>this</code> para cada invocação da <code>callback</code>. Caso contrário, será usado o valor {{jsxref("undefined")}}.</p>

<p>O método <code>find</code> não altera o array no qual é invocado.</p>

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

<h2 id="Exemplos">Exemplos</h2>

<h3 id="Encontrar_um_objeto_num_array_através_de_uma_das_suas_propriedades">Encontrar um objeto num array através de uma das suas propriedades</h3>

<pre class="brush: js">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 }</pre>

<h3 id="Encontrar_um_número_primo_num_array">Encontrar um número primo num array</h3>

<p>O seguinte exemplo encontra um elemento no array que seja um número primo (caso não exista, retorna {{jsxref("undefined")}} ).</p>

<pre class="brush: js">function isPrime(element, index, array) {
  var start = 2;
  while (start &lt;= Math.sqrt(element)) {
    if (element % start++ &lt; 1) {
      return false;
    }
  }
  return element &gt; 1;
}

console.log([4, 6, 8, 12].find(isPrime)); // undefined, not found
console.log([4, 5, 8, 12].find(isPrime)); // 5
</pre>

<p>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.</p>

<pre class="brush: js">// 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);
});

</pre>

<h2 id="Polyfill">Polyfill</h2>

<p>Este método foi adicionado ao <em>ECMAScript 2015 Language Specification </em>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:</p>

<pre class="brush: js">// 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 &gt;&gt;&gt; 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 &lt; len
      while (k &lt; 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;
    }
  });
}
</pre>

<p>É melhor não utilizar o polyfill <code>Array.prototype</code> para motores JavaScript obsoletos que não suportem métodos <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty">Object.defineProperty</a></code>, uma vez que, não é possível torna-los não-enumeráveis.</p>

<h2 id="Especificações">Especificações</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Especificação</th>
   <th scope="col">Estado</th>
   <th scope="col">Comentário</th>
  </tr>
  <tr>
   <td>{{SpecName('ES2015', '#sec-array.prototype.find', 'Array.prototype.find')}}</td>
   <td>{{Spec2('ES2015')}}</td>
   <td>Initial definition.</td>
  </tr>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-array.prototype.find', 'Array.prototype.find')}}</td>
   <td>{{Spec2('ESDraft')}}</td>
   <td> </td>
  </tr>
 </tbody>
</table>

<h2 id="Compatibilidade_de_Browsers">Compatibilidade de Browsers</h2>

<div>


<p>{{Compat("javascript.builtins.Array.find")}}</p>
</div>

<h2 id="Ver_também">Ver também</h2>

<ul>
 <li>{{jsxref("Array.prototype.findIndex()")}} – procurar e obter um index</li>
 <li>{{jsxref("Array.prototype.includes()")}} – testar se existe um valor num array</li>
 <li>{{jsxref("Array.prototype.filter()")}} – encontrar todos os elementos</li>
 <li>{{jsxref("Array.prototype.every()")}} – testar se todos os elementos cumprem o requisito</li>
</ul>