diff options
Diffstat (limited to 'files/fr/web/api/keyboardevent/key/index.html')
| -rw-r--r-- | files/fr/web/api/keyboardevent/key/index.html | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/files/fr/web/api/keyboardevent/key/index.html b/files/fr/web/api/keyboardevent/key/index.html new file mode 100644 index 0000000000..cf51e90dc4 --- /dev/null +++ b/files/fr/web/api/keyboardevent/key/index.html @@ -0,0 +1,227 @@ +--- +title: KeyboardEvent.key +slug: Web/API/KeyboardEvent/key +tags: + - API + - DOM + - KeyboardEvent + - Lecture-seule + - Propriété + - Reference + - UI Events +translation_of: Web/API/KeyboardEvent/key +--- +<p>{{APIRef("DOM Events")}}</p> + +<p>La propriété en lecture seule de <code>key</code> de l'interface {{domxref("KeyboardEvent")}} retourne la valeur d’une ou plusieurs touches pressées par l’utilisateur, tout en tenant compte de l'état des touches de modification telles que la touche <kbd>Shift</kbd> (<em>majuscules</em>) ainsi que les paramètres régionaux des clavier et mise en page. Ce peut être l’une des valeurs suivantes :</p> + +<div class="pull-aside moreinfo"> +<h4 id="Valeurs_des_touches">Valeurs des touches</h4> + +<p>Voir une liste complète des <a href="https://developer.mozilla.org/fr/docs/Web/API/KeyboardEvent/key/Key_Values">valeurs de touches</a></p> +</div> + +<ul> + <li> + <p>Si la valeur a une représentation d’impression, ce sera une chaîne de caractères Unicode non vide</p> + </li> + <li>Si la valeur est une touche de contrôle, une des <a href="#Key_values">valeurs de touches pré-définies</a>.</li> + <li>Si l’<code>KeyboardEvent</code> est causé par l’appui sur une touche morte, la valeur de la touche sera "<code>Dead</code>".</li> + <li>Certaines touches de clavier spécialisées (telles que les touches étendues de contrôle des médias sur les claviers multimédias) ne génèrent pas de codes de touches sous Windows ; à la place, ils déclenchent les événements <code>WM_APPCOMMAND</code>. Ces événements sont connectés aux événements de clavier DOM et sont répertoriés parmi les «codes de touche virtuelle» pour Windows, même s'ils ne sont pas réellement des codes de touche.</li> + <li>Si la valeur ne peut être identifiée, '<code>Unidentified</code>' sera retourné.</li> +</ul> + +<h2 id="Séquence_KeyboardEvent">Séquence KeyboardEvent</h2> + +<p>Les événements <code>KeyboardEvents</code> sont déclenchés selon une séquence prédéterminée, et la compréhension de ces éléments contribuera à comprendre la valeur de la propriété <code>key</code> pour un événement <code>KeyboardEvent</code> particulier. Pour une touche donnée, la séquence de KeyboardEvents est la suivante, en supposant que {{domxref ("Event.preventDefault")}} n'est pas appelée :</p> + +<ol> + <li>Un événement {{domxref("Element/keydown_event", "keydown")}} (<em>touche abaissée</em>) est d'abord déclenché. Si la touche est maintenue enfoncée et que la touche est une touche de caractère, l'événement continue d'être émis dans un intervalle dépendant de l'implémentation de la plateforme, et la propriété en lecture seule {{domxref ("KeyboardEvent.repeat")}} est définie sur <code>true</code> (<em>vrai</em>).</li> + <li>Si la touche est une touche de caractère qui entraînerait l'insertion d'un caractère dans {{HTMLElement ("entrée")}}, {{HTMLElement ("textarea")}} ou un élément dont {{domxref ("HTMLElement. contentEditable ")}} a la valeur <code>true</code>, les types d'événements {{domxref("HTMLElement/beforeinput_event", "beforeinput")}} et {{domxref("HTMLElement/input_event", "input")}} sont déclenchés dans cet ordre. Notez que d'autres implémentations peuvent déclencher l'événement {{event ("keypress")}} si elles sont prises en charge. Les événements seront déclenchés à plusieurs reprises tant que la touche est maintenue enfoncée.</li> + <li>Un évènement {{domxref("Element/keyup_event", "keyup")}} est déclenché une fois la touche relachée. Ceci complète le processus.</li> +</ol> + +<p>Dans les étapes 1 et 3, l'attribut <code>KeyboardEent.key</code> est défini et est déclaré à une valeur appropriée en fonction des règles définies.</p> + +<h2 id="Exemple_de_séquence_KeyboardEvent">Exemple de séquence KeyboardEvent</h2> + +<p>Considérez la séquence d'événements générée lorsque nous interagissons avec la touche <kbd>Shift</kbd> et la touche <kbd>2</kbd> en utilisant un clavier américain et un clavier britannique.</p> + +<p>Essayez d'expérimenter en utilisant les deux cas de test suivants :</p> + +<ol> + <li>Maintenez la touche <kbd>shift</kbd> enfoncée, puis appuyez sur <kbd>2</kbd> et relâchez-la. Ensuite, relâchez la touche <kbd>shift</kbd>.</li> + <li>Maintenez la touche <code>shift</code> enfoncée, puis appuyez sur <kbd>2</kbd>. Relâchez la touche <kbd>shift</kbd>. Finalement, relâchez la touche <kbd>2</kbd>.</li> +</ol> + +<h3 id="HTML">HTML</h3> + +<pre class="brush: html line-numbers language-html"><code class="language-html"><span class="tag token"><span class="tag token"><span class="punctuation token"><</span>div</span> <span class="attr-name token">class</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>fx<span class="punctuation token">"</span></span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>div</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>textarea</span> <span class="attr-name token">rows</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>5<span class="punctuation token">"</span></span> <span class="attr-name token">name</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>test-target<span class="punctuation token">"</span></span> <span class="attr-name token">id</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>test-target<span class="punctuation token">"</span></span><span class="punctuation token">></span></span><span class="tag token"><span class="tag token"><span class="punctuation token"></</span>textarea</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>button</span> <span class="attr-name token">type</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>button<span class="punctuation token">"</span></span> <span class="attr-name token">name</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>btn-clear-console<span class="punctuation token">"</span></span> <span class="attr-name token">id</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>btn-clear-console<span class="punctuation token">"</span></span><span class="punctuation token">></span></span>clear console<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>button</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"></</span>div</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>div</span> <span class="attr-name token">class</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>flex<span class="punctuation token">"</span></span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>div</span> <span class="attr-name token">id</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>console-log<span class="punctuation token">"</span></span><span class="punctuation token">></span></span><span class="tag token"><span class="tag token"><span class="punctuation token"></</span>div</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"></</span>div</span><span class="punctuation token">></span></span> +<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>div</span><span class="punctuation token">></span></span></code></pre> + +<h3 id="CSS">CSS</h3> + +<pre class="brush: css line-numbers language-css"><code class="language-css"><span class="selector token"><span class="class token">.fx</span> </span><span class="punctuation token">{</span> + <span class="property token">-webkit-display</span><span class="punctuation token">:</span> flex<span class="punctuation token">;</span> + <span class="property token">display</span><span class="punctuation token">:</span> flex<span class="punctuation token">;</span> + <span class="property token">margin-left</span><span class="punctuation token">:</span> -<span class="number token">20</span>px<span class="punctuation token">;</span> + <span class="property token">margin-right</span><span class="punctuation token">:</span> -<span class="number token">20</span>px<span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="selector token"><span class="class token">.fx</span> > div </span><span class="punctuation token">{</span> + <span class="property token">padding-left</span><span class="punctuation token">:</span> <span class="number token">20</span>px<span class="punctuation token">;</span> + <span class="property token">padding-right</span><span class="punctuation token">:</span> <span class="number token">20</span>px<span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="selector token"><span class="class token">.fx</span> > div<span class="pseudo-class token">:first-child</span> </span><span class="punctuation token">{</span> + <span class="property token">width</span><span class="punctuation token">:</span> <span class="number token">30%</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="selector token"><span class="class token">.flex</span> </span><span class="punctuation token">{</span> + <span class="property token">-webkit-flex</span><span class="punctuation token">:</span> <span class="number token">1</span><span class="punctuation token">;</span> + <span class="property token">flex</span><span class="punctuation token">:</span> <span class="number token">1</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="selector token"><span class="id token">#test-target</span> </span><span class="punctuation token">{</span> + <span class="property token">display</span><span class="punctuation token">:</span> block<span class="punctuation token">;</span> + <span class="property token">width</span><span class="punctuation token">:</span> <span class="number token">100%</span><span class="punctuation token">;</span> + <span class="property token">margin-bottom</span><span class="punctuation token">:</span> <span class="number token">10</span>px<span class="punctuation token">;</span> +<span class="punctuation token">}</span></code></pre> + +<h3 id="JavaScript">JavaScript</h3> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">let</span> textarea <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">getElementById</span><span class="punctuation token">(</span><span class="string token">'test-target'</span><span class="punctuation token">)</span><span class="punctuation token">,</span> +consoleLog <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">getElementById</span><span class="punctuation token">(</span><span class="string token">'console-log'</span><span class="punctuation token">)</span><span class="punctuation token">,</span> +btnClearConsole <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">getElementById</span><span class="punctuation token">(</span><span class="string token">'btn-clear-console'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +<span class="keyword token">function</span> <span class="function token">logMessage</span><span class="punctuation token">(</span>message<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">let</span> p <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">createElement</span><span class="punctuation token">(</span><span class="string token">'p'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + p<span class="punctuation token">.</span><span class="function token">appendChild</span><span class="punctuation token">(</span>document<span class="punctuation token">.</span><span class="function token">createTextNode</span><span class="punctuation token">(</span>message<span class="punctuation token">)</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + consoleLog<span class="punctuation token">.</span><span class="function token">appendChild</span><span class="punctuation token">(</span>p<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +textarea<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">'keydown'</span><span class="punctuation token">,</span> <span class="punctuation token">(</span>e<span class="punctuation token">)</span> <span class="operator token">=</span><span class="operator token">></span> <span class="punctuation token">{</span> + <span class="keyword token">if</span> <span class="punctuation token">(</span><span class="operator token">!</span>e<span class="punctuation token">.</span>repeat<span class="punctuation token">)</span> + <span class="function token">logMessage</span><span class="punctuation token">(</span>`first keydown event<span class="punctuation token">.</span> key property value is <span class="string token">"${e.key}"</span><span class="template-string token"><span class="string token">`); + else + logMessage(`</span></span>keydown event repeats<span class="punctuation token">.</span> key property value is <span class="string token">"${e.key}"</span>`<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +textarea<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">'beforeinput'</span><span class="punctuation token">,</span> <span class="punctuation token">(</span>e<span class="punctuation token">)</span> <span class="operator token">=</span><span class="operator token">></span> <span class="punctuation token">{</span> + <span class="function token">logMessage</span><span class="punctuation token">(</span>`beforeinput event<span class="punctuation token">.</span> you are about inputing <span class="string token">"${e.data}"</span>`<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +textarea<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">'input'</span><span class="punctuation token">,</span> <span class="punctuation token">(</span>e<span class="punctuation token">)</span> <span class="operator token">=</span><span class="operator token">></span> <span class="punctuation token">{</span> + <span class="function token">logMessage</span><span class="punctuation token">(</span>`input event<span class="punctuation token">.</span> you have just inputed <span class="string token">"${e.data}"</span>`<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +textarea<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">'keyup'</span><span class="punctuation token">,</span> <span class="punctuation token">(</span>e<span class="punctuation token">)</span> <span class="operator token">=</span><span class="operator token">></span> <span class="punctuation token">{</span> + <span class="function token">logMessage</span><span class="punctuation token">(</span>`keyup event<span class="punctuation token">.</span> key property value is <span class="string token">"${e.key}"</span>`<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +btnClearConsole<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">'click'</span><span class="punctuation token">,</span> <span class="punctuation token">(</span>e<span class="punctuation token">)</span> <span class="operator token">=</span><span class="operator token">></span> <span class="punctuation token">{</span> + <span class="keyword token">let</span> child <span class="operator token">=</span> consoleLog<span class="punctuation token">.</span>firstChild<span class="punctuation token">;</span> + <span class="keyword token">while</span> <span class="punctuation token">(</span>child<span class="punctuation token">)</span> <span class="punctuation token">{</span> + consoleLog<span class="punctuation token">.</span><span class="function token">removeChild</span><span class="punctuation token">(</span>child<span class="punctuation token">)</span><span class="punctuation token">;</span> + child <span class="operator token">=</span> consoleLog<span class="punctuation token">.</span>firstChild<span class="punctuation token">;</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<h3 id="Résultat">Résultat</h3> + +<p>{{EmbedLiveSample('Exemple_de_séquence_KeyboardEvent')}}</p> + +<div class="blockIndicator note"> +<p><strong>Note :</strong> Sur les navigateurs qui n'implémentent pas complètement l'interface {{domxref("InputEvent")}} qui est utilisée pour les événements {{domxref("HTMLElement/beforeinput_event", "beforeinput")}} et {{domxref("HTMLElement/input_event", "input")}}, vous pouvez obtenir une réponse incorrecte sur ces lignes du journal de sortie.</p> +</div> + +<h3 id="Cas_1">Cas 1</h3> + +<p>Lorsque la touche Maj (<em>shift</em>) est enfoncée, un événement {{domxref("Element/keydown_event", "keydown")}} est d'abord déclenché et la valeur de la propriété <code>key</code> est définie sur la chaîne <code>"Shift"</code>. Comme nous gardons cette touche enfoncée, l'événement {{event ("keydown")}} est continu et ne se répéte pas car la touche Maj ne produit pas de caractère.</p> + +<p>Lorsque la <code>key 2</code> est enfoncée, un autre événement {{domxref("Element/keydown_event", "keydown")}} est déclenché pour cette nouvelle touche, et la valeur de la propriété <code>key</code> pour l'événement est définie sur la chaîne <code>"@"</code> pour le clavier de type américain et <code>"""</code> pour le clavier de type britannique, à cause de la touche de changement de modificateur active. Les événements {{domxref("HTMLElement/beforeinput_event", "beforeinput")}} et {{domxref("HTMLElement/input_event", "input")}} sont déclenchés ensuite parce qu'une touche de caractère a été activée.</p> + +<p>Lorsque nous relâchons la <code>key 2</code>, un événement {{domxref("Element/keyup_event", "keyup")}} est déclenché et la propriété <code>key</code> conserve les valeurs de chaîne <code>"@"</code> et <code>"""</code> pour les différents claviers respectivement.</p> + +<p>Lorsque nous relâchons enfin la touche <code>shift</code>, un autre événement {{domxref("Element/keyup_event", "keyup")}} est déclenché pour elle, et la valeur de l'attribut de la touche reste <code>"Shift"</code>.</p> + +<h3 id="Cas_2">Cas 2</h3> + +<p>Lorsque la touche Maj est enfoncée, un événement {{domxref("Element/keydown_event", "keydown")}} est d'abord déclenché et la valeur de la propriété <code>key</code> est définie sur la chaîne "Shift". Comme nous maintenons cette touche enfoncée, l'événement {{domxref("Element/keydown_event", "keydown")}} est continu et ne se répéte pas car la touche Maj ne produit pas de caractère.</p> + +<p>Lorsque la <code>key 2</code> est enfoncée, un autre événement {{domxref("Element/keydown_event", "keydown")}} est déclenché pour cette nouvelle touche, et la valeur de la propriété <code>key</code> pour l'événement est définie sur la chaîne <code>"@"</code> pour le clavier de type américain et <code>"""</code> pour le clavier de type britanique, à cause de la touche de changement de modificateur active. Les événements {{domxref("HTMLElement/beforeinput_event", "beforeinput")}} et {{domxref("HTMLElement/input_event", "input")}} sont déclenchés ensuite parce qu'une touche de caractère a été activée. Comme nous maintenons la touche enfoncée, l'événement {{domxref("Element/keydown_event", "keydown")}} continue à se déclencher à plusieurs reprises et la propriété {{domxref ("KeyboardEvent.repeat")}} est définie sur <code>true</code>. Les évènements {{domxref("HTMLElement/beforeinput_event", "beforeinput")}} et {{domxref("HTMLElement/input_event", "input")}} sont également déclenchés.</p> + +<p>Lorsque nous relâchons la touche <code>shift</code>, un événement {{domxref("Element/keyup_event", "keyup")}} est déclenché et la valeur de l'attribut clé reste "Shift". À ce stade, notez que la valeur de la propriété <code>key</code> pour l'événement de répétition du clavier de la touche <code>key 2</code> est désormais "2" car la touche de modification du sélecteur n'est plus active. Il en va de même pour la propriété {{domxref("HTMLElement/beforeinput_event", "beforeinput")}} des événements {{domxref("HTMLElement/input_event", "input")}} et {{event ("input")}}.</p> + +<p>Lorsque nous relâchons enfin la touche <code>key 2</code>, un événement {{domxref("Element/keyup_event", "keyup")}} est déclenché mais la propriété <code>key</code> est définie sur la valeur de chaîne <code>"2"</code> pour les deux configurations de clavier car la touche de modification <code>shift</code> n'est plus active.</p> + +<h2 id="Exemple">Exemple</h2> + +<p><span id="result_box" lang="fr"><span>Cet exemple utilise {{domxref("EventTarget.addEventListener()")}} pour écouter les événements </span></span> {{domxref("Element/keydown_event", "keydown")}} <span lang="fr"><span>.</span> <span>Quand ils se produisent, la valeur de la touche est vérifiée pour voir si c'est l'une des touches qui intéressent le code, et si c'est le cas, elle est traitée (éventuellement en pilotant un vaisseau spatial, peut-être en changeant la cellule sélectionnée dans une feuille de calcul</span><span>).</span></span></p> + +<pre class="brush: js">window.addEventListener("keydown", function (event) { + if (event.defaultPrevented) { + return; // Ne devrait rien faire si l'événement de la touche était déjà consommé. + } + + switch (event.key) { + case "ArrowDown": + // Faire quelque chose pour la touche "flèche vers le bas" pressée. + break; + case "ArrowUp": + // Faire quelque chose pour la touche "up arrow" pressée. + break; + case "ArrowLeft": + // Faire quelque chose pour la touche "left arrow" pressée. + break; + case "ArrowRight": + // Faire quelque chose pour la touche "right arrow" pressée. + break; + case "Enter": + // Faire quelque chose pour les touches "enter" ou "return" pressées. + break; + case "<code>Escape</code>": + // Faire quelque chose pour la touche "esc" pressée. + break; + default: + return; // Quitter lorsque cela ne gère pas l'événement touche. + } + + // Annuler l'action par défaut pour éviter qu'elle ne soit traitée deux fois. + event.preventDefault(); +}, true); +</pre> + +<h2 id="Spécification">Spécification</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Spécification</th> + <th scope="col">Statut</th> + <th scope="col">Commentaire</th> + </tr> + <tr> + <td>{{SpecName('DOM3 Events', '#widl-KeyboardEvent-key', 'KeyboardEvent.key')}}</td> + <td>{{Spec2('DOM3 Events')}}</td> + <td>Définition initiale, incluant les valeurs de touches.</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilité_des_navigateurs">Compatibilité des navigateurs</h2> + + + +<p>{{Compat("api.KeyboardEvent.key")}}</p> + +<div id="compat-desktop"></div> + +<div id="compat-mobile"></div> |