HighlightRegistry.entries() — Methode · JavaScript-Referenz

Signatur

HighlightRegistry.prototype.entries()

Beschreibung

Die Methode entries() der Schnittstelle HighlightRegistry (erreichbar über CSS.highlights) gibt einen neuen Iterator zurück. Er liefert für jede registrierte Hervorhebung ein Array [name, highlight]. Dabei ist name der Bezeichner, der im CSS über ::highlight(name) angesprochen wird, und highlight das zugehörige Highlight-Objekt.

HighlightRegistry ist ein Map-ähnliches Objekt. entries() verhält sich deshalb genau wie Map.prototype.entries(): Die Einträge kommen in der Reihenfolge, in der sie mit set() hinzugefügt wurden. Weil entries() auch der Standard-Iterator ([Symbol.iterator]) der Registry ist, liefert for (const [name, hl] of CSS.highlights) dasselbe Ergebnis.

Typische Einsatzfälle sind das Debuggen, also die Frage, welche Hervorhebungen gerade aktiv sind, das gezielte Aufräumen von Hervorhebungen mit einem bestimmten Namensmuster und das Auswerten, wie viele Range-Objekte jede Hervorhebung enthält.

Rückgabewert

Typ

Iterator<[string, Highlight]>

Beschreibung

Ein neuer Iterator. Jeder Schritt liefert ein Array aus zwei Elementen: den registrierten Namen (string) und das zugehörige Highlight-Objekt.

Beispiele

Alle registrierten Hervorhebungen auflisten

// Zwei Hervorhebungen anlegen und registrieren
const p = document.querySelector('p');

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

const r2 = new Range();
r2.setStart(p.firstChild, 6);
r2.setEnd(p.firstChild, 11);

CSS.highlights.set('suchtreffer', new Highlight(r1, r2));
CSS.highlights.set('fehler', new Highlight(r1));

for (const [name, highlight] of CSS.highlights.entries()) {
  console.log(`${name}: ${highlight.size} Bereich(e)`);
}

suchtreffer: 2 Bereich(e) fehler: 1 Bereich(e)

Iterator manuell mit next() durchlaufen

CSS.highlights.clear();
CSS.highlights.set('a', new Highlight());
CSS.highlights.set('b', new Highlight());

const it = CSS.highlights.entries();
console.log(it.next().value[0]);
console.log(it.next().value[0]);
console.log(it.next().done);

a b true

Hervorhebungen nach Namensmuster entfernen

// Alle Hervorhebungen löschen, deren Name mit 'temp-' beginnt.
// Zuerst in ein Array kopieren, damit die Registry nicht während der Iteration verändert wird.
const zuLoeschen = [...CSS.highlights.entries()]
  .filter(([name]) => name.startsWith('temp-'))
  .map(([name]) => name);

zuLoeschen.forEach((name) => CSS.highlights.delete(name));
console.log([...CSS.highlights.keys()]);

z. B. ["suchtreffer", "fehler"]

Übersicht als Objekt für das Debugging

const uebersicht = Object.fromEntries(
  [...CSS.highlights.entries()].map(([name, hl]) => [
    name,
    { bereiche: hl.size, prioritaet: hl.priority, typ: hl.type }
  ])
);
console.table(uebersicht);

Tabelle mit Name, Anzahl der Bereiche, Priorität und Typ je Hervorhebung

// Wichtig · Fallstricke

Browser-Kompatibilität: Die CSS Custom Highlight API wird von Chromium-Browsern ab Version 105 und von Safari ab 17.2 unterstützt, von Firefox erst seit Version 140. Prüfe die Unterstützung vorher mit if ('highlights' in CSS).
Den Iterator erhältst du nicht direkt über den Konstruktor HighlightRegistry, sondern immer über die globale Instanz CSS.highlights.
Der Iterator ist live: Wenn du während der Iteration Einträge mit set() hinzufügst oder mit delete() entfernst, ändert sich auch der weitere Durchlauf. Kopiere die Einträge deshalb vorher mit [...CSS.highlights.entries()], wenn du sie verändern willst.
Ein Iterator lässt sich nur einmal durchlaufen. Für einen zweiten Durchlauf rufst du entries() erneut auf.
Der Iterator liefert nur die Highlight-Objekte, nicht deren Range-Objekte. Um an die Bereiche zu kommen, iterierst du zusätzlich über das jeweilige Highlight, das Set-ähnlich ist.

Siehe auch

HighlightRegistry HighlightRegistry.keys() HighlightRegistry.values() HighlightRegistry.forEach() HighlightRegistry.set() Highlight Map.prototype.entries()