Highlight.entries() — Methode · JavaScript-Referenz

Signatur

Highlight.prototype.entries()

Beschreibung

Die Methode entries() der Schnittstelle Highlight aus der CSS Custom Highlight API gibt einen neuen Iterator zurück. Er durchläuft alle im Highlight gespeicherten AbstractRange-Objekte (also Range oder StaticRange) in der Reihenfolge, in der sie eingefügt wurden.

Highlight verhält sich wie ein Set (setlike). Deshalb besteht jeder Eintrag aus einem zweielementigen Array [range, range]: Schlüssel und Wert sind dasselbe Objekt. Das entspricht genau Set.prototype.entries() und macht die API mit Map-artigem Code kompatibel.

In der Praxis brauchen Sie entries() eher selten. Für einfaches Durchlaufen reichen meist values(), forEach() oder direkt for...of über das Highlight. Nützlich ist entries(), wenn generischer Code einheitlich mit Schlüssel-Wert-Paaren arbeitet, etwa beim Umwandeln von Sammlungen oder bei Hilfsfunktionen, die sowohl Map als auch Set annehmen.

Rückgabewert

Typ

Iterator<[AbstractRange, AbstractRange]>

Beschreibung

Ein neuer Set-Iterator. Jeder Schritt liefert ein Array [range, range], in dem beide Elemente dasselbe AbstractRange-Objekt sind.

Beispiele

Highlight anlegen und Einträge durchlaufen

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

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

const r2 = new StaticRange({ startContainer: text, startOffset: 6, endContainer: text, endOffset: 11 });

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

for (const [schluessel, wert] of highlight.entries()) {
  console.log(schluessel === wert, wert.toString?.() ?? `${wert.startOffset}-${wert.endOffset}`);
}

true Hallo true 6-11

Iterator manuell mit next() abfragen

const text = document.body.firstChild;
const range = document.createRange();
range.selectNodeContents(document.body);

const highlight = new Highlight(range);
const iter = highlight.entries();

console.log(iter.next().value[0] === range);
console.log(iter.next().done);

true true

Suchtreffer hervorheben und Positionen auflisten

// CSS: ::highlight(treffer) { background: yellow; }
const markiereTreffer = (element, begriff) => {
  const highlight = new Highlight();
  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
  let node;
  while ((node = walker.nextNode())) {
    const inhalt = node.textContent.toLowerCase();
    let pos = inhalt.indexOf(begriff.toLowerCase());
    while (pos !== -1) {
      const r = new Range();
      r.setStart(node, pos);
      r.setEnd(node, pos + begriff.length);
      highlight.add(r);
      pos = inhalt.indexOf(begriff.toLowerCase(), pos + begriff.length);
    }
  }
  CSS.highlights.set('treffer', highlight);
  return highlight;
};

const hl = markiereTreffer(document.querySelector('article'), 'javascript');
const positionen = [...hl.entries()].map(([r], i) => `#${i + 1}: Offset ${r.startOffset}`);
console.log(positionen);

["#1: Offset 12", "#2: Offset 87"] (abhängig vom Inhalt)

// Wichtig · Fallstricke

Doppelter Wert: Jeder Eintrag ist [range, range] und nicht [index, range]. Einen Index bekommen Sie über [...highlight.entries()].map((e, i) => …).
Lebender Iterator: Werden während des Durchlaufs Bereiche mit add() oder delete() geändert, sieht der Iterator das wie bei einem Set. Neu hinzugefügte Bereiche erscheinen noch. Wenn Sie beim Durchlaufen ändern wollen, legen Sie vorher mit [...highlight] eine Kopie an.
StaticRange: StaticRange passt sich DOM-Änderungen nicht an und hat keine Methode toString(). Prüfen Sie den Typ, bevor Sie auf Range-Methoden zugreifen.
Kompatibilität: Die CSS Custom Highlight API gibt es in Chromium ab Version 105 und in Safari ab 17.2. Firefox unterstützt sie erst in neueren Versionen. Prüfen Sie die Unterstützung vorher mit if ('highlights' in CSS).

Siehe auch

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