Navigator.keyboard — Eigenschaft · JavaScript-Referenz

Signatur

get Navigator.keyboard

Beschreibung

Die schreibgeschützte Eigenschaft navigator.keyboard gibt ein Keyboard-Objekt zurück. Es gehört zur Keyboard API und bietet zwei Funktionen: die Keyboard Map API und die Keyboard Lock API.

keyboard.getLayoutMap() liefert ein Promise mit einer KeyboardLayoutMap. Sie ordnet physische Tastencodes (z. B. "KeyW") dem Zeichen zu, das im aktuellen Layout auf der Taste liegt, also etwa "w" bei QWERTZ oder "z" bei AZERTY.
keyboard.lock(keyCodes) fängt Tasten oder Tastenkombinationen ab, die sonst der Browser oder das Betriebssystem verarbeiten würde, etwa Esc, Alt+Tab oder Strg+W. Mit keyboard.unlock() wird die Sperre wieder aufgehoben.

Typische Anwendungen sind Browserspiele mit WASD-Steuerung, bei denen die Tastenbelegung auf dem Bildschirm zum Layout des Nutzers passen soll. Dazu kommen Remote-Desktop-Clients, virtuelle Maschinen und Web-IDEs im Vollbildmodus, die Systemkürzel selbst verarbeiten müssen.

Die Eigenschaft ist nur in einem sicheren Kontext (HTTPS) verfügbar. Weil die Unterstützung eingeschränkt ist, sollte man vor der Nutzung immer mit 'keyboard' in navigator prüfen, ob sie vorhanden ist.

Rückgabewert

Typ

Keyboard

Beschreibung

Ein Keyboard-Objekt mit den Methoden getLayoutMap(), lock() und unlock(). Es ist pro Dokument immer dasselbe Objekt. In Browsern ohne Unterstützung ist der Wert undefined.

Beispiele

Unterstützung prüfen

const hasKeyboardApi = 'keyboard' in navigator && window.isSecureContext;

if (hasKeyboardApi) {
  console.log('Keyboard API verfügbar:', navigator.keyboard);
} else {
  console.log('Keyboard API nicht verfügbar – Standard-Tastenbezeichnungen verwenden.');
}

Keyboard API verfügbar: Keyboard {}

Spielsteuerung passend zum Tastaturlayout anzeigen

const showControls = async () => {
  const codes = ['KeyW', 'KeyA', 'KeyS', 'KeyD'];
  let labels = ['W', 'A', 'S', 'D']; // Rückfall: QWERTY-Beschriftung

  if (navigator.keyboard?.getLayoutMap) {
    const layoutMap = await navigator.keyboard.getLayoutMap();
    labels = codes.map((code) => (layoutMap.get(code) ?? code).toUpperCase());
  }

  console.log(`Bewegen mit: ${labels.join(' / ')}`);
};

showControls();

Bewegen mit: Z / Q / S / D (bei französischem AZERTY-Layout)

Systemtasten im Vollbild abfangen (Remote-Desktop)

const startBtn = document.querySelector('#fullscreen');

startBtn.addEventListener('click', async () => {
  await document.documentElement.requestFullscreen();

  if (navigator.keyboard?.lock) {
    // Nur bestimmte Tasten sperren; ohne Argument werden alle gesperrt
    await navigator.keyboard.lock(['Escape', 'KeyW', 'Tab', 'MetaLeft']);
    console.log('Tastatur gesperrt – Esc gedrückt halten zum Verlassen.');
  }
});

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

document.addEventListener('keydown', (e) => {
  if (e.code === 'KeyW' && e.ctrlKey) {
    e.preventDefault();
    console.log('Strg+W an entfernten Rechner weitergeleitet');
  }
});

Tastatur gesperrt – Esc gedrückt halten zum Verlassen.

// Wichtig · Fallstricke

Experimentell und eingeschränkte Unterstützung: Die API gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Deshalb immer auf Vorhandensein prüfen und eine Ausweichlösung vorsehen.
Nur in sicheren Kontexten: Die Eigenschaft ist nur über HTTPS oder localhost verfügbar.
lock() wirkt nur im Vollbild: Die Sperre greift erst, wenn das Dokument per requestFullscreen() im Vollbildmodus ist. Nutzer können die Sperre jederzeit aufheben, indem sie Esc gedrückt halten.
Einschränkungen in iframes: getLayoutMap() kann in iframes durch die Permissions Policy keyboard-map blockiert sein. lock() ist in iframes grundsätzlich nicht verfügbar.
Datenschutz: Das Tastaturlayout ist ein zusätzliches Merkmal für Fingerprinting. Es sollte daher nur abgefragt werden, wenn es tatsächlich gebraucht wird.
getLayoutMap() liefert für manche Tasten wie Modifikatoren oder Funktionstasten keinen Eintrag. In dem Fall eine Ausweichlösung verwenden, z. B. layoutMap.get(code) ?? code.

Siehe auch

Keyboard Keyboard.lock() Keyboard.unlock() Navigator Navigator.clipboard