MDN will be in maintenance mode on Thursday September 21st, starting at 10 AM Pacific / 5 PM UTC, for about 1 hour.

Метод find() повертає значення першого елементу в масиві, що задовільняє передану функцію тестування. Інакше вертається undefined.

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

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

Зверніть увагу також на метод findIndex(), що натомість повертає індекс знайденого елементу масиву, а не значення.

Якщо вам необхідно знайти розташування елементу або дізнатись чи існує шукане значення в масиві, використовуйте Array.prototype.indexOf() або Array.prototype.includes().

Синтаксис

arr.find(callback[, thisArg])

Параметри

callback
Функція, що виконується для кожного значення в масиві і приймає три аргументи:
element
Значення поточного елементу масиву.
index
Індекс поточного елементу масиву.
array
Масив для якого було викликано find().
thisArg Optional
Об'єкт який використовувати як this коли виконується callback.

Вертає

Значення в масиві якщо елемент проходить тест; в іншому випадку, undefined.

Опис

Метод find() виконує callback функцію один раз для кожного елементу в масиві, аж поки не буде знайдено такий, для якого callback повертає значення true. Щойно такий елемент знайдено, find() одразу ж повертає значення цього елементу. В іншому випадку, find() повертає undefined. Функція callback викликається лише для тих індексів масиву, які мають присвоєне значення; вона ніколи не викликається для тих індексів які було видалено або які ніколи не мали присвоєного значення.

Функція callback викликається з трьома параметрами: значення елементу, індекс елементу, і посилання на об'єкт класу Array, перебір якого здійснюється.

Якщо параметр thisArg передано до find(), його буде використано як this для кожного виклику callback. Якщо його не передано, тоді undefined використовуватиметься.

Власне метод find() не змінює масив для на якому він викликаний. Але ніщо не завадить зробити якісь зміни з функції callback.

Діапазон елементів, що їх має обробити find(), визначається ще до першого виклику функції callback. Всі елементи, які буде додано до масива після виклику метода find(), буде проігноровано — функція callback для них не викликатиметься:

var arr = [111, 222, 333];
var visited = [];

var found = arr.find(function(value, index, array) {
  array.push(999);
  visited.push(value);
  return false;
});

console.log(found);    // виводить undefined
console.log(arr);      // виводить [111, 222, 333, 999, 999, 999]
console.log(visited);  // виводить [111, 222, 333]

Якщо наявні від початку, але ще не відвідані, елементи змінити з функції callback, зміни буде враховано:

var arr = ['old-1', 'old-2', 'old-3'];

var found = arr.find(function(value, index, array) {
  if (index === 1) {
    array[2] = 'new';
  }
  return value === 'new';
});

console.log(found);  // виводить 'new'
console.log(arr);    // ['old-1', 'old-2', 'new']

Втім, змінювання значення елементу під час його відвідин, не вплине на перебіг виконання find():

var arr = ['old-1', 'old-2', 'old-3'];

var found = arr.find(function(value, index, array) {
  if (value === 'old-2') {
    array[index] = 'new';
    return true;
  }

  return false;
});

console.log(found);  // виводить 'old-2'
console.log(arr);    // ['old-1', 'new', 'old-3']

Більш того, видалені елементи все одно буде відвідано:

var arr = [111, 222, 333, 444, 555, 666];
var visited = [];

var found = arr.find(function(value, index, array) {
  visited.push(value);
  if (value === 222) {
    delete array[2];       // 333
    array[4] = undefined;  // 555
  }
  return false;
});

console.log(found);    // виводить undefined
console.log(arr);      // [111, 222, undefined, 444, undefined, 666]
console.log(visited);  // [111, 222, undefined, 444, undefined, 666]

Приклади

Знайти об'єкт в масиві за однією з його властивостей

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

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

// виводить { name: 'cherries', quantity: 5 }
console.log(inventory.find(findCherries));

Знайти просте число в масиві

Наступний приклад знаходить елемент в масиві, який є простим числом (або повертає undefined якщо простого числа немає):

function isPrime(element, index, array) {
  var start = 2;
  while (start <= Math.sqrt(element)) {
    if (element % start++ < 1) {
      return false;
    }
  }
  return element > 1;
}

[4, 6, 8, 12].find(isPrime);  // вертає undefined, простих чисел не знайдено
[4, 5, 8, 12].find(isPrime);  // вертає 5

Запасний варіант (поліфіл)

Якщо вам потрібно забезпечити підтримку вкрай застарілих рушіїв JavaScript, в яких відсутня підтримка Object.defineProperty, було б краще взагалі не додавати методів до Array.prototype через відсутність можливості заборонити їх перебір.

Цей метод з'явився в ECMAScript 2015, тож, можливо, наявний не у всякій реалізації JavaScript. Проте, ви можете використати наступний код для забезпечення запасного варіанту:

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

Специфікації

Специфікації Статус Коментар
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Array.prototype.find' in that specification.
Standard Первинне визначення.
ECMAScript Latest Draft (ECMA-262)
The definition of 'Array.prototype.find' in that specification.
Living Standard  

Підтримка веб-переглядачами

Feature Chrome Firefox (Gecko) Internet Explorer Edge Opera Safari
Basic support 45.0 25.0 (25.0) No support 12 32.0 7.1
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Edge Opera Mobile Safari Mobile
Basic support No support No support 25.0 (25.0) No support 12 No support 8.0

Див. також

Мітки документа й учасники

 Зробили внесок у цю сторінку: asmforce, Careless_angel, RuslanaGRA, braggae
 Востаннє оновлена: asmforce,