Array.prototype.values()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since May 2018.

Die values() Methode von Array Instanzen gibt ein neues Array-Iterator-Objekt zurück, das den Wert jedes Eintrags des Arrays durchläuft.

Probieren Sie es aus

const array1 = ["a", "b", "c"];
const iterator = array1.values();

for (const value of iterator) {
  console.log(value);
}

// Expected output: "a"
// Expected output: "b"
// Expected output: "c"

Syntax

values()

Beschreibung

Array.prototype.values() ist die Standardimplementierung von Array.prototype[Symbol.iterator]().

Array.prototype.values === Array.prototype[Symbol.iterator]; // true

Wird die Methode auf dünn besetzten Arrays verwendet, iteriert sie über leere Slots, als hätten sie den Wert undefined.

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

Beispiele

Iteration mit einer for...of Schleife

Da values() einen iterablen Iterator zurückgibt, können Sie eine for...of Schleife verwenden, um darüber zu iterieren.

const arr = ["a", "b", "c", "d", "e"];
const iterator = arr.values();

for (const letter of iterator) {
  console.log(letter);
} // "a" "b" "c" "d" "e"

Iteration mit next()

Da der Rückgabewert auch ein Iterator ist, können Sie direkt dessen next() Methode aufrufen.

const arr = ["a", "b", "c", "d", "e"];
const iterator = arr.values();
iterator.next(); // { value: "a", done: false }
iterator.next(); // { value: "b", done: false }
iterator.next(); // { value: "c", done: false }
iterator.next(); // { value: "d", done: false }
iterator.next(); // { value: "e", done: false }
iterator.next(); // { value: undefined, done: true }
console.log(iterator.next().value); // undefined

Wiederverwendung des Iterables

Warnung: Das Array-Iterator-Objekt sollte nur einmal verwendet werden. Verwenden Sie es nicht erneut.

Das Iterable, das von values() zurückgegeben wird, ist nicht wiederverwendbar. Wenn next().done = true oder currentIndex > length, endet die for...of Schleife, und ein weiteres Iterieren hat keinen Effekt.

const arr = ["a", "b", "c", "d", "e"];
const values = arr.values();
for (const letter of values) {
  console.log(letter);
}
// "a" "b" "c" "d" "e"
for (const letter of values) {
  console.log(letter);
}
// undefined

Wenn Sie eine break Anweisung verwenden, um die Iteration frühzeitig zu beenden, kann der Iterator an der aktuellen Position fortfahren, wenn Sie ihn weiter iterieren.

const arr = ["a", "b", "c", "d", "e"];
const values = arr.values();
for (const letter of values) {
  console.log(letter);
  if (letter === "b") {
    break;
  }
}
// "a" "b"

for (const letter of values) {
  console.log(letter);
}
// "c" "d" "e"

Änderungen während der Iteration

Es werden keine Werte im Array-Iterator-Objekt gespeichert, das von values() zurückgegeben wird; stattdessen speichert es die Adresse des Arrays, das bei seiner Erstellung verwendet wurde, und liest den aktuell besuchten Index bei jeder Iteration. Daher hängt die Ausgabe der Iteration von dem Wert ab, der zu diesem Zeitpunkt an diesem Index gespeichert ist. Wenn sich die Werte im Array ändern, ändern sich auch die Werte des Array-Iterator-Objekts.

const arr = ["a", "b", "c", "d", "e"];
const iterator = arr.values();
console.log(iterator); // Array Iterator { }
console.log(iterator.next().value); // "a"
arr[1] = "n";
console.log(iterator.next().value); // "n"

Im Gegensatz zu iterativen Methoden speichert das Array-Iterator-Objekt nicht die Länge des Arrays bei seiner Erstellung, sondern liest sie bei jeder Iteration. Daher, wenn das Array während der Iteration wächst, wird der Iterator auch die neuen Elemente besuchen. Dies kann zu Endlosschleifen führen.

const arr = [1, 2, 3];
for (const e of arr) {
  arr.push(e * 10);
}
// RangeError: invalid array length

Iteration von dünn besetzten Arrays

values() wird leere Slots besuchen, als wären sie undefined.

for (const element of [, "a"].values()) {
  console.log(element);
}
// undefined
// 'a'

Aufruf von values() auf Nicht-Array-Objekten

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

const arrayLike = {
  length: 3,
  0: "a",
  1: "b",
  2: "c",
  3: "d", // ignored by values() since length is 3
};
for (const entry of Array.prototype.values.call(arrayLike)) {
  console.log(entry);
}
// a
// b
// c

Spezifikationen

Specification
ECMAScript® 2026 Language Specification # sec-array.prototype.values