Array.prototype.find()

Podsumowanie

Metoda find() zwraca pierwszy element tablicy, który spełnia warunek podanej funkcji testującej. W przeciwnym razie, gdy żaden element tablicy nie spełni warunku, zwracana jest wartość undefined.

function isBigEnough(element) {
  return element >= 15;
}

[12, 5, 8, 130, 44].find(isBigEnough); // 130

Zobacz także metodę findIndex(), która zwraca indeks znalezionego elementu zamiast jego wartości.

Jeżeli chcesz znaleźć pozycję w tablicy, na której znajduje się dany element, lub sprawdzić, czy element istnieje w tablicy, możesz odnieść się do metod Array.prototype.indexOf() oraz Array.prototype.includes().

Składnia

arr.find(callback[, thisArg])

Parametry

callback

Funkcja do wykonania przy każdym elemencie tablicy, przyjmująca trzy wartości:

element

Element obecnie przetwarzany przez funkcję.

index

Indeks obecnie przetwarzanego elementu.

array

Tablica, na której wywołano funkcję find.

thisArg

Opcjonalny. Obiekt, który będzie się znajdował pod this w czasie wykonywania funkcji callback.

Zwracana wartość

Wartość znajdująca się w tablicy, jeżeli dla danego elementu predykat był dla niego prawdziwy. W przeciwnym wypadku: undefined.

Opis

Metoda find wywołuje raz funkcję callback dla każdego elementu w tablicy, aż do momentu w którym znajdzie taki element, dla którego callback zwraca wartość true. W momencie, w którym taki element zostaje znaleziony, find natychmiast zwraca wartość tego elementu. W przeciwnym razie zostaje zwrócona wartość undefined. Funkcja callback jest wywoływana tylko dla tych indeksów w tablicy, które mają przypisaną jakąś wartość; nie jest natomiast wywoływana dla indeksów, które zostały usunięte, lub którym nigdy nie przypisano wartości.

Funkcja callback jest wywoływana z trzema argumentami, kolejno: wartością elementu tablicy, indeksem tego elementu i obiektem typu Array, który jest przeszukiwany.

Jeżeli parametr thisArg zostanie dostarczony do metody find, będzie on użyty jako wartość this dla każdego wywołania funkcji zwrotnej callback. Jeżeli parametr ten nie zostanie przekazany, to wartość undefined zostanie użyta.

Metoda find nie modyfikuje tablicy, na której jest wywoływana. 

Zakres elementów przetwarzanych przez metodę find jest ustalony przed pierwszym wywołaniem funkcji zwrotnej callback. Elementy, które zostaną dodane do tablicy już po wywołaniu metody find nie zostaną uwzględnione i odwiedzone przez funkcję callback. Jeżeli uprzednio istniejący, nieodwiedzony element zostaje zmodyfikowany przez callback, jego wartość przy wywołaniu callback będzie wartością z chwili, w której find odwiedza indeks tego elementu; elementy usunięte nie są odwiedzane.

Examples

Example: Find a prime number in an array

The following example finds an element in the array that is a prime number (or returns undefined if there is no prime number).

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

This method has been added to the ECMAScript 6 specification and may not be available in all JavaScript implementations yet. However, you can polyfill Array.prototype.find with the following snippet:

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;
  };
}

Specifications

Browser compatibility

See also

• Array.prototype.findIndex()
• Array.prototype.every()