HighlightRegistry.forEach() — Methode · JavaScript-Referenz

Signatur

HighlightRegistry.prototype.forEach(callbackFn, thisArg)

Beschreibung

HighlightRegistry ist das Register der CSS Custom Highlight API und über CSS.highlights erreichbar. Es verhält sich wie eine Map: Die Schlüssel sind die Namen der Hervorhebungen (die in CSS über ::highlight(name) angesprochen werden), die Werte sind Highlight-Objekte.

forEach() geht alle Einträge in der Reihenfolge durch, in der sie mit set() eingefügt wurden. Die Callback-Funktion bekommt wie bei Map.prototype.forEach() drei Argumente: den Wert (das Highlight), den Schlüssel (den Namen) und das Register selbst.

Typische Einsatzfälle sind das Debuggen oder Protokollieren aller aktiven Hervorhebungen, das Zählen der markierten Bereiche (Ranges) pro Hervorhebung und das gezielte Aufräumen, zum Beispiel wenn Hervorhebungen mit einem bestimmten Präfix entfernt oder neu berechnet werden sollen.

Parameter

Name	Typ	Default	Beschreibung
$callbackFn Pflicht	(highlight: Highlight, name: string, registry: HighlightRegistry) => void		Funktion, die für jeden Eintrag aufgerufen wird. Sie erhält das `Highlight`-Objekt, den registrierten Namen (`string`) und das Register selbst.
$thisArg	any	undefined	Wert, der beim Ausführen von `callbackFn` als `this` gilt. Bei Pfeilfunktionen hat er keine Wirkung.

Rückgabewert

Typ

undefined

Beschreibung

Die Methode gibt nichts zurück (undefined). Sie lässt sich daher nicht verketten.

Beispiele

Alle registrierten Hervorhebungen protokollieren

// HTML: <p id="text">Hallo Welt, hallo JavaScript</p>
const textNode = document.getElementById('text').firstChild;

const makeRange = (start, end) => {
  const range = new Range();
  range.setStart(textNode, start);
  range.setEnd(textNode, end);
  return range;
};

CSS.highlights.set('begruessung', new Highlight(makeRange(0, 5), makeRange(12, 17)));
CSS.highlights.set('sprache', new Highlight(makeRange(18, 28)));

CSS.highlights.forEach((highlight, name) => {
  console.log(`${name}: ${highlight.size} Bereich(e), Priorität ${highlight.priority}`);
});

begruessung: 2 Bereich(e), Priorität 0 sprache: 1 Bereich(e), Priorität 0

Suchtreffer-Hervorhebungen gezielt entfernen

// Namen merken und erst danach löschen, damit das Register
// nicht während des Durchlaufs verändert wird
const zuLoeschen = [];

CSS.highlights.forEach((_highlight, name) => {
  if (name.startsWith('suche-')) {
    zuLoeschen.push(name);
  }
});

zuLoeschen.forEach((name) => CSS.highlights.delete(name));
console.log(`${zuLoeschen.length} Such-Hervorhebung(en) entfernt`);

2 Such-Hervorhebung(en) entfernt

thisArg für einen Statistik-Sammler verwenden

const statistik = {
  gesamt: 0,
  zaehlen(highlight) {
    this.gesamt += highlight.size;
  }
};

// Normale Funktion, damit thisArg greift
CSS.highlights.forEach(function (highlight) {
  this.zaehlen(highlight);
}, statistik);

console.log(`Markierte Bereiche insgesamt: ${statistik.gesamt}`);

Markierte Bereiche insgesamt: 3

// Wichtig · Fallstricke

Reihenfolge der Argumente: Wie bei Map kommt zuerst der Wert (Highlight) und dann der Schlüssel (Name). Diese beiden werden oft verwechselt.
Kein Abbruch möglich: break und return beenden die Schleife nicht vorzeitig. Wenn du abbrechen willst, nimm for (const [name, highlight] of CSS.highlights).
Änderungen während der Iteration: Einträge, die während des Durchlaufs hinzugefügt werden, werden ebenfalls besucht. Gelöschte Einträge, die noch nicht dran waren, werden übersprungen. Besser erst sammeln und danach ändern.
Nicht asynchron: Wenn der Callback eine async-Funktion ist, wartet forEach() nicht auf die zurückgegebenen Promises.
Browser-Unterstützung: Die CSS Custom Highlight API gibt es in Chromium ab Version 105, in Safari ab 17.2 und in Firefox erst ab Version 140. Prüfe die Verfügbarkeit vorher mit if ('highlights' in CSS).

Siehe auch

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