Highlight.keys() — Methode · JavaScript-Referenz

Signatur

Highlight.prototype.keys()

Beschreibung

Die Methode keys() der Schnittstelle Highlight liefert ein neues Iterator-Objekt, das die im Highlight enthaltenen Bereiche (Range oder StaticRange) in Einfügereihenfolge durchläuft. Da Highlight sich wie ein Set verhält, gibt es keine getrennten Schlüssel: keys() ist ein reiner Alias für values() und liefert exakt dieselben Werte.

Die Methode ist Teil der CSS Custom Highlight API, mit der man beliebige Textbereiche per ::highlight(name) gestalten kann, ohne das DOM zu verändern (z. B. für Suchtreffer, Rechtschreibmarkierungen oder kollaborative Cursor). Mit keys() lassen sich die registrierten Bereiche nachträglich auswerten – etwa um sie zu zählen, zu filtern oder den markierten Text auszulesen.

In der Praxis wird meist for...of direkt über das Highlight oder values() verwendet. keys() existiert vor allem aus Gründen der Konsistenz mit der Set-Schnittstelle, damit generischer Code, der mit Set-ähnlichen Objekten arbeitet, auch mit Highlight funktioniert.

Rückgabewert

Typ

Iterator<AbstractRange>

Beschreibung

Ein neuer Set-Iterator, der alle im Highlight enthaltenen Range-/StaticRange-Objekte in Einfügereihenfolge liefert.

Beispiele

Bereiche eines Highlights durchlaufen

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

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

const r2 = new Range();
r2.setStart(text, 10);
r2.setEnd(text, 15);

const markierung = new Highlight(r1, r2);
CSS.highlights.set('suche', markierung);

for (const range of markierung.keys()) {
  console.log(range.toString());
}

Hallo (Text der Zeichen 10–15)

keys() und values() liefern dasselbe

const range = new Range();
range.selectNodeContents(document.body);

const hl = new Highlight(range);
const ausKeys = hl.keys().next().value;
const ausValues = hl.values().next().value;

console.log(ausKeys === ausValues);

true

Suchtreffer auswerten und als Array weiterverarbeiten

const markiereTreffer = (element, begriff) => {
  const knoten = element.firstChild;
  const inhalt = knoten.textContent.toLowerCase();
  const hl = new Highlight();
  let pos = inhalt.indexOf(begriff.toLowerCase());
  while (pos !== -1) {
    const r = new Range();
    r.setStart(knoten, pos);
    r.setEnd(knoten, pos + begriff.length);
    hl.add(r);
    pos = inhalt.indexOf(begriff.toLowerCase(), pos + 1);
  }
  CSS.highlights.set('treffer', hl);
  return hl;
};

const hl = markiereTreffer(document.querySelector('#artikel'), 'api');
const positionen = [...hl.keys()].map((r) => r.startOffset);
console.log(`${hl.size} Treffer an Position(en):`, positionen);

3 Treffer an Position(en): [4, 27, 61]

// Wichtig · Fallstricke

Reiner Alias: keys() und values() verhalten sich identisch; entries() liefert dagegen Paare [range, range].
Live-Iterator: Werden während der Iteration Bereiche mit add() oder delete() verändert, wirkt sich das wie bei Set auf den laufenden Iterator aus. Bei Bedarf vorher mit [...hl.keys()] eine Kopie anlegen.
Live-Ranges: Range-Objekte passen sich DOM-Änderungen an, StaticRange nicht – ausgelesene Offsets können daher veraltet sein.
Kompatibilität: Die CSS Custom Highlight API wird in Chromium-Browsern seit Version 105 und in Safari seit 17.2 unterstützt, in Firefox erst ab Version 140. Vorher mit if ('highlights' in CSS) prüfen.
Ein Highlight wird erst sichtbar, wenn es in CSS.highlights registriert und per ::highlight(name) gestaltet wurde – für keys() selbst ist die Registrierung aber nicht nötig.

Siehe auch

Highlight Highlight.values() Highlight.entries() Highlight.forEach() Set.prototype.keys() Range