Highlight.add() — Methode · JavaScript-Referenz

Signatur

Highlight.prototype.add(range)

Beschreibung

Die Methode add() gehört zur Schnittstelle Highlight der CSS Custom Highlight API. Ein Highlight verhält sich wie ein Set aus Bereichen (AbstractRange). Mit add() fügst du einen weiteren Textbereich hinzu. Existiert genau dieses Range-Objekt schon im Set, passiert nichts.

Damit die Bereiche sichtbar hervorgehoben werden, musst du das Highlight unter einem Namen in CSS.highlights (einer HighlightRegistry) registrieren und im Stylesheet mit dem Pseudo-Element ::highlight(name) gestalten. Anders als beim Umschließen mit <mark>- oder <span>-Elementen bleibt der DOM-Baum dabei unverändert. Das ist deutlich schneller und stört weder Frameworks noch Barrierefreiheit oder Textauswahl.

Typische Einsatzfälle sind Suchtreffer-Hervorhebung, Syntax-Highlighting in Editoren, die Markierung von Rechtschreibfehlern und kollaborative Cursor bzw. Auswahlen. Weil add() das Highlight-Objekt selbst zurückgibt, kannst du mehrere Aufrufe verketten.

Parameter

Name	Typ	Default	Beschreibung
$range Pflicht	AbstractRange (Range \| StaticRange)		Der Textbereich, der zum Highlight hinzukommen soll. Ein `Range` passt sich an DOM-Änderungen an, ein `StaticRange` nicht.

Rückgabewert

Typ

Highlight

Beschreibung

Das Highlight-Objekt, auf dem die Methode aufgerufen wurde. Dadurch lassen sich Aufrufe verketten, genau wie bei Set.prototype.add().

Beispiele

Einen Textbereich hervorheben

// 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();
highlight.add(range);

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

1

Suchtreffer ohne DOM-Änderung markieren

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

  const highlight = new Highlight();
  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
  const suchText = begriff.toLowerCase();

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

  CSS.highlights.set('suche', highlight);
  return highlight.size;
};

const anzahl = markiereTreffer(document.querySelector('article'), 'JavaScript');
console.log(`${anzahl} Treffer markiert`);

z. B. "7 Treffer markiert"

Verkettung und doppeltes Hinzufügen

const text = document.querySelector('h1').firstChild;

const r1 = new StaticRange({ startContainer: text, startOffset: 0, endContainer: text, endOffset: 3 });
const r2 = new StaticRange({ startContainer: text, startOffset: 4, endContainer: text, endOffset: 8 });

const highlight = new Highlight();
highlight.add(r1).add(r2).add(r1); // r1 wird nur einmal gespeichert

console.log(highlight.size);
console.log(highlight.has(r2));

2 true

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium ab 105 und Safari ab 17.2. Firefox unterstützt die API erst seit Version 140. Prüfe vorher mit if ('highlights' in CSS) und sieh eine Ausweichlösung vor, etwa <mark>-Elemente.
Ohne Registrierung keine Wirkung: add() allein hebt nichts sichtbar hervor. Das Highlight muss mit CSS.highlights.set(name, highlight) registriert sein, und im CSS muss eine passende Regel ::highlight(name) existieren.
Doppelte Einträge: Die Gleichheit wird über die Objektidentität geprüft, nicht über den Inhalt. Zwei verschiedene Range-Objekte, die denselben Text abdecken, werden beide gespeichert.
Range vs. StaticRange: Ein Range wird bei DOM-Änderungen automatisch angepasst, was bei sehr vielen Bereichen Leistung kostet. Ein StaticRange ist günstiger, kann nach DOM-Änderungen aber ungültig werden und wird dann nicht mehr dargestellt.
Erlaubte CSS-Eigenschaften: In ::highlight() wirken nur wenige Eigenschaften, z. B. color, background-color, text-decoration, text-shadow sowie einige SVG-Eigenschaften. Layout-Eigenschaften wie padding oder font-size werden ignoriert.
Überlappen sich mehrere Highlights, entscheidet die Eigenschaft highlight.priority, welches oben liegt.

Siehe auch

Highlight Highlight.delete() Highlight.clear() Highlight.has() Range Set.prototype.add()