Capturer des touches avec l'API Keyboard Lock

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

Thomas Steiner

De plus en plus d'utilisateurs passent la majeure partie de leur temps dans le navigateur. Les sites Web, les jeux, le streaming de bureau à distance et le streaming d'applications hautement interactifs 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 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 l'OS hôte (voir la section Compatibilité avec les navigateurs).

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

Utiliser l'API Keyboard Lock

L'interface Keyboard de l'API Keyboard fournit des fonctions qui activent et désactivent la capture des pressions sur les touches du clavier physique, ainsi que des informations sur la disposition du clavier de l'utilisateur.

Conditions préalables

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

await document.documentElement.requestFullscreen();

Détection de fonctionnalités

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

Capturer toutes les touches

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

navigator.keyboard.lock();

Capturer des touches spécifiques

L'exemple suivant capture les touches W, A, S et D. Il capture ces touches, quels que soient les modificateurs utilisés avec la pression sur la touche. En supposant que vous utilisiez 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é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épondre 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éverrouiller le 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émo

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

Considérations de sécurité

L'un des problèmes liés à cette API est qu'elle peut être utilisée pour saisir toutes les touches et (en association 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 pour l'utilisateur de déverrouiller le clavier, même si toutes les touches sont demandées par l'API. Dans Chrome, cette échappatoire consiste à appuyer de manière prolongée (deux secondes) sur la touche Échap pour quitter le verrouillage du clavier.

Remerciements

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