NodeList — Schnittstelle · JavaScript-Referenz

Signatur

interface NodeList

Beschreibung

NodeList ist eine array-ähnliche Sammlung von Node-Objekten. Sie begegnet einem vor allem als Rückgabewert von document.querySelectorAll(), Element.querySelectorAll(), Node.childNodes und document.getElementsByName(). Der Zugriff erfolgt über einen Index (list[0]) oder list.item(0), die Anzahl liefert length.

Wichtig ist der Unterschied zwischen live und statisch: Node.childNodes und getElementsByName() liefern eine live-Liste, die sich automatisch aktualisiert, wenn sich das DOM ändert. querySelectorAll() liefert dagegen eine statische Momentaufnahme, die spätere DOM-Änderungen nicht widerspiegelt.

Eine NodeList ist kein Array. Sie bietet forEach(), entries(), keys(), values() und ist mit for...of iterierbar, besitzt aber keine Methoden wie map(), filter() oder reduce(). Dafür wandelt man sie mit Array.from() oder dem Spread-Operator ([...list]) in ein echtes Array um.

Wesentliche Mitglieder:

NodeList.length – Anzahl der Knoten (nur lesbar).
NodeList.item(index) – Knoten am Index oder null.
NodeList.forEach(callback, thisArg) – ruft den Callback für jeden Knoten auf.
NodeList.entries(), keys(), values() – liefern Iteratoren.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Für `item(index)` bzw. `list[index]`: nullbasierte Position des gewünschten Knotens.
$callback Pflicht	(node: Node, index: number, list: NodeList) => void		Für `forEach()`: Funktion, die für jeden Knoten aufgerufen wird.
$thisArg	any	undefined	Für `forEach()`: Wert, der im Callback als `this` verwendet wird.

Rückgabewert

Typ

NodeList

Beschreibung

Eine NodeList-Instanz wird nie direkt erzeugt (kein öffentlicher Konstruktor), sondern von DOM-Methoden und -Eigenschaften zurückgegeben. item() liefert Node | null, forEach() liefert undefined.

Beispiele

NodeList erhalten und mit forEach durchlaufen

// Alle Buttons mit der Klasse .js-toggle holen (statische NodeList)
const buttons = document.querySelectorAll('button.js-toggle');
console.log(buttons.length, buttons instanceof NodeList);

buttons.forEach((btn, i) => {
  btn.dataset.index = i;
  btn.addEventListener('click', () => btn.classList.toggle('active'));
});

3 true

In ein Array umwandeln für map/filter

const links = document.querySelectorAll('a[href]');

// NodeList hat kein filter()/map() – daher umwandeln
const externe = [...links]
  .filter((a) => a.hostname !== location.hostname)
  .map((a) => a.href);

// Alternative mit Mapping-Funktion
const texte = Array.from(links, (a) => a.textContent.trim());
console.log(externe, texte);

["https://example.org/", ...] ["Start", "Kontakt", ...]

Live- vs. statische NodeList

const ul = document.createElement('ul');
ul.innerHTML = '<li>A</li><li>B</li>';

const live = ul.childNodes;             // live
const statisch = ul.querySelectorAll('li'); // statisch

ul.appendChild(document.createElement('li'));

console.log(live.length);     // aktualisiert sich
console.log(statisch.length); // bleibt beim alten Stand

3 2

Iteration mit for...of, entries() und item()

const items = document.querySelectorAll('li');

for (const [i, li] of items.entries()) {
  console.log(i, li.textContent);
}

console.log(items.item(0) === items[0]); // true
console.log(items.item(999));            // null
console.log(items[999]);                 // undefined

0 "Erster" 1 "Zweiter" true null undefined

// Wichtig · Fallstricke

Kein Array: map(), filter(), reduce() usw. fehlen. Mit Array.from() oder [...list] umwandeln.
Live-Listen beim Verändern: Wer beim Durchlaufen von childNodes Knoten entfernt oder hinzufügt, verändert gleichzeitig die Liste – Elemente werden übersprungen oder Endlosschleifen entstehen. Vorher mit Array.from() eine Kopie ziehen oder rückwärts iterieren.
Textknoten: childNodes enthält auch Text- und Kommentarknoten (z. B. Leerzeichen/Zeilenumbrüche). Nur Elemente liefert Element.children (ein HTMLCollection).
Kein Unterschied zu HTMLCollection übersehen: getElementsByClassName()/getElementsByTagName() geben eine HTMLCollection zurück, die kein forEach() hat.
Keine Iteration mit for...in: Dabei werden auch length, item und weitere Eigenschaften aufgezählt.
Kompatibilität: forEach(), entries(), keys(), values() und die Iterierbarkeit funktionieren in allen modernen Browsern; der Internet Explorer unterstützt sie nicht (dort Array.prototype.forEach.call(list, fn)).
Leeres Ergebnis: querySelectorAll() liefert bei keinem Treffer eine leere NodeList (length === 0), niemals null.

Siehe auch

Node Element.children Array.from() FileList MediaList