Signatur
Beschreibung
Die Methode updateControlBounds() der Schnittstelle EditContext meldet dem Betriebssystem das Rechteck, das der bearbeitbare Textbereich auf dem Bildschirm einnimmt. Mit diesen Angaben können Eingabemethoden (IME) wie Kandidatenfenster für chinesische oder japanische Eingabe, Bildschirmtastaturen oder Handschrifterkennung ihre Oberfläche passend neben dem Eingabefeld anzeigen.
Gebraucht wird sie vor allem bei eigenen Editoren, die ihren Text selbst zeichnen, zum Beispiel in einem <canvas>. In diesem Fall weiß der Browser nicht, wo der Text sichtbar ist. Rufe die Methode nach dem Verbinden des EditContext mit einem Element auf. Danach immer dann, wenn sich Lage oder Größe des Elements ändert, etwa durch Scrollen, Größenänderung, Layoutwechsel oder einen Zoom.
Die Koordinaten beziehen sich auf den Viewport in CSS-Pixeln, genau wie die Werte von Element.getBoundingClientRect(). Für die Position der Einfügemarke bzw. der Auswahl gibt es die ergänzende Methode updateSelectionBounds(). Für die einzelnen Zeichen während einer Komposition gibt es updateCharacterBounds().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $controlBounds Pflicht | DOMRect | Ein DOMRect mit Position (x, y) und Größe (width, height) des bearbeitbaren Bereichs in Viewport-Koordinaten (CSS-Pixel). Meist liefert man direkt das Ergebnis von getBoundingClientRect(). |
Rückgabewert
undefined).Beispiele
Grenzen nach dem Verbinden mit einem Canvas melden
const canvas = document.querySelector('#editor');
if ('EditContext' in window) {
const editContext = new EditContext();
canvas.editContext = editContext;
// Aktuelle Position und Größe des Canvas an das Betriebssystem melden
const bounds = canvas.getBoundingClientRect();
editContext.updateControlBounds(bounds);
console.log('Control-Bounds gesetzt:', bounds.width, 'x', bounds.height);
} else {
console.warn('EditContext wird nicht unterstützt');
}Bei Größenänderung und Scrollen aktuell halten
const editor = document.querySelector('#editor');
const editContext = new EditContext();
editor.editContext = editContext;
const syncBounds = () => {
editContext.updateControlBounds(editor.getBoundingClientRect());
};
// Beim Ändern der Elementgröße
new ResizeObserver(syncBounds).observe(editor);
// Beim Scrollen verschiebt sich die Viewport-Position
window.addEventListener('scroll', syncBounds, { passive: true });
// Beim Ändern der Fenstergröße
window.addEventListener('resize', syncBounds);
syncBounds();Zusammen mit Selection-Bounds im characterboundsupdate-Kontext
const canvas = document.querySelector('canvas');
const editContext = new EditContext({ text: 'Hallo' });
canvas.editContext = editContext;
const caretRect = (index) => {
const r = canvas.getBoundingClientRect();
const charWidth = 10; // vereinfachtes Monospace-Layout
return new DOMRect(r.x + 8 + index * charWidth, r.y + 8, 1, 18);
};
canvas.addEventListener('focus', () => {
editContext.updateControlBounds(canvas.getBoundingClientRect());
editContext.updateSelectionBounds(caretRect(editContext.selectionEnd));
});// Wichtig · Fallstricke
Kompatibilität: Die EditContext-API ist experimentell. Sie gibt es bisher nur in Chromium-Browsern (Chrome und Edge ab Version 121). Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer vorher mit 'EditContext' in window.
- Die Werte veralten nicht automatisch. Wer nach Scrollen, Zoom oder Layoutänderungen nicht neu meldet, bekommt falsch platzierte IME-Fenster.
- Erwartet werden Viewport-Koordinaten und keine Dokument-Koordinaten. Addiere also nicht
scrollX/scrollY. - Übergib ein
DOMRect. Andere Objekte führen zu einemTypeError. - Rufe die Methode bei Scroll-Ereignissen nicht übermäßig oft auf. Bei Bedarf mit
requestAnimationFramebündeln. - Die Methode ersetzt
updateSelectionBounds()nicht. Für eine gute IME-Platzierung sollten beide aufgerufen werden.