Capturer des touches avec l'API Keyboard Lock

Offrez une expérience immersive en plein écran pour divers cas d'utilisation, y compris les sites Web interactifs, les jeux, et le streaming d'applications ou de bureau à distance.

Thomas Steiner

Comme les utilisateurs passent de plus en plus de temps dans leur navigateur, les sites Web interactifs, les jeux, le streaming de bureau à distance et le streaming d'applications s'efforcent de proposer une expérience immersive en plein écran. Pour ce faire, les sites doivent avoir accès à des touches et des raccourcis clavier spéciaux lorsqu'ils sont en mode plein écran, afin de pouvoir les utiliser pour la navigation, les menus ou les jeux. Voici quelques exemples de touches qui peuvent être requises : Échap, Alt+Tab, Cmd+` et Ctrl+N.

Par défaut, ces touches ne sont pas disponibles pour l'application Web, car elles sont capturées par le navigateur ou le système d'exploitation sous-jacent. L'API Keyboard Lock permet aux sites Web d'utiliser toutes les touches disponibles autorisées par l'OS hôte (voir Compatibilité avec les navigateurs).

Ubuntu Linux diffusé dans un onglet de navigateur dans Chrome sur macOS (pas encore en mode plein écran).
Le problème : un bureau à distance Ubuntu Linux diffusé en streaming qui ne s'exécute pas en mode plein écran et sans verrouillage actif du clavier. Les touches système sont donc toujours capturées par le système d'exploitation hôte macOS, et l'expérience n'est pas encore immersive.

Utiliser l'API Keyboard Lock

L'interface Keyboard de l'API Keyboard fournit des fonctions qui permettent d'activer ou de désactiver la capture des touches du clavier physique, ainsi que d'obtenir des informations sur la disposition du clavier de l'utilisateur.

Conditions préalables

Il existe deux types de plein écran dans les navigateurs récents : celui initié par JavaScript via l'API Fullscreen et celui initié par l'utilisateur via un raccourci clavier. L'API Keyboard Lock n'est disponible que lorsque le plein écran initié par JavaScript est actif. Voici un exemple de plein écran initié par JavaScript :

await document.documentElement.requestFullscreen();

Détection de caractéristiques

Vous pouvez utiliser le modèle suivant pour vérifier si l'API Keyboard Lock est compatible :

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

Verrouiller le clavier

La méthode lock() de l'interface Keyboard renvoie une promesse après avoir activé la capture des pressions sur les touches pour une partie ou l'ensemble des touches du clavier physique. Cette méthode ne peut capturer que les clés auxquelles le système d'exploitation sous-jacent accorde l'accès. La méthode lock() utilise un tableau d'un ou de plusieurs codes de touche à verrouiller. Si aucun code de clé n'est fourni, toutes les clés seront verrouillées. La liste des valeurs de code de touche valides est disponible dans la spécification UI Events KeyboardEvent code Values.

Capturer toutes les touches

L'exemple suivant capture toutes les pressions sur les touches.

navigator.keyboard.lock();

Capturer des clés spécifiques

L'exemple suivant capture les touches W, A, S et D. Il capture ces touches, quels que soient les modificateurs utilisés lors de l'appui sur la touche. En supposant une disposition QWERTY américaine, l'enregistrement de "KeyW" garantit que W, Maj + W, Ctrl + W, Ctrl + Maj + W et toutes les autres combinaisons de touches de modification avec W sont envoyés à l'application. Il en va de même pour "KeyA", "KeyS" et "KeyD".

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

Vous pouvez répondre aux pressions de touches capturées à l'aide d'événements de clavier. Par exemple, ce code utilise l'événement 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.
  }
});

Déverrouiller le clavier

La méthode unlock() déverrouille toutes les touches capturées par la méthode lock() et renvoie de manière synchrone.

navigator.keyboard.unlock();

Lorsqu'un document est fermé, le navigateur appelle toujours implicitement unlock().

Démo

Vous pouvez tester l'API Keyboard Lock en exécutant cette démonstration. N'oubliez pas de consulter le code source. Si vous cliquez sur le bouton "Passer en plein écran" ci-dessous, la démo s'ouvre dans une nouvelle fenêtre pour pouvoir passer en mode plein écran.

Points à noter concernant la sécurité

Cette API pourrait être utilisée pour récupérer toutes les touches et (en conjonction avec l'API Fullscreen et l'API PointerLock) empêcher l'utilisateur de quitter la page Web. Pour éviter cela, la spécification exige que le navigateur fournisse un moyen à l'utilisateur de quitter le verrouillage du clavier, même si toutes les touches sont demandées par l'API. Dans Chrome, cette issue de secours consiste à appuyer de manière prolongée (pendant deux secondes) sur la touche Esc pour quitter le verrouillage du clavier.

Remerciements

Cet article a été examiné par Joe Medley et Kayce Basques. La spécification Keyboard Lock a été rédigée par Gary Kacmarcik et Jamie Walch.