KeyboardLayoutMap.get() — Methode · JavaScript-Referenz

Signatur

KeyboardLayoutMap.prototype.get(key)

Beschreibung

Die Methode get() einer KeyboardLayoutMap übersetzt einen physischen Tastencode (z. B. "KeyZ", "Semicolon") in den Wert, den diese Taste im aktuell eingestellten Tastaturlayout des Nutzers liefert. Auf einer deutschen QWERTZ-Tastatur ergibt get("KeyZ") also "y", auf einer US-Tastatur "z".

Eine KeyboardLayoutMap erhält man über navigator.keyboard.getLayoutMap(), das ein Promise zurückgibt. Die Map ist schreibgeschützt und verhält sich wie eine gewöhnliche Map (get(), has(), keys(), entries(), forEach(), size).

Typischer Einsatz: In Spielen, Editoren oder Web-Anwendungen mit Tastenkürzeln, die über event.code an physische Positionen gebunden sind (etwa WASD-Steuerung), soll dem Nutzer die tatsächlich beschriftete Taste angezeigt werden — z. B. „Drücke Z zum Springen“ vs. „Drücke W“ auf einem AZERTY-Layout.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Physischer Tastencode im Format von `KeyboardEvent.code`, z. B. `"KeyQ"`, `"Digit1"`, `"BracketLeft"`.

Rückgabewert

Typ

string | undefined

Beschreibung

Der Tastenwert (meist ein einzelnes Zeichen in Kleinschreibung, ohne Umschalt-Modifikator) im aktuellen Layout, oder undefined, wenn der Code nicht in der Map enthalten ist.

Beispiele

Beschriftung einer physischen Taste ermitteln

const zeigeTaste = async () => {
  if (!navigator.keyboard?.getLayoutMap) {
    console.log('Keyboard Map API nicht verfügbar');
    return;
  }
  const layoutMap = await navigator.keyboard.getLayoutMap();
  console.log(layoutMap.get('KeyZ'));
  console.log(layoutMap.get('KeyW'));
};

zeigeTaste();

y (bei deutschem QWERTZ-Layout) w

Steuerungshinweise für ein Spiel mit WASD-Belegung

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

const erzeugeHinweise = async () => {
  const layoutMap = await navigator.keyboard.getLayoutMap();
  return Object.entries(bewegung).map(([code, aktion]) => {
    // Fallback auf den Code, falls die Taste nicht gemappt ist
    const taste = (layoutMap.get(code) ?? code).toUpperCase();
    return `${taste} = ${aktion}`;
  });
};

erzeugeHinweise().then((liste) => console.log(liste.join(', ')));

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

Tastenkürzel im Keydown-Handler anzeigen

let layoutMap = null;
navigator.keyboard?.getLayoutMap().then((map) => { layoutMap = map; });

document.addEventListener('keydown', (event) => {
  const beschriftung = layoutMap?.get(event.code);
  console.log(`Code: ${event.code}, Beschriftung: ${beschriftung ?? 'unbekannt'}`);
});

Code: Semicolon, Beschriftung: ö (bei deutschem Layout)

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Keyboard Map API ist experimentell und nur in Chromium-basierten Browsern (Chrome, Edge, Opera ab ca. Version 69) verfügbar. Firefox und Safari unterstützen sie nicht — immer per Feature-Detection (navigator.keyboard?.getLayoutMap) prüfen und einen Fallback vorsehen.
Nur in sicheren Kontexten (HTTPS) verfügbar. In Iframes kann der Zugriff per Permissions Policy (keyboard-map) blockiert sein; getLayoutMap() wird dann mit einem SecurityError abgelehnt.
Der Rückgabewert berücksichtigt keine Modifikatoren (Umschalt, AltGr); er liefert den Basiswert der Taste, i. d. R. in Kleinbuchstaben. Für die Anzeige ggf. toUpperCase() verwenden.
Die Map ist eine Momentaufnahme. Wechselt der Nutzer das Layout, muss getLayoutMap() erneut aufgerufen werden (das Ereignis layoutchange ist bislang nicht breit implementiert).
Tasten wie "Enter", "ShiftLeft" oder Funktionstasten sind meist nicht enthalten — get() liefert dann undefined.
Datenschutz: Das Layout kann zum Browser-Fingerprinting beitragen, weshalb Browser den Zugriff einschränken können.

Siehe auch

Map.prototype.get() KeyboardLayoutMap.entries() KeyboardLayoutMap.has() KeyboardLayoutMap.keys() KeyboardLayoutMap.values()