HighlightRegistry.keys() — Methode · JavaScript-Referenz

Signatur

HighlightRegistry.prototype.keys()

Beschreibung

Die Methode keys() des Interfaces HighlightRegistry (erreichbar über CSS.highlights) gibt ein neues Iterator-Objekt zurück. Es liefert die Namen aller registrierten Highlights in der Reihenfolge, in der sie eingefügt wurden. Diese Namen sind die Zeichenketten, die Sie in CSS mit dem Pseudo-Element ::highlight(name) ansprechen.

HighlightRegistry ist ein Map-ähnliches Objekt. Deshalb verhält sich keys() genau wie Map.prototype.keys(): Der Iterator funktioniert mit for...of, mit dem Spread-Operator oder mit Array.from(). Seit ES2025 stehen außerdem Iterator-Helfer wie .map() und .filter() bereit.

Typische Einsatzfälle:

Sie wollen prüfen, welche Hervorhebungen gerade aktiv sind, etwa beim Debuggen oder in Entwicklerwerkzeugen.
Sie wollen gezielt alle Highlights mit einem bestimmten Namenspräfix entfernen, zum Beispiel search-*.
Sie wollen den aktuellen Zustand der Hervorhebungen mit einer Anwendungslogik abgleichen, etwa bei Syntaxhervorhebung oder Suchtreffern.

Rückgabewert

Typ

Iterator<string>

Beschreibung

Ein neuer Map-Iterator, der die Namen (string) aller registrierten Highlights in Einfügereihenfolge liefert.

Beispiele

Registrierte Highlight-Namen auflisten

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

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

const range2 = new Range();
range2.setStart(text, 6);
range2.setEnd(text, 11);

CSS.highlights.set('suchtreffer', new Highlight(range1));
CSS.highlights.set('rechtschreibung', new Highlight(range2));

for (const name of CSS.highlights.keys()) {
  console.log(name);
}

suchtreffer rechtschreibung

Alle Highlights mit Präfix entfernen

const clearHighlightsByPrefix = (prefix) => {
  // Erst in ein Array kopieren, damit beim Löschen nicht über die Live-Sammlung iteriert wird
  const names = [...CSS.highlights.keys()].filter((name) => name.startsWith(prefix));
  names.forEach((name) => CSS.highlights.delete(name));
  return names;
};

CSS.highlights.set('search-0', new Highlight());
CSS.highlights.set('search-1', new Highlight());
CSS.highlights.set('fehler', new Highlight());

console.log(clearHighlightsByPrefix('search-'));
console.log([...CSS.highlights.keys()]);

['search-0', 'search-1'] ['fehler']

Iterator manuell mit next() abfragen

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

const it = CSS.highlights.keys();
console.log(it.next());
console.log(it.next());

{ value: 'aktiv', done: false } { value: undefined, done: true }

// Wichtig · Fallstricke

Browser-Kompatibilität: Die CSS Custom Highlight API gibt es in Chromium seit Version 105 und in Safari seit 17.2. Firefox unterstützt sie erst ab Version 140. Prüfen Sie die Unterstützung vorher mit if ('highlights' in CSS).
Der Iterator ist live: Einträge, die während der Iteration hinzukommen, werden noch geliefert, gelöschte dagegen übersprungen. Wenn Sie während der Iteration Einträge löschen oder hinzufügen, wandeln Sie ihn vorher mit [...CSS.highlights.keys()] in ein Array um.
Ein Iterator lässt sich nur einmal durchlaufen. Für einen zweiten Durchlauf rufen Sie keys() erneut auf.
Die Methode liefert nur die Namen. Die zugehörigen Highlight-Objekte erhalten Sie mit values() oder entries().
Die Einfügereihenfolge bestimmt nicht, welches Highlight bei Überlappung oben gezeichnet wird. Das steuert die Eigenschaft Highlight.priority.

Siehe auch

Highlight HighlightRegistry.clear() HighlightRegistry.get() HighlightRegistry.has() HighlightRegistry.set()