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 September 2016.
Метод includes()
экземпляров Array
определяет, содержит ли массив определенное значение, возвращая true
или 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
Спецификации
Specification |
---|
ECMAScript Language Specification # sec-array.prototype.includes |
Совместимость с браузерами
BCD tables only load in the browser