Keyboard.getLayoutMap() — Methode · JavaScript-Referenz

Signatur

Keyboard.prototype.getLayoutMap()

Beschreibung

Die Methode getLayoutMap() gehört zum Keyboard-Interface, das über navigator.keyboard erreichbar ist. Sie liefert ein Promise, das mit einem KeyboardLayoutMap-Objekt erfüllt wird. Diese Map verhält sich wie eine schreibgeschützte Map: Die Schlüssel sind physische Tastencodes wie "KeyW" oder "Semicolon", die Werte sind die Zeichen, die diese Taste im aktuell eingestellten Layout erzeugt, zum Beispiel "w" bei QWERTY oder "z" bei AZERTY.

Gebraucht wird das vor allem bei Spielen, Web-Editoren und Anwendungen mit Tastenkürzeln, die Tasten über ihre physische Position auswerten (event.code). Die Steuerung „WASD“ liegt auf einer französischen AZERTY-Tastatur zum Beispiel auf „ZQSD“. Mit getLayoutMap() zeigt die Oberfläche dem Nutzer die Beschriftung, die tatsächlich auf seiner Taste steht.

Die Map enthält nur Zeichen, die die Taste ohne Modifikatoren erzeugt, also ohne Umschalt- oder AltGr-Taste. Tasten, die kein druckbares Zeichen erzeugen (z. B. "ShiftLeft" oder "Enter"), fehlen in der Map meist. Rechne deshalb bei get() immer mit undefined.

Rückgabewert

Typ

Promise<KeyboardLayoutMap>

Beschreibung

Ein Promise, das mit einer KeyboardLayoutMap erfüllt wird. Die Map unterstützt get(), has(), keys(), values(), entries(), forEach(), size und for…of. Das Promise wird mit einem SecurityError abgelehnt, wenn der Aufruf aus einem nicht erlaubten Kontext kommt, etwa aus einem fremden iframe ohne passende Permissions-Policy.

Beispiele

Beschriftung einer physischen Taste ermitteln

const zeigeTaste = async () => {
  if (!('keyboard' in navigator)) {
    console.log('Keyboard API wird nicht unterstützt');
    return;
  }
  const layoutMap = await navigator.keyboard.getLayoutMap();
  const zeichen = layoutMap.get('KeyW');
  console.log(`Taste für „vorwärts“: ${zeichen?.toUpperCase() ?? '?'}`);
};

zeigeTaste();

Taste für „vorwärts“: W (auf AZERTY: Z)

Spielsteuerung layoutgerecht beschriften

const steuerung = {
  hoch: 'KeyW',
  links: 'KeyA',
  runter: 'KeyS',
  rechts: 'KeyD'
};

const beschrifteSteuerung = async () => {
  // Fallback: Codes ohne Präfix „Key“ anzeigen
  let map = null;
  try {
    map = await navigator.keyboard?.getLayoutMap();
  } catch (err) {
    console.warn('Layout nicht abrufbar:', err.name);
  }

  return Object.fromEntries(
    Object.entries(steuerung).map(([aktion, code]) => [
      aktion,
      (map?.get(code) ?? code.replace('Key', '')).toUpperCase()
    ])
  );
};

beschrifteSteuerung().then(console.log);

{ hoch: 'W', links: 'A', runter: 'S', rechts: 'D' } (auf AZERTY: { hoch: 'Z', links: 'Q', runter: 'S', rechts: 'D' })

Gesamte Layout-Map auflisten

const listeLayout = async () => {
  const map = await navigator.keyboard.getLayoutMap();
  console.log(`Anzahl Einträge: ${map.size}`);
  for (const [code, zeichen] of map) {
    if (code.startsWith('Digit')) console.log(code, '→', zeichen);
  }
};

listeLayout();

Anzahl Einträge: 48 Digit0 → 0 Digit1 → 1 … (auf AZERTY z. B. Digit1 → &)

Tastendruck mit Layout-Zeichen ausgeben

const init = async () => {
  const map = await navigator.keyboard.getLayoutMap();
  document.addEventListener('keydown', (event) => {
    const label = map.get(event.code) ?? event.key;
    console.log(`Physisch: ${event.code}, Beschriftung: ${label}`);
  });
};

init();

Physisch: KeyQ, Beschriftung: q

// Wichtig · Fallstricke

Browser-Unterstützung: Die Methode gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen die Keyboard API nicht. Prüfe deshalb immer vorher mit 'keyboard' in navigator und sieh einen Fallback vor.
Sicherer Kontext: Die API ist nur über HTTPS oder localhost verfügbar.
iframes: In eingebetteten Frames verlangt Chrome die Permissions-Policy keyboard-map (<iframe allow="keyboard-map">). Fehlt sie, wird das Promise mit einem SecurityError abgelehnt.
Layoutwechsel: Die zurückgegebene Map ist eine Momentaufnahme. Wechselt der Nutzer das Layout, bleibt sie unverändert. Chromium hat dafür das experimentelle Event layoutchange auf navigator.keyboard. Alternativ ruft man getLayoutMap() einfach erneut auf, etwa bei focus.
Nur Grundbelegung: Zeichen, die man mit Umschalt- oder AltGr-Taste erzeugt, stehen nicht in der Map. Auch tote Tasten (z. B. ^ auf deutschen Tastaturen) können je nach System fehlen oder abweichen.
Datenschutz: Das Tastaturlayout verrät etwas über Sprache und Region des Nutzers und kann zum Fingerprinting beitragen. Deshalb ist die API in manchen Browsern eingeschränkt.

Siehe auch

Keyboard Navigator.keyboard Keyboard.lock() KeyboardLayoutMap.forEach() Keyboard.unlock()