Toetsen vastleggen met de Keyboard Lock API

Bied een meeslepende beleving op volledig scherm voor verschillende toepassingen, waaronder interactieve websites, games en streaming van externe desktops of apps.

Thomas Steiner

Steeds meer gebruikers brengen het grootste deel van hun tijd door in de browser. Rijk interactieve websites, games, streaming op afstand en app-streaming proberen een meeslepende ervaring op volledig scherm te bieden. Hiervoor hebben sites toegang nodig tot speciale toetsen en sneltoetsen terwijl ze in de modus voor volledig scherm staan, zodat ze kunnen worden gebruikt voor navigatie, menu's of games. Enkele voorbeelden van toetsen die nodig kunnen zijn, zijn Esc, Alt + Tab, Cmd + ` en Ctrl + N.

Standaard zijn deze toetsen niet beschikbaar voor de web-app omdat ze worden vastgelegd door de browser of het onderliggende besturingssysteem. Met de Keyboard Lock API kunnen websites alle beschikbare toetsen gebruiken die zijn toegestaan door het host-OS (zie Browsercompatibiliteit).

Ubuntu Linux gestreamd naar een browsertabblad in macOS Chrome (nog niet in de modus Volledig scherm).
Het probleem: een gestreamde Ubuntu Linux-remote desktop die niet in de modus Volledig scherm wordt uitgevoerd en zonder actieve toetsenbordvergrendeling, waardoor systeemtoetsen nog steeds worden vastgelegd door het macOS-hostbesturingssysteem en de functionaliteit nog niet meeslepend is.

De Keyboard Lock API gebruiken

De Keyboard-interface van de Keyboard API biedt functies die het vastleggen van toetsaanslagen op het fysieke toetsenbord aan- en uitzetten en informatie ophalen over de toetsenbordindeling van de gebruiker.

Vereiste

In moderne browsers zijn er 2 typen volledig scherm beschikbaar: door JavaScript gestart via de Fullscreen API en door de gebruiker gestart via een sneltoets. De Keyboard Lock API is alleen beschikbaar als Door JavaScript gestart volledig scherm actief is. Hier is een voorbeeld van een volledig scherm dat door JavaScript is gestart:

await document.documentElement.requestFullscreen();

Functiedetectie

Je kunt het volgende patroon gebruiken om te checken of de Keyboard Lock API wordt ondersteund:

if ('keyboard' in navigator && 'lock' in navigator.keyboard) {
  // Supported!
}

Het toetsenbord vergrendelen

De methode lock() van de interface Keyboard retourneert een promise nadat de registratie van toetsaanslagen is aangezet voor een of alle toetsen op het fysieke toetsenbord. Met deze methode kunnen alleen sleutels worden vastgelegd waartoe het onderliggende besturingssysteem toegang heeft verleend. De methode lock() gebruikt een array van een of meer sleutelcodes om te vergrendelen. Als er geen sleutelcodes worden verstrekt, worden alle sleutels vergrendeld. Een lijst met geldige sleutelcodewaarden is beschikbaar in de specificatie UI Events KeyboardEvent code Values.

Alle toetsen vastleggen

In het volgende voorbeeld worden alle toetsaanslagen vastgelegd.

navigator.keyboard.lock();

Specifieke toetsen vastleggen

In het volgende voorbeeld worden de toetsen W, A, S en D vastgelegd. Deze toetsen worden vastgelegd, ongeacht welke functietoetsen worden gebruikt bij het indrukken van de toets. Uitgaande van een Amerikaanse QWERTY-indeling zorgt de registratie van "KeyW" ervoor dat W, Shift + W, Control + W, Control + Shift + W en alle andere combinaties van functietoetsen met W naar de app worden gestuurd. Hetzelfde geldt voor "KeyA", "KeyS" en "KeyD".

await navigator.keyboard.lock([
  "KeyW",
  "KeyA",
  "KeyS",
  "KeyD",
]);

Je kunt reageren op vastgelegde toetsaanslagen met toetsenbordgebeurtenissen. Deze code gebruikt bijvoorbeeld de gebeurtenis onkeydown:

document.addEventListener('keydown', (event) => {
  if ((event.code === 'KeyA') && !(event.ctrlKey || event.metaKey)) {
    // Do something when the 'A' key was pressed, but only
    // when not in combination with the command or control key.
  }
});

Het toetsenbord ontgrendelen

De methode unlock() ontgrendelt alle toetsen die zijn vastgelegd door de methode lock() en keert synchroon terug.

navigator.keyboard.unlock();

Als een document wordt gesloten, roept de browser altijd impliciet unlock() aan.

Demo

Je kunt de Keyboard Lock API testen door deze demo uit te voeren. Check de broncode. Als je hieronder op de knop Volledig scherm openen klikt, wordt de demo in een nieuw venster geopend, zodat deze in de modus voor volledig scherm kan worden geopend.

Beveiligingsoverwegingen

Een probleem met deze API is dat deze kan worden gebruikt om alle toetsen te pakken en (in combinatie met de Fullscreen API en de PointerLock API) te voorkomen dat de gebruiker de webpagina verlaat. Om dit te voorkomen, vereist de specificatie dat de browser de gebruiker een manier biedt om de toetsenbordvergrendeling te verlaten, zelfs als alle toetsen door de API worden aangevraagd. In Chrome is deze ontsnappingsroute een lange (2 seconden) druk op de Esc-toets om de toetsenbordvergrendeling te verlaten.

Erkenning

Dit artikel is beoordeeld door Joe Medley en Kayce Basques. De specificatie voor toetsenbordvergrendeling is geschreven door Gary Kacmarcik en Jamie Walch.