Array.prototype.includes()

Интерактивный пример

const array1 = [1, 2, 3];

console.log(array1.includes(2));
// Expected output: true

const pets = ["cat", "dog", "bat"];

console.log(pets.includes("cat"));
// Expected output: true

console.log(pets.includes("at"));
// Expected output: false

Синтаксис

includes(searchElement)
includes(searchElement, fromIndex)

Параметры

searchElement

Проверяемое значение.

fromIndex Необязательный

Индекс, с которого начинать поиск. Начинается с нуля и преобразуется в целое число.

• При отрицательных значениях поиск производится с конца массива. Если -array.length <= fromIndex < 0, то будет применено значение fromIndex + array.length. Однако в этом случае поиск будет производится с начала массива.
• Если fromIndex < -array.length или fromIndex не указан, то используется значение 0, то есть производится поиск по всему массиву.
• Если fromIndex >= array.length, то поиск не производится и возвращается false.

Возвращаемое значение

Логическое значение, true если значение searchElement найдено в массиве (или части массива, если указан параметр fromIndex).

Описание

Метод includes() сравнивает searchElement с элементами массива используя алгоритм сравнения SameValueZero. Все нулевые значения считаются равными, независимо от знака (то есть -0 и 0 равны), но false не равно 0. Значение NaN доступно для поиска.

При использовании в разреженных массивах, метод includes() метод считает, что пустые позиции имеют значение undefined.

Метод includes() является универсальным, то есть может быть вызван не только у массивов, но и у массивоподобных объектов (у которых значение this имеет свойство length и свойства с целочисленными ключами).

Примеры

Использование includes()

[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
["1", "2", "3"].includes(3); // false

fromIndex больше или равен длине массива

Если fromIndex больше или равен длине массива, то возвращается false. При этом поиск не производится.

const arr = ["a", "b", "c"];

arr.includes("c", 3); // false
arr.includes("c", 100); // false

Вычисленный индекс меньше нуля 0

Если fromIndex отрицательный, то вычисляется индекс, начиная с которого будет производиться поиск элемента searchElement. Если вычисленный индекс меньше нуля, то поиск будет производиться во всём массиве.

// длина массива равна 3
// fromIndex равен -100
// вычисленный индекс равен 3 + (-100) = -97

const arr = ["a", "b", "c"];

arr.includes("a", -100); // true
arr.includes("b", -100); // true
arr.includes("c", -100); // true
arr.includes("a", -2); // false

Использование includes() в разреженных массивах

Можно производить поиск undefined в разреженном массиве и получать true.

console.log([1, , 3].includes(undefined)); // true

Вызов includes() у объектов, не являющихся массивами

Метод include() считывает свойство length у this, а затем обращается к каждому свойству, ключ которого представляет собой неотрицательное целое число, меньшее length.

const arrayLike = {
  length: 3,
  0: 2,
  1: 3,
  2: 4,
  3: 1, // includes() не будет обращаться к этому элементу, потому что свойство length равно 3
};
console.log(Array.prototype.includes.call(arrayLike, 2));
// true
console.log(Array.prototype.includes.call(arrayLike, 1));
// false

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

Совместимость с браузерами

Смотрите также

• Полифил Array.prototype.includes в core-js
• Руководство по индексируемым коллекциям
• Array
• Array.prototype.indexOf()
• Array.prototype.find()
• Array.prototype.findIndex()
• TypedArray.prototype.includes()
• String.prototype.includes()