CompositionEvent.initCompositionEvent() — Methode · JavaScript-Referenz

Signatur

CompositionEvent.prototype.initCompositionEvent(type, canBubble, cancelable, view, data, locale)

Beschreibung

initCompositionEvent() belegt die Attribute eines CompositionEvent-Objekts nachträglich mit Werten. Die Methode stammt aus der Zeit, bevor Event-Konstruktoren eingeführt wurden. Damals erzeugte man ein leeres Ereignisobjekt mit document.createEvent("CompositionEvent") und initialisierte es anschließend mit dieser Methode, bevor man es mit dispatchEvent() auslöste.

Composition-Events (compositionstart, compositionupdate, compositionend) entstehen bei der Texteingabe über einen Eingabemethoden-Editor (IME). Das ist zum Beispiel bei Chinesisch, Japanisch oder Koreanisch der Fall, außerdem bei Akzent-Kombinationen oder bei der Spracheingabe. Synthetische Composition-Events braucht man vor allem in Tests, etwa um das Verhalten eines Editors oder einer Autovervollständigung bei IME-Eingaben nachzustellen.

Die Methode ist veraltet. In neuem Code solltest du stattdessen den Konstruktor new CompositionEvent(type, options) verwenden. Er ist kürzer, besser lesbar und erlaubt es, alle Eigenschaften in einem Schritt zu setzen. initCompositionEvent() ist nur noch für älteren Code oder sehr alte Browser relevant.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"compositionstart"`, `"compositionupdate"` oder `"compositionend"`.
$canBubble Pflicht	boolean		Gibt an, ob das Ereignis im DOM nach oben weitergereicht wird (Bubbling). Wird in `event.bubbles` gespeichert.
$cancelable Pflicht	boolean		Gibt an, ob das Ereignis mit `preventDefault()` abgebrochen werden kann. Wird in `event.cancelable` gespeichert.
$view Pflicht	Window \| null		Das `Window`, zu dem das Ereignis gehört, meist `window`. Wird in `event.view` gespeichert.
$data Pflicht	string		Der aktuelle Kompositionstext. Wird in `event.data` gespeichert.
$locale	string	""	Sprachkennung der Eingabemethode, z. B. `"ja-JP"`. Nicht standardisiert und nicht in allen Browsern unterstützt (Chrome ignoriert den Parameter).

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Das Ereignisobjekt wird direkt verändert.

Beispiele

Klassische Initialisierung mit createEvent

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

input.addEventListener('compositionend', (e) => {
  console.log(`IME-Eingabe abgeschlossen: ${e.data}`);
});

// Leeres Ereignisobjekt erzeugen und anschließend initialisieren
const evt = document.createEvent('CompositionEvent');
evt.initCompositionEvent('compositionend', true, false, window, '東京', 'ja-JP');

input.dispatchEvent(evt);

IME-Eingabe abgeschlossen: 東京

Moderne Alternative: der CompositionEvent-Konstruktor

const editor = document.querySelector('[contenteditable]');

editor.addEventListener('compositionupdate', (e) => {
  console.log('Zwischenstand:', e.data);
});

// Empfohlen: alle Eigenschaften in einem Schritt setzen
const evt = new CompositionEvent('compositionupdate', {
  bubbles: true,
  cancelable: false,
  data: 'にほ'
});

editor.dispatchEvent(evt);

Zwischenstand: にほ

Hilfsfunktion mit Fallback für Tests

const createCompositionEvent = (type, data) => {
  if (typeof CompositionEvent === 'function') {
    try {
      return new CompositionEvent(type, { bubbles: true, data });
    } catch {
      // Sehr alte Browser ohne Konstruktor-Unterstützung
    }
  }
  const evt = document.createEvent('CompositionEvent');
  evt.initCompositionEvent(type, true, false, window, data, '');
  return evt;
};

// IME-Sequenz in einem Test nachstellen
const field = document.querySelector('input');
['compositionstart', 'compositionupdate', 'compositionend'].forEach((type) => {
  field.addEventListener(type, (e) => console.log(type, JSON.stringify(e.data)));
});

field.dispatchEvent(createCompositionEvent('compositionstart', ''));
field.dispatchEvent(createCompositionEvent('compositionupdate', 'ka'));
field.dispatchEvent(createCompositionEvent('compositionend', 'か'));

compositionstart "" compositionupdate "ka" compositionend "か"

// Wichtig · Fallstricke

Veraltet: Verwende in neuem Code new CompositionEvent(). Browser können initCompositionEvent() künftig entfernen.
Nach dem Auslösen wirkungslos: Wird die Methode aufgerufen, nachdem das Ereignis bereits mit dispatchEvent() ausgelöst wurde, hat sie keine Wirkung.
locale uneinheitlich: Chrome und Safari kennen den sechsten Parameter nicht und haben keine Eigenschaft event.locale. Verlass dich nicht auf diesen Wert.
Nicht vertrauenswürdig: Synthetische Ereignisse haben isTrusted === false. Sie fügen keinen Text in Eingabefelder ein und lösen keine echte IME-Eingabe aus. Es werden nur die registrierten Listener aufgerufen.
Die Parameter müssen in der vorgegebenen Reihenfolge übergeben werden. Ein vergessenes Argument verschiebt alle folgenden Werte. Auch das spricht für den Konstruktor mit Options-Objekt.

Siehe auch

CompositionEvent CompositionEvent.data Document.createEvent() EventTarget.dispatchEvent() UIEvent.initUIEvent()