KeyboardLayoutMap.forEach() — Methode · JavaScript-Referenz

Signatur

KeyboardLayoutMap.prototype.forEach(callbackFn, thisArg)

Beschreibung

Die Methode forEach() des Interfaces KeyboardLayoutMap durchläuft alle Einträge der Map. Jeder Eintrag ordnet einem physischen Tastencode wie "KeyQ" oder "Semicolon" das Zeichen zu, das diese Taste im aktiven Tastaturlayout des Nutzers erzeugt. Auf einer deutschen QWERTZ-Tastatur liefert "KeyY" zum Beispiel "z".

Die Map bekommen Sie asynchron über navigator.keyboard.getLayoutMap(). Sie ist schreibgeschützt und verhält sich wie eine Map, die nur gelesen werden kann. Deshalb bekommt die Rückruffunktion ihre Argumente in derselben Reihenfolge wie bei Map.prototype.forEach(): zuerst den Wert (das Zeichen), dann den Schlüssel (den Tastencode) und zuletzt die Map selbst.

Typische Anwendungsfälle:

Tastenkürzel richtig beschriften, etwa in Spielen oder Editoren. Statt „Drücke KeyW“ zeigen Sie das Zeichen an, das auf der Taste des Nutzers steht.
Das vollständige Layout zur Fehlersuche ausgeben.
Eine eigene Nachschlagetabelle aufbauen, zum Beispiel eine Umkehrzuordnung von Zeichen zu Tastencode.

Parameter

Name	Typ	Default	Beschreibung
$callbackFn Pflicht	(value: string, key: string, map: KeyboardLayoutMap) => void		Wird für jeden Eintrag aufgerufen. Sie erhält: `value` (das erzeugte Zeichen, z. B. `"z"`), `key` (den physischen Tastencode, z. B. `"KeyY"`) und `map` (die durchlaufene `KeyboardLayoutMap`).
$thisArg	any	undefined	Wert, der beim Aufruf von `callbackFn` als `this` gilt. Bei Pfeilfunktionen hat er keine Wirkung.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. forEach() dient nur für Seiteneffekte und lässt sich nicht verketten.

Beispiele

Gesamtes Tastaturlayout ausgeben

const logLayout = async () => {
  if (!navigator.keyboard?.getLayoutMap) {
    console.warn('Keyboard API wird nicht unterstützt');
    return;
  }
  const layoutMap = await navigator.keyboard.getLayoutMap();
  // Achtung: zuerst der Wert (Zeichen), dann der Schlüssel (Tastencode)
  layoutMap.forEach((zeichen, code) => {
    console.log(`${code} → ${zeichen}`);
  });
};

logLayout();

KeyQ → q KeyW → w KeyY → z BracketLeft → ü ... (Ausgabe hängt vom Layout ab, hier deutsches QWERTZ)

Umkehrtabelle: Zeichen → Tastencode

const buildReverseMap = async () => {
  const layoutMap = await navigator.keyboard.getLayoutMap();
  const zeichenZuCode = new Map();
  layoutMap.forEach((zeichen, code) => {
    zeichenZuCode.set(zeichen, code);
  });
  return zeichenZuCode;
};

buildReverseMap().then((reverse) => {
  // Auf welcher physischen Taste liegt das "z"?
  console.log(reverse.get('z'));
});

KeyY (bei deutschem QWERTZ-Layout; bei US-QWERTY: KeyZ)

Spielsteuerung mit korrekten Tastenbeschriftungen

const steuerung = {
  KeyW: 'Vorwärts',
  KeyA: 'Links',
  KeyS: 'Rückwärts',
  KeyD: 'Rechts'
};

const zeigeSteuerung = async () => {
  const layoutMap = await navigator.keyboard.getLayoutMap();
  const zeilen = [];
  layoutMap.forEach(function (zeichen, code) {
    if (code in this) {
      zeilen.push(`${zeichen.toUpperCase()}: ${this[code]}`);
    }
  }, steuerung); // thisArg = steuerung
  console.log(zeilen.join('\n'));
};

zeigeSteuerung();

W: Vorwärts A: Links S: Rückwärts D: Rechts (bei französischem AZERTY stattdessen z. B. Z: Vorwärts, Q: Links)

// Wichtig · Fallstricke

Reihenfolge der Argumente: Wie bei Map.prototype.forEach() kommt zuerst der Wert (das Zeichen) und danach der Schlüssel (der Tastencode). Beides zu vertauschen ist ein häufiger Fehler.
Browser-Unterstützung: Die Keyboard API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, ab Version 69). Firefox und Safari unterstützen sie nicht. Prüfen Sie deshalb vorher mit navigator.keyboard?.getLayoutMap, ob sie vorhanden ist.
Sicherer Kontext: Die API steht nur über HTTPS oder auf localhost zur Verfügung. In iframes kann sie über die Permissions-Policy keyboard-map gesperrt sein.
Momentaufnahme: Die Map zeigt das Layout zum Zeitpunkt des Aufrufs von getLayoutMap(). Wechselt der Nutzer später das Layout, müssen Sie die Map neu abrufen.
Die Map enthält nur Tasten, die ein druckbares Zeichen erzeugen. Modifikatortasten wie ShiftLeft oder Enter tauchen nicht auf.
Einen vorzeitigen Abbruch mit break gibt es nicht. Wenn Sie abbrechen müssen, verwenden Sie for (const [code, zeichen] of layoutMap). Beachten Sie, dass der Iterator die Reihenfolge [Schlüssel, Wert] liefert.
Die Werte sind die Zeichen ohne Umschalttaste, also meist Kleinbuchstaben.

Siehe auch

CSSFontFeatureValuesMap.forEach() KeyboardLayoutMap.get() KeyboardLayoutMap.has() KeyboardLayoutMap.keys() KeyboardLayoutMap.entries()