HighlightRegistry.delete() — Methode · JavaScript-Referenz

Signatur

HighlightRegistry.prototype.delete(name)

Beschreibung

Die Methode delete() der Schnittstelle HighlightRegistry entfernt ein benanntes Highlight aus der globalen Registry, die über CSS.highlights erreichbar ist. Die Registry verhält sich wie eine Map: Schlüssel sind Zeichenketten (die Highlight-Namen), Werte sind Highlight-Objekte. delete() folgt deshalb genau der Semantik von Map.prototype.delete().

Sobald ein Highlight aus der Registry entfernt ist, wendet der Browser die zugehörigen ::highlight(name)-CSS-Regeln nicht mehr an. Die Hervorhebung verschwindet sofort, ohne dass das DOM verändert wird. Das ist der eigentliche Vorteil der CSS Custom Highlight API: Man muss keine <mark>- oder <span>-Elemente einfügen und später wieder entfernen.

Typische Einsatzfälle sind das Zurücksetzen einer Suchtrefferanzeige, das Ausschalten von Rechtschreib- oder Syntaxmarkierungen und das Aufräumen, wenn eine Komponente entfernt wird. Das Highlight-Objekt selbst mit seinen Range-Objekten bleibt dabei erhalten. Man kann es später mit CSS.highlights.set() wieder registrieren.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des zu entfernenden Highlights, also der Schlüssel, unter dem es mit `CSS.highlights.set(name, highlight)` registriert wurde. Groß- und Kleinschreibung werden unterschieden.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn ein Highlight mit diesem Namen vorhanden war und entfernt wurde, sonst false.

Beispiele

Highlight registrieren und wieder entfernen

// CSS: ::highlight(treffer) { background-color: 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.has('treffer'));

// Hervorhebung entfernen – das DOM bleibt unverändert
const entfernt = CSS.highlights.delete('treffer');
console.log(entfernt, CSS.highlights.has('treffer'));

true true false

Rückgabewert prüfen bei nicht vorhandenem Namen

const ergebnis = CSS.highlights.delete('gibt-es-nicht');
console.log(ergebnis);

false

Suchtreffer bei leerem Suchfeld zurücksetzen

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

const markiereTreffer = (begriff) => {
  // alte Treffer immer zuerst entfernen
  CSS.highlights.delete('suche');
  if (!begriff) return;

  const walker = document.createTreeWalker(artikel, NodeFilter.SHOW_TEXT);
  const ranges = [];
  const suchwort = begriff.toLowerCase();
  let node;
  while ((node = walker.nextNode())) {
    const text = node.textContent.toLowerCase();
    let pos = text.indexOf(suchwort);
    while (pos !== -1) {
      const r = new Range();
      r.setStart(node, pos);
      r.setEnd(node, pos + suchwort.length);
      ranges.push(r);
      pos = text.indexOf(suchwort, pos + suchwort.length);
    }
  }
  if (ranges.length) CSS.highlights.set('suche', new Highlight(...ranges));
};

input.addEventListener('input', (e) => markiereTreffer(e.target.value.trim()));

Feature-Erkennung und Wiederverwenden des Highlight-Objekts

if ('highlights' in CSS) {
  const range = document.createRange();
  range.selectNodeContents(document.querySelector('h1'));
  const hl = new Highlight(range);

  CSS.highlights.set('titel', hl);
  CSS.highlights.delete('titel');   // unsichtbar
  CSS.highlights.set('titel', hl);  // wieder sichtbar – Ranges blieben erhalten
  console.log(CSS.highlights.size);
} else {
  console.warn('CSS Custom Highlight API wird nicht unterstützt');
}

1

// Wichtig · Fallstricke

Browser-Unterstützung: Die CSS Custom Highlight API gibt es in Chromium-Browsern ab Version 105, in Safari ab 17.2 und in Firefox erst ab Version 140. Vorher sollte man mit 'highlights' in CSS prüfen, ob sie verfügbar ist, bevor man CSS.highlights.delete() aufruft. Sonst wirft der Aufruf einen TypeError.
Kein Fehler bei unbekanntem Namen: Gibt es keinen Eintrag unter dem Namen, gibt delete() nur false zurück. Tippfehler im Namen fallen deshalb leicht nicht auf.
Nur der Registry-Eintrag wird entfernt: Das Highlight-Objekt und seine Ranges bleiben bestehen. Soll ein Highlight bestehen bleiben, aber einzelne Bereiche verlieren, nutzt man stattdessen highlight.delete(range) oder highlight.clear(). Das sind die Methoden von Highlight, nicht von HighlightRegistry.
Alle Highlights entfernen: Dafür gibt es CSS.highlights.clear(). Eine Schleife mit delete() ist nicht nötig.
Die Registry gilt pro Dokument. Highlights in iframes haben ihre eigene Registry, erreichbar über das CSS-Objekt des jeweiligen Fensters.

Siehe auch

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