KeyboardLayoutMap — Schnittstelle · JavaScript-Referenz

Signatur

interface KeyboardLayoutMap

Beschreibung

KeyboardLayoutMap gehört zur Keyboard API. Eine Instanz bekommt man nicht über einen Konstruktor, sondern nur über navigator.keyboard.getLayoutMap(). Das Promise wird mit einer Map aufgelöst. Ihre Schlüssel sind physische Tastencodes wie bei KeyboardEvent.code (etwa "KeyQ", "Digit1", "BracketLeft"), ihre Werte die Zeichen, die diese Tasten im aktiven Layout des Nutzers erzeugen.

Gebraucht wird das vor allem bei Tastenkürzeln, die sich an der Position der Taste orientieren, etwa WASD-Steuerung in Spielen oder Kürzel in Editoren. Die Anwendung prüft intern event.code und zeigt dem Nutzer trotzdem die richtige Beschriftung an. Auf einer deutschen QWERTZ-Tastatur liefert "KeyY" zum Beispiel "z", auf einer französischen AZERTY-Tastatur liefert "KeyQ" den Wert "a".

Die Schnittstelle verhält sich wie ein schreibgeschütztes Map. Es gibt die Eigenschaft size sowie die Methoden get(key), has(key), keys(), values(), entries(), forEach(callback) und [Symbol.iterator](). Methoden zum Ändern wie set, delete oder clear fehlen.

size: Anzahl der enthaltenen Einträge.
get(code): Zeichen zum Tastencode oder undefined.
has(code): true, wenn der Tastencode enthalten ist.
entries() / keys() / values(): Iteratoren wie bei Map.
forEach(callback, thisArg): ruft callback(value, key, map) für jeden Eintrag auf.

Parameter

Name	Typ	Default	Beschreibung
$code Pflicht	string		Physischer Tastencode im Format von `KeyboardEvent.code`, z. B. `"KeyW"`. Wird von `get()` und `has()` erwartet.
$callback	(value: string, key: string, map: KeyboardLayoutMap) => void		Funktion, die `forEach()` für jeden Eintrag aufruft.
$thisArg	any	undefined	Wert für `this` innerhalb von `callback` bei `forEach()`.

Rückgabewert

Typ

Promise<KeyboardLayoutMap>

Beschreibung

Wird von navigator.keyboard.getLayoutMap() zurückgegeben. get() liefert string | undefined, has() liefert boolean, size ist eine number.

Beispiele

Layout-Map abrufen und eine Taste abfragen

const zeigeTaste = async () => {
  if (!('keyboard' in navigator) || !navigator.keyboard.getLayoutMap) {
    console.log('Keyboard API nicht verfügbar');
    return;
  }
  const layoutMap = await navigator.keyboard.getLayoutMap();
  // Welches Zeichen liegt auf der physischen Taste "KeyY"?
  const zeichen = layoutMap.get('KeyY');
  console.log(`Die Taste an Position Y erzeugt: ${zeichen}`);
  console.log('Anzahl Einträge:', layoutMap.size);
};

zeigeTaste();

Die Taste an Position Y erzeugt: z (bei deutschem QWERTZ-Layout) Anzahl Einträge: 48

WASD-Steuerung für Spiele passend zum Layout beschriften

const bewegungsTasten = {
  KeyW: 'vorwärts',
  KeyA: 'links',
  KeyS: 'rückwärts',
  KeyD: 'rechts'
};

const beschrifteSteuerung = async () => {
  const layoutMap = await navigator.keyboard.getLayoutMap();
  for (const [code, aktion] of Object.entries(bewegungsTasten)) {
    const label = (layoutMap.get(code) ?? code).toUpperCase();
    console.log(`${label} = ${aktion}`);
  }
};

// Im Spiel wird positionsbasiert event.code ausgewertet
document.addEventListener('keydown', (event) => {
  if (event.code in bewegungsTasten) {
    console.log('Aktion:', bewegungsTasten[event.code]);
  }
});

beschrifteSteuerung();

Z = vorwärts Q = links S = rückwärts D = rechts (bei französischem AZERTY-Layout)

Gesamte Zuordnung ausgeben und durchsuchen

const findeCodeFuerZeichen = async (gesucht) => {
  const layoutMap = await navigator.keyboard.getLayoutMap();

  // forEach wie bei Map: (value, key)
  layoutMap.forEach((wert, code) => {
    if (code.startsWith('Digit')) console.log(code, '→', wert);
  });

  // Umgekehrte Suche: Welcher Code erzeugt das Zeichen?
  const treffer = [...layoutMap.entries()].find(([, wert]) => wert === gesucht);
  return treffer ? treffer[0] : null;
};

findeCodeFuerZeichen('ß').then((code) => console.log('ß liegt auf:', code));

Digit1 → 1 Digit2 → 2 … ß liegt auf: Minus (bei deutschem Layout)

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Schnittstelle ist experimentell und gibt es nur in Chromium-Browsern (Chrome/Edge 69+, Opera). Firefox und Safari unterstützen sie nicht. Prüfen Sie deshalb immer vorab mit navigator.keyboard?.getLayoutMap, ob sie verfügbar ist, und sehen Sie einen Ersatzweg vor, zum Beispiel event.key.
Nur im sicheren Kontext (HTTPS oder localhost). In Iframes kann die Permissions Policy keyboard-map den Zugriff sperren. Dann wird das Promise mit einem SecurityError abgelehnt.
Die Map ist eine Momentaufnahme. Wechselt der Nutzer das Layout, muss getLayoutMap() erneut aufgerufen werden. Das Ereignis layoutchange ist spezifiziert, aber kaum umgesetzt.
Die Werte sind die Zeichen ohne Modifikatortasten, meist also Kleinbuchstaben. Tote Tasten und Zeichen, die nur mit Shift oder AltGr entstehen, sind nicht verlässlich abgebildet. Sondertasten wie Enter oder ShiftLeft fehlen in der Regel.
Datenschutz: Das Tastaturlayout kann zum Fingerprinting beitragen. Rufen Sie die Map deshalb nur ab, wenn Sie sie wirklich brauchen.
Es gibt keinen öffentlichen Konstruktor. new KeyboardLayoutMap() wirft einen TypeError.

Siehe auch

Keyboard Keyboard.getLayoutMap() Keyboard.lock() KeyboardEvent KeyboardEvent.code KeyboardEvent.key Map