Les objets KeyboardEvent décrivent l'interaction d'un utilisateur avec le clavier. Chaque événement décrit une touche ; le type d'événement (keydown, keypress, ou keyup) identifie quel type d'activité a été effectué.

Note : KeyboardEvent indique exactement ce qui est en train de se passer sur une touche. Lorsque vous devez gérer une saisie de texte, utilisez l'événement input HTML5 à la place. Par exemple, si un utilisateur saisit du texte à partir d'un système d'écriture à la main comme une tablette PC, les événements touche peuvent ne pas être déclenchés.

Constructeur

KeyboardEvent()
Crée un objet KeyboardEvent.

Méthodes

Cette interface hérite également des méthodes de ses parents, UIEvent et Event.

KeyboardEvent.getModifierState()
Retourne un Boolean indiquant si une touche modifcatrice, telle que AltShiftCtrl, ou Meta, était pressée quand l'évènement a été créé.
KeyboardEvent.initKeyEvent()
Initialise un objet KeyboardEvent. Ceci a été implémenté seulement par Gecko (d'autres utilisaient KeyboardEvent.initKeyboardEvent()) et ne devrait plus être utilisé. La manière moderne standard consiste à utiliser le constructeur KeyboardEvent().
KeyboardEvent.initKeyboardEvent()
Initialise un objet KeyboardEvent. Cela n'a jamais été implémenté par Gecko (qui utilisait KeyboardEvent.initKeyEvent()) et ne devrait plus être utilisé. La manière moderne standard consiste à utiliser le constructeur KeyboardEvent().

Propriétés

Cette interface hérite également des propriétés de ses parents, UIEvent et Event.

KeyboardEvent.altKey Lecture seule
Returne un Boolean qui est true si la touche Alt (Option ou  sous OS X) était active quand l'évènement touche a été généré.
KeyboardEvent.char Lecture seule
Renvoie une DOMString représentant la valeur de caractère de la touche. Si la touche correspond à un caractère imprimable, cette valeur est une chaîne Unicode non vide contenant ce caractère. Si la touche n'a pas de représentation imprimable, il s'agit d'une chaîne vide.

Note : si la touche est utilisée comme une macro insérant plusieurs caractères, la valeur de cet attribut est la chaîne entière, pas seulement le premier caractère.

Avertissement : cela a été supprimé des DOM Level 3 Events. C'est pris en charge uniquement sur IE9 + et Microsoft Edge.

KeyboardEvent.charCode Lecture seule
Retourne un Number représentant le numéro de référence Unicode de la touche ; cet attribut est utilisé uniquement par l'événement keypress. Pour les touches dont l'attribut char contient plusieurs caractères, il s'agit de la valeur Unicode du premier caractère de cet attribut. Dans Firefox 26, cela retourne des codes pour les caractères imprimables.

Avertissement : cet attribut est obsolète : vous devriez utiliser KeyboardEvent.key à la place, si disponible.

KeyboardEvent.code Lecture seule
Retourne une DOMString avec la valeur du code de la touche représentée par l'événement.
KeyboardEvent.ctrlKey Lecture seule
Retourne un Boolean qui est true si la touche Ctrl était active lorsque l'événement touche a été généré.
KeyboardEvent.isComposing Lecture seule
Renvoie un Boolean qui est true si l'événement est déclenché après compositionstart et avant compositionend.
KeyboardEvent.key Lecture seule
Retourne une DOMString représentant la valeur de touche de la touche représentée par l'événement.
KeyboardEvent.keyCode  Lecture seule
Retourne un Number représentant un code numérique dépendant du système et de l'implémentation, identifiant la valeur non modifiée de la touche pressée.
Avertissement : cet attribut est obsolète. vous devriez utiliser KeyboardEvent.key à la place, si disponible.
KeyboardEvent.keyIdentifier Lecture seule
Cette propriété n'est pas standard et a été abandonnée en faveur de KeyboardEvent.key. Elle faisait partie d'une ancienne version de DOM Level 3 Events.
KeyboardEvent.keyLocation Lecture seule
C'est un alias obsolète non standard pour KeyboardEvent.location. Il faisait partie d'une ancienne version de DOM Level 3 Events.
KeyboardEvent.locale Lecture seule
Retourne une DOMString représentant une chaîne de paramètres régionaux indiquant les paramètres régionaux pour lesquels le clavier est configuré. Cela peut être une chaîne vide si le navigateur ou l'appareil ne connaît pas les paramètres régionaux du clavier.
Note : cela ne décrit pas les paramètres régionaux des données entrées. Un utilisateur peut utiliser une disposition du clavier donnée, tout en saisissant du texte dans une autre langue.
KeyboardEvent.location Lecture seule
Retourne un Number représentant l'emplacement de la touche du clavier ou tout autre dispositif d'entrée.
KeyboardEvent.metaKey Lecture seule
Retourne un Boolean qui est true si la touche Meta (sur les claviers Mac, la touche ⌘ Command ; sur les claviers Windows, la touche Windows ()) était active quand l'évènement touche a été généré.
KeyboardEvent.repeat Lecture seule
Retourne un Booléen qui est true si la touche est maintenue enfoncée de telle sorte qu'elle se répète automatiquement.
KeyboardEvent.shiftKey Lecture seule
Retourne un Boolean qui est true si la touche Shift était active quand l'évènement touche a été généré.
KeyboardEvent.which Lecture seule
Retourne un Number représentant un code numérique dépendant du système et de l'implémentation, identifiant la valeur non modifiée de la touche pressée ; c'est généralement le même que keyCode.
Avertissement : cet attribut est obsolète ; vous devriez utiliser KeyboardEvent.key à la place, si disponible.

Notes

Les événements existants sont keydown, keypress et keyup. Pour la plupart des touches, Gecko génère une suite d'événements touche comme suit :

  1. lorsque la touche est d'abord enfoncée, l'événement keydown est envoyé ;
  2. si la touche n'est pas une touche de modification, l'événement keypress est envoyé ;
  3. lorsque l'utilisateur relâche la touche, l'événement keyup est envoyé.

Cas particuliers

Certaines touches inversent l'état d'un voyant lumineux ; celles-ci comprennent des touches telles que Caps Lock, Num Lock et Scroll Lock. Sous Windows et Linux, ces touches génèrent uniquement les événements keydown et keyup.

Sous Linux, Firefox 12 et les versions antérieures ont également envoyé l'événement keypress pour ces touches.

Cependant, une limitation du modèle d'événement Mac OS X fait que Caps Lock ne génère que l'événement keydown. Num Lock était supporté sur certains modèles d'ordinateurs portables plus anciens (modèles 2007 et plus anciens), mais depuis lors, Mac OS X n'a pas supporté Num Lock même sur les claviers externes. Sur les MacBooks plus anciens avec une touche Num Lock, cette touche ne génère aucun événement touche. Gecko supporte la touche Scroll Lock si un clavier externe ayant une touche F14 est connecté. Dans certaines anciennes versions de Firefox, cette touche générait un événement keypress ; ce comportement incohérent était le bug 602812.

Gestion de l'auto-répétition

 

Lorsqu'une touche est maintenue enfoncée, elle commence à se répéter automatiquement. Cela a pour résultat qu'une suite d'événements similaire à ce qui suit est générée :

  1. keydown
  2. keypress
  3. keydown
  4. keypress
  5. << répétition jusqu'à ce que l'utilisateur relâche la touche >>
  6. keyup

C'est ce que la spécification DOM Niveau 3 dit qu'il devrait se produire. Cependant, il y a quelques mises en garde, comme décrit ci-dessous.

 

Auto-répétition sur certains environnements GTK tels que Ubuntu 9.4

Dans certains environnements basés sur GTK, l'auto-répétition génère automatiquement un événement natif lors de la répétition automatique, et Gecko n'a aucun moyen de connaître la différence entre une suite répétée de touches et une répétition automatique. Sur ces plateformes, une touche auto-répétée génère donc la suite d'événements suivante :

  1. keydown
  2. keypress
  3. keyup
  4. keydown
  5. keypress
  6. keyup
  7. << répétition jusqu'à ce que l'utilisateur relâche la touche >>
  8. keyup

Dans ces environnements, malheureusement, il n'y a aucun moyen pour que le contenu Web puisse faire la différence entre les touches répétées automatiquement et les touches qui sont simplement pressées à plusieurs reprises.

Gestion de l'auto-répétition avant Gecko 5.0

Avant Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), la gestion du clavier était moins cohérente entre les plates-formes.

