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

Syntax

js
includes(searchElement)
includes(searchElement, fromIndex)

Parameter

searchElement

Der zu suchende Wert.

fromIndex Optional

Der nullbasierte Index, ab dem die Suche startet, in eine ganze Zahl konvertiert.

  • Ein negativer Index zählt vom Ende des Arrays zurück — falls -array.length <= fromIndex < 0, wird fromIndex + array.length verwendet. Das Array wird in diesem Fall jedoch weiterhin 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, wird das Array nicht durchsucht und false zurückgegeben.

Rückgabewert

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

Beschreibung

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

Wenn die includes() Methode auf lückenhaften Arrays verwendet wird, durchläuft sie leere Slots, als ob sie den Wert undefined hätten.

Die includes() Methode ist generisch. Es wird nur erwartet, dass der this Wert eine length Eigenschaft und Integer-gekachelte 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 Array-Länge

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 zur Verwendung als Position im Array berechnet, um mit der Suche nach searchElement zu beginnen. 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() auf lückenhaften Arrays

Sie können nach undefined in einem lückenhaften Array suchen und true erhalten.

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

Aufruf von includes() auf Nicht-Array-Objekten

Die includes() Methode liest die length Eigenschaft von this und greift dann auf jede Eigenschaft zu, deren Schlüssel eine nichtnegative Ganzzahl 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 Language Specification
# sec-array.prototype.includes

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch