Element: compositionstart — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("compositionstart", handler)

Beschreibung

Das Ereignis compositionstart wird ausgelöst, wenn der Nutzer mit einem Input-Method-Editor (IME) anfängt, Text zusammenzusetzen. Das passiert zum Beispiel bei der Eingabe von Chinesisch, Japanisch oder Koreanisch, bei Akzentzeichen über Tottasten (etwa ´ + e → é) sowie bei Spracheingabe oder Handschrift auf Mobilgeräten. Die Sitzung läuft danach über compositionupdate weiter und endet mit compositionend.

Man nutzt das Ereignis vor allem, um Logik während der Komposition auszusetzen. Dazu gehören Live-Suche, Autovervollständigung, Eingabevalidierung und Tastenkürzel wie „Enter sendet“. Solange die Komposition läuft, ist der Text im Feld nur vorläufig. Wer ihn in dieser Phase verarbeitet, bekommt halbfertige Zeichenfolgen.

Das Ereignisobjekt ist ein CompositionEvent. Seine Eigenschaft data enthält bei compositionstart den Text, den die Komposition ersetzen wird, also die aktuelle Auswahl. Ohne Auswahl ist sie meist ein leerer String. Das Ereignis steigt im DOM auf (bubbles: true), lässt sich aber laut Spezifikation nicht abbrechen. Es gibt auch die Handler-Eigenschaft oncompositionstart, allerdings nicht in jedem Browser (siehe Hinweise). Deshalb ist addEventListener der empfohlene Weg.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"compositionstart"`.
$handler Pflicht	(event: CompositionEvent) => void		Die Callback-Funktion. Sie erhält ein `CompositionEvent` mit den Eigenschaften `data` (der zu ersetzende Text) und `locale` (veraltet).
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Einstellungen wie `capture`, `once`, `passive` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein CompositionEvent.

Beispiele

Kompositionsbeginn protokollieren

const input = document.querySelector('#name');

input.addEventListener('compositionstart', (event) => {
  console.log('Komposition gestartet, ersetzt:', JSON.stringify(event.data));
});

input.addEventListener('compositionend', (event) => {
  console.log('Komposition beendet, Ergebnis:', event.data);
});

Komposition gestartet, ersetzt: "" Komposition beendet, Ergebnis: 日本

Live-Suche während der IME-Eingabe pausieren

const search = document.querySelector('#search');
let composing = false;

const runSearch = (term) => console.log('Suche nach:', term);

search.addEventListener('compositionstart', () => {
  composing = true;
});

search.addEventListener('compositionend', (event) => {
  composing = false;
  runSearch(event.target.value); // erst jetzt ist der Text endgültig
});

search.addEventListener('input', (event) => {
  // event.isComposing wird zusätzlich geprüft, weil es der verlässlichere Weg ist
  if (composing || event.isComposing) return;
  runSearch(event.target.value);
});

Suche nach: 東京

Enter zum Senden – aber nicht beim Bestätigen im IME

const chat = document.querySelector('#chat-input');
const send = (text) => console.log('Gesendet:', text);

chat.addEventListener('keydown', (event) => {
  // Enter bestätigt während einer Komposition nur die IME-Auswahl
  if (event.key === 'Enter' && !event.isComposing && event.keyCode !== 229) {
    event.preventDefault();
    send(chat.value);
    chat.value = '';
  }
});

chat.addEventListener('compositionstart', () => {
  chat.classList.add('is-composing');
});
chat.addEventListener('compositionend', () => {
  chat.classList.remove('is-composing');
});

Gesendet: こんにちは

Handler über oncompositionstart setzen und entfernen

const field = document.querySelector('textarea');

const onStart = () => console.log('IME aktiv');

// Variante 1: addEventListener / removeEventListener
field.addEventListener('compositionstart', onStart);
field.removeEventListener('compositionstart', onStart);

// Variante 2: Handler-Eigenschaft (nicht in jedem Browser vorhanden)
if ('oncompositionstart' in field) {
  field.oncompositionstart = onStart;
  field.oncompositionstart = null; // wieder entfernen
}

// Wichtig · Fallstricke

Nicht abbrechbar: event.preventDefault() in compositionstart verhindert die Komposition nicht. Den IME kann man nicht per Skript blockieren.
Handler-Eigenschaft: oncompositionstart fehlt in manchen Browsern als Attribut bzw. Eigenschaft (in Chrome und Edge etwa ist sie nicht vorhanden). Verwenden Sie daher addEventListener.
Reihenfolge der Ereignisse ist uneinheitlich: Chrome und Safari feuern input auch während der Komposition, mit isComposing: true. Die Reihenfolge von compositionend und dem letzten input unterscheidet sich zwischen den Browsern. Prüfen Sie am besten sowohl event.isComposing als auch ein eigenes Flag.
Safari/Enter-Falle: In Safari kann keydown für die bestätigende Enter-Taste nach compositionend kommen, sodass isComposing dann false ist. Zusätzlich auf keyCode === 229 zu prüfen, ist ein verbreiteter Workaround.
Mobilgeräte: Android-Tastaturen mit Wortvorschlägen starten oft auch bei lateinischer Schrift eine Komposition, teils schon für jedes Wort. Code, der Eingaben während einer Komposition ignoriert, muss auf compositionend reagieren, sonst verarbeitet er dort gar keine Eingaben.
Das Ereignis tritt nur bei bearbeitbaren Elementen auf (<input>, <textarea>, contenteditable).

Siehe auch

Element: compositionend Element: compositionupdate Element: transitionstart Element: animationstart Element: gesturestart