CompositionEvent.locale — Eigenschaft · JavaScript-Referenz

Signatur

CompositionEvent.locale

Beschreibung

Die Eigenschaft locale eines CompositionEvent gibt als Zeichenkette das Gebietsschema der Eingabemethode an, die gerade eine Komposition ausführt. Eine Komposition entsteht, wenn Text nicht direkt Zeichen für Zeichen, sondern über einen Input Method Editor (IME) eingegeben wird, etwa beim Tippen japanischer, chinesischer oder koreanischer Schriftzeichen oder bei Akzentzeichen über Tottasten.

Gedacht war die Eigenschaft für Editoren, Rechtschreibprüfungen und Eingabefelder, die je nach Eingabesprache unterschiedlich reagieren sollen, etwa beim Wechsel der Wortgrenzen-Logik oder der Autovervollständigung. Der Wert ist ein BCP-47-Sprachtag wie "ja-JP" oder "zh-CN". Ist das Gebietsschema unbekannt, bleibt er leer ("").

In der Praxis ist locale kaum brauchbar: Die Eigenschaft stammt aus einem älteren Entwurf der Spezifikation „UI Events“, wurde später daraus entfernt und nur von Firefox umgesetzt. Selbst dort ist der Wert bei echten IME-Ereignissen meist leer. Verlasse dich deshalb nicht auf sie. Frag sie nur mit einer Funktionserkennung ab und sieh einen Ersatzwert vor, etwa navigator.language oder das lang-Attribut des Eingabeelements.

Rückgabewert

Typ

string

Beschreibung

Ein BCP-47-Sprachtag (z. B. "ja-JP") oder eine leere Zeichenkette, wenn das Gebietsschema nicht bekannt ist. In Browsern ohne Unterstützung ist die Eigenschaft undefined.

Beispiele

Gebietsschema beim Start einer IME-Komposition ausgeben

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

input.addEventListener('compositionstart', (event) => {
  // locale ist nicht standardisiert: Ersatzwert vorsehen
  const locale = event.locale || navigator.language;
  console.log(`Komposition gestartet, Gebietsschema: ${locale}`);
});

Komposition gestartet, Gebietsschema: ja-JP

Funktionserkennung mit Ersatzwert

const supportsLocale = 'locale' in CompositionEvent.prototype;

const getImeLocale = (event, element) => {
  if (supportsLocale && event.locale) {
    return event.locale;
  }
  // Ersatz: lang-Attribut des Elements, danach die Browsersprache
  return element.closest('[lang]')?.lang || navigator.language;
};

const editor = document.querySelector('#editor');
editor.addEventListener('compositionend', (event) => {
  console.log('Eingabe:', event.data, '| Sprache:', getImeLocale(event, editor));
});

Eingabe: 東京 | Sprache: de-DE

Synthetisches CompositionEvent mit locale erzeugen (Firefox)

const event = new CompositionEvent('compositionupdate', {
  data: 'かな',
  locale: 'ja-JP' // wird nur von Firefox übernommen
});

console.log(event.data);   // "かな"
console.log(event.locale); // Firefox: "ja-JP", andere Browser: undefined

かな ja-JP

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Die Eigenschaft wurde aus der Spezifikation „UI Events“ entfernt. Nur Firefox setzt sie um. In Chrome, Edge und Safari liefert sie undefined.
Auch in Firefox ist der Wert bei echten IME-Eingaben oft eine leere Zeichenkette. Das Betriebssystem gibt die Eingabesprache nämlich nicht zuverlässig an den Browser weiter.
Die Eigenschaft ist nur lesbar. Beim Konstruktor lässt sie sich (nur in Firefox) über das Initialisierungsobjekt setzen.
Sieh immer einen Ersatzwert vor: navigator.language, navigator.languages oder das lang-Attribut des Dokuments bzw. Elements. Beachte, dass diese Werte die Sprache des Browsers bzw. der Seite angeben und nicht zwingend die gerade aktive Eingabemethode.
Für neue Projekte solltest du die Eigenschaft nicht verwenden. Wenn du auf die Komposition reagieren willst, nutze stattdessen event.data sowie InputEvent.isComposing.

Siehe auch

Navigator.language CompositionEvent.data MutationEvent.newValue PopStateEvent.state CSSPositionTryRule.name