Highlight.clear() — Methode · JavaScript-Referenz

Signatur

Highlight.prototype.clear()

Beschreibung

Die Methode clear() gehört zur Schnittstelle Highlight aus der CSS Custom Highlight API. Ein Highlight ist ein mengenähnliches Objekt (setlike) und enthält Range- oder StaticRange-Objekte. Über ::highlight(name) in CSS werden diese Bereiche gestaltet, ohne dass das DOM verändert wird.

clear() leert das Highlight vollständig. Das Objekt selbst bleibt dabei erhalten und ist weiterhin in der HighlightRegistry (CSS.highlights) unter seinem Namen registriert. Du kannst es also sofort mit neuen Bereichen füllen, etwa bei einer Live-Suche, bei der sich die Treffer mit jedem Tastendruck ändern.

Die Methode verhält sich wie Set.prototype.clear(): Sie erwartet keine Argumente und gibt undefined zurück. Danach ist highlight.size gleich 0, und der Browser zeichnet die Hervorhebung neu, also ohne die entfernten Bereiche.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Das Highlight wird direkt verändert.

Beispiele

Hervorhebung erstellen und wieder leeren

// CSS: ::highlight(markiert) { background-color: yellow; }
const absatz = document.querySelector('p');
const range = new Range();
range.setStart(absatz.firstChild, 0);
range.setEnd(absatz.firstChild, 5);

const highlight = new Highlight(range);
CSS.highlights.set('markiert', highlight);
console.log(highlight.size);

highlight.clear();
console.log(highlight.size);
console.log(CSS.highlights.has('markiert'));

1 0 true

Live-Suche: Treffer bei jeder Eingabe neu markieren

// CSS: ::highlight(suche) { background-color: orange; }
const eingabe = document.querySelector('#suche');
const inhalt = document.querySelector('#inhalt');
const trefferHighlight = new Highlight();
CSS.highlights.set('suche', trefferHighlight);

eingabe.addEventListener('input', () => {
  // Alte Treffer entfernen, Highlight-Objekt wiederverwenden
  trefferHighlight.clear();
  const begriff = eingabe.value.trim().toLowerCase();
  if (!begriff) return;

  const walker = document.createTreeWalker(inhalt, NodeFilter.SHOW_TEXT);
  let knoten;
  while ((knoten = walker.nextNode())) {
    const text = knoten.textContent.toLowerCase();
    let index = text.indexOf(begriff);
    while (index !== -1) {
      const range = new Range();
      range.setStart(knoten, index);
      range.setEnd(knoten, index + begriff.length);
      trefferHighlight.add(range);
      index = text.indexOf(begriff, index + begriff.length);
    }
  }
  console.log(`${trefferHighlight.size} Treffer`);
});

z. B. "3 Treffer"

Mit Feature-Erkennung absichern

const alleMarkierungenEntfernen = (name) => {
  if (!('highlights' in CSS)) {
    console.warn('CSS Custom Highlight API nicht unterstützt');
    return;
  }
  CSS.highlights.get(name)?.clear();
};

alleMarkierungenEntfernen('suche');

// Wichtig · Fallstricke

clear() oder delete(): highlight.clear() leert nur den Inhalt, die Registrierung bleibt bestehen. Soll die Hervorhebung ganz verschwinden, nutze CSS.highlights.delete(name) oder CSS.highlights.clear(). Letzteres entfernt alle registrierten Highlights, nicht nur die Bereiche eines einzelnen.
Die Range-Objekte selbst werden nicht zerstört. Hältst du noch Verweise darauf, kannst du sie erneut mit add() hinzufügen.
Einmal leeren und dann neu befüllen ist meist günstiger, als bei jeder Änderung ein neues Highlight zu erzeugen und neu zu registrieren.
Kompatibilität: Chromium-Browser ab Version 105 und Safari ab 17.2 unterstützen die API. Firefox unterstützt sie erst in neueren Versionen (ab 140). Prüfe die Unterstützung vorher mit 'highlights' in CSS.

Siehe auch

Highlight Highlight.add() Highlight.delete() Highlight.size Set.prototype.clear()