HighlightRegistry.get() — Methode · JavaScript-Referenz

Signatur

HighlightRegistry.prototype.get(name)

Beschreibung

Die Methode get() des HighlightRegistry-Interfaces gibt das Highlight-Objekt zurück, das unter einem bestimmten Namen registriert wurde. Das Register erreicht man über CSS.highlights. Es verhält sich wie ein Map: Die Schlüssel sind Namen (Zeichenketten), die Werte sind Highlight-Objekte. get() funktioniert genauso wie Map.prototype.get().

Gebraucht wird die Methode vor allem, wenn man ein bestehendes Highlight ändern will, statt es neu anzulegen – etwa um bei einer Suchfunktion weitere Range-Objekte hinzuzufügen, einzelne Bereiche zu entfernen oder die priority anzupassen. Weil Highlight selbst Set-artig ist, wirken sich solche Änderungen sofort auf die Darstellung über das Pseudo-Element ::highlight(name) aus.

Ist unter dem Namen nichts registriert, gibt die Methode undefined zurück. Vor dem Zugriff auf Methoden des Ergebnisses sollte man also prüfen, ob etwas zurückkam, oder die Methode has() verwenden.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Der Name, unter dem das Highlight mit `CSS.highlights.set(name, highlight)` registriert wurde. Er muss dem Bezeichner in `::highlight(name)` im CSS entsprechen. Groß- und Kleinschreibung werden unterschieden.

Rückgabewert

Typ

Highlight | undefined

Beschreibung

Das registrierte Highlight-Objekt oder undefined, wenn unter dem Namen kein Eintrag existiert.

Beispiele

Registriertes Highlight abrufen

// CSS: ::highlight(suche) { background-color: yellow; }
const absatz = document.querySelector('p');
const range = new Range();
range.setStart(absatz.firstChild, 0);
range.setEnd(absatz.firstChild, 5);

CSS.highlights.set('suche', new Highlight(range));

const hl = CSS.highlights.get('suche');
console.log(hl instanceof Highlight, hl.size);
console.log(CSS.highlights.get('gibtEsNicht'));

true 1 undefined

Bestehendes Highlight um weitere Treffer erweitern

const markiereTreffer = (textNode, begriff) => {
  // Highlight holen oder beim ersten Aufruf anlegen
  let hl = CSS.highlights.get('suche');
  if (!hl) {
    hl = new Highlight();
    CSS.highlights.set('suche', hl);
  }

  const text = textNode.textContent.toLowerCase();
  const suchbegriff = begriff.toLowerCase();
  let pos = text.indexOf(suchbegriff);
  while (pos !== -1) {
    const r = new Range();
    r.setStart(textNode, pos);
    r.setEnd(textNode, pos + suchbegriff.length);
    hl.add(r);
    pos = text.indexOf(suchbegriff, pos + suchbegriff.length);
  }
  return hl.size;
};

const node = document.querySelector('#artikel').firstChild;
console.log(markiereTreffer(node, 'JavaScript'));

3 (Anzahl der Treffer, abhängig vom Text)

Priorität ändern und Highlight leeren

const fehler = CSS.highlights.get('rechtschreibung');

if (fehler) {
  // Soll bei Überlappung über anderen Highlights liegen
  fehler.priority = 10;
  // Alle Bereiche entfernen, Registrierung bleibt aber bestehen
  fehler.clear();
  console.log(fehler.size);
}

// Wichtig · Fallstricke

Feature-Erkennung: In älteren Browsern gibt es weder CSS.highlights noch Highlight. Vor der Nutzung prüfen: if ('highlights' in CSS) { … }. Chromium unterstützt die API seit Version 105, Safari seit 17.2, Firefox erst seit neueren Versionen.
Keine neue Instanz: get() gibt dasselbe Objekt zurück, das mit set() registriert wurde, keine Kopie. Änderungen daran sind sofort auf der Seite sichtbar.
Rückgabewert undefined: Direktes Verketten wie CSS.highlights.get('x').add(r) löst einen TypeError aus, wenn der Name fehlt. Hier hilft optionale Verkettung (?.) oder eine vorherige Prüfung.
Name muss zum CSS passen: Groß- und Kleinschreibung werden unterschieden. Ein Tippfehler zwischen JavaScript und ::highlight() bringt keine Fehlermeldung, sondern führt einfach dazu, dass nichts angezeigt wird.
Eine Range ist eine Live-Referenz auf das DOM. Wird das DOM geändert, kann sie leer werden oder sich verschieben. Bei dynamischen Inhalten sollte man die Bereiche daher neu berechnen.

Siehe auch

Highlight Range Map.prototype.get() HighlightRegistry.set() HighlightRegistry.has()