NodeIterator.filter — Eigenschaft · JavaScript-Referenz

Signatur

NodeIterator.filter

Beschreibung

Die Eigenschaft NodeIterator.filter gibt genau den Filter zurück, der beim Aufruf von document.createNodeIterator(root, whatToShow, filter) als dritter Parameter übergeben wurde. Das kann eine Funktion sein oder ein Objekt mit einer Methode acceptNode(node). Wurde kein Filter angegeben, ist der Wert null.

Der Filter wird bei jedem Aufruf von nextNode() bzw. previousNode() für jeden Knoten aufgerufen, der die Bitmaske aus whatToShow bereits passiert hat. Er muss eine der Konstanten NodeFilter.FILTER_ACCEPT (1), NodeFilter.FILTER_REJECT (2) oder NodeFilter.FILTER_SKIP (3) zurückgeben.

In der Praxis braucht man filter vor allem, um einen vorhandenen Filter zu prüfen oder wiederzuverwenden: Zum Beispiel lässt sich damit ein zweiter Iterator mit gleichen Regeln erzeugen, oder man liest den Zustand eines zustandsbehafteten Filter-Objekts (etwa einen Zähler) aus. Die Eigenschaft ist schreibgeschützt. Wer einen anderen Filter nutzen will, muss einen neuen Iterator erzeugen.

Rückgabewert

Typ

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

Beschreibung

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

Beispiele

Filter-Funktion setzen und über filter wiedererkennen

const container = document.createElement('div');
container.innerHTML = '<p>Eins</p><span>Zwei</span><p>Drei</p>';

// Nur <p>-Elemente akzeptieren
const nurAbsaetze = (node) =>
  node.nodeName === 'P' ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;

const it = document.createNodeIterator(container, NodeFilter.SHOW_ELEMENT, nurAbsaetze);

console.log(it.filter === nurAbsaetze);

let node;
while ((node = it.nextNode())) {
  console.log(node.textContent);
}

true Eins Drei

Ohne Filter ist der Wert null

const it = document.createNodeIterator(document.body, NodeFilter.SHOW_TEXT);
console.log(it.filter);

null

Zustandsbehaftetes Filter-Objekt auslesen und Filter wiederverwenden

const liste = document.createElement('ul');
liste.innerHTML = '<li class="aktiv">A</li><li>B</li><li class="aktiv">C</li>';

const aktivFilter = {
  treffer: 0,
  acceptNode(node) {
    if (node.classList.contains('aktiv')) {
      this.treffer++;
      return NodeFilter.FILTER_ACCEPT;
    }
    return NodeFilter.FILTER_SKIP;
  }
};

const it = document.createNodeIterator(liste, NodeFilter.SHOW_ELEMENT, aktivFilter);
while (it.nextNode()) { /* durchlaufen */ }

// Zustand über die filter-Eigenschaft abfragen
console.log(it.filter.treffer);

// Gleichen Filter für einen neuen Iterator verwenden
const it2 = document.createNodeIterator(liste, it.whatToShow, it.filter);
console.log(it2.nextNode().textContent);

2 A

Filter unabhängig von seiner Form manuell aufrufen

const pruefe = (iterator, node) => {
  const f = iterator.filter;
  if (f === null) return NodeFilter.FILTER_ACCEPT;
  return typeof f === 'function' ? f(node) : f.acceptNode(node);
};

const it = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  (n) => (n.hidden ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT)
);

const versteckt = document.createElement('div');
versteckt.hidden = true;
console.log(pruefe(it, versteckt));

2

// Wichtig · Fallstricke

Schreibgeschützt: it.filter = … wird im nicht-strikten Modus stillschweigend ignoriert, im Strict Mode (also auch in ES-Modulen) wirft es einen TypeError.
Form des Rückgabewerts: Zurück kommt die übergebene Referenz, also eine Funktion oder ein Objekt. Wer den Filter selbst aufruft, muss beide Fälle abfangen (siehe Beispiel 4).
REJECT und SKIP: Bei NodeIterator wirken FILTER_REJECT und FILTER_SKIP gleich, weil die Liste flach ist und Kindknoten trotzdem besucht werden. Nur bei TreeWalker überspringt FILTER_REJECT den ganzen Teilbaum.
Keine DOM-Änderungen im Filter: Ein Filter, der das DOM verändert oder rekursiv denselben Iterator nutzt, führt zu einer InvalidStateError-DOMException. Andere Ausnahmen im Filter werden von nextNode()/previousNode() weitergereicht.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Das veraltete vierte Argument entityReferenceExpansion älterer Spezifikationen wird ignoriert.

Siehe auch

Navigator.buildID NodeIterator.root NodeIterator.whatToShow NodeIterator.referenceNode NodeIterator.pointerBeforeReferenceNode