new CompositionEvent() — Methode · JavaScript-Referenz

Signatur

new CompositionEvent(type, options)

Beschreibung

Mit new CompositionEvent() erzeugen Sie ein synthetisches Kompositions-Event. Solche Events feuert der Browser normalerweise selbst, wenn Nutzer Text über einen Input Method Editor (IME) eingeben, etwa bei Japanisch, Chinesisch oder Koreanisch, bei Akzentzeichen über Tottasten oder bei der Spracheingabe. Es gibt drei Event-Typen: compositionstart, compositionupdate und compositionend.

Den Konstruktor brauchen Sie vor allem für automatisierte Tests und für Komponenten-Bibliotheken, zum Beispiel für Editoren, Autovervollständigung oder Eingabemasken. Damit prüfen Sie, ob Ihr Code eine laufende Komposition richtig erkennt und z. B. Tastenkürzel oder die Validierung erst nach compositionend ausführt.

Das Ergebnis ist ein normales DOM-Event. Sie lösen es mit EventTarget.dispatchEvent() aus. Es hat isTrusted === false und verändert nicht den Inhalt eines Eingabefelds. Den Text müssen Sie in Tests selbst setzen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Events, üblicherweise `"compositionstart"`, `"compositionupdate"` oder `"compositionend"`. Groß- und Kleinschreibung zählt.
$options	CompositionEventInit	{}	Optionales Objekt. Es erbt alle Felder von `UIEventInit` und `EventInit`: `data` (`string`, Standard `""`): der Kompositionstext, wird zu `event.data` `bubbles` (`boolean`, Standard `false`) `cancelable` (`boolean`, Standard `false`) `composed` (`boolean`, Standard `false`): legt fest, ob das Event die Shadow-DOM-Grenze überquert `view` (`Window \| null`, Standard `null`) `detail` (`number`, Standard `0`)

Rückgabewert

Typ

CompositionEvent

Beschreibung

Ein neues CompositionEvent-Objekt mit den übergebenen Werten. isTrusted ist dabei immer false.

Beispiele

Event erzeugen und Eigenschaften lesen

const evt = new CompositionEvent('compositionupdate', {
  data: 'にほ',
  bubbles: true
});

console.log(evt.type);      // Event-Typ
console.log(evt.data);      // Kompositionstext
console.log(evt.bubbles);
console.log(evt.isTrusted); // synthetisch

compositionupdate にほ true false

IME-Eingabe im Test simulieren

const input = document.createElement('input');
document.body.append(input);

let composing = false;
input.addEventListener('compositionstart', () => { composing = true; });
input.addEventListener('compositionend', (e) => {
  composing = false;
  console.log(`Fertig komponiert: ${e.data}`);
});

// Ablauf nachbilden
input.dispatchEvent(new CompositionEvent('compositionstart', { data: '' }));
console.log('Komposition aktiv:', composing);
input.value = '日本';
input.dispatchEvent(new CompositionEvent('compositionend', { data: '日本' }));
console.log('Komposition aktiv:', composing);

Komposition aktiv: true Fertig komponiert: 日本 Komposition aktiv: false

Enter-Taste während der Komposition ignorieren

const search = document.createElement('input');
document.body.append(search);

let isComposing = false;
search.addEventListener('compositionstart', () => (isComposing = true));
search.addEventListener('compositionend', () => (isComposing = false));

search.addEventListener('keydown', (e) => {
  // Enter bestätigt hier nur die IME-Auswahl, nicht die Suche
  if (e.key === 'Enter' && !isComposing && !e.isComposing) {
    console.log('Suche gestartet:', search.value);
  }
});

search.dispatchEvent(new CompositionEvent('compositionstart'));
search.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter' }));
search.dispatchEvent(new CompositionEvent('compositionend', { data: '東京' }));
search.value = '東京';
search.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter' }));

Suche gestartet: 東京

// Wichtig · Fallstricke

Keine echte Eingabe: Ein selbst ausgelöstes CompositionEvent ändert weder value noch den Inhalt von contenteditable. Es löst auch keine input- oder beforeinput-Events aus. Wenn Ihr Code darauf reagiert, müssen Sie diese Events im Test selbst erzeugen.
Standardwert von bubbles: Ohne bubbles: true erreicht das Event keine Listener auf Elternelementen. Das betrifft auch Event-Delegation, etwa auf document. Echte Browser-Events steigen dagegen auf.
isTrusted ist immer false: Code, der nur vertrauenswürdige Events akzeptiert, ignoriert synthetische Events.
Veraltete Variante: document.createEvent('CompositionEvent') mit initCompositionEvent() ist veraltet. Verwenden Sie den Konstruktor.
Kompatibilität: Der Konstruktor ist in allen modernen Browsern verfügbar, im Internet Explorer nicht. jsdom unterstützt ihn in aktuellen Versionen. In Node.js gibt es ihn ohne DOM-Umgebung nicht.
Die Reihenfolge von Kompositions- und Tastatur-Events unterscheidet sich je nach Browser und Betriebssystem. Prüfen Sie im keydown-Handler zusätzlich KeyboardEvent.isComposing.

Siehe auch

new TransitionEvent() new AnimationEvent() new CSSPositionValue() new CustomEvent() new NotificationEvent()