InputEvent.isComposing — Eigenschaft · JavaScript-Referenz

Signatur

InputEvent.isComposing

Beschreibung

Die Eigenschaft isComposing eines InputEvent zeigt an, ob die Eingabe gerade Teil einer Komposition ist. Eine Komposition entsteht, wenn ein Eingabemethoden-Editor (IME) benutzt wird, etwa für Japanisch, Chinesisch oder Koreanisch, oder bei Tottasten (z. B. ´ + e = é) und bei manchen virtuellen Tastaturen auf Mobilgeräten mit Autokorrektur.

Während der Komposition ist der eingegebene Text vorläufig: Der Nutzer wählt noch Zeichen aus oder bestätigt Vorschläge. Die Ereignisse beforeinput und input werden trotzdem ausgelöst, nur eben mit isComposing === true. Erst nach compositionend steht der endgültige Text fest.

In der Praxis braucht man die Eigenschaft vor allem für Live-Suche, Validierung, Autovervollständigung und Tastenkürzel. Solche Logik sollte während einer laufenden Komposition nicht ausgeführt werden, sonst entstehen unnötige Anfragen, falsche Zwischentreffer oder abgebrochene Eingaben. Die gleichnamige Eigenschaft gibt es auch bei KeyboardEvent.isComposing. Damit lässt sich z. B. verhindern, dass Enter ein Formular absendet, während der Nutzer eigentlich nur einen IME-Vorschlag bestätigt.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Ereignis innerhalb einer laufenden Komposition ausgelöst wurde, sonst false. Schreibgeschützt.

Beispiele

Live-Suche erst nach abgeschlossener Komposition auslösen

const search = document.querySelector('#search');

const runSearch = async (term) => {
  const res = await fetch(`/api/search?q=${encodeURIComponent(term)}`);
  const hits = await res.json();
  console.log(`${hits.length} Treffer für "${term}"`);
};

search.addEventListener('input', (event) => {
  // Vorläufigen IME-Text ignorieren
  if (event.isComposing) return;
  runSearch(search.value);
});

// Nach Abschluss der Komposition einmal mit dem endgültigen Text suchen
search.addEventListener('compositionend', () => {
  runSearch(search.value);
});

3 Treffer für "東京"

Enter während der IME-Auswahl nicht als Absenden werten

const chatInput = document.querySelector('#chat');

chatInput.addEventListener('keydown', (event) => {
  // keyCode 229 als Rückfall für ältere Safari-Versionen
  if (event.isComposing || event.keyCode === 229) return;

  if (event.key === 'Enter' && !event.shiftKey) {
    event.preventDefault();
    console.log('Nachricht gesendet:', chatInput.value);
    chatInput.value = '';
  }
});

Nachricht gesendet: こんにちは

Kompositionsstatus beim Tippen protokollieren

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

field.addEventListener('beforeinput', (event) => {
  console.log({
    inputType: event.inputType,
    data: event.data,
    isComposing: event.isComposing
  });
});

{ inputType: 'insertCompositionText', data: 'に', isComposing: true } { inputType: 'insertCompositionText', data: '日本', isComposing: true }

Synthetisches InputEvent mit isComposing erzeugen

const ev = new InputEvent('input', {
  data: 'a',
  inputType: 'insertCompositionText',
  isComposing: true
});

console.log(ev.isComposing);
console.log(new InputEvent('input').isComposing);

true false

// Wichtig · Fallstricke

Uneinheitliche Reihenfolge: Die Browser lösen input und compositionend in unterschiedlicher Reihenfolge aus. In Chrome kommt das letzte input mit isComposing === false meist nach compositionend, in Safari teilweise davor und noch mit true. Wer auf den endgültigen Text angewiesen ist, sollte zusätzlich compositionend auswerten.
Safari und keydown: Ältere Safari-Versionen setzen KeyboardEvent.isComposing für das bestätigende Enter nicht zuverlässig. Als Rückfall prüft man zusätzlich keyCode === 229.
Mobile Tastaturen: Android-Tastaturen (z. B. Gboard) behandeln oft jedes Wort als Komposition. Deshalb kann isComposing auch bei lateinischer Schrift true sein. Logik, die Kompositionsereignisse komplett ignoriert, wirkt dort womöglich „verzögert“.
preventDefault() auf beforeinput wirkt bei Kompositions-Eingaben (insertCompositionText) in der Regel nicht und lässt sich nicht verlässlich abbrechen.
Die Eigenschaft ist schreibgeschützt. Bei synthetischen Ereignissen lässt sie sich nur über das Initialisierungsobjekt des Konstruktors setzen. Solche Ereignisse lösen keine echte Komposition aus.

Siehe auch

InputEvent.inputType InputEvent.data InputEvent.dataTransfer KeyboardEvent.isComposing Event.composed