Windows
Le comportement de la répétition automatique est le même que dans Gecko 4.0 et ultérieur.
Mac
Après l'événement keydown initial, seuls les événements keypress sont envoyés jusqu'à ce que l'événement keyup se produise ; les événements de clavier intermédiaires ne sont pas envoyés.
Linux
Le comportement de l'événement dépend de la plate-forme particulière. Il se comportera comme Windows ou Mac suivant ce que fait le modèle d'événement natif.

Note : le déclenchement manuel d'un événement ne génère pas l'action par défaut associée à cet événement. Par exemple, le déclenchement manuel d'un événement touche n'entraîne pas l'apparition de cette lettre dans une zone de saisie de texte ayant la focalisation. Dans le cas des événements de l'interface utilisateur, cela est important pour des raisons de sécurité, car cela empêche les scripts de simuler les actions de l'utilisateur interagissant avec le navigateur lui-même.

Exemple

<!DOCTYPE html>
<html>
<head>
<script>
'use strict';

document.addEventListener('keydown', (event) => {
  const nomTouche = event.key;

  if (nomTouche === 'Control') {
    // Pas d'alerte si seule la touche Control est pressée.
    return;
  }

  if (event.ctrlKey) {
    // Même si event.key n'est pas 'Control' (par ex., 'a' is pressed),
    // event.ctrlKey peut être true si la touche Ctrl est pressée dans le même temps.
    alert(`Combinaison de ctrlKey + ${nomTouche}`);
  } else {
    alert(`Touche pressée ${nomTouche}`);
  }
}, false);

