HighlightRegistry.highlightsFromPoint() — Methode · JavaScript-Referenz

Signatur

HighlightRegistry.prototype.highlightsFromPoint(x, y, options)

Beschreibung

Mit highlightsFromPoint() lässt sich über CSS.highlights abfragen, welche benutzerdefinierten Hervorhebungen der CSS Custom Highlight API an bestimmten Koordinaten im Ansichtsfenster liegen. Hervorhebungen, die über ::highlight() gestaltet werden, sind keine DOM-Elemente. Deshalb erreichen sie keine Maus- oder Zeiger-Events, und document.elementFromPoint() findet sie nicht. Diese Methode schließt genau diese Lücke.

Typische Einsatzfälle sind interaktive Hervorhebungen: Tooltips für markierte Rechtschreibfehler, Kontextmenüs für Suchtreffer, Klicks auf Anmerkungen oder Hover-Effekte bei Syntax-Hervorhebungen. Meist reicht man dafür event.clientX und event.clientY aus einem click- oder pointermove-Event weiter.

Zurück kommt ein Array von Objekten mit den Eigenschaften highlight (das Highlight-Objekt) und ranges (die Bereiche dieses Highlights, die den Punkt tatsächlich enthalten). Die Einträge sind absteigend nach Highlight.priority sortiert. Der erste Eintrag ist also die Hervorhebung, die optisch oben liegt.

Parameter

Name	Typ	Default	Beschreibung
$x Pflicht	number		Horizontale Koordinate in CSS-Pixeln, bezogen auf das Ansichtsfenster (wie `clientX`).
$y Pflicht	number		Vertikale Koordinate in CSS-Pixeln, bezogen auf das Ansichtsfenster (wie `clientY`).
$options	{ shadowRoots?: ShadowRoot[] }	{}	Optionales Objekt. `shadowRoots` ist ein Array von `ShadowRoot`-Objekten. Hervorhebungen innerhalb dieser Shadow Roots werden ebenfalls berücksichtigt, sonst bleiben sie verborgen.

Rückgabewert

Typ

Array<{ highlight: Highlight, ranges: AbstractRange[] }>

Beschreibung

Array mit den Treffern, absteigend nach Priorität sortiert. Jeder Eintrag enthält das Highlight und die Bereiche (Range/StaticRange), die den Punkt abdecken. Ohne Treffer oder bei Koordinaten außerhalb des Ansichtsfensters ist das Array leer.

Beispiele

Angeklickte Hervorhebung ermitteln

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

// Bereich für die Wörter 0–5 hervorheben
const range = new Range();
range.setStart(textNode, 0);
range.setEnd(textNode, 5);

const suchtreffer = new Highlight(range);
CSS.highlights.set('suchtreffer', suchtreffer);
// CSS: ::highlight(suchtreffer) { background: yellow; }

document.addEventListener('click', (event) => {
  const treffer = CSS.highlights.highlightsFromPoint(event.clientX, event.clientY);
  if (treffer.length === 0) return;

  const { highlight, ranges } = treffer[0];
  console.log(highlight === suchtreffer, ranges[0].toString());
});

true "Hallo" // bei Klick auf das hervorgehobene Wort

Tooltip für Rechtschreibfehler beim Überfahren

const fehlerHighlight = new Highlight();
fehlerHighlight.priority = 10;
CSS.highlights.set('rechtschreibung', fehlerHighlight);

// Hinweistexte pro Range speichern
const hinweise = new WeakMap();

const markiereFehler = (node, start, ende, vorschlag) => {
  const r = new Range();
  r.setStart(node, start);
  r.setEnd(node, ende);
  fehlerHighlight.add(r);
  hinweise.set(r, vorschlag);
};

const tooltip = document.querySelector('#tooltip');

document.addEventListener('pointermove', ({ clientX, clientY }) => {
  const eintrag = CSS.highlights
    .highlightsFromPoint(clientX, clientY)
    .find(({ highlight }) => highlight === fehlerHighlight);

  if (eintrag) {
    tooltip.textContent = `Meinten Sie: ${hinweise.get(eintrag.ranges[0])}?`;
    tooltip.style.left = `${clientX + 12}px`;
    tooltip.style.top = `${clientY + 12}px`;
    tooltip.hidden = false;
  } else {
    tooltip.hidden = true;
  }
});

Hervorhebungen im Shadow DOM einbeziehen

const host = document.querySelector('mein-editor');
const shadow = host.shadowRoot; // Shadow Root muss zugänglich sein (mode: 'open')

host.addEventListener('click', (event) => {
  // Ohne feature detection kein Aufruf
  if (!('highlightsFromPoint' in CSS.highlights)) return;

  const treffer = CSS.highlights.highlightsFromPoint(
    event.clientX,
    event.clientY,
    { shadowRoots: [shadow] }
  );

  // Namen der Highlights ermitteln
  const namen = treffer.map(({ highlight }) =>
    [...CSS.highlights].find(([, h]) => h === highlight)?.[0]
  );
  console.log(namen);
});

["kommentar", "syntax-keyword"]

// Wichtig · Fallstricke

Experimentelle API: Bisher nur in Chromium-Browsern (ab Version 140) verfügbar. Deshalb vor dem Aufruf per Feature-Erkennung prüfen: 'highlightsFromPoint' in CSS.highlights. Die CSS Custom Highlight API selbst (Highlight, ::highlight()) wird dagegen in allen modernen Browsern breit unterstützt.
Koordinaten sind relativ zum Ansichtsfenster anzugeben, nicht zur Seite. Verwenden Sie clientX/clientY, nicht pageX/pageY, sonst liefert die Methode nach dem Scrollen falsche oder leere Ergebnisse.
Hervorhebungen in einem Shadow DOM werden nur gefunden, wenn der jeweilige ShadowRoot in options.shadowRoots übergeben wird. Das schützt die Kapselung geschlossener Shadow Roots.
Der Rückgabewert enthält keine Highlight-Namen. Soll der Name bekannt sein, muss man die Registry (CSS.highlights) durchsuchen oder eine eigene Zuordnung (Map/WeakMap) pflegen.
Leistung: Bei pointermove wird die Methode sehr oft aufgerufen. Bei vielen Ranges empfiehlt es sich, die Aufrufe zu drosseln (z. B. mit requestAnimationFrame).
Die Methode berücksichtigt keine CSS-Eigenschaft pointer-events. Auch Hervorhebungen ohne sichtbare Gestaltung werden gefunden, solange sie in der Registry stehen.

Siehe auch

Highlight Highlight.priority CSS.highlights Range HighlightRegistry.entries()