Appuyez sur une touche et lisez chaque propriété du KeyboardEvent résultant : key, code, keyCode, which, location et les drapeaux ctrl, shift, alt et meta, plus un JSON copiable.
Appuyez sur une touche. Voyez exactement ce que le navigateur rapporte. Cliquez sur la zone de capture ci-dessous et appuyez sur n'importe quelle touche ou combinaison. Chaque propriété du KeyboardEvent est affichée côte à côte, pour que vous choisissiez la bonne pour votre gestionnaire de raccourci au lieu de deviner.
event.key
–
event.code
–
event.keyCode
–
event.which
–
event.location
–
Modificateurs maintenus
aucun
key, code et keyCode ne sont pas la même chose
Trois propriétés, trois questions différentes
Un KeyboardEvent expose plusieurs façons d'identifier une touche, et elles répondent à des questions véritablement différentes. event.key est le caractère ou la valeur nommée produite par l'appui après application de la disposition et des modificateurs. Appuyer sur la touche physique A donne a, ou A avec shift maintenu, ou une lettre tout autre sur une disposition Dvorak ou AZERTY. Les touches nommées arrivent sous forme de chaînes descriptives telles que Enter, Escape, ArrowLeft et F5.
event.code identifie plutôt la position physique de la touche, à l'aide d'un nom indépendant de la disposition tiré d'un clavier US théorique. La touche à la position de A est toujours KeyA, quelle que soit la disposition de l'utilisateur. Les chiffres de la rangée du haut sont Digit1 à Digit0, et le pavé numérique renvoie Numpad1 et consorts, si bien que vous pouvez distinguer les deux rangées de chiffres.
event.keyCode et son jumeau event.which sont les identifiants numériques hérités. Tous deux sont officiellement obsolètes, tous deux sont encore implémentés partout, et tous deux sont incohérents entre navigateurs pour la ponctuation. Ils valent la peine d'être lus quand vous maintenez du code ancien, mais la gestion de nouveaux raccourcis devrait utiliser key ou code.
Choisir entre key et code
La règle générale est simple : utilisez code quand la position compte et key quand le sens compte. Un jeu qui lie le déplacement à WASD veut code, car le groupe physique sous la main gauche du joueur doit rester au même endroit sur un clavier AZERTY même s'il produit ZQSD. Un éditeur de texte qui lie « enregistrer » à Ctrl+S veut key, car l'utilisateur pense en termes de la lettre S plutôt que de la touche à côté de A.
Les drapeaux de modificateurs sont des booléens séparés : ctrlKey, shiftKey, altKey et metaKey. Testez-les explicitement plutôt que de les déduire de key, et rappelez-vous que le modificateur de raccourci principal est Command sur macOS et Control ailleurs. Un motif courant consiste à accepter event.metaKey || event.ctrlKey pour qu'un seul gestionnaire couvre les deux plateformes.
event.location désambiguïse les touches dupliquées. Elle vaut 0 pour une touche standard, 1 pour le membre gauche d'une paire comme le Shift gauche, 2 pour le membre droit, et 3 pour une touche du pavé numérique.
Pièges pratiques
Toutes les touches ne produisent pas les événements attendus. Le navigateur réserve certaines combinaisons à lui-même - Ctrl+W, Ctrl+T et Command+Q ferment généralement les onglets ou quittent l'application avant qu'une page ne les voie, et preventDefault ne peut pas les récupérer. Testez tout raccourci dans une vraie fenêtre de navigateur plutôt que de supposer qu'il atteindra votre gestionnaire.
Maintenir une touche produit un flux d'événements de répétition avec event.repeat défini à true après le premier. Ignorez les répétitions quand le raccourci doit se déclencher une fois, et respectez-les quand le comportement est continu, comme le défilement ou le déplacement d'un curseur.
Enfin, keydown et keyup décrivent les touches, tandis que keypress décrivait les caractères et a été retiré de la norme. Pour la saisie de texte, préférez écouter l'événement input ou lire beforeinput, qui gèrent la composition, l'autocomplétion et les claviers mobiles de façon bien plus fiable que tout événement au niveau des touches.
FAQ
Dois-je utiliser key ou code pour un raccourci clavier ?
Utilisez `code` quand la position physique compte, comme le déplacement WASD dans un jeu. Utilisez `key` quand le sens compte, comme Ctrl+S pour enregistrer, afin que le raccourci suive la disposition propre à l'utilisateur.
Pourquoi keyCode est-il obsolète mais toujours fonctionnel ?
Il précède les événements conscients de la disposition et renvoie des nombres incohérents pour la ponctuation selon les navigateurs. Chaque moteur l'implémente encore pour compatibilité, mais la spécification oriente le nouveau code vers `key` et `code`.
Rien ne se passe quand j'appuie sur Ctrl+W ou Command+Q.
Ces combinaisons sont réclamées par le navigateur ou le système d'exploitation et sont gérées avant que la page ne les reçoive. Il n'y a aucun moyen fiable de les intercepter depuis une page web normale.
Comment écrire un raccourci unique qui fonctionne sur macOS et Windows ?
Acceptez l'un ou l'autre modificateur principal en testant `event.metaKey || event.ctrlKey`. Cela correspond à Command sur macOS et Control sur Windows et Linux sans brancher sur l'agent utilisateur.
Que signifie location 3 ?
La touche est sur le pavé numérique. Les locations 1 et 2 désignent le membre gauche et droit d'une paire dupliquée comme Shift ou Control, et 0 désigne une touche ordinaire sans doublon.
Puis-je utiliser ceci pour construire un gestionnaire de saisie de texte ?
Il vaut mieux écouter l'événement `input`. Les événements clavier manquent la composition des claviers IME, l'autocomplétion et de nombreux claviers virtuels mobiles, que `input` rapporte correctement.