Метод includes() з'ясовує, чи масив містить елемент із вказаним значенням, та вертає відповідно true або false.

Синтаксис

var boolean = array.includes(value[, fromIndex])

Параметри

value
Значення елемента, який слід знайти.
fromIndex Optional
Індекс елемента, з якого має розпочатися пошук. Від'ємний індекс означає відлік від кінця масиву (тобто array.length + fromIndex), але пошук у всякому разі здійснюється в напрямку зростання індексу. Якщо fromIndex не вказано, пошук перебиратиме всі елементи від початку до кінця.

Вертає

Boolean.

Приклади

[1, 2, 3].includes(2);      // true
[1, 2, 3].includes(4);      // false
[1, 2, 3].includes(3, 3);   // false
[1, 2, 3].includes(3, -1);  // true
[1, 2, NaN].includes(NaN);  // true

Якщо fromIndex >= array.length

Якщо fromIndex дорівнює або перевищує довжину масиву, пошук не здійснюється й завжди вертається false:

var arr = ['a', 'b', 'c'];

arr.includes('c', 3);    // вертає false
arr.includes('c', 100);  // вертає false

Якщо fromIndex < 0

Якщо значення fromIndex від'ємне, викорстовується обчислений індекс, що визначається відносно кінця масиву:

// Довжина масиву дорівнює 4
// fromIndex дорівнює -2
// Обчислений індекс дорівнює 4 - 2 = 2 (length - fromIndex)

var arr = ['a', 'b', 'c', 'd'];

arr.includes('b', -2);  // вертає false
arr.includes('c', -2);  // вертає true

Водночас, якщо обчислений індекс також менше нуля, пошук здійснюється по всьому масиву:

var arr = ['a', 'b', 'c'];

arr.includes('a', -100);  // вертає true
arr.includes('b', -100);  // вертає true
arr.includes('c', -100);  // вертає true

Узагальнене застосування метода includes()

Реалізація метода includes() є зумисне узагальненою. Об'єкт, на який вказує this, не обов'язково повинен належати до класу Array, тож використання includes() можна поширити на інші масивоподібні об'єкти. В наведеному нижче прикладі його застосовано до об'єкта arguments:

(function() {
  console.log([].includes.call(arguments, 'a'));  // виводить true
  console.log([].includes.call(arguments, 'd'));  // виводить false
})('a','b','c');

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

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

// https://tc39.github.io/ecma262/#sec-array.prototype.includes
if (!Array.prototype.includes) {
  Object.defineProperty(Array.prototype, 'includes', {
    value: function(searchElement, fromIndex) {

      // 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 len is 0, return false.
      if (len === 0) {
        return false;
      }

      // 4. Let n be ? ToInteger(fromIndex).
      //    (If fromIndex is undefined, this step produces the value 0.)
      var n = fromIndex | 0;

      // 5. If n ≥ 0, then
      //  a. Let k be n.
      // 6. Else n < 0,
      //  a. Let k be len + n.
      //  b. If k < 0, let k be 0.
      var k = Math.max(n >= 0 ? n : len - Math.abs(n), 0);

      function sameValueZero(x, y) {
        return x === y || (typeof x === 'number' && typeof y === 'number' && isNaN(x) && isNaN(y));
      }

      // 7. Repeat, while k < len
      while (k < len) {
        // a. Let elementK be the result of ? Get(O, ! ToString(k)).
        // b. If SameValueZero(searchElement, elementK) is true, return true.
        // c. Increase k by 1. 
        if (sameValueZero(o[k], searchElement)) {
          return true;
        }
        k++;
      }

      // 8. Return false
      return false;
    }
  });
}

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

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

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

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung InternetNode.js
Basic supportChrome Full support 47Edge Full support 14Firefox Full support 43IE No support NoOpera Full support 34Safari Full support 9WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support 14Firefox Android Full support 43Opera Android Full support 34Safari iOS Full support 9Samsung Internet Android Full support Yesnodejs Full support 6.0.0
Full support 6.0.0
Full support 5.0.0
Disabled
Disabled From version 5.0.0: 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.

Див. також

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

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