new CharacterBoundsUpdateEvent() — Methode · JavaScript-Referenz

Signatur

new CharacterBoundsUpdateEvent(type, options)

Beschreibung

Der Konstruktor CharacterBoundsUpdateEvent() erzeugt ein Ereignisobjekt vom Typ CharacterBoundsUpdateEvent. Es gehört zur EditContext-API. Mit dieser API bauen Entwickler eigene Texteditoren, etwa auf Basis von <canvas>, und binden trotzdem das Texteingabesystem des Betriebssystems an (IME, Diktierfunktion, Bildschirmtastatur).

Normalerweise löst der Browser das Ereignis characterboundsupdate selbst auf einem EditContext aus. Das passiert, wenn das Betriebssystem die Bildschirmpositionen bestimmter Zeichen braucht, zum Beispiel um ein IME-Kandidatenfenster direkt an der Einfügemarke anzuzeigen. Die Eigenschaften rangeStart und rangeEnd geben an, für welche Zeichen die Anwendung mit EditContext.updateCharacterBounds() die Begrenzungsrechtecke liefern soll.

Selbst ruft man den Konstruktor vor allem in Tests und Simulationen auf. So lässt sich prüfen, ob der eigene characterboundsupdate-Handler richtig rechnet, ohne dass eine echte IME-Eingabe nötig ist.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Wird Groß-/Kleinschreibung beachtend behandelt. Der Browser verwendet immer `"characterboundsupdate"`.
$options	object	{}	Optionales Objekt. Zusätzlich zu den Feldern von `EventInit` (`bubbles`, `cancelable`, `composed`) enthält es: `rangeStart` (`number`, Standard `0`): Index des ersten Zeichens im Text des `EditContext`, dessen Begrenzungsrechteck angefordert wird. `rangeEnd` (`number`, Standard `0`): Index direkt nach dem letzten angeforderten Zeichen (exklusiv).

Rückgabewert

Typ

CharacterBoundsUpdateEvent

Beschreibung

Ein neues CharacterBoundsUpdateEvent-Objekt mit den übergebenen Werten für rangeStart und rangeEnd.

Beispiele

Ereignis erzeugen und Eigenschaften lesen

if ('CharacterBoundsUpdateEvent' in window) {
  const event = new CharacterBoundsUpdateEvent('characterboundsupdate', {
    rangeStart: 3,
    rangeEnd: 7
  });

  console.log(event.type, event.rangeStart, event.rangeEnd, event.isTrusted);
} else {
  console.log('EditContext-API wird nicht unterstützt');
}

characterboundsupdate 3 7 false

Handler für echte Anfragen des Browsers

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

// Monospace-Annahme: jedes Zeichen 10px breit, 20px hoch
const CHAR_WIDTH = 10;
const LINE_HEIGHT = 20;

editContext.addEventListener('characterboundsupdate', (e) => {
  const canvasRect = canvas.getBoundingClientRect();
  const bounds = [];
  for (let i = e.rangeStart; i < e.rangeEnd; i++) {
    bounds.push(new DOMRect(
      canvasRect.x + i * CHAR_WIDTH,
      canvasRect.y,
      CHAR_WIDTH,
      LINE_HEIGHT
    ));
  }
  // Positionen an das Betriebssystem/IME melden
  editContext.updateCharacterBounds(e.rangeStart, bounds);
});

Handler im Test mit synthetischem Ereignis prüfen

const editContext = new EditContext({ text: 'Beispieltext' });

editContext.addEventListener('characterboundsupdate', (e) => {
  const count = e.rangeEnd - e.rangeStart;
  console.log(`Angefordert: ${count} Zeichen ab Index ${e.rangeStart}`);
  const text = editContext.text.slice(e.rangeStart, e.rangeEnd);
  console.log(`Betroffener Text: "${text}"`);
});

editContext.dispatchEvent(
  new CharacterBoundsUpdateEvent('characterboundsupdate', {
    rangeStart: 0,
    rangeEnd: 8
  })
);

Angefordert: 8 Zeichen ab Index 0 Betroffener Text: "Beispiel"

// Wichtig · Fallstricke

Experimentelle API: CharacterBoundsUpdateEvent und EditContext gibt es derzeit nur in Chromium-basierten Browsern (Chrome/Edge ab Version 121). Prüfe die Unterstützung vorher, etwa mit 'EditContext' in window.
Selbst erzeugte Ereignisse haben isTrusted === false. Sie lösen keine Anfrage beim Betriebssystem aus und eignen sich nur zum Testen der eigenen Handler-Logik.
rangeEnd ist exklusiv. Die Anzahl der Zeichen ist also rangeEnd - rangeStart. Das Array für updateCharacterBounds() muss genau so viele DOMRect-Einträge haben.
Die Rechtecke müssen in Viewport-Koordinaten angegeben werden, also relativ zum sichtbaren Fensterausschnitt und nicht zum Canvas. Wenn gescrollt oder das Layout verschoben wird, müssen sie neu berechnet werden.
Ohne den Aufruf new wirft der Konstruktor einen TypeError.

Siehe auch

new BackgroundFetchUpdateUIEvent() new PaymentRequestUpdateEvent() new TextFormatUpdateEvent() new TextUpdateEvent() new BackgroundFetchEvent()