Keyboard.lock() — Methode · JavaScript-Referenz

Signatur

Keyboard.prototype.lock(keyCodes)

Beschreibung

navigator.keyboard.lock() gehört zur Keyboard Lock API. Normalerweise verarbeiten Browser und Betriebssystem bestimmte Tastenkombinationen selbst, bevor die Seite sie sieht, zum Beispiel Esc, Alt+Tab, Strg+W oder die Windows-Taste. Mit lock() gehen diese Tastendrücke stattdessen als ganz normale keydown- und keyup-Ereignisse an die Webanwendung.

Die Methode ist für Anwendungen im Vollbildmodus gedacht, die die ganze Tastatur brauchen. Typische Beispiele sind Browser-Spiele (etwa mit Esc als Menütaste), Remote-Desktop- und VNC-Clients, Cloud-Gaming und Terminal-Emulatoren. Ohne Argument werden alle Tasten gesperrt. Als Argument kannst du ein Array mit Werten von KeyboardEvent.code übergeben (z. B. "KeyW", "Escape", "MetaLeft"), dann werden nur diese Tasten gesperrt.

Jeder neue Aufruf von lock() ersetzt die vorherige Sperre vollständig. Die Tasten werden also nicht addiert. Aufgehoben wird die Sperre mit navigator.keyboard.unlock(). Das passiert auch automatisch, wenn der Vollbildmodus endet oder das Dokument gewechselt wird. In Chromium wirkt die Sperre nur, solange die Seite über Element.requestFullscreen() im Vollbildmodus ist. Außerhalb davon wird das Promise zwar erfüllt, aber es werden keine Tasten abgefangen.

Parameter

Name	Typ	Default	Beschreibung
$keyCodes	string[]	undefined (alle Tasten)	Array mit Werten von `KeyboardEvent.code`, die gesperrt werden sollen, z. B. `["KeyW", "KeyA", "KeyS", "KeyD", "Escape"]`. Ohne Argument oder bei einem leeren Array werden alle Tasten gesperrt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das ohne Wert erfüllt wird, sobald die Sperre aktiv ist. Abgelehnt wird es mit:

AbortError: Ein weiterer lock()-Aufruf kam, bevor der vorherige abgeschlossen war.
InvalidAccessError: Ein Eintrag in keyCodes ist kein gültiger KeyboardEvent.code-Wert.
InvalidStateError: Die Methode wurde nicht im obersten Browsing-Kontext aufgerufen (z. B. in einem iframe) oder das Dokument ist nicht aktiv.

Beispiele

Vollbild starten und alle Tasten sperren

const startButton = document.querySelector('#start');
const game = document.querySelector('#game');

startButton.addEventListener('click', async () => {
  // Vollbild muss durch eine Nutzeraktion ausgelöst werden
  await game.requestFullscreen();

  if ('keyboard' in navigator && 'lock' in navigator.keyboard) {
    await navigator.keyboard.lock();
    console.log('Alle Tasten gesperrt');
  } else {
    console.log('Keyboard Lock API wird nicht unterstützt');
  }
});

document.addEventListener('keydown', (event) => {
  // Escape kommt jetzt bei der Seite an, statt den Vollbildmodus zu beenden
  if (event.code === 'Escape') {
    event.preventDefault();
    console.log('Spielmenü öffnen');
  }
});

Alle Tasten gesperrt Spielmenü öffnen

Nur bestimmte Tasten sperren (WASD + Escape)

const lockGameKeys = async () => {
  try {
    await navigator.keyboard.lock(['KeyW', 'KeyA', 'KeyS', 'KeyD', 'Escape']);
    console.log('Spieltasten gesperrt');
  } catch (error) {
    console.error(`${error.name}: ${error.message}`);
  }
};

document.documentElement.requestFullscreen().then(lockGameKeys);

Spieltasten gesperrt

Sperre an den Vollbildmodus koppeln

document.addEventListener('fullscreenchange', async () => {
  if (!('keyboard' in navigator)) return;

  if (document.fullscreenElement) {
    // Remote-Desktop: Systemkürzel wie Alt+Tab oder Meta an die Gegenstelle weiterreichen
    await navigator.keyboard.lock(['MetaLeft', 'MetaRight', 'AltLeft', 'Tab', 'Escape']);
    console.log('Sperre aktiv');
  } else {
    navigator.keyboard.unlock();
    console.log('Sperre aufgehoben');
  }
});

Sperre aktiv Sperre aufgehoben

// Wichtig · Fallstricke

Browser-Unterstützung: Die API ist experimentell und gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Prüfe deshalb vorher mit 'keyboard' in navigator, ob sie verfügbar ist.
Sicherer Kontext: Die API steht nur über HTTPS (oder localhost) zur Verfügung, und nur im obersten Dokument. In iframes schlägt der Aufruf fehl.
Nur im Vollbildmodus wirksam: Chromium fängt Tasten nur ab, solange der Vollbildmodus über requestFullscreen() aktiv ist. Der Vollbildmodus über F11 zählt nicht.
Ausweg für Nutzer: Auch wenn Escape gesperrt ist, verlässt langes Drücken von Esc (etwa 2 Sekunden) den Vollbildmodus. Dabei endet auch die Sperre. Der Browser zeigt einen entsprechenden Hinweis an.
Kein Hinzufügen: Jeder Aufruf ersetzt die vorherige Tastenliste. Wenn du Tasten ergänzen willst, übergib die vollständige Liste erneut.
Manche Kombinationen kann das Betriebssystem grundsätzlich nicht an die Seite abgeben, z. B. Strg+Alt+Entf unter Windows.
Verwende physische code-Werte, nicht key-Werte. "KeyZ" meint unabhängig vom Tastaturlayout immer dieselbe physische Taste.

Siehe auch

Keyboard Keyboard.unlock() Navigator.keyboard Element.requestFullscreen() KeyboardEvent.code new KeyboardEvent()