EditContext: compositionend — Ereignis · JavaScript-Referenz

Signatur

editContext.addEventListener("compositionend", handler)

Beschreibung

Das Ereignis compositionend der Schnittstelle EditContext wird ausgelöst, wenn eine Komposition über einen Input Method Editor (IME) endet. IMEs werden zum Beispiel für Chinesisch, Japanisch oder Koreanisch verwendet. Dabei werden mehrere Tastenanschläge zu einem Zeichen zusammengesetzt. Die Komposition endet, wenn der Nutzer den Kandidaten bestätigt, das IME-Fenster schließt oder den Fokus wechselt.

Die EditContext-API ist für eigene Editoren gedacht, die ihren Text selbst darstellen, etwa auf einem <canvas> oder in einem selbst verwalteten DOM. Ein Element mit zugewiesenem editContext bekommt Texteingaben als Ereignisse am EditContext geliefert. compositionend ist das Gegenstück zu compositionstart. Typischerweise entfernt man hier die Hervorhebung des vorläufigen Textes (z. B. eine Unterstreichung), die man während der Komposition über textformatupdate gezeichnet hat.

Das Ereignis-Objekt ist ein CompositionEvent. Die Eigenschaft data enthält den zuletzt komponierten Text. Den eigentlichen Textinhalt pflegt der EditContext aber schon über textupdate. Zum Einfügen von Text braucht man compositionend deshalb nicht, es dient vor allem dazu, Zustand und Darstellung zu aktualisieren.

Als Handler registriert man entweder addEventListener("compositionend", …) oder die Eigenschaft editContext.oncompositionend.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"compositionend"`.
$handler Pflicht	(event: CompositionEvent) => void		Callback, der ein `CompositionEvent` erhält. `event.data` enthält den komponierten Text.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal` zum späteren Entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein CompositionEvent.

Beispiele

Kompositionsstatus mit addEventListener verfolgen

const editor = document.querySelector('#editor');
const editContext = new EditContext();
editor.editContext = editContext;

let isComposing = false;

editContext.addEventListener('compositionstart', () => {
  isComposing = true;
  editor.classList.add('composing');
});

editContext.addEventListener('compositionend', (event) => {
  isComposing = false;
  editor.classList.remove('composing');
  console.log('Komposition beendet:', event.data);
});

Komposition beendet: 日本

Unterstreichung auf dem Canvas nach dem Ende der Komposition entfernen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const editContext = new EditContext();
canvas.editContext = editContext;

let formats = [];

const render = () => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.font = '20px sans-serif';
  ctx.fillText(editContext.text, 10, 30);
  // Unterstreichungen für den vorläufigen IME-Text
  for (const f of formats) {
    const x1 = 10 + ctx.measureText(editContext.text.slice(0, f.rangeStart)).width;
    const x2 = 10 + ctx.measureText(editContext.text.slice(0, f.rangeEnd)).width;
    ctx.fillRect(x1, 34, x2 - x1, 2);
  }
};

editContext.addEventListener('textupdate', render);
editContext.addEventListener('textformatupdate', (e) => {
  formats = e.getTextFormats();
  render();
});
editContext.addEventListener('compositionend', () => {
  formats = []; // Hervorhebung entfernen
  render();
});

Handler über oncompositionend setzen und wieder entfernen

const editContext = new EditContext();
document.querySelector('#editor').editContext = editContext;

editContext.oncompositionend = (event) => {
  console.log(`IME-Eingabe abgeschlossen (${event.data.length} Zeichen)`);
};

// Später wieder entfernen
setTimeout(() => {
  editContext.oncompositionend = null;
}, 60_000);

IME-Eingabe abgeschlossen (2 Zeichen)

// Wichtig · Fallstricke

Browser-Unterstützung: Die EditContext-API ist experimentell. Sie gibt es nur in Chromium-Browsern ab Version 121, nicht in Firefox und Safari. Deshalb vorher die Unterstützung prüfen: if ('EditContext' in window) { … }. Andernfalls auf contenteditable oder <textarea> zurückfallen.
Das Ereignis wird am EditContext ausgelöst, nicht am zugehörigen Element. Ein Listener am Element (element.addEventListener('compositionend', …)) bekommt diese Kompositionsereignisse nicht.
Text nicht in compositionend einfügen: Der Text ist schon über textupdate in editContext.text angekommen. Wer ihn hier noch einmal einfügt, hat ihn doppelt.
event.data kann leer sein, etwa wenn die Komposition abgebrochen wurde (Escape, Fokusverlust).
Reihenfolge und Anzahl der Ereignisse hängen von IME und Betriebssystem ab. Man sollte sich also nicht auf eine genaue Abfolge von textupdate und compositionend verlassen.

Siehe auch

EditContext EditContext: compositionstart EditContext: textupdate EditContext: textformatupdate CompositionEvent Element: compositionend HTMLMediaElement: waitingforkey