HighlightRegistry.values() — Methode · JavaScript-Referenz

Signatur

HighlightRegistry.prototype.values()

Beschreibung

Die Methode values() des Interfaces HighlightRegistry (erreichbar über CSS.highlights) gibt ein neues Iterator-Objekt zurück. Es liefert die Highlight-Objekte jedes Eintrags in der Reihenfolge, in der sie registriert wurden. HighlightRegistry ist ein Map-ähnliches Objekt: Die Schlüssel sind die Highlight-Namen (Strings), die Werte sind Highlight-Instanzen.

Brauchbar ist values() immer dann, wenn du alle aktiven Hervorhebungen durchgehen willst, ohne dass dich ihre Namen interessieren. Das gilt etwa, wenn du alle Bereiche (Range-Objekte) zählen, Prioritäten anpassen oder jedes Highlight leeren möchtest. Brauchst du die Namen zusätzlich, nimm entries() oder forEach().

Der zurückgegebene Iterator ist selbst iterierbar. Du kannst ihn also direkt in for...of-Schleifen, mit dem Spread-Operator oder mit Array.from() verwenden. In Umgebungen mit Iterator-Helpern (ES2025) gibt es außerdem Methoden wie .map() oder .filter() direkt auf dem Iterator.

Rückgabewert

Typ

Iterator<Highlight>

Beschreibung

Ein neuer Map-Iterator, der die Highlight-Objekte des Registers in Einfügereihenfolge liefert.

Beispiele

Alle registrierten Highlights durchlaufen

// Zwei Textbereiche im ersten Absatz markieren
const textNode = document.querySelector('p').firstChild;

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

const range2 = new Range();
range2.setStart(textNode, 6);
range2.setEnd(textNode, 10);

CSS.highlights.set('suche', new Highlight(range1));
CSS.highlights.set('fehler', new Highlight(range2, range1));

for (const highlight of CSS.highlights.values()) {
  console.log(`Highlight mit ${highlight.size} Bereich(en)`);
}

Highlight mit 1 Bereich(en) Highlight mit 2 Bereich(en)

Gesamtzahl aller markierten Bereiche ermitteln

const zaehleBereiche = () =>
  [...CSS.highlights.values()].reduce((summe, h) => summe + h.size, 0);

console.log(`Insgesamt ${zaehleBereiche()} markierte Bereiche`);

Insgesamt 3 markierte Bereiche

Alle Highlights leeren, aber registriert lassen

// Entfernt alle Ranges, die Einträge in CSS.highlights bleiben bestehen
for (const highlight of CSS.highlights.values()) {
  highlight.clear();
}

console.log(CSS.highlights.size); // Anzahl der Einträge bleibt gleich

2

Iterator manuell mit next() abfragen

const iter = CSS.highlights.values();

const erstes = iter.next();
console.log(erstes.done, erstes.value instanceof Highlight);

// Iterator ist erschöpft, sobald alle Werte gelesen wurden
[...iter];
console.log(iter.next().done);

false true true

// Wichtig · Fallstricke

Kompatibilität: Die CSS Custom Highlight API wird in Chromium-Browsern ab Version 105, in Safari ab 17.2 und in Firefox erst ab Version 140 unterstützt. Prüfe die Verfügbarkeit vorher mit if ('highlights' in CSS) { … }. In Node.js gibt es die API nicht.
Einmal verwendbar: Ein Iterator lässt sich nur einmal durchlaufen. Für einen zweiten Durchlauf rufst du values() erneut auf oder wandelst das Ergebnis vorher mit Array.from() in ein Array um.
Änderungen während der Iteration: Wie bei Map ist der Iterator „live“. Einträge, die du während der Schleife per set() hinzufügst, werden noch besucht. Gelöschte Einträge werden übersprungen.
Keine Namen: values() liefert nur die Highlight-Objekte. Die zugehörigen Namen bekommst du über keys() oder entries().
Kein Zusammenhang mit Stilen: Ein Highlight wird nur sichtbar, wenn im CSS ein passender ::highlight(name)-Selektor existiert. Die Iteration verrät nicht, ob ein Stil definiert ist.

Siehe auch

Highlight Map.prototype.values() HighlightRegistry.has() HighlightRegistry.clear() HighlightRegistry.delete()