NodeIterator.root — Eigenschaft · JavaScript-Referenz

Signatur

NodeIterator.root

Beschreibung

Die Eigenschaft root gibt den Node zurück, der beim Erzeugen des Iterators mit document.createNodeIterator(root, whatToShow, filter) als erstes Argument übergeben wurde. Er legt fest, welcher Teilbaum durchlaufen wird: Der Iterator besucht nur den Wurzelknoten selbst und seine Nachfahren.

Die Eigenschaft ist schreibgeschützt und ändert sich während der gesamten Lebensdauer des Iterators nicht. Das gilt auch, wenn andere Knoten im Teilbaum entfernt oder verschoben werden. Wenn Sie einen anderen Teilbaum durchlaufen wollen, müssen Sie einen neuen Iterator anlegen.

In der Praxis brauchen Sie root vor allem dann, wenn ein Iterator an Hilfsfunktionen weitergereicht wird. Diese können damit prüfen, auf welchen Bereich sie gerade arbeiten, etwa um Protokolle auszugeben, den Bereich hervorzuheben oder Knoten relativ zur Wurzel einzuordnen (zum Beispiel mit root.contains(node)).

Rückgabewert

Typ

Node

Beschreibung

Der Wurzelknoten, der beim Aufruf von createNodeIterator() angegeben wurde. Das kann jede Art von Node sein, also z. B. Element, Document oder DocumentFragment.

Beispiele

Wurzel eines Iterators auslesen

document.body.innerHTML = '<main id="inhalt"><p>Hallo</p></main>';
const main = document.getElementById('inhalt');

const iterator = document.createNodeIterator(main, NodeFilter.SHOW_ELEMENT);

console.log(iterator.root === main);
console.log(iterator.root.id);

true inhalt

Hilfsfunktion, die den Iterator-Bereich protokolliert

const sammleTexte = (iterator) => {
  const texte = [];
  let node;
  while ((node = iterator.nextNode())) {
    const text = node.textContent.trim();
    if (text) texte.push(text);
  }
  const wurzel = iterator.root;
  console.log(`Durchlaufen: <${wurzel.nodeName.toLowerCase()}> – ${texte.length} Texte`);
  return texte;
};

document.body.innerHTML = '<article><h2>Titel</h2><p>Absatz</p></article>';
const article = document.querySelector('article');
const it = document.createNodeIterator(article, NodeFilter.SHOW_TEXT);
console.log(sammleTexte(it));

Durchlaufen: <article> – 2 Texte ["Titel", "Absatz"]

root ist schreibgeschützt und bleibt stabil

'use strict';
const liste = document.createElement('ul');
liste.innerHTML = '<li>A</li><li>B</li>';
const iterator = document.createNodeIterator(liste, NodeFilter.SHOW_ELEMENT);

try {
  iterator.root = document.body; // Zuweisung ist nicht erlaubt
} catch (err) {
  console.log(err instanceof TypeError);
}

// Auch Änderungen im Teilbaum ändern root nicht
liste.firstElementChild.remove();
console.log(iterator.root === liste);

true true

// Wichtig · Fallstricke

Schreibgeschützt: Im nicht-strikten Modus wird eine Zuweisung an root stillschweigend ignoriert, im strikten Modus löst sie einen TypeError aus. Für einen anderen Bereich brauchen Sie einen neuen Iterator.
Der Wurzelknoten ist selbst Teil der Iteration: Der erste Aufruf von nextNode() liefert root, sofern er zu whatToShow und zum Filter passt.
Der Iterator hält eine Referenz auf root. Auch nachdem die Wurzel aus dem Dokument entfernt wurde, zeigt root weiter auf sie. Solange der Iterator lebt, kann der Knoten also nicht vom Garbage Collector freigegeben werden.
Anders als bei TreeWalker gibt es beim NodeIterator kein currentNode, das Sie frei setzen können. Stattdessen bietet er referenceNode (ebenfalls schreibgeschützt).
Kompatibilität: Die Eigenschaft wird von allen modernen Browsern unterstützt, auch von alten Versionen des Internet Explorer ab Version 9. In Node.js steht sie nur über DOM-Implementierungen wie jsdom zur Verfügung.

Siehe auch

ElementInternals.ariaRowCount ElementInternals.shadowRoot NodeIterator.filter NodeIterator.whatToShow NodeIterator.referenceNode