KeyboardEvent.isComposing — Eigenschaft · JavaScript-Referenz

Signatur

KeyboardEvent.isComposing

Beschreibung

Die Eigenschaft isComposing eines KeyboardEvent ist true, wenn das Ereignis innerhalb einer Kompositionssitzung ausgelöst wird, also nach compositionstart und vor compositionend. Solche Sitzungen entstehen bei Eingabemethoden (IME), etwa beim Tippen von Japanisch, Chinesisch oder Koreanisch, aber auch bei Akzent- bzw. Tottasten oder manchen Bildschirmtastaturen auf Mobilgeräten.

Gebraucht wird die Eigenschaft vor allem in Tastatur-Handlern, die auf Tasten wie Enter, Escape oder die Pfeiltasten reagieren. Mit einem IME bestätigt der Nutzer seine Auswahl mit Enter. Das darf aber kein Formular abschicken, keine Chatnachricht senden und keinen Eintrag in einer Autovervollständigung auswählen. Prüfen Sie deshalb event.isComposing und brechen Sie ab, wenn der Wert true ist.

Die Eigenschaft gibt es bei keydown und keyup. Gleichwertige Eigenschaften haben auch InputEvent.isComposing (bei input/beforeinput). Selbst erzeugte Ereignisse können sie über das Konstruktor-Wörterbuch setzen (new KeyboardEvent("keydown", { isComposing: true })).

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Ereignis Teil einer laufenden Komposition ist, sonst false.

Beispiele

Enter bei IME-Eingabe nicht als Absenden werten

const input = document.querySelector('#chat-input');

input.addEventListener('keydown', (event) => {
  // Während der Komposition bestätigt Enter nur die IME-Auswahl
  if (event.isComposing || event.keyCode === 229) return;

  if (event.key === 'Enter') {
    event.preventDefault();
    console.log('Nachricht senden:', input.value);
    input.value = '';
  }
});

Nachricht senden: こんにちは (erst nach der Bestätigung der IME-Auswahl und einem weiteren Enter)

Kompositionsstatus protokollieren

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

const logKey = (event) => {
  console.log(`${event.type}: key=${event.key}, isComposing=${event.isComposing}`);
};

field.addEventListener('keydown', logKey);
field.addEventListener('keyup', logKey);
field.addEventListener('compositionstart', () => console.log('--- Komposition beginnt'));
field.addEventListener('compositionend', (e) => console.log('--- Komposition endet:', e.data));

--- Komposition beginnt keydown: key=Process, isComposing=true ... --- Komposition endet: 日本

Autovervollständigung: Pfeiltasten nur außerhalb der Komposition

const search = document.querySelector('#search');
let activeIndex = -1;

const handleNav = (event) => {
  if (event.isComposing) return; // IME-Kandidatenliste nicht stören
  if (event.key === 'ArrowDown') activeIndex++;
  if (event.key === 'ArrowUp') activeIndex = Math.max(-1, activeIndex - 1);
  console.log('Aktiver Vorschlag:', activeIndex);
};

search.addEventListener('keydown', handleNav);
// Später wieder entfernen
// search.removeEventListener('keydown', handleNav);

Aktiver Vorschlag: 0

Synthetisches Ereignis mit isComposing

const evt = new KeyboardEvent('keydown', { key: 'Enter', isComposing: true });
console.log(evt.isComposing);

const normal = new KeyboardEvent('keydown', { key: 'Enter' });
console.log(normal.isComposing);

true false

// Wichtig · Fallstricke

Browser-Unterschiede bei der Reihenfolge: Wenn der Nutzer die Komposition beendet, feuert Safari das keydown für Enter erst nach compositionend. Dann ist isComposing bereits false. Zusätzlich zu prüfen hilft: event.keyCode === 229 ist zwar veraltet, zeigt aber zuverlässig einen IME-Tastendruck an. Alternativ kann man sich den Kompositionsstatus selbst über compositionstart/compositionend merken.
Während der Komposition hat event.key oft den Wert "Process" oder ist nicht aussagekräftig. Verlassen Sie sich dann nicht auf den Tastenwert.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird still ignoriert (im Strict Mode gibt es einen TypeError).
Bei keypress ist die Eigenschaft praktisch bedeutungslos, weil während einer Komposition meist gar kein keypress ausgelöst wird. Außerdem ist keypress veraltet.
Kompatibilität: Chrome 56+, Firefox 31+, Safari 10.1+, Edge 79+. Ältere Browser liefern undefined, was sich in Bedingungen wie false verhält.

Siehe auch

KeyboardEvent.location KeyboardEvent.code KeyboardEvent.charCode KeyboardEvent.ctrlKey KeyboardEvent.keyCode