KeyboardLayoutMap.keys() — Methode · JavaScript-Referenz

Signatur

KeyboardLayoutMap.prototype.keys()

Beschreibung

Die Methode keys() einer KeyboardLayoutMap gibt ein neues Iterator-Objekt zurück, das die Schlüssel der Map in Einfügereihenfolge liefert. Die Schlüssel sind Werte von KeyboardEvent.code, also Bezeichner für die physische Position einer Taste, etwa "KeyA", "Digit1" oder "Semicolon". Das Verhalten entspricht Map.prototype.keys(), denn KeyboardLayoutMap ist ein schreibgeschütztes, Map-ähnliches Objekt.

An eine KeyboardLayoutMap kommt man über navigator.keyboard.getLayoutMap(). Mit keys() lässt sich feststellen, welche physischen Tasten die Map abdeckt. So kann man z. B. eine Liste der Tasten erstellen, die man als Tastenkürzel belegen kann, oder die Map mit Hilfe von get() gezielt nach der Beschriftung jeder Taste abfragen.

Braucht man nur die Beschriftungen, ist values() die richtige Methode. Für Paare aus Code und Beschriftung nimmt man entries() oder direkt for...of über die Map. Der zurückgegebene Iterator lässt sich nur einmal durchlaufen. Wenn man die Schlüssel mehrfach braucht, wandelt man sie mit Array.from() oder dem Spread-Operator in ein Array um.

Rückgabewert

Typ

Iterator<string>

Beschreibung

Ein neuer Iterator, der die Schlüssel der Map liefert. Jeder Schlüssel ist ein KeyboardEvent.code-String (z. B. "KeyW").

Beispiele

Alle physischen Tastencodes auflisten

const listKeyCodes = async () => {
  if (!navigator.keyboard?.getLayoutMap) {
    console.warn('Keyboard Map API wird nicht unterstützt.');
    return [];
  }
  const layoutMap = await navigator.keyboard.getLayoutMap();
  const codes = [...layoutMap.keys()];
  console.log(`${codes.length} Tasten gefunden`);
  console.log(codes.slice(0, 5));
  return codes;
};

listKeyCodes();

48 Tasten gefunden ["Backquote", "Backslash", "BracketLeft", "BracketRight", "Comma"]

Buchstabentasten mit ihrer Beschriftung im aktuellen Layout

const showLetterKeys = async () => {
  const layoutMap = await navigator.keyboard.getLayoutMap();
  for (const code of layoutMap.keys()) {
    if (code.startsWith('Key')) {
      // Beschriftung im aktiven Layout, z. B. "z" für KeyY auf QWERTZ
      console.log(`${code} → ${layoutMap.get(code)}`);
    }
  }
};

showLetterKeys();

KeyA → a KeyB → b … KeyY → z KeyZ → y

Spielsteuerung: WASD-Beschriftungen für die Anzeige ermitteln

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

const getMovementLabels = async () => {
  const layoutMap = await navigator.keyboard.getLayoutMap();
  const available = new Set(layoutMap.keys());
  return movementCodes.map((code) =>
    available.has(code) ? layoutMap.get(code).toUpperCase() : code
  );
};

getMovementLabels().then((labels) => {
  // Auf AZERTY z. B. Z, Q, S, D
  console.log(`Bewegung: ${labels.join(' / ')}`);
});

Bewegung: W / A / S / D

// Wichtig · Fallstricke

Browser-Unterstützung: Die Keyboard Map API gibt es nur in Chromium-Browsern (Chrome/Edge 69+). Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man deshalb prüfen, ob sie vorhanden ist (navigator.keyboard?.getLayoutMap).
Nur im sicheren Kontext: Die API funktioniert nur über HTTPS bzw. localhost. In Iframes kann die Permissions Policy keyboard-map den Zugriff sperren.
Einmaliger Iterator: Ist der Iterator einmal durchlaufen, liefert er nichts mehr. Für mehrfachen Zugriff wandelt man ihn z. B. mit [...map.keys()] in ein Array um.
Die Schlüssel stehen für physische Tastenpositionen, nicht für Zeichen. Welches Zeichen eine Taste erzeugt, liefert get() bzw. values().
Die Map ist eine Momentaufnahme des Layouts. Wechselt der Nutzer das Tastaturlayout, muss man getLayoutMap() erneut aufrufen. Ein zuverlässiges Ereignis für Layoutwechsel gibt es nicht.
Welche und wie viele Tasten enthalten sind, hängt von Betriebssystem und Layout ab. Man sollte sich also nicht darauf verlassen, dass ein bestimmter Code immer vorhanden ist.

Siehe auch

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