Signatur
Beschreibung
CompositionEvent steht für Ereignisse, die ausgelöst werden, wenn jemand Text nicht direkt Zeichen für Zeichen eintippt, sondern schrittweise über einen Eingabemethoden-Editor (IME) zusammensetzt. Typische Fälle sind japanische, chinesische oder koreanische Tastaturen, Tottasten für Akzentzeichen (etwa ´ + e → é), Sprach- und Handschrifteingabe sowie manche mobilen Tastaturen mit Wortvorschlägen.
Zum Interface gehören drei Ereignistypen:
compositionstart: Eine neue Komposition beginnt.compositionupdate: Ein Zeichen wurde zur laufenden Komposition hinzugefügt oder daraus entfernt.compositionend: Die Komposition ist abgeschlossen oder wurde abgebrochen.
Die wichtigste Eigenschaft ist data. Sie enthält den aktuell zusammengesetzten Text. Bei compositionend ist das der endgültig übernommene Text. Über die veraltete Eigenschaft locale ließ sich früher die Sprache der Eingabemethode abfragen. Von UIEvent und Event erbt das Interface Eigenschaften wie view, detail, target und type.
In der Praxis braucht man CompositionEvent vor allem, damit Live-Suche, Autovervollständigung, Zeichenzähler oder Tastenkürzel nicht mitten in einer IME-Eingabe auslösen. Solange eine Komposition läuft, ist der Text im Feld nur ein Zwischenstand. Mit InputEvent.isComposing oder KeyboardEvent.isComposing lässt sich außerdem prüfen, ob gerade eine Komposition aktiv ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Name des Ereignisses beim Konstruktoraufruf new CompositionEvent(type, options): "compositionstart", "compositionupdate" oder "compositionend". |
|
| $options | object | {} | Optionales Wörterbuch (CompositionEventInit). Neben den UIEventInit-Feldern (bubbles, cancelable, composed, view, detail) gibt es data (string, Standard "") mit dem Anfangswert der Eigenschaft data. |
Rückgabewert
CompositionEvent-Objekt. Die schreibgeschützte Eigenschaft data (string) enthält den zusammengesetzten Text.Beispiele
Kompositionsphasen protokollieren
const input = document.querySelector('#name');
const log = (event) => {
// event ist ein CompositionEvent
console.log(`${event.type}: "${event.data}"`);
};
input.addEventListener('compositionstart', log);
input.addEventListener('compositionupdate', log);
input.addEventListener('compositionend', log);Live-Suche erst nach abgeschlossener IME-Eingabe starten
const search = document.querySelector('#search');
let composing = false;
const runSearch = async (term) => {
if (!term.trim()) return;
const res = await fetch(`/api/search?q=${encodeURIComponent(term)}`);
const hits = await res.json();
console.log(`${hits.length} Treffer für "${term}"`);
};
search.addEventListener('compositionstart', () => { composing = true; });
search.addEventListener('compositionend', (event) => {
composing = false;
// Endgültigen Text übernehmen
runSearch(search.value);
});
search.addEventListener('input', (event) => {
// Zwischenstände der IME ignorieren
if (composing || event.isComposing) return;
runSearch(search.value);
});Enter-Taste während der Komposition nicht als Absenden werten
const chat = document.querySelector('#chat-input');
chat.addEventListener('keydown', (event) => {
// Enter bestätigt bei aktiver IME nur die Zeichenauswahl
if (event.key === 'Enter' && !event.isComposing && event.keyCode !== 229) {
event.preventDefault();
console.log('Nachricht senden:', chat.value);
chat.value = '';
}
});CompositionEvent synthetisch erzeugen (z. B. für Tests)
const field = document.createElement('input');
field.addEventListener('compositionend', (e) => {
console.log(e instanceof CompositionEvent, e.data);
});
const event = new CompositionEvent('compositionend', {
data: 'Grüße',
bubbles: true
});
field.dispatchEvent(event);// Wichtig · Fallstricke
- Reihenfolge der Ereignisse: Sie ist nicht in allen Browsern gleich. In Chrome und Edge kommt das letzte
input-Ereignis meist vorcompositionend. Safari kanncompositionendvor dem zugehörigenkeydownauslösen. Verlassen Sie sich deshalb nicht allein auf ein einzelnes Flag, sondern prüfen Sie zusätzlichevent.isComposing. - Safari und Enter: Bei Safari ist
isComposingimkeydownder bestätigenden Enter-Taste oft schonfalse. Die zusätzliche Prüfung aufkeyCode === 229ist deshalb ein verbreiteter Ausweg.keyCodeist allerdings veraltet. - Nicht abbrechbar:
compositionupdateundcompositionendsind nicht abbrechbar. ObpreventDefault()beicompositionstartwirkt, hängt vom Browser ab. Eine IME-Eingabe lässt sich damit also nicht zuverlässig unterbinden. Zum Filtern eignet sich eherbeforeinput. - Veraltet:
localeundinitCompositionEvent()sind veraltet. Nutzen Sie stattdessen den Konstruktornew CompositionEvent(). - Nur in bearbeitbaren Elementen: Die Ereignisse treten nur in
<input>,<textarea>und beicontenteditableauf. - Synthetische Ereignisse: Selbst erzeugte Ereignisse (
isTrusted === false) ändern den Feldinhalt nicht. Sie lösen nur die registrierten Handler aus. - Kompatibilität: In allen aktuellen Browsern verfügbar. Auf mobilen Tastaturen, etwa Android mit Wortvorschlägen, können Kompositionsereignisse auch bei lateinischer Schrift auftreten.