EditContext.updateSelectionBounds() — Methode · JavaScript-Referenz

Signatur

EditContext.prototype.updateSelectionBounds(selectionBounds)

Beschreibung

updateSelectionBounds() gehört zur EditContext-API, mit der Entwickler eigene Texteditoren bauen können, etwa auf Basis von <canvas> oder mit selbst gerendertem DOM. Weil der Browser in solchen Editoren die Darstellung des Textes nicht selbst übernimmt, weiß er nicht, wo auf dem Bildschirm die Auswahl oder der Cursor liegt. Diese Methode liefert ihm genau diese Information.

Das Betriebssystem braucht die Auswahlgrenzen vor allem für Eingabemethoden (IME), zum Beispiel für Japanisch, Chinesisch oder Koreanisch. Damit werden Kandidatenfenster, Autokorrektur-Vorschläge und Bildschirmtastaturen direkt neben dem Cursor angezeigt statt irgendwo auf dem Bildschirm.

Rufe die Methode immer dann auf, wenn sich die sichtbare Position der Auswahl ändert: nach einer Texteingabe, nach Cursor-Bewegungen per Tastatur oder Maus, beim Scrollen, bei Größenänderungen des Fensters und im Event characterboundsupdate. Übergeben wird ein DOMRect in Client-Koordinaten, also relativ zum Viewport. Ist die Auswahl leer (nur ein Cursor), beschreibt das Rechteck die Position des Cursors, meist mit der Breite 0.

Parameter

Name	Typ	Default	Beschreibung
$selectionBounds Pflicht	DOMRect		Rechteck um die aktuelle Auswahl bzw. den Cursor in Client-Koordinaten (relativ zum Viewport). Bei leerer Auswahl typischerweise mit `width` = 0 und der Zeilenhöhe als `height`.

Beispiele

Cursorposition in einem Canvas-Editor melden

const canvas = document.querySelector('#editor');
const ctx2d = canvas.getContext('2d');
ctx2d.font = '16px monospace';

const editContext = new EditContext();
canvas.editContext = editContext;

const LINE_HEIGHT = 20;
const PADDING = 10;

const reportSelection = () => {
  const text = editContext.text.slice(0, editContext.selectionStart);
  const x = PADDING + ctx2d.measureText(text).width;
  const rect = canvas.getBoundingClientRect();
  // Client-Koordinaten = Canvas-Position + lokale Position
  const bounds = new DOMRect(rect.left + x, rect.top + PADDING, 0, LINE_HEIGHT);
  editContext.updateSelectionBounds(bounds);
  console.log('Auswahl gemeldet:', bounds.x, bounds.y);
};

editContext.addEventListener('textupdate', reportSelection);

Auswahl gemeldet: 58.4 110

Auswahl und Control-Bounds bei Scroll und Resize aktualisieren

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

// Liefert das Rechteck der aktuellen Auswahl aus dem gerenderten DOM
const getSelectionRect = () => {
  const sel = window.getSelection();
  if (!sel.rangeCount) return editorEl.getBoundingClientRect();
  return sel.getRangeAt(0).getBoundingClientRect();
};

const syncBounds = () => {
  editContext.updateControlBounds(editorEl.getBoundingClientRect());
  editContext.updateSelectionBounds(getSelectionRect());
};

window.addEventListener('scroll', syncBounds, { passive: true });
window.addEventListener('resize', syncBounds);
document.addEventListener('selectionchange', syncBounds);
syncBounds();

Mit Feature-Erkennung absichern

const supportsEditContext = 'EditContext' in window;

if (supportsEditContext) {
  const el = document.querySelector('#editor');
  const editContext = new EditContext();
  el.editContext = editContext;
  const r = el.getBoundingClientRect();
  editContext.updateSelectionBounds(new DOMRect(r.left, r.top, 0, 18));
  console.log('EditContext aktiv');
} else {
  console.log('Fallback auf contenteditable');
}

EditContext aktiv

// Wichtig · Fallstricke

Experimentelle API: Bisher nur in Chromium-Browsern verfügbar (Chrome/Edge ab 121). Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit 'EditContext' in window und sieh einen Fallback vor, etwa contenteditable oder <textarea>.
Koordinatensystem: Die Werte müssen in Client-Koordinaten (Viewport) angegeben werden, nicht relativ zum Canvas oder zum Dokument. Rechne die Position des Elements aus getBoundingClientRect() immer mit ein.
Veraltete Werte: Der Browser berechnet die Grenzen nicht selbst neu. Wer nach Scrollen, Zoomen oder Layoutänderungen nicht erneut aufruft, bekommt falsch platzierte IME-Fenster.
Die Methode wirft einen TypeError, wenn kein DOMRect übergeben wird. Ein einfaches Objekt wie {x, y, width, height} reicht nicht.
Ergänzend sollten updateControlBounds() und, im Event characterboundsupdate, auch updateCharacterBounds() aufgerufen werden.

Siehe auch

EditContext.updateSelection() EditContext.updateControlBounds() EditContext.updateCharacterBounds() EditContext.characterBounds() EditContext.updateText()