Document.createNodeIterator() — Methode · JavaScript-Referenz

Signatur

Document.prototype.createNodeIterator(root, whatToShow, filter)

Beschreibung

document.createNodeIterator() liefert einen NodeIterator, der alle Knoten unterhalb (und einschließlich) eines Wurzelknotens root in Dokumentreihenfolge (Tiefensuche, Pre-Order) als flache Liste durchläuft. Mit nextNode() und previousNode() bewegt man sich vorwärts und rückwärts durch diese Liste.

Anders als querySelectorAll() erfasst ein NodeIterator auch Nicht-Element-Knoten wie Textknoten, Kommentare oder Verarbeitungsanweisungen. Das macht ihn nützlich, um z. B. alle Textknoten für eine Suchen-und-Hervorheben-Funktion zu sammeln, HTML-Kommentare aufzuspüren oder Knoten nach komplexen Regeln zu filtern.

Über die Bitmaske whatToShow (Konstanten von NodeFilter, z. B. NodeFilter.SHOW_TEXT) wird festgelegt, welche Knotentypen überhaupt betrachtet werden. Zusätzlich kann ein filter für jeden Knoten NodeFilter.FILTER_ACCEPT, FILTER_REJECT oder FILTER_SKIP zurückgeben. Bei einem NodeIterator verhalten sich FILTER_REJECT und FILTER_SKIP identisch – Kindknoten werden trotzdem besucht, da die Struktur flach ist.

Wer die Baumstruktur (Eltern, Geschwister, Kinder) navigieren oder ganze Teilbäume überspringen will, greift stattdessen zu createTreeWalker().

Parameter

Name	Typ	Default	Beschreibung
$root Pflicht	Node		Wurzelknoten, ab dem iteriert wird. Der Knoten selbst ist der erste Treffer (sofern er vom Filter akzeptiert wird).
$whatToShow	number	NodeFilter.SHOW_ALL (0xFFFFFFFF)	Bitmaske aus `NodeFilter.SHOW_*`-Konstanten, z. B. `NodeFilter.SHOW_ELEMENT`, `NodeFilter.SHOW_TEXT`, `NodeFilter.SHOW_COMMENT`. Mehrere Typen mit `\|` kombinieren.
$filter	NodeFilter \| ((node: Node) => number) \| null	null	Funktion oder Objekt mit `acceptNode(node)`-Methode, die `NodeFilter.FILTER_ACCEPT`, `FILTER_REJECT` oder `FILTER_SKIP` zurückgibt.

Rückgabewert

Typ

NodeIterator

Beschreibung

Ein neues NodeIterator-Objekt mit den Methoden nextNode(), previousNode() und detach() sowie den Eigenschaften root, referenceNode, whatToShow und filter.

Beispiele

Alle Textknoten eines Artikels sammeln

// HTML: <article id="post"><h1>Titel</h1><p>Hallo <b>Welt</b></p></article>
const root = document.getElementById('post');
const iterator = document.createNodeIterator(root, NodeFilter.SHOW_TEXT);

const texte = [];
let node;
while ((node = iterator.nextNode())) {
  texte.push(node.nodeValue);
}
console.log(texte);

["Titel", "Hallo ", "Welt"]

HTML-Kommentare finden und entfernen

const iterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_COMMENT
);

// Erst sammeln, dann entfernen – sicherer als während der Iteration
const kommentare = [];
let c;
while ((c = iterator.nextNode())) kommentare.push(c);

kommentare.forEach((k) => k.remove());
console.log(`${kommentare.length} Kommentare entfernt`);

z. B. "3 Kommentare entfernt"

Eigener Filter: nicht-leere Textknoten mit Suchbegriff

const suche = 'javascript';

const iterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_TEXT,
  (node) => {
    // Text in <script>/<style> ignorieren
    const tag = node.parentElement?.tagName;
    if (tag === 'SCRIPT' || tag === 'STYLE') return NodeFilter.FILTER_REJECT;
    return node.nodeValue.toLowerCase().includes(suche)
      ? NodeFilter.FILTER_ACCEPT
      : NodeFilter.FILTER_SKIP;
  }
);

const treffer = [];
for (let n = iterator.nextNode(); n; n = iterator.nextNode()) {
  treffer.push(n.parentElement);
}
console.log('Treffer in', treffer.length, 'Elementen');

z. B. "Treffer in 4 Elementen"

Elemente und Text kombiniert, rückwärts laufen

const ul = document.createElement('ul');
ul.innerHTML = '<li>Eins</li><li>Zwei</li>';

const it = document.createNodeIterator(
  ul,
  NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT
);

// Bis zum Ende vorlaufen
while (it.nextNode());

// Rückwärts ausgeben
let n;
while ((n = it.previousNode())) {
  console.log(n.nodeName, n.nodeValue ?? '');
}

#text Zwei LI #text Eins LI UL

// Wichtig · Fallstricke

Der Wurzelknoten zählt mit: Der erste Aufruf von nextNode() liefert root selbst, falls er zu whatToShow passt und vom Filter akzeptiert wird.
FILTER_REJECT = FILTER_SKIP: Beim NodeIterator überspringt FILTER_REJECT nicht den Teilbaum; das tut nur der TreeWalker. Im Beispiel mit SHOW_TEXT ist das egal, da Elemente ohnehin nicht betrachtet werden.
DOM-Änderungen: Der Iterator ist „live“ und passt sich an entfernte Knoten an, trotzdem ist Sammeln-dann-Ändern robuster und besser lesbar.
Filter-Ausnahmen: Wirft die Filterfunktion eine Ausnahme, bricht nextNode() ab. Ein Filter darf den Iterator nicht rekursiv aufrufen (sonst InvalidStateError).
detach() ist heute wirkungslos und nur aus Kompatibilitätsgründen vorhanden.
Der Parameter whatToShow ist seit neueren Spezifikationen optional; sehr alte Browser (IE ≤ 8) unterstützen die Methode gar nicht, der veraltete vierte Parameter entityReferenceExpansion wird ignoriert.
Für reine Element-Suchen sind querySelectorAll() oder children meist einfacher und schneller.

Siehe auch

RTCStatsReport.[Symbol.iterator]() Document.createComment() Document.createElement() Document.createElementNS() Document.createEvent()