Highlight.has() — Methode · JavaScript-Referenz

Signatur

Highlight.prototype.has(range)

Beschreibung

Die Methode has() gehört zur CSS Custom Highlight API. Ein Highlight-Objekt verhält sich wie ein Set: Es fasst mehrere Bereiche (Range- oder StaticRange-Objekte) zusammen, die später gemeinsam über das Pseudoelement ::highlight(name) per CSS eingefärbt werden, ohne dass das DOM verändert wird. has() sagt dir, ob ein bestimmter Bereich bereits Teil dieser Menge ist.

Wichtig ist, dass der Vergleich über die Objektidentität läuft, genau wie bei Set.prototype.has(). Zwei verschiedene Range-Objekte, die exakt denselben Textabschnitt abdecken, gelten als verschieden. has() liefert also nur dann true, wenn genau dieselbe Objektreferenz vorher mit add() hinzugefügt (oder dem Konstruktor übergeben) wurde.

Typische Einsatzfälle sind Umschaltfunktionen (Markierung setzen oder entfernen), das Vermeiden unnötiger add()-Aufrufe und Aufräumlogik, bevor Bereiche mit delete() entfernt werden.

Parameter

Name	Typ	Default	Beschreibung
$range Pflicht	AbstractRange (Range \| StaticRange)		Das Bereichsobjekt, nach dem im `Highlight` gesucht wird. Verglichen wird die Referenz, nicht der abgedeckte Inhalt.

Beispiele

Grundlegende Prüfung nach add()

const absatz = document.querySelector('p');
const range = new Range();
range.selectNodeContents(absatz);

const highlight = new Highlight();
console.log(highlight.has(range)); // noch nicht enthalten

highlight.add(range);
console.log(highlight.has(range));

CSS.highlights.set('markiert', highlight);

false true

Objektidentität statt Inhaltsvergleich

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

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

// Gleicher Textabschnitt, aber neues Objekt
const r2 = new Range();
r2.setStart(text, 0);
r2.setEnd(text, 5);

const highlight = new Highlight(r1);
console.log(highlight.has(r1));
console.log(highlight.has(r2));

true false

Markierung einer Auswahl umschalten

// CSS: ::highlight(notiz) { background: yellow; }
const notizen = new Highlight();
CSS.highlights.set('notiz', notizen);
const gespeichert = new Map(); // Text -> Range

document.addEventListener('keydown', (event) => {
  if (event.key !== 'm') return;
  const auswahl = document.getSelection();
  if (!auswahl || auswahl.isCollapsed) return;

  const schluessel = auswahl.toString();
  const vorhanden = gespeichert.get(schluessel);

  if (vorhanden && notizen.has(vorhanden)) {
    notizen.delete(vorhanden);
    gespeichert.delete(schluessel);
    console.log(`Markierung entfernt: ${schluessel}`);
  } else {
    const range = auswahl.getRangeAt(0).cloneRange();
    notizen.add(range);
    gespeichert.set(schluessel, range);
    console.log(`Markiert: ${schluessel}`);
  }
});

Markiert: Beispieltext Markierung entfernt: Beispieltext

Feature-Erkennung vor der Nutzung

if ('highlights' in CSS && typeof Highlight !== 'undefined') {
  const range = document.createRange();
  range.selectNode(document.body.firstElementChild);
  const h = new Highlight(range);
  console.log('Enthalten:', h.has(range));
} else {
  console.log('CSS Custom Highlight API wird nicht unterstützt');
}

Enthalten: true

// Wichtig · Fallstricke

Referenzvergleich: has() vergleicht Objektreferenzen. Wer Bereiche später wiederfinden will, muss die ursprünglichen Range-Objekte aufbewahren, z. B. in einer Map.
Live-Ranges: Ein Range passt sich an DOM-Änderungen an. Er bleibt auch dann im Highlight enthalten, wenn er inzwischen leer ist (collapsed). has() sagt nichts darüber aus, ob der Bereich noch sichtbar ist.
Selection.getRangeAt() kann bei jeder neuen Auswahl ein anderes Objekt zurückgeben. Deshalb vor dem Speichern cloneRange() aufrufen.
Kompatibilität: Die CSS Custom Highlight API gibt es in Chromium-Browsern ab Version 105 und in Safari ab 17.2. Firefox unterstützt sie erst seit neueren Versionen (ab 140). Vor der Nutzung mit 'highlights' in CSS prüfen.
Die Methode stammt aus der setartigen Schnittstelle von Highlight. Genauso stehen add(), delete(), clear(), forEach(), size sowie die Iteration mit for...of zur Verfügung.

Siehe auch

Highlight Highlight.add() Highlight.delete() Highlight.clear() Range Set.prototype.has()