KeyboardLayoutMap.has() — Methode · JavaScript-Referenz

Signatur

KeyboardLayoutMap.prototype.has(key)

Beschreibung

Die Methode has() gehört zur schreibgeschützten, Map-ähnlichen Schnittstelle KeyboardLayoutMap. Diese erhält man über navigator.keyboard.getLayoutMap(). Sie ordnet physische Tastencodes wie "KeyQ" oder "Digit1" (die Werte aus KeyboardEvent.code) den Zeichen zu, die diese Tasten im aktuell eingestellten Tastaturlayout erzeugen.

Mit has() lässt sich vor einem Zugriff über get() prüfen, ob für einen Tastencode überhaupt eine Zuordnung existiert. Das ist nützlich für Spiele und Web-Anwendungen mit Tastenkürzeln: Man legt Tasten nach ihrer physischen Position fest (z. B. WASD) und zeigt dem Nutzer die passende Beschriftung seines Layouts an, etwa „Z“ statt „W“ bei einer französischen AZERTY-Tastatur.

Als Schlüssel wird ein KeyboardEvent.code-String erwartet, nicht der Wert aus KeyboardEvent.key. Die Prüfung unterscheidet Groß- und Kleinschreibung: "keyw" liefert false. Die Map enthält im Wesentlichen druckbare Tasten (Buchstaben, Ziffern, Satzzeichen). Steuertasten wie "Enter", "ShiftLeft" oder "ArrowUp" sind in der Regel nicht enthalten.

Parameter

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

Beispiele

Einfache Prüfung eines Tastencodes

const layoutMap = await navigator.keyboard.getLayoutMap();

console.log(layoutMap.has('KeyW'));      // Buchstabentaste
console.log(layoutMap.has('keyw'));      // falsche Schreibweise
console.log(layoutMap.has('ShiftLeft')); // Steuertaste

true false false

Tastenbeschriftungen für WASD-Steuerung passend zum Layout anzeigen

const showControls = async () => {
  if (!('keyboard' in navigator) || !navigator.keyboard.getLayoutMap) {
    console.log('Keyboard Map API nicht verfügbar – Standardbeschriftung');
    return;
  }
  const layoutMap = await navigator.keyboard.getLayoutMap();
  const controls = { hoch: 'KeyW', links: 'KeyA', runter: 'KeyS', rechts: 'KeyD' };

  for (const [aktion, code] of Object.entries(controls)) {
    const label = layoutMap.has(code) ? layoutMap.get(code).toUpperCase() : code;
    console.log(`${aktion}: ${label}`);
  }
};

showControls();

// Auf französischer AZERTY-Tastatur: hoch: Z links: Q runter: S rechts: D

Tastenkürzel im keydown-Handler auflösen

const layoutMap = await navigator.keyboard.getLayoutMap();

document.addEventListener('keydown', (event) => {
  if (layoutMap.has(event.code)) {
    console.log(`Physische Taste ${event.code} erzeugt "${layoutMap.get(event.code)}"`);
  } else {
    console.log(`${event.code} ist keine druckbare Taste`);
  }
});

// Beim Drücken von Y auf deutscher QWERTZ-Tastatur: Physische Taste KeyZ erzeugt "y"

// Wichtig · Fallstricke

Kompatibilität: Die Keyboard Map API ist experimentell und nur in Chromium-Browsern (Chrome, Edge, Opera ab Version 69) verfügbar. Firefox und Safari unterstützen sie nicht. Prüfe deshalb vorher mit 'keyboard' in navigator, ob die API vorhanden ist.
Die API funktioniert nur in einem sicheren Kontext (HTTPS). In eingebetteten iframes kann sie über die Permissions-Policy keyboard-map gesperrt sein.
getLayoutMap() liefert eine Momentaufnahme. Wechselt der Nutzer später das Layout, wird die Map nicht aktualisiert. Hole sie bei Bedarf neu, z. B. bei focus oder visibilitychange.
Als Schlüssel muss ein KeyboardEvent.code-Wert verwendet werden. Mit event.key (z. B. "w") liefert has() immer false.
Die Map ist schreibgeschützt: Es gibt keine Methoden set(), delete() oder clear().

Siehe auch

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