document.addEventListener('keyup', (event) => {
  const nomTouche = event.key;

  // Dès que l'utilisateur relâche la touche Ctrl, la touche n'est plus active.
  // Aussi event.ctrlKey est false.
  if (nomTouche === 'Control') {
    alert('La touche Control a été relâchée');
  }
}, false);

</script>
</head>

<body>
</body>
</html>

Spécifications

Spécification Statut Commentaire
UI Events
La définition de 'KeyboardEvent' dans cette spécification.
Version de travail  

La spécification d'interface KeyboardEvent est passée par de nombreuses versions préliminaires, d'abord sous DOM Events Level 2 où elle a été supprimée du fait qu'aucun consensus n'avait émergé, puis sous DOM Events Level 3. Cela conduit à l'implémentation de méthodes d'initialisation non standard, la version ancienne DOM Events Level 2, KeyboardEvent.initKeyEvent() par les navigateurs Gecko et la version prémiminaire DOM Events Level 3, KeyboardEvent.initKeyboardEvent() par d'autres navigateurs. Tous deux ont été remplacés par l'utilisation moderne d'un constructeur : KeyboardEvent().

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidEdge MobileFirefox pour AndroidOpera pour AndroidSafari pour iOSSamsung Internet
Support simpleChrome Support complet OuiEdge Support complet OuiFirefox Support complet OuiIE Support complet OuiOpera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet OuiOpera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android ?
KeyboardEventChrome Support complet OuiEdge ? Firefox Support complet 31IE Aucun support NonOpera Support complet OuiSafari ? WebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile ? Firefox Android Support complet 31Opera Android Support complet OuiSafari iOS ? Samsung Internet Android ?
altKeyChrome Support complet OuiEdge Support complet OuiFirefox Support complet OuiIE Support complet OuiOpera Support complet OuiSafari Support complet OuiWebView Android ? Chrome Android ? Edge Mobile Support complet OuiFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
charCode
ObsolèteNon-standard
Chrome Support complet 26Edge Support complet OuiFirefox Support complet 3IE Support complet 9Opera Support complet 12.1Safari Support complet 5.1WebView Android ? Chrome Android ? Edge Mobile Support complet OuiFirefox Android Support complet OuiOpera Android ? Safari iOS Support complet 5.1Samsung Internet Android ?
codeChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
ctrlKeyChrome Support complet OuiEdge Support complet OuiFirefox Support complet OuiIE Support complet OuiOpera Support complet OuiSafari Support complet OuiWebView Android ? Chrome Android ? Edge Mobile Support complet OuiFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
isComposingChrome Support complet 56Edge ? Firefox Support complet 31IE Aucun support NonOpera Support complet 43Safari Aucun support NonWebView Android Support complet 56Chrome Android Support complet 56Edge Mobile ? Firefox Android Support complet 31Opera Android Support complet 43Safari iOS Aucun support NonSamsung Internet Android ?
keyChrome Support complet 51Edge Support complet OuiFirefox Support complet 23IE Support complet 9
Notes
Support complet 9
Notes
Notes IE's impementation does not completely match the current spec because it is based on an older version of the spec.
Opera Support complet 38Safari Support complet OuiWebView Android Support complet 51Chrome Android Support complet 51Edge Mobile Support complet OuiFirefox Android Support complet 23Opera Android Support complet 38Safari iOS Support complet OuiSamsung Internet Android ?
keyCode
ObsolèteNon-standard
Chrome Support complet 26Edge Support complet OuiFirefox Support complet 3IE Support complet 6Opera Support complet 11.6Safari Support complet 5WebView Android ? Chrome Android ? Edge Mobile Support complet OuiFirefox Android ? Opera Android ? Safari iOS Support complet 5.1Samsung Internet Android ?
keyIdentifier
ObsolèteNon-standard
Chrome Aucun support 26 — 54Edge ? Firefox Aucun support NonIE Aucun support NonOpera Aucun support 15 — 41Safari Support complet 5.1WebView Android Aucun support ? — 54Chrome Android Aucun support 26 — 54Edge Mobile ? Firefox Android Aucun support NonOpera Android Aucun support ? — 41Safari iOS Support complet 5.1Samsung Internet Android ?
locationChrome Support complet OuiEdge Support complet OuiFirefox Support complet 15IE Support complet 9Opera Support complet OuiSafari Support complet 6.1WebView Android ? Chrome Android ? Edge Mobile Support complet OuiFirefox Android Support complet 15Opera Android ? Safari iOS Support complet 8Samsung Internet Android ?
metaKeyChrome Support complet OuiEdge Support complet OuiFirefox Support complet OuiIE Support complet OuiOpera Support complet OuiSafari Support complet OuiWebView Android ? Chrome Android ? Edge Mobile Support complet OuiFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
repeatChrome Support complet OuiEdge Aucun support NonFirefox Support complet 28IE Aucun support NonOpera ? Safari Support complet 10.1WebView Android ? Chrome Android ? Edge Mobile Aucun support NonFirefox Android Support complet 28Opera Android ? Safari iOS Support complet 10.1Samsung Internet Android ?
shiftKeyChrome Support complet OuiEdge Support complet OuiFirefox Support complet OuiIE Support complet OuiOpera Support complet OuiSafari Support complet OuiWebView Android ? Chrome Android ? Edge Mobile Support complet OuiFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
which
ObsolèteNon-standard
Chrome Support complet 4Edge Support complet OuiFirefox Support complet 2
Notes
Support complet 2
Notes
Notes Firefox also implements this property on the UIEvent interface.
IE Support complet 9Opera Support complet 10.1Safari Support complet 5.1WebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet Oui
Notes
Support complet Oui
Notes
Notes Firefox also implements this property on the UIEvent interface.
Opera Android ? Safari iOS Support complet 5.1Samsung Internet Android ?
getModifierStateChrome Support complet 31Edge Support complet OuiFirefox Support complet 15IE Support complet 9Opera Aucun support NonSafari Aucun support NonWebView Android Support complet 4.4.3Chrome Android Support complet 31Edge Mobile Support complet OuiFirefox Android Support complet 15Opera Android Aucun support NonSafari iOS Aucun support NonSamsung Internet Android ?
DOM_KEY_LOCATION_LEFTChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
DOM_KEY_LOCATION_NUMPADChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
DOM_KEY_LOCATION_RIGHTChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
DOM_KEY_LOCATION_STANDARDChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Compatibilité inconnue  
Compatibilité inconnue
Fonctionnalité non-standard. Celle-ci peut être incorrectement supportée par les autres navigateurs.
Fonctionnalité non-standard. Celle-ci peut être incorrectement supportée par les autres navigateurs.
Obsolète. Les nouveaux sites web ne doivent pas utiliser cette fonctionnalité.
Obsolète. Les nouveaux sites web ne doivent pas utiliser cette fonctionnalité.
Voir les notes d'implémentation.
Voir les notes d'implémentation.

Voir aussi

Étiquettes et contributeurs liés au document

Dernière mise à jour par : wbamberg,