HighlightRegistry.set() — Methode · JavaScript-Referenz

Signatur

HighlightRegistry.prototype.set(name, highlight)

Beschreibung

HighlightRegistry.prototype.set() ist das zentrale Bindeglied der CSS Custom Highlight API. Ein Highlight-Objekt ist eine Sammlung von Range- bzw. StaticRange-Objekten. Sichtbar wird es aber erst, wenn es mit set() unter einem Namen in der globalen Registry CSS.highlights eingetragen ist. Danach wirkt die CSS-Regel ::highlight(name) auf alle enthaltenen Textbereiche.

Die Registry verhält sich wie eine Map (sie ist maplike): Existiert der Name schon, wird das alte Highlight ersetzt. Ansonsten wird ein neuer Eintrag angelegt. Weil set() die Registry selbst zurückgibt, kannst du mehrere Aufrufe verketten.

Typische Anwendungsfälle sind Suchtreffer-Markierungen, Syntax-Highlighting, Rechtschreibhinweise und die Anzeige der Cursor oder Auswahlen anderer Personen beim gemeinsamen Bearbeiten. Anders als bei klassischen Lösungen mit <mark>- oder <span>-Elementen wird der DOM-Baum dabei nicht verändert. Das ist schneller und lässt Frameworks, Event-Listener und die Textstruktur unangetastet.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des Highlights, auf den sich der CSS-Pseudo-Element-Selektor `::highlight(name)` bezieht. Muss ein gültiger CSS-Bezeichner sein (`<custom-ident>`), damit CSS ihn ansprechen kann.
$highlight Pflicht	Highlight		Das zu registrierende `Highlight`-Objekt mit den zu markierenden `Range`- bzw. `StaticRange`-Objekten.

Rückgabewert

Typ

HighlightRegistry

Beschreibung

Die Registry selbst (CSS.highlights). Dadurch lassen sich mehrere Aufrufe verketten.

Beispiele

Suchbegriff im Text hervorheben

// CSS: ::highlight(suche) { background-color: yellow; color: black; }
const hebeSuchbegriffHervor = (container, begriff) => {
  if (!('highlights' in CSS)) return; // Feature-Erkennung

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

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

  CSS.highlights.set('suche', new Highlight(...ranges));
  console.log(`${ranges.length} Treffer markiert`);
};

hebeSuchbegriffHervor(document.querySelector('article'), 'javascript');

z. B. "4 Treffer markiert"

Vorhandenes Highlight ersetzen statt anhäufen

const input = document.querySelector('#suchfeld');
const absatz = document.querySelector('p');

input.addEventListener('input', () => {
  const begriff = input.value.trim();
  if (!begriff) {
    CSS.highlights.delete('suche');
    return;
  }
  const text = absatz.firstChild; // erster Textknoten
  const index = text.textContent.indexOf(begriff);
  if (index === -1) return CSS.highlights.delete('suche');

  const range = new Range();
  range.setStart(text, index);
  range.setEnd(text, index + begriff.length);

  // Gleicher Name -> altes Highlight wird überschrieben
  CSS.highlights.set('suche', new Highlight(range));
  console.log(CSS.highlights.size);
});

1

Mehrere Highlights verketten und priorisieren

// CSS:
// ::highlight(fehler) { text-decoration: wavy underline red; }
// ::highlight(hinweis) { background-color: #ffe08a; }
const p = document.querySelector('p');
const text = p.firstChild;

const r1 = new Range();
r1.setStart(text, 0);
r1.setEnd(text, 5);

const r2 = new Range();
r2.setStart(text, 3);
r2.setEnd(text, 10);

const fehler = new Highlight(r1);
const hinweis = new Highlight(r2);
fehler.priority = 1; // gewinnt bei Überlappung

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

console.log([...CSS.highlights.keys()]);

["fehler", "hinweis"]

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome/Edge ab 105, Safari ab 17.2 und Firefox ab 140. Prüfe die Unterstützung vorher mit 'highlights' in CSS und sieh für ältere Browser z. B. <mark> als Ersatz vor.
Überschreiben: Ein erneuter Aufruf mit demselben Namen ersetzt das bisherige Highlight vollständig. Die Bereiche werden nicht zusammengeführt. Willst du Bereiche ergänzen, nutze highlight.add(range) auf dem vorhandenen Objekt, z. B. über CSS.highlights.get(name).
Nur wenige CSS-Eigenschaften: In ::highlight() wirken nur bestimmte Eigenschaften, etwa color, background-color, text-decoration, text-shadow und -webkit-text-stroke. Layout-Eigenschaften wie padding oder font-size werden ignoriert.
Lebende Bereiche: Ein Range passt sich automatisch an, wenn sich der DOM ändert. Ein StaticRange tut das nicht. Wird der markierte Text entfernt, kann das Highlight daher verschwinden oder an einer unerwarteten Stelle erscheinen.
Speicher: Registrierte Highlights halten Referenzen auf ihre Bereiche und damit auf DOM-Knoten. Entferne Highlights, die du nicht mehr brauchst, mit delete() oder clear().
Der Name wird nicht auf Gültigkeit geprüft. Ein Name, der kein gültiger CSS-Bezeichner ist, wird zwar gespeichert, lässt sich aber mit ::highlight() nicht ansprechen.

Siehe auch

Highlight Range Map.prototype.set() HighlightRegistry.get() HighlightRegistry.has()