CompositionEvent.data — Eigenschaft · JavaScript-Referenz

Signatur

CompositionEvent.data

Beschreibung

Die schreibgeschützte Eigenschaft data eines CompositionEvent enthält den Text, den eine Eingabemethode (Input Method Editor, IME) gerade erzeugt. Das betrifft etwa die Eingabe chinesischer, japanischer oder koreanischer Schriftzeichen, Bildschirmtastaturen auf Mobilgeräten mit Wortvorschlägen, Spracheingabe oder das Zusammensetzen von Akzentzeichen mit Tottasten.

Was in data steht, hängt vom Ereignistyp ab:

compositionstart: der Text, der beim Start der Komposition markiert ist und ersetzt wird – meist ein leerer String.
compositionupdate: der aktuelle, noch nicht bestätigte Kompositionstext (z. B. "にほ" während der Eingabe von „nihon“).
compositionend: der endgültig bestätigte Text, der ins Eingabefeld übernommen wird (z. B. "日本"), oder ein leerer String, wenn die Komposition abgebrochen wurde.

In der Praxis braucht man data vor allem dann, wenn Eingaben in Echtzeit verarbeitet werden – Live-Suche, Zeichenzähler, Autovervollständigung oder eigene Editoren. Solche Logik sollte während einer laufenden Komposition pausieren und erst bei compositionend mit dem bestätigten Text aus data weiterarbeiten. So vermeidet man, dass unfertige Zwischenstände (etwa lateinische Umschrift oder halbe Hangul-Silben) Suchanfragen oder Validierungen auslösen.

Rückgabewert

Typ

string

Beschreibung

Die von der Eingabemethode erzeugten bzw. bestätigten Zeichen. Kann ein leerer String sein (typisch bei compositionstart oder bei abgebrochener Komposition).

Beispiele

Kompositionsphasen protokollieren

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

const log = (event) => {
  console.log(`${event.type}: "${event.data}"`);
};

input.addEventListener('compositionstart', log);
input.addEventListener('compositionupdate', log);
input.addEventListener('compositionend', log);

// Japanische IME, Eingabe „nihon“ + Umwandlung: compositionstart: "" compositionupdate: "n" compositionupdate: "に" compositionupdate: "にほ" compositionupdate: "にほん" compositionupdate: "日本" compositionend: "日本"

Live-Suche erst nach bestätigter IME-Eingabe auslösen

const suchfeld = document.querySelector('#suche');
let komponiert = false;

const suche = async (begriff) => {
  if (!begriff.trim()) return;
  const res = await fetch(`/api/suche?q=${encodeURIComponent(begriff)}`);
  const treffer = await res.json();
  console.log('Treffer:', treffer.length);
};

suchfeld.addEventListener('compositionstart', () => {
  komponiert = true;
});

suchfeld.addEventListener('compositionend', (event) => {
  komponiert = false;
  console.log('Bestätigt:', event.data);
  suche(suchfeld.value);
});

suchfeld.addEventListener('input', (event) => {
  // Zwischenstände der IME ignorieren
  if (komponiert || event.isComposing) return;
  suche(suchfeld.value);
});

Bestätigt: 東京 Treffer: 12

Vorschau des Kompositionstexts anzeigen

const editor = document.querySelector('#editor');
const vorschau = document.querySelector('#vorschau');

editor.addEventListener('compositionupdate', (event) => {
  vorschau.textContent = `Wird eingegeben: ${event.data}`;
});

editor.addEventListener('compositionend', (event) => {
  vorschau.textContent = event.data
    ? `Übernommen: ${event.data}`
    : 'Eingabe abgebrochen';
});

Wird eingegeben: 한 Übernommen: 한국

Synthetisches CompositionEvent erzeugen (z. B. für Tests)

const feld = document.createElement('input');

feld.addEventListener('compositionend', (event) => {
  console.log('data =', event.data, '| schreibgeschützt:', !Object.getOwnPropertyDescriptor(CompositionEvent.prototype, 'data').set);
});

const ev = new CompositionEvent('compositionend', { data: 'テスト', bubbles: true });
feld.dispatchEvent(ev);

data = テスト | schreibgeschützt: true

// Wichtig · Fallstricke

Schreibgeschützt: data lässt sich nach dem Erzeugen nicht ändern. Den Wert für synthetische Ereignisse setzt man über das Options-Objekt von new CompositionEvent(type, { data }).
Nicht für die Eingabeprüfung verwenden: data spiegelt nur die Komposition wider, nicht den gesamten Feldinhalt. Für den tatsächlichen Wert immer input.value bzw. den DOM-Inhalt lesen.
Browser-Unterschiede: Die Reihenfolge von compositionend und dem letzten input-Ereignis unterscheidet sich zwischen den Engines (Chrome feuert input vor compositionend, ältere Safari-Versionen auch umgekehrt). Auch der Inhalt von data bei compositionstart ist nicht überall gleich. Bei Android-Tastaturen kann schon normales Tippen lateinischer Buchstaben Kompositionsereignisse auslösen (Wortvorschläge).
Abbruch: Bricht der Nutzer die Komposition ab (z. B. mit Esc), liefert compositionend meist einen leeren String – das sollte der Code berücksichtigen.
Alternative: InputEvent.isComposing und KeyboardEvent.isComposing zeigen an, ob gerade eine Komposition läuft. Bei keydown während der Komposition melden viele Browser keyCode 229.
Die Eigenschaft wird von allen modernen Browsern unterstützt. Die früher vorhandene Eigenschaft locale ist veraltet und sollte nicht mehr genutzt werden.

Siehe auch

CompositionEvent.locale InputEvent.data MessageEvent.data PushEvent.data BlobEvent.data