NodeList.values() — Methode · JavaScript-Referenz

Signatur

NodeList.prototype.values()

Beschreibung

Die Methode values() einer NodeList gibt ein Iterator-Objekt zurück, das dem Iterationsprotokoll entspricht. Jeder Aufruf von next() liefert ein Objekt { value, done }, wobei value der jeweils nächste Knoten in Dokumentreihenfolge ist.

In der Praxis nutzt man values() selten direkt, denn NodeList.prototype[Symbol.iterator] ist genau dieselbe Funktion. Eine for...of-Schleife oder der Spread-Operator ([...nodeList]) greifen also implizit auf values() zurück. Nützlich ist der explizite Aufruf, wenn man einen Iterator manuell steuern will (z. B. schrittweise mit next()) oder ihn an Funktionen übergeben möchte, die einen Iterator erwarten.

Zu beachten: Ist die NodeList live (etwa element.childNodes), spiegelt der Iterator Änderungen am DOM während der Iteration wider. Die von querySelectorAll() gelieferte Liste ist dagegen statisch.

Rückgabewert

Typ

Iterator<Node>

Beschreibung

Ein neues Iterator-Objekt, das die Knoten der NodeList der Reihe nach liefert.

Beispiele

Knoten manuell mit next() durchlaufen

const list = document.createElement('ul');
list.innerHTML = '<li>Äpfel</li><li>Birnen</li><li>Kirschen</li>';

const iterator = list.querySelectorAll('li').values();

console.log(iterator.next().value.textContent);
console.log(iterator.next().value.textContent);
console.log(iterator.next().value.textContent);
console.log(iterator.next().done);

Äpfel Birnen Kirschen true

Mit for...of über alle Kindknoten iterieren

const container = document.createElement('div');
container.append(
  document.createElement('p'),
  document.createTextNode('Text'),
  document.createElement('span')
);

for (const node of container.childNodes.values()) {
  console.log(node.nodeName);
}

P #text SPAN

Iterator in ein Array umwandeln und filtern

document.body.innerHTML = `
  <input name="email" required>
  <input name="name">
  <input name="plz" required>`;

const pflichtfelder = [...document.querySelectorAll('input').values()]
  .filter((el) => el.required)
  .map((el) => el.name);

console.log(pflichtfelder);

["email", "plz"]

// Wichtig · Fallstricke

NodeList.prototype.values === NodeList.prototype[Symbol.iterator] ergibt true. for (const n of nodeList) ist daher gleichwertig und meist lesbarer.
Bei live-Listen wie childNodes kann das Entfernen oder Einfügen von Knoten während der Iteration dazu führen, dass Elemente übersprungen oder doppelt besucht werden. In dem Fall vorher mit Array.from() eine Kopie anlegen.
Ein Iterator ist nach einem Durchlauf erschöpft und lässt sich nicht zurücksetzen; für einen weiteren Durchlauf values() neu aufrufen.
HTMLCollection (z. B. getElementsByTagName()) besitzt keine Methode values(), ist aber über Symbol.iterator ebenfalls mit for...of iterierbar.
Im Internet Explorer nicht verfügbar; in allen modernen Browsern (Chrome 51+, Firefox 50+, Safari 10+, Edge 16+) unterstützt.

Siehe auch

NodeList.keys() NodeList.entries() NodeList.forEach() NodeList Document.querySelectorAll() for...of CSSUnparsedValue.values()