O método includes()
determina se um array contém um determinado elemento, devolvendo true
ou false
. É utilizado o algoritmo sameValueZero para determinar se o elemento especificado foi encontrado.
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
Syntax
arr.includes(searchElement[, fromIndex])
Parameters
searchElement
- The element to search for.
fromIndex
Optional- The position in this array at which to begin searching for
searchElement
. A negative value searches from the index ofarray.length - fromIndex
by asc. Defaults to 0.
Return value
A Boolean
.
Examples
[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 is greater than or equal to the array length
If fromIndex
is greater than or equal to the length of the array, false
is returned. The array will not be searched.
var arr = ['a', 'b', 'c'];
arr.includes('c', 3); // false
arr.includes('c', 100); // false
Computed index is less than 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 0, the entire array will be searched.
// 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
includes() used as a generic method
includes()
method is intentionally generic. It does not require this
value to be an Array object, so it can be applied to other kinds of objects (e.g. array-like objects). The example below illustrates includes()
method called on the function's arguments object.
(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(searchElement, 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(searchElement, elementK) is true, return true.
if (sameValueZero(o[k], searchElement)) {
return true;
}
// c. Increase k by 1.
k++;
}
// 8. Return false
return false;
}
});
}
If you need to support truly obsolete JavaScript engines that don't support Object.defineProperty
, it's best not to polyfill Array.prototype
methods at all, as you can't make them non-enumerable.
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript 2016 (ECMA-262) The definition of 'Array.prototype.includes' in that specification. |
Standard | Initial definition. |
ECMAScript (ECMA-262) The definition of 'Array.prototype.includes' in that specification. |
Living Standard |
Browser compatibility
BCD tables only load in the browser