HighlightRegistry.clear() — Methode · JavaScript-Referenz

Signatur

HighlightRegistry.prototype.clear()

Beschreibung

Die Methode clear() gehört zur Schnittstelle HighlightRegistry. Die Registry erreichst du über CSS.highlights. Sie funktioniert wie eine Map: Jeder Name gehört zu einem Highlight-Objekt, und über diesen Namen kannst du im CSS mit dem Pseudoelement ::highlight(name) Textbereiche gestalten, ohne das DOM zu verändern.

clear() entfernt alle Einträge auf einmal. Danach ist CSS.highlights.size gleich 0, und der Browser entfernt alle eigenen Hervorhebungen aus dem Dokument. Die Highlight-Objekte selbst und die Range-Objekte darin bleiben erhalten. Solange du noch eine Referenz auf sie hast, kannst du sie später mit set() wieder registrieren.

Typische Einsatzfälle sind das Zurücksetzen einer Suchfunktion, das Löschen einer Syntaxhervorhebung vor einem neuen Durchlauf oder das Aufräumen, wenn eine Komponente oder Ansicht verlassen wird. Willst du nur eine bestimmte Hervorhebung entfernen, nimm stattdessen CSS.highlights.delete(name).

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück.

Beispiele

Alle Hervorhebungen entfernen

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

CSS.highlights.set('treffer', new Highlight(range));
console.log(CSS.highlights.size);

CSS.highlights.clear();
console.log(CSS.highlights.size);

1 0

Suchfunktion: alte Treffer vor jeder neuen Suche löschen

// CSS: ::highlight(suche) { background: orange; color: black; }
const inhalt = document.querySelector('#inhalt');
const eingabe = document.querySelector('#suche');

const textKnoten = (wurzel) => {
  const walker = document.createTreeWalker(wurzel, NodeFilter.SHOW_TEXT);
  const knoten = [];
  while (walker.nextNode()) knoten.push(walker.currentNode);
  return knoten;
};

eingabe.addEventListener('input', () => {
  CSS.highlights.clear(); // alte Treffer entfernen
  const begriff = eingabe.value.trim().toLowerCase();
  if (!begriff) return;

  const ranges = textKnoten(inhalt).flatMap((knoten) => {
    const text = knoten.textContent.toLowerCase();
    const treffer = [];
    let pos = text.indexOf(begriff);
    while (pos !== -1) {
      const r = new Range();
      r.setStart(knoten, pos);
      r.setEnd(knoten, pos + begriff.length);
      treffer.push(r);
      pos = text.indexOf(begriff, pos + begriff.length);
    }
    return treffer;
  });

  CSS.highlights.set('suche', new Highlight(...ranges));
});

Mit Feature-Erkennung sicher zurücksetzen und später wiederherstellen

const zuruecksetzen = () => {
  if (!('highlights' in CSS)) {
    console.warn('CSS Custom Highlight API nicht unterstützt');
    return new Map();
  }
  // Einträge vorher sichern, falls sie wiederhergestellt werden sollen
  const sicherung = new Map(CSS.highlights);
  CSS.highlights.clear();
  return sicherung;
};

const gesichert = zuruecksetzen();
// später wiederherstellen:
gesichert.forEach((highlight, name) => CSS.highlights.set(name, highlight));
console.log(CSS.highlights.size === gesichert.size);

true

// Wichtig · Fallstricke

Wirkt global: clear() entfernt auch Hervorhebungen, die andere Skripte, Bibliotheken oder Komponenten auf derselben Seite registriert haben. Nutze in geteilten Umgebungen besser gezielt delete(name).
Die Highlight- und Range-Objekte werden nicht gelöscht. Nur die Registrierung verschwindet. Behältst du Referenzen, kannst du sie später wieder mit set() registrieren.
Die Registry gilt nur für das eigene Dokument. Iframes haben jeweils ein eigenes CSS.highlights.
Browser-Kompatibilität: Unterstützt ab Chrome/Edge 105, Safari 17.2 und Firefox 140. Prüfe die Unterstützung vorher mit 'highlights' in CSS.
Für wiederholte Aufrufe, etwa bei jedem Tastendruck, ist clear() und anschließend set() deutlich günstiger als DOM-basiertes Hervorheben mit <mark>-Elementen. Es verändert kein Layout und keine DOM-Struktur.

Siehe auch

Highlight Range Map.prototype.clear() HighlightRegistry.delete() HighlightRegistry.get()