Array.prototype.includes()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨август 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