Keyboard — Schnittstelle · JavaScript-Referenz

Signatur

interface Keyboard extends EventTarget

Beschreibung

Das Interface Keyboard gehört zur Keyboard API. Man erzeugt es nicht selbst, sondern bekommt die einzige Instanz über navigator.keyboard. Es hat zwei Aufgaben: Es verrät, welches Zeichen eine physische Taste im aktuellen Layout des Nutzers erzeugt, und es kann Tastenkombinationen abfangen, die sonst das Betriebssystem oder der Browser verarbeiten würde.

getLayoutMap() – gibt ein Promise<KeyboardLayoutMap> zurück. Diese Map ordnet physische Tastencodes (KeyboardEvent.code, z. B. "KeyW") den Zeichen im aktiven Layout zu (auf einer französischen AZERTY-Tastatur z. B. "z").
lock(keyCodes) – gibt ein Promise<void> zurück und leitet die angegebenen Tasten (ohne Argument: alle Tasten) direkt an die Seite weiter, etwa Esc, Alt+Tab oder Strg+W.
unlock() – hebt eine vorhandene Tastatursperre wieder auf.

Typische Einsatzfälle sind Spiele (Steuerungshinweise wie „Drücke W“ passend zum Layout anzeigen), Remote-Desktop- und VNC-Clients, Cloud-Gaming und im Browser laufende Editoren oder IDEs, die Systemtastenkürzel selbst belegen möchten.

Die Sperre wirkt nur, wenn sich die Seite im Vollbildmodus befindet, der über Element.requestFullscreen() gestartet wurde. Weil die API nur in Chromium-Browsern verfügbar ist, sollte man vorher immer mit 'keyboard' in navigator prüfen, ob sie vorhanden ist, und sonst auf die normalen KeyboardEvent-Daten zurückfallen.

Parameter

Name	Typ	Default	Beschreibung
$keyCodes	string[]	alle Tasten	Parameter von `lock()`: Liste physischer Tastencodes im Format von `KeyboardEvent.code` (z. B. `["Escape", "KeyW"]`). Ein ungültiger Code führt zu einem abgelehnten Promise mit `InvalidAccessError`.

Rückgabewert

Typ

Keyboard

Beschreibung

Die Instanz aus navigator.keyboard. getLayoutMap() liefert Promise<KeyboardLayoutMap>, lock() liefert Promise<void> und unlock() liefert undefined.

Beispiele

Unterstützung prüfen und Layout-Zeichen ermitteln

const zeigeSteuerung = async () => {
  if (!('keyboard' in navigator)) {
    console.log('Keyboard API nicht verfügbar – zeige Standardbelegung');
    return;
  }
  const layout = await navigator.keyboard.getLayoutMap();
  // Physische Taste oben links im WASD-Block
  const vorwaerts = layout.get('KeyW');
  console.log(`Vorwärts: Taste ${vorwaerts.toUpperCase()}`);
};

zeigeSteuerung();

Vorwärts: Taste W (bei AZERTY: "Vorwärts: Taste Z")

Alle Tastenzuordnungen auflisten

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

// KeyboardLayoutMap verhält sich wie eine schreibgeschützte Map
for (const [code, zeichen] of layout) {
  if (code.startsWith('Digit')) {
    console.log(code, '→', zeichen);
  }
}
console.log('Anzahl Tasten:', layout.size);

Digit1 → 1 Digit2 → 2 ... Anzahl Tasten: 48

Tasten im Vollbild sperren (z. B. für Remote-Desktop)

const startButton = document.querySelector('#vollbild');

startButton.addEventListener('click', async () => {
  await document.documentElement.requestFullscreen();
  // Esc und Systemkürzel an die Seite weiterleiten
  await navigator.keyboard.lock(['Escape', 'Tab', 'MetaLeft', 'MetaRight', 'KeyW']);
  console.log('Tastatur gesperrt');
});

document.addEventListener('keydown', (event) => {
  if (event.code === 'Escape') {
    console.log('Esc an Remote-Sitzung weitergeleitet');
  }
});

document.addEventListener('fullscreenchange', () => {
  if (!document.fullscreenElement) {
    navigator.keyboard.unlock();
    console.log('Sperre aufgehoben');
  }
});

Tastatur gesperrt Esc an Remote-Sitzung weitergeleitet

// Wichtig · Fallstricke

Browser-Unterstützung: Die API gibt es nur in Chromium-Browsern (Chrome/Edge ab 68, getLayoutMap() ab 69). Firefox und Safari unterstützen sie nicht. Deshalb immer vorher prüfen, ob sie vorhanden ist.
Nur über HTTPS: Die API funktioniert nur in sicheren Kontexten (HTTPS oder localhost).
Sperre nur im Vollbild: lock() wird zwar auch außerhalb des Vollbilds erfüllt, wirkt aber erst im Vollbildmodus, der über requestFullscreen() gestartet wurde. Mit F11 ausgelöstes Browser-Vollbild zählt nicht. Hält der Nutzer Esc etwa zwei Sekunden lang gedrückt, verlässt er das Vollbild trotzdem. Das ist eine Schutzfunktion, die sich nicht abschalten lässt.
iframes: In fremden iframes ist getLayoutMap() durch die Permissions Policy keyboard-map blockiert und lock() nur im obersten Browserkontext erlaubt.
Mehrere lock()-Aufrufe: Ein neuer Aufruf ersetzt die vorherige Sperre. Läuft noch ein anderer Aufruf, wird das ältere Promise mit AbortError abgelehnt.
Die KeyboardLayoutMap enthält nur Tasten, die ein Zeichen erzeugen. Für Modifikatortasten wie ShiftLeft liefert get() den Wert undefined.
Datenschutz: Das Layout kann zum Wiedererkennen von Nutzern (Fingerprinting) beitragen. Deshalb ist der Zugriff eingeschränkt, und andere Browser zögern mit der Umsetzung.

Siehe auch

Keyboard.lock() Keyboard.unlock() Navigator.keyboard Clipboard KeyboardEvent