HighlightRegistry — Schnittstelle · JavaScript-Referenz

Signatur

interface HighlightRegistry (Map-artig, erreichbar über CSS.highlights)

Beschreibung

HighlightRegistry ist das zentrale Verzeichnis der CSS Custom Highlight API. Du erzeugst keine eigene Instanz. Es gibt pro Dokument genau eine, und die erreichst du über CSS.highlights. Darin legst du Highlight-Objekte unter einem frei wählbaren Namen ab. Erst durch diese Registrierung wirkt das Pseudo-Element ::highlight(name) in deinem CSS auf die zugehörigen Ranges.

Die Schnittstelle verhält sich wie eine Map (sie ist „maplike“). Schlüssel ist ein String (der Highlight-Name), Wert ist ein Highlight. Es stehen die bekannten Methoden und Eigenschaften zur Verfügung:

set(name, highlight): registriert ein Highlight oder ersetzt ein vorhandenes. Gibt die Registry zurück.
get(name), has(name), delete(name) und clear().
size, keys(), values(), entries(), forEach() sowie Iteration mit for...of.
highlightsFromPoint(x, y, options) (experimentell): liefert die Highlights an einer Bildschirmkoordinate.

Der typische Einsatz sind Hervorhebungen, bei denen du das DOM nicht verändern willst: Suchtreffer, Rechtschreibmarkierungen, Syntax-Hervorhebung, Markierungen bei gemeinsamer Bearbeitung oder Kommentar-Anker. Früher musste man dafür Text in <mark>- oder <span>-Elemente einpacken. Das kostet Leistung und bricht leicht Struktur und Event-Handler. Mit der Registry bleibt der DOM-Baum unverändert. Der Browser zeichnet die Hervorhebung nur beim Rendern.

Parameter

Name	Typ	Beschreibung
$name Pflicht	string	Parameter von `set()`, `get()`, `has()` und `delete()`. Der Name, unter dem das Highlight registriert ist. Er muss exakt dem Namen in `::highlight(name)` im CSS entsprechen, also ohne Anführungszeichen und als gültiger CSS-Bezeichner.
$highlight Pflicht	Highlight	Parameter von `set()`. Ein `Highlight`-Objekt, das eine Menge von `Range`- bzw. `StaticRange`-Objekten enthält.
$callbackFn	(highlight: Highlight, name: string, registry: HighlightRegistry) => void	Parameter von `forEach()`. Die Funktion wird für jeden Eintrag aufgerufen.

Rückgabewert

Typ

HighlightRegistry

Beschreibung

CSS.highlights liefert die eine Registry des Dokuments. Die Rückgabewerte der Methoden entsprechen denen von Map: set() gibt die Registry zurück, get() ein Highlight oder undefined, has() und delete() einen boolean, clear() undefined.

Beispiele

Highlight registrieren und per CSS stylen

// CSS: ::highlight(markiert) { background-color: yellow; color: black; }
const absatz = document.querySelector('p');
const textNode = absatz.firstChild;

const range = new Range();
range.setStart(textNode, 0);
range.setEnd(textNode, 5);

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

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

true 1

Suchtreffer hervorheben, ohne das DOM zu ändern

// CSS: ::highlight(suche) { background-color: orange; }
const sucheHervorheben = (container, begriff) => {
  CSS.highlights.delete('suche');
  if (!begriff) return 0;

  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
  const ranges = [];
  const needle = begriff.toLowerCase();

  while (walker.nextNode()) {
    const node = walker.currentNode;
    const text = node.textContent.toLowerCase();
    let index = text.indexOf(needle);
    while (index !== -1) {
      const range = new Range();
      range.setStart(node, index);
      range.setEnd(node, index + needle.length);
      ranges.push(range);
      index = text.indexOf(needle, index + needle.length);
    }
  }

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

document.querySelector('#suchfeld').addEventListener('input', (e) => {
  const treffer = sucheHervorheben(document.querySelector('article'), e.target.value.trim());
  console.log(`${treffer} Treffer`);
});

z. B. "3 Treffer"

Registry durchlaufen und aufräumen

CSS.highlights.set('fehler', new Highlight());
CSS.highlights.set('hinweis', new Highlight());

for (const [name, hl] of CSS.highlights) {
  console.log(name, hl.size);
}

CSS.highlights.delete('hinweis');
console.log([...CSS.highlights.keys()]);

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

fehler 0 hinweis 0 ["fehler"] 0

Feature-Erkennung mit Fallback

const unterstuetzt = typeof CSS !== 'undefined' && 'highlights' in CSS;

if (unterstuetzt) {
  console.log('Custom Highlight API verfügbar');
} else {
  console.log('Fallback: <mark>-Elemente verwenden');
}

Custom Highlight API verfügbar

// Wichtig · Fallstricke

Kein Konstruktor: new HighlightRegistry() wirft einen TypeError. Verwende immer CSS.highlights.
Namen müssen passen: Der Schlüssel in set() muss exakt dem Bezeichner in ::highlight(name) entsprechen. Groß- und Kleinschreibung zählt.
Nur wenige CSS-Eigenschaften: In ::highlight() wirken nur color, background-color, text-decoration, text-shadow, -webkit-text-stroke und Ähnliches. padding, margin oder font-weight werden ignoriert.
Ranges sind „live“: Wenn sich das DOM ändert, passen sich Range-Objekte an. Wird Text ersetzt, etwa über textContent, fallen die Ranges oft zusammen. Berechne die Highlights danach neu.
Überlappungen: Überschneiden sich mehrere Highlights, entscheidet Highlight.priority. Bei gleicher Priorität gewinnt das später registrierte.
Leistung: Tausende Ranges sind möglich, aber lege das Highlight lieber einmal mit allen Ranges an als in einer Schleife ständig set()/delete() aufzurufen.
Kompatibilität: Chrome/Edge ab 105, Safari ab 17.2, Firefox erst ab 140. Nutze für ältere Browser eine Feature-Erkennung über 'highlights' in CSS. highlightsFromPoint() ist experimentell und nur in neuen Chromium-Versionen vorhanden.
Highlights sind rein visuell. Screenreader bekommen davon nichts mit. Für wichtige Informationen brauchst du zusätzlich semantische Hinweise, z. B. ARIA-Attribute.

Siehe auch

Highlight Range CSS.highlights Map AmbientLightSensor