TreeWalker.filter — Eigenschaft · JavaScript-Referenz

Signatur

TreeWalker.filter

Beschreibung

TreeWalker.filter liefert genau das Filter-Objekt, das beim Aufruf von document.createTreeWalker(root, whatToShow, filter) als drittes Argument angegeben wurde. Das kann eine Funktion sein oder ein Objekt mit einer Methode acceptNode(node). Wurde kein Filter übergeben, ist der Wert null.

Der Filter entscheidet für jeden Knoten, der die whatToShow-Bitmaske bereits bestanden hat, ob er angenommen (NodeFilter.FILTER_ACCEPT), übersprungen (NodeFilter.FILTER_SKIP, Kinder werden trotzdem besucht) oder samt Teilbaum verworfen (NodeFilter.FILTER_REJECT) wird.

In der Praxis braucht man die Eigenschaft vor allem, wenn ein TreeWalker an Hilfsfunktionen weitergereicht wird und man dort nachsehen will, ob und wie gefiltert wird, etwa beim Debuggen oder um mit demselben Filter einen zweiten Walker zu erzeugen (z. B. mit anderer Wurzel). Die Eigenschaft ist schreibgeschützt. Den Filter kann man nachträglich nicht austauschen, dafür muss man einen neuen TreeWalker erzeugen.

Rückgabewert

Typ

NodeFilter | ((node: Node) => number) | null

Beschreibung

Das beim Erzeugen übergebene Filter-Objekt bzw. die Filterfunktion (dieselbe Referenz), oder null, wenn kein Filter angegeben wurde.

Beispiele

Filter auslesen und Referenz prüfen

const onlyVisible = (node) =>
  node.hidden ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT;

const walker = document.createTreeWalker(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  onlyVisible
);

console.log(walker.filter === onlyVisible);

const plainWalker = document.createTreeWalker(document.body);
console.log(plainWalker.filter);

true null

Objekt mit acceptNode als Filter

const skipScripts = {
  acceptNode(node) {
    return node.closest('script, style')
      ? NodeFilter.FILTER_REJECT
      : NodeFilter.FILTER_ACCEPT;
  }
};

const walker = document.createTreeWalker(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  skipScripts
);

console.log(typeof walker.filter.acceptNode);

function

Filter wiederverwenden: zweiten Walker mit anderer Wurzel erzeugen

const textFilter = (node) =>
  node.textContent.trim()
    ? NodeFilter.FILTER_ACCEPT
    : NodeFilter.FILTER_SKIP;

const walker = document.createTreeWalker(
  document.body,
  NodeFilter.SHOW_TEXT,
  textFilter
);

// Gleiche Einstellungen, aber nur innerhalb von <main>
const cloneWalker = (w, newRoot) =>
  document.createTreeWalker(newRoot, w.whatToShow, w.filter);

const mainWalker = cloneWalker(walker, document.querySelector('main'));

const texts = [];
while (mainWalker.nextNode()) {
  texts.push(mainWalker.currentNode.textContent.trim());
}
console.log(texts);

["Überschrift", "Erster Absatz …"]

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie walker.filter = fn hat keine Wirkung. Im Strict Mode wirft sie einen TypeError. Wer einen anderen Filter braucht, erzeugt einen neuen TreeWalker.
Zurückgegeben wird die Original-Referenz. Ist es eine Funktion, lässt sie sich direkt aufrufen. Bei einem Objekt ruft man walker.filter.acceptNode(node) auf. Vorher sollte man auf null prüfen.
Der Filter wird erst für Knoten aufgerufen, die whatToShow bereits zulässt. FILTER_REJECT und FILTER_SKIP verhalten sich beim TreeWalker unterschiedlich: REJECT überspringt den ganzen Teilbaum, SKIP nur den Knoten selbst. Beim NodeIterator verhalten sich beide gleich.
Wirft der Filter eine Ausnahme oder verändert er das DOM, kann der Durchlauf unerwartet enden. Wenn möglich, sollte der Filter keine Nebenwirkungen haben.
Kompatibilität: wird von allen modernen Browsern unterstützt. Sehr alte Implementierungen (IE) gaben für Funktionsfilter teils ein Objekt statt der Funktion zurück.

Siehe auch

ScreenDetailed.availLeft TreeWalker.root TreeWalker.whatToShow TreeWalker.currentNode NodeIterator.filter