Array.prototype.includes()

¥Syntax

includes(searchElement)
includes(searchElement, fromIndex)

¥Parameters

searchElement

要搜索的值。

fromIndex Optional

开始搜索的从零开始的索引，转换为整数。

• 负索引从数组末尾开始倒数 — 如果使用 -array.length <= fromIndex < 0、fromIndex + array.length。然而，在这种情况下，仍然从前往后搜索数组。
• 如果省略 fromIndex < -array.length 或 fromIndex，则使用 0，导致搜索整个数组。
• 如果是 fromIndex >= array.length，则不搜索数组并返回 false。

¥Return value

一个布尔值，如果在数组（或由索引 fromIndex 指示的数组部分，如果指定）中找到值 searchElement，则为 true。

¥A boolean value which is true if the value searchElement is found within the array (or the part of the array indicated by the index fromIndex, if specified).

¥Description

includes() 方法使用 SameValueZero 算法将 searchElement 与数组的元素进行比较。无论符号如何，零值都被视为相等。（即 -0 等于 0），但 false 不被认为与 0 相同。可以正确搜索到 NaN。

¥The includes() method compares searchElement to elements of the array using the SameValueZero algorithm. Values of zero are all considered to be equal, regardless of sign. (That is, -0 is equal to 0), but false is not considered to be the same as 0. NaN can be correctly searched for.

当在 稀疏数组 上使用时，includes() 方法会迭代空槽，就好像它们具有值 undefined 一样。

¥When used on sparse arrays, the includes() method iterates empty slots as if they have the value undefined.

includes() 方法是 generic。它只期望 this 值具有 length 属性和整数键控属性。

¥The includes() method is generic. It only expects the this value to have a length property and integer-keyed properties.

¥Examples

¥Using 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 is greater than or equal to the array length

如果 fromIndex 大于或等于数组长度，则返回 false。不会搜索该数组。

¥If fromIndex is greater than or equal to the length of the array, false is returned. The array will not be searched.

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

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

¥Computed index is less than 0

如果 fromIndex 为负数，则计算出的索引将用作数组中开始搜索 searchElement 的位置。如果计算出的索引小于或等于 0，则将搜索整个数组。

¥If fromIndex is negative, the computed index is calculated to be used as a position in the array at which to begin searching for searchElement. If the computed index is less than or equal to 0, the entire array will be searched.

// array length is 3
// fromIndex is -100
// computed index is 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

¥Using includes() on sparse arrays

你可以在稀疏数组中搜索 undefined 并得到 true。

¥You can search for undefined in a sparse array and get true.

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

¥Calling includes() on non-array objects

includes() 方法读取 this 的 length 属性，然后访问键为小于 length 的非负整数的每个属性。

¥The includes() method reads the length property of this and then accesses each property whose key is a nonnegative integer less than length.

const arrayLike = {
  length: 3,
  0: 2,
  1: 3,
  2: 4,
  3: 1, // ignored by includes() since length is 3
};
console.log(Array.prototype.includes.call(arrayLike, 2));
// true
console.log(Array.prototype.includes.call(arrayLike, 1));
// false

¥See also

• core-js 中 Array.prototype.includes 的 Polyfill
• 索引集合 指南
• Array
• Array.prototype.indexOf()
• Array.prototype.find()
• Array.prototype.findIndex()
• TypedArray.prototype.includes()
• String.prototype.includes()