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.

Die includes() Methode von Array Instanzen bestimmt, ob ein Array einen bestimmten Wert unter seinen Einträgen enthält und gibt entsprechend true oder false zurück.

Probieren Sie es aus

const array1 = [1, 2, 3];

console.log(array1.includes(2));
// Expected output: true

const pets = ["cat", "dog", "bat"];

console.log(pets.includes("cat"));
// Expected output: true

console.log(pets.includes("at"));
// Expected output: false

Syntax

js
includes(searchElement)
includes(searchElement, fromIndex)

Parameter

searchElement

Der Wert, nach dem gesucht werden soll.

fromIndex Optional

Der nullbasierte Index, bei dem die Suche beginnen soll, umgewandelt in eine Ganzzahl.

  • Ein negativer Index zählt vom Ende des Arrays zurück — wenn -array.length <= fromIndex < 0, wird fromIndex + array.length verwendet. In diesem Fall wird das Array jedoch trotzdem von vorne nach hinten durchsucht.
  • Wenn fromIndex < -array.length oder fromIndex weggelassen wird, wird 0 verwendet, wodurch das gesamte Array durchsucht wird.
  • Wenn fromIndex >= array.length ist, wird das Array nicht durchsucht und false wird zurückgegeben.

Rückgabewert

Ein boolescher Wert, der true ist, wenn der Wert searchElement im Array (oder im angegebenen Teil des Arrays durch den Index fromIndex) gefunden wird.

Beschreibung

Die includes() Methode vergleicht searchElement mit Elementen des Arrays anhand des SameValueZero Algorithmus. Werte von Null werden alle als gleich angesehen, unabhängig vom Vorzeichen. (Das heißt, -0 ist gleich 0), aber false wird nicht als dasselbe wie 0 angesehen. NaN kann korrekt gesucht werden.

Bei Verwendung für dünn besetzte Arrays durchläuft die includes() Methode leere Stellen, als hätten sie den Wert undefined.

Die includes() Methode ist generisch. Sie erwartet nur, dass der this Wert eine length Eigenschaft und integer-beschriftete Eigenschaften hat.

Beispiele

Verwendung von includes()

js
[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 ist größer oder gleich der Länge des Arrays

Wenn fromIndex größer oder gleich der Länge des Arrays ist, wird false zurückgegeben. Das Array wird nicht durchsucht.

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

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

Berechneter Index ist kleiner als 0

Wenn fromIndex negativ ist, wird der berechnete Index verwendet, um eine Position im Array zu bestimmen, an der die Suche nach searchElement begonnen werden soll. Wenn der berechnete Index kleiner oder gleich 0 ist, wird das gesamte Array durchsucht.

js
// 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

Verwendung von includes() bei dünn besetzten Arrays

Sie können nach undefined in einem dünn besetzten Array suchen und erhalten true.

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

Aufrufen von includes() bei Nicht-Array-Objekten

Die includes() Methode liest die length Eigenschaft von this und greift dann auf jede Eigenschaft zu, deren Schlüssel eine nicht-negative Ganzzahl ist, die kleiner als length ist.

js
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

Spezifikationen

Specification
ECMAScript® 2025 Language Specification
# sec-array.prototype.includes

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch