CSS.highlights — Eigenschaft · JavaScript-Referenz

Signatur

CSS.highlights

Beschreibung

CSS.highlights ist der Einstiegspunkt der CSS Custom Highlight API. Die Eigenschaft gibt das dokumentweite HighlightRegistry zurück, ein Map-ähnliches Objekt. Darin registrieren Sie unter einem frei gewählten Namen Highlight-Objekte, die wiederum aus einem oder mehreren Range- bzw. StaticRange-Objekten bestehen.

Im Stylesheet sprechen Sie die registrierten Hervorhebungen über das Pseudoelement ::highlight(name) an. So lassen sich Suchtreffer, Syntax-Hervorhebung, Rechtschreibmarkierungen oder Markierungen von anderen Bearbeitern in Echtzeit-Editoren gestalten, ohne dass Sie den DOM-Baum verändern müssen. Es werden also keine zusätzlichen <span>- oder <mark>-Elemente eingefügt. Das ist deutlich schneller und lässt die Struktur des Dokuments unangetastet.

Das Registry bietet die bekannten Map-Methoden set(), get(), has(), delete(), clear(), forEach() und size und lässt sich mit for...of durchlaufen. Neuere Browser bieten zusätzlich highlightsFromPoint(x, y), um die Hervorhebungen an einer Bildschirmkoordinate zu ermitteln.

Rückgabewert

Typ

HighlightRegistry

Beschreibung

Das Map-ähnliche Registry des aktuellen Dokuments. Es ordnet Namen (string) den zugehörigen Highlight-Objekten zu.

Beispiele

Einfache Hervorhebung eines Textbereichs

// CSS: ::highlight(wichtig) { 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, 10);

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

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

true 1

Suchtreffer markieren, ohne das DOM zu ändern

// CSS: ::highlight(suchtreffer) { background-color: orange; }
const markiereTreffer = (container, suchbegriff) => {
  CSS.highlights.delete('suchtreffer');
  if (!suchbegriff) return;

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

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

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

document.querySelector('#suche').addEventListener('input', (e) => {
  markiereTreffer(document.querySelector('article'), e.target.value.trim());
});

z. B. "3 Treffer markiert"

Feature-Erkennung und Registry durchlaufen

if (!('highlights' in CSS)) {
  console.warn('CSS Custom Highlight API wird nicht unterstützt');
} else {
  const fehler = new Highlight();
  fehler.priority = 1; // gewinnt bei Überlappung
  CSS.highlights.set('rechtschreibung', fehler);
  CSS.highlights.set('grammatik', new Highlight());

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

  CSS.highlights.clear(); // alle Hervorhebungen entfernen
}

rechtschreibung 0 1 grammatik 0 0

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium ab 105, Safari ab 17.2, Firefox erst ab 140. Nutzen Sie die Feature-Erkennung mit 'highlights' in CSS und sehen Sie für ältere Browser eine Ausweichlösung vor, etwa <mark>-Elemente.
CSS.highlights selbst ist schreibgeschützt. Eine Zuweisung wie CSS.highlights = … hat keine Wirkung. Ändern Sie stattdessen den Inhalt des Registrys.
Innerhalb von ::highlight() ist nur eine begrenzte Auswahl an Eigenschaften erlaubt: color, background-color, text-decoration samt Untereigenschaften, text-shadow, -webkit-text-stroke-color, -webkit-text-fill-color und -webkit-text-stroke-width. Layout-Eigenschaften wie font-size oder padding werden ignoriert.
Live-Range-Objekte passen sich an, wenn sich das DOM ändert. StaticRange-Objekte tun das nicht und können nach DOM-Änderungen auf falsche Stellen zeigen.
Überlappen sich Hervorhebungen, entscheidet Highlight.priority. Bei gleicher Priorität gewinnt die zuletzt registrierte.
Das Registry gilt nur für das eigene Dokument. iframes haben ein eigenes CSS.highlights.
Barrierefreiheit: Hervorhebungen sind rein optisch und werden von Screenreadern nicht vorgelesen. Vermitteln Sie wichtige Bedeutung zusätzlich auf anderem Weg, etwa über ARIA-Live-Regionen.

Siehe auch

Highlight Range CSS CSSMathMin.values CSS.paintWorklet