Array.prototype.includes()

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since August 2016.

Методincludes() экземпляровArray определяет, содержит ли массив определенное значение, возвращаяtrue илиfalse.

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

const array1 = [1, 2, 3];console.log(array1.includes(2));// Expected output: trueconst pets = ["cat", "dog", "bat"];console.log(pets.includes("cat"));// Expected output: trueconsole.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); // falsearr.includes("c", 100); // false

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

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

// длина массива равна 3// fromIndex равен -100// вычисленный индекс равен 3 + (-100) = -97const arr = ["a", "b", "c"];arr.includes("a", -100); // truearr.includes("b", -100); // truearr.includes("c", -100); // truearr.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));// trueconsole.log(Array.prototype.includes.call(arrayLike, 1));// false