includes() 方法用来判断一个数组是否包含一个指定的值,根据情况,如果包含则返回 true,否则返回false。

语法

arr.includes(valueToFind[fromIndex])

参数

valueToFind

需要查找的元素值。

Note: When comparing strings and characters, includes() is case-sensitive.

fromIndex 可选
The position in this array at which to begin searching for valueToFind; the first character to be searched is found at fromIndex for positive values of fromIndex, or at array.length + fromIndex for negative values of fromIndex (using the absolute value of fromIndex as the number of characters from the end of the string at which to start the search). Defaults to 0.
从该索引处开始查找 searchElement。如果为负值,则按升序从 array.length - fromIndex 的索引开始搜索。默认为 0。

返回值

A Boolean which is true if the value valueToFind is found within the array (or the part of the array indicated by the index fromIndex, if specified). Values of zero are all considered to be equal regardless of sign (that is, -0 is considered to be equal to both 0 and +0), but false is not considered to be the same as 0.

Note: Technically speaking, includes() uses the sameValueZero algorithm to determine whether the given element is found.

示例

[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

fromIndex 大于等于数组长度

如果 fromIndex 大于等于数组的长度,则会返回 false,且该数组不会被搜索。

var arr = ['a', 'b', 'c'];

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

计算出的索引小于 0

如果 fromIndex 为负值,计算出的索引将作为开始搜索searchElement的位置。如果计算出的索引小于 0,则整个数组都会被搜索。

// array length is 3
// fromIndex is -100
// computed index is 3 + (-100) = -97

var 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()

includes() 方法有意设计为通用方法。它不要求this值是数组对象,所以它可以被用于其他类型的对象 (比如类数组对象)。下面的例子展示了 在函数的 arguments 对象上调用的 includes() 方法。

(function() {
  console.log([].includes.call(arguments, 'a')); // true
  console.log([].includes.call(arguments, 'd')); // false
})('a','b','c');

Polyfill

// https://tc39.github.io/ecma262/#sec-array.prototype.includes
if (!Array.prototype.includes) {
  Object.defineProperty(Array.prototype, 'includes', {
    value: function(valueToFind, fromIndex) {

      if (this == null) {
        throw new TypeError('"this" is null or not defined');
      }

      // 1. Let O be ? ToObject(this value).
      var o = Object(this);

      // 2. Let len be ? ToLength(? Get(O, "length")).
      var len = o.length >>> 0;

      // 3. If len is 0, return false.
      if (len === 0) {
        return false;
      }

      // 4. Let n be ? ToInteger(fromIndex).
      //    (If fromIndex is undefined, this step produces the value 0.)
      var n = fromIndex | 0;

      // 5. If n ≥ 0, then
      //  a. Let k be n.
      // 6. Else n < 0,
      //  a. Let k be len + n.
      //  b. If k < 0, let k be 0.
      var k = Math.max(n >= 0 ? n : len - Math.abs(n), 0);

      function sameValueZero(x, y) {
        return x === y || (typeof x === 'number' && typeof y === 'number' && isNaN(x) && isNaN(y));
      }

      // 7. Repeat, while k < len
      while (k < len) {
        // a. Let elementK be the result of ? Get(O, ! ToString(k)).
        // b. If SameValueZero(valueToFind, elementK) is true, return true.
        if (sameValueZero(o[k], valueToFind)) {
          return true;
        }
        // c. Increase k by 1. 
        k++;
      }

      // 8. Return false
      return false;
    }
  });
}

译者注:polyfill 没有实现 对于 NaN 的检测。

如果你需要支持那些不支持Object.defineProperty的废弃JavaScript 引擎,你最好不要 polyfill Array.prototype 方法,因为你不能使它们不可枚举。

规范

规范 状态 备注
ECMAScript 2016 (ECMA-262)
Array.prototype.includes
Standard Initial definition.
ECMAScript Latest Draft (ECMA-262)
Array.prototype.includes
Draft  

浏览器兼容性

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
includesChrome Full support 47Edge Full support 14Firefox Full support 43IE No support NoOpera Full support 34Safari Full support 9WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support 14Firefox Android Full support 43Opera Android Full support 34Safari iOS Full support 9Samsung Internet Android Full support Yesnodejs Full support 6.0.0
Full support 6.0.0
Full support 5.0.0
Disabled
Disabled From version 5.0.0: this feature is behind the --harmony runtime flag.

Legend

Full support  
Full support
No support  
No support
User must explicitly enable this feature.
User must explicitly enable this feature.

参见

文档标签和贡献者

最后编辑者: mdnwebdocs-bot,