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
省略可-
検索し始める位置のゼロから始まるインデックスで、整数に変換されます。
- インデックスが負の場合、配列の末尾からさかのぼって数えます。
fromIndex < 0
の場合、fromIndex + array.length
が使用されます。ただし、この場合でも配列は前から後ろに向けて検索されます。 fromIndex < -array.length
またはfromIndex
が省略された場合は0
が使用され、配列全体に対して検索が行われます。fromIndex >= array.length
の場合、配列の検索は行われず、false
が返されます。
- インデックスが負の場合、配列の末尾からさかのぼって数えます。
返値
論理値で、searchElement
の値が配列内(fromIndex
が指定されていた場合は、配列のその位置以降の部分)にあった場合は true
を返します。
解説
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
の検索を開始するための配列内の位置として、計算により位置が算出されます。計算された位置が 0
以下の場合は、配列全体が検索されます。
// 配列の長さは 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() の呼び出し
includes()
メソッドは this
の length
プロパティを読み込み、次にキーが length
より小さい非負の整数であるそれぞれのプロパティにアクセスします。
const arrayLike = {
length: 3,
0: 2,
1: 3,
2: 4,
3: 1, // length が 3 なので includes() からは無視される
};
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