CharacterBoundsUpdateEvent.rangeEnd — Eigenschaft · JavaScript-Referenz

Signatur

CharacterBoundsUpdateEvent.rangeEnd

Beschreibung

rangeEnd ist eine schreibgeschützte Eigenschaft des CharacterBoundsUpdateEvent. Dieses Ereignis gehört zur EditContext-API. Ein EditContext feuert es als characterboundsupdate, wenn das Betriebssystem wissen muss, wo bestimmte Zeichen auf dem Bildschirm liegen. Das braucht es zum Beispiel, um das Kandidatenfenster einer Eingabemethode (IME) für Japanisch oder Chinesisch richtig zu platzieren.

Zusammen mit rangeStart legt rangeEnd den angefragten Bereich fest. Beide Werte sind Offsets in UTF-16-Codeeinheiten innerhalb von editContext.text. In der Praxis wird der Bereich als halboffenes Intervall [rangeStart, rangeEnd) behandelt: Man geht von rangeStart bis ausschließlich rangeEnd durch den Text und erzeugt für jedes Zeichen ein DOMRect.

Diese Rechtecke gibt man mit EditContext.prototype.updateCharacterBounds(rangeStart, rects) an den Browser zurück. Das Array sollte genau rangeEnd - rangeStart Einträge haben.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative ganze Zahl: der End-Offset des angefragten Zeichenbereichs in UTF-16-Codeeinheiten, bezogen auf editContext.text.

Beispiele

Angefragten Bereich protokollieren

const editor = document.querySelector('#editor');
const editContext = new EditContext({ text: 'Hallo Welt' });
editor.editContext = editContext;

editContext.addEventListener('characterboundsupdate', (e) => {
  const anzahl = e.rangeEnd - e.rangeStart;
  console.log(`Bereich ${e.rangeStart}–${e.rangeEnd} (${anzahl} Zeichen)`);
  console.log('Text:', editContext.text.slice(e.rangeStart, e.rangeEnd));
});

Bereich 6–10 (4 Zeichen) Text: Welt

Zeichengrenzen mit Range berechnen und zurückmelden

// Der Editor rendert den Text als einzelnen Textknoten
const editor = document.querySelector('#editor');
const editContext = new EditContext();
editor.editContext = editContext;

editContext.addEventListener('textupdate', (e) => {
  editor.textContent = editContext.text;
});

editContext.addEventListener('characterboundsupdate', (e) => {
  const textNode = editor.firstChild;
  if (!textNode) return;

  const range = document.createRange();
  const rects = [];

  // rangeEnd ist exklusiv: offset < e.rangeEnd
  for (let offset = e.rangeStart; offset < e.rangeEnd; offset++) {
    range.setStart(textNode, offset);
    range.setEnd(textNode, offset + 1);
    rects.push(range.getBoundingClientRect());
  }

  editContext.updateCharacterBounds(e.rangeStart, rects);
});

Feature-Erkennung vor der Nutzung

if ('EditContext' in window && 'CharacterBoundsUpdateEvent' in window) {
  console.log('EditContext-API verfügbar');
} else {
  console.log('Fallback auf contenteditable/textarea nötig');
}

EditContext-API verfügbar

// Wichtig · Fallstricke

Kompatibilität: Die EditContext-API ist experimentell und bisher nur in Chromium-Browsern verfügbar (Chrome/Edge ab 121). Firefox und Safari unterstützen sie nicht. Prüfe deshalb vorher auf Unterstützung und sieh einen Fallback vor.
Exklusives Ende: Lies den Wert als halboffenes Intervall, also offset < rangeEnd. Mit <= entsteht ein Rechteck zu viel, und ein setEnd hinter dem Textende kann eine IndexSizeError auslösen.
UTF-16-Offsets: Die Offsets zählen Codeeinheiten, nicht sichtbare Zeichen (Grapheme). Emojis oder Zeichen außerhalb der Basic Multilingual Plane belegen zwei Einheiten.
Die Rechtecke müssen in Viewport-Koordinaten angegeben werden, so wie getBoundingClientRect() sie liefert. Wenn du den Text selbst renderst, zum Beispiel in einem <canvas>, musst du die Koordinaten selbst umrechnen.
Die Eigenschaft ist schreibgeschützt. Zuweisungen werden ignoriert, im Strict-Modus lösen sie einen TypeError aus.

Siehe auch

CharacterBoundsUpdateEvent CharacterBoundsUpdateEvent.rangeStart EditContext EditContext.prototype.updateCharacterBounds() Range.prototype.getBoundingClientRect() XRReferenceSpaceEvent.transform