KeyboardLayoutMap.entries() — Methode · JavaScript-Referenz

Signatur

KeyboardLayoutMap.prototype.entries()

Beschreibung

Die Methode entries() einer KeyboardLayoutMap gibt einen neuen Iterator zurück. Jeder Eintrag ist ein zweielementiges Array [code, key]: code ist der physische Tastencode, wie ihn KeyboardEvent.code liefert (z. B. "KeyZ"), und key ist das Zeichen, das diese Taste in der aktiven Tastaturbelegung erzeugt (auf einer deutschen QWERTZ-Tastatur z. B. "y").

An die KeyboardLayoutMap kommt man über navigator.keyboard.getLayoutMap(), das ein Promise zurückgibt. Die Map ist ein schreibgeschütztes, Map-ähnliches Objekt und verhält sich bei der Iteration wie Map.prototype.entries(). Deshalb kann man sie auch direkt mit for...of durchlaufen, denn [Symbol.iterator] verweist auf dieselbe Funktion.

Praktisch nützlich ist entries() vor allem, um Tastenkürzel oder Steuerungs-Hinweise passend zur Belegung anzuzeigen. Ein Beispiel ist ein Spiel, das „WASD“ nutzt: Auf einer AZERTY-Tastatur liegen diese Befehle auf den Tasten „ZQSD“. Mit entries() kann man außerdem eine vollständige Zuordnungstabelle aufbauen oder die Einträge per Object.fromEntries() weiterverarbeiten.

Rückgabewert

Typ

Iterator<[string, string]>

Beschreibung

Ein neuer Iterator. Jedes geliefertes Element ist ein Array [code, key] mit dem physischen Tastencode und dem Zeichen, das die Taste in der aktuellen Belegung erzeugt.

Beispiele

Alle Tastenzuordnungen ausgeben

const zeigeBelegung = async () => {
  if (!('keyboard' in navigator)) {
    console.warn('Keyboard API wird nicht unterstützt');
    return;
  }
  const layoutMap = await navigator.keyboard.getLayoutMap();
  for (const [code, key] of layoutMap.entries()) {
    console.log(`${code} → ${key}`);
  }
};

zeigeBelegung();

Backquote → ^ Digit1 → 1 ... KeyY → z KeyZ → y ... (Ausgabe mit deutscher QWERTZ-Belegung)

Steuerungs-Hinweise für ein Spiel an die Belegung anpassen

const bewegungsTasten = ['KeyW', 'KeyA', 'KeyS', 'KeyD'];

const beschrifteSteuerung = async () => {
  const layoutMap = await navigator.keyboard.getLayoutMap();
  const zuordnung = new Map(layoutMap.entries());
  const beschriftung = bewegungsTasten
    .map((code) => (zuordnung.get(code) ?? '?').toUpperCase())
    .join('');
  console.log(`Bewegen mit: ${beschriftung}`);
};

beschrifteSteuerung();

Bewegen mit: ZQSD (auf französischer AZERTY-Tastatur) Bewegen mit: WASD (auf QWERTY/QWERTZ)

Belegung als einfaches Objekt exportieren

const exportiereBelegung = async () => {
  const layoutMap = await navigator.keyboard.getLayoutMap();
  const obj = Object.fromEntries(layoutMap.entries());
  console.log(obj.KeyQ, obj.Semicolon);
  return JSON.stringify(obj);
};

exportiereBelegung().then((json) => console.log(json.length > 0));

q ö true (deutsche Belegung)

// Wichtig · Fallstricke

Kompatibilität: Die Keyboard API ist experimentell und nur in Chromium-Browsern (Chrome, Edge, Opera) verfügbar. Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man mit 'keyboard' in navigator prüfen, ob die API vorhanden ist.
Sicherer Kontext: Die API steht nur über HTTPS bzw. localhost zur Verfügung. In iframes muss sie über die Permissions Policy keyboard-map erlaubt sein.
Momentaufnahme: Die Map gibt die Belegung zum Zeitpunkt des Aufrufs von getLayoutMap() wieder. Wechselt der Nutzer die Belegung, muss man getLayoutMap() erneut aufrufen, damit die Daten aktuell sind.
Der Iterator lässt sich nur einmal durchlaufen. Für mehrfaches Nachschlagen kopiert man die Einträge besser in eine Map oder nutzt direkt layoutMap.get(code).
Tasten ohne druckbares Zeichen, etwa Umschalt, Strg oder Funktionstasten, sind in der Regel nicht enthalten. Bei Tottasten wie ^ kann der Wert je nach Browser vom erwarteten Zeichen abweichen.

Siehe auch

KeyboardLayoutMap.values() KeyboardLayoutMap.get() KeyboardLayoutMap.has() KeyboardLayoutMap.keys() KeyboardLayoutMap.forEach()