Capturer des touches avec l'API Keyboard Lock

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

Thomas Steiner

De plus en plus d'utilisateurs passent la majeure partie de leur temps sur le navigateur. C'est pourquoi les sites Web, les jeux, le streaming depuis un bureau à distance et le streaming d'application ont pour objectif d'offrir une expérience immersive en plein écran. Pour ce faire, les sites doivent avoir accès à des touches spéciales et à des raccourcis clavier en mode plein écran afin de pouvoir les utiliser pour la navigation, les menus ou les jeux. Les touches Esc, Esc+Esc, Esc+Esc et Esc+Esc peuvent être requises.

Par défaut, ces clés 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 le système d'exploitation hôte (voir Compatibilité du navigateur).

Ubuntu Linux s'exécute en streaming dans un onglet du navigateur dans Chrome sous macOS (pas encore en mode plein écran).
Le problème: un bureau à distance Ubuntu Linux diffusé en streaming ne s'exécute pas en mode plein écran et sans verrouillage actif du clavier. Par conséquent, les touches système sont 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 pressions sur les touches du clavier physique et d'obtenir des informations sur la disposition du clavier de l'utilisateur.

Prérequis

Deux types de plein écran sont disponibles dans les navigateurs récents: celui déclenché par JavaScript via l'API Fullscreen et par l'utilisateur via un raccourci clavier. L'API Keyboard Lock n'est disponible que lorsque le mode plein écran JavaScript déclenché est actif. Voici un exemple de plein écran déclenché par JavaScript:

await document.documentElement.requestFullscreen();

Détection de fonctionnalités

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

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

Verrouillage du 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 la totalité des touches du clavier physique. Cette méthode ne peut capturer que les clés auxquelles l'accès a été accordé par le système d'exploitation sous-jacent. La méthode lock() nécessite un tableau d'un ou plusieurs codes de touche à verrouiller. Si aucun code de clé n'est fourni, toutes les clés seront verrouillées. Une liste de valeurs de code de touche valides est disponible dans la spécification des valeurs de code des événements clavier de l'interface utilisateur.

Capture de toutes les clés...

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

navigator.keyboard.lock();

Capturer des clés spécifiques

L'exemple suivant capture les clés W, A, S et D. Il capture ces touches quels que soient les modificateurs utilisés en cas de pression sur les touches. Avec une disposition QWERTY américaine, l'enregistrement d'"KeyW" garantit que les combinaisons W, Maj+W, Ctrl+W, Ctrl+Maj+W, ainsi que toutes les autres combinaisons de modificateurs de touches avec W sont envoyées à l'application. Il en va de même pour "KeyA", "KeyS" et "KeyD".

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

Vous pouvez réagir aux pressions sur les 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éverrouillage du clavier

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

navigator.keyboard.unlock();

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

Démonstration

Vous pouvez tester l'API Keyboard Lock en exécutant la démonstration sur Glitch. N'oubliez pas de consulter le code source. Cliquez sur le bouton "Activer le mode plein écran" ci-dessous pour lancer la démo dans une nouvelle fenêtre afin de pouvoir passer en mode plein écran.

Considérations de sécurité

L'un des problèmes avec cette API est qu'elle pourrait être utilisée pour récupérer toutes les clés et (conjointement 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 offre à l'utilisateur un moyen de désactiver le verrouillage du clavier, même si toutes les touches sont demandées par l'API. Dans Chrome, ce mécanisme de sortie consiste à appuyer sur la touche Esc de deux secondes pour déclencher une sortie à partir du verrouillage du clavier.

Remerciements

Cet article a été lu par Joe Medley et Kayce Basques. La spécification de verrouillage du clavier a été rédigée par Gary Kacmarcik et Jamie Walch. Image héros par Ken Suarez sur Unsplash.