event

« Référence du DOM

Introduction

Ce chapitre décrit le modèle d'évènement du DOM Level 2 tel qu'implémenté par Gecko. L'interface Event elle-même est décrite, ainsi que les interfaces pour l'enregistrement des évènements sur d'autres nœuds du DOM, les gestionnaires et « écouteurs » (listeners) d'évènements, et quelques exemples plus longs montrant la manière dont les différentes interfaces d'évènements sont liées l'une à l'autre.

Il existe un très bon diagramme expliquant clairement les trois phases du parcours de event au travers de DOM dans le document DOM Level 3 Events draft (en).

L'interface DOM Event

L'interface DOM <code>event</code> est exposée dans les objets <code>event</code> qui sont passés aux gestionnaires d'évènements sur divers éléments du DOM.

Les gestionnaires d'évènements peuvent être attachés à différents éléments dans le DOM. Lorsqu'un évènement se produit, un objet évènement est créé dynamiquement, et passé séquentiellement aux « écouteurs » d'évènements qui sont autorisés à gérer l'évènement. L'interface DOM Event est alors accessible par le gestionnaire de fonction, via l'objet évènement passé comme premier (et unique) argument.

Given that we don't list the three ways right here, the sentence is unclear, and is not perfectly right either IMO. -Nickolay There are three ways to attach an event listener to an element. With 2 of those techniques, the event object is passed to the handler function implicitly. The remaining technique requires you to specify the <code>event</code> object as a parameter, which is passed explicitly to the event handler function. L'exemple très simple ci-dessous montre la façon dont un objet event peut être référencé et manipulé depuis un tel gestionnaire d'évènement.

Notez qu'aucun paramètre « evt » n'est passé à la fonction ci-dessous. L'objet d'évènement est passé automatiquement à la fonction foo. Tout ce qu'il y a à faire est définir un paramètre dans le gestionnaire d'évènement pour recevoir cet objet.

function foo(evt) {
  // les fonctions de gestion d'évènements comme celle-ci
  // reçoivent une référence vers l'évènement géré
  // (dans ce cas, la variable « evt »).
  alert(evt);
}
table_el.onclick = foo;

Cet exemple est extrêmement simpliste, mais il montre une fonctionnalité importante des évènements dans le DOM Gecko, qui est qu'on accède typiquement aux objets event depuis les fonctions de gestion d'évènements. Une fois que vous avez une référence à l'objet event, vous pouvez accéder à toutes les propriétés et méthodes décrites dans ce chapitre.

Voir aussi l'exemple 5 : Propagation des évènements dans le chapitre Exemples pour un exemple plus détaillé de la façon dont les évènements se propagent dans le DOM.

Liste des gestionnaires d'évènements DOM

En plus de l'objet event décrit ici, le DOM fournit également des méthodes pour enregistrer des écouteurs d'évènements (listeners) sur des nœuds du DOM, en enlever, et déclencher des évènements depuis le DOM. Celles-ci et les nombreux gestionnaires d'évènements sur les éléments HTML ou XML sont les points d'entrée principaux pour les évènements dans le DOM. Ces trois méthodes sont décrites dans la liste de la référence de DOM element.

Vous pouvez également passer la référence à l'objet event comme un paramètre prédéfini, appelé event, à la fonction de gestion de cet évènement. Cela ressemble très fort à la manière dont this fonctionne, mais pour des objets d'évènements plutôt que des références à des objets d'éléments.

<html>
<head>
<title>Exemple de paramètre d'objet "event"</title>

<script type="text/javascript">

function afficheCoords(evt){
  alert(
    "Valeur de clientX : " + evt.clientX + "\n" +
    "Valeur de clientY : " + evt.clientY + "\n"
  );
}

</script>
</head>

<body onmousedown="afficheCoords(event)">
<p>Pour afficher les coordonnées de la souris, cliquez n'importe où dans la page.</p>
</body>
</html>

L'utilisation du paramètre prédéfini de l'objet event vous permet de passer également d'autres paramètres au gestionnaire d'évènements DOM, si nécessaire :

<html>
<head>
<title>Pour afficher les coordonnées de la souris, cliquez n'importe où dans la page.</title>

<script type="text/javascript">

var par2 = 'hello';
var par3 = 'world!';

function afficheCoords(evt, p2, p3){
  alert(
    "Valeur de clientX : " + evt.clientX + "\n"
    + "Valeur de clientY : " + evt.clientY + "\n"
    + "p2 : " + p2 + "\n"
    + "p3 : " + p3 + "\n"
  );
}

</script>
</head>

<body onmousedown="afficheCoords(event, par2, par3)">
<p>Pour afficher les coordonnées de la souris, cliquez n'importe où dans la page.</p>
</body>
</html>

Propriétés

event.altKey
Renvoie une valeur booléenne indiquant si la touche <alt> était enfoncée au cours de l'évènement.
event.bubbles
Renvoie une valeur booléenne indiquant si l'évènement se propage vers le haut dans le DOM ou non.
event.button
Renvoie le bouton de la souris.
event.cancelBubble
Renvoie une valeur booléenne indiquant si la propagation vers le haut de l'évènement a été annulée ou non.
event.cancelable
Renvoie une valeur booléenne indiquant si l'évènement est annulable.
event.charCode
Renvoie la valeur Unicode de la touche caractère qui a été enfoncée dans le cadre d'un évènement keypress.
event.clientX
Renvoie la position horizontale de l'évènement.
event.clientY
Renvoie la position verticale de l'évènement.
event.ctrlKey
Renvoie une valeur booléenne indiquant si la touche <ctrl> était enfoncée au cours de l'évènement.
event.currentTarget
Renvoie une référence vers la cible actuellement enregistrée pour l'évènement.
event.detail
Renvoie des détails concernant l'évènement, selon le type d'évènement.
event.eventPhase
Utilisée pour indiquer dans quelle phase de l'évènement on se trouve actuellement.
event.explicitOriginalTarget
La cible explicite originale de l'évènement (spécifique à Mozilla).
event.isChar
Renvoie une valeur booléenne indiquant si l'évènement a produit une touche de caractère ou non.
event.keyCode
Renvoie la valeur Unicode de toute touche non caractère dans un évènement keypress ou de toute touche dans les autres types d'évènement clavier.
event.layerX
Renvoie la coordonnée horizontale de l'évènement, relativement au calque courant.
event.layerY
Renvoie la coordonnée verticale de l'évènement, relativement au calque courant.
event.metaKey
Renvoie une valeur booléenne indiquant si la touche meta était enfoncée lors de l'évènement.
event.originalTarget
La cible originale de l'évènement, avant toute modification de celle-ci (spécifique à Mozilla).
event.pageX
Renvoie la coordonnée horizontale de l'évènement relativement à la page.
event.pageY
Renvoie la coordonnée verticale de l'évènement relativement à la page.
event.relatedTarget
Identifie une cible secondaire pour l'évènement.
event.screenX
Renvoie la position horizontale de l'évènement sur l'écran.
event.screenY
Renvoie la position verticale de l'évènement sur l'écran.
event.shiftKey
Renvoie une valeur booléenne indiquant si la touche <shift> était enfoncée lors du déclenchement de l'évènement.
event.target
Renvoie une référence à la cible vers laquelle l'évènement était originellement destiné.
event.timeStamp
Renvoie le moment de création de l'évènement.
event.type
Renvoie le nom de l'évènement (insensible à la casse).
event.view
Identifie l'AbstractView dont est originaire l'évènement.
event.which
Renvoie la valeur Unicode de la touche dans un évènement clavier, qu'elle soit ou non un caractère.

Méthodes

event.initEvent
Initialise la valeur d'un objet Event créé via l'interface DocumentEvent.
event.initKeyEvent
Initialise un évènement clavier. Spécifique à Gecko.
event.initMouseEvent
Initialise la valeur d'un évènement souris une fois qu'il a été créé.
event.initUIEvent
Initialise un évènement UI (interface utilisateur) une fois qu'il a été créé.
event.preventDefault
Annule l'évènement (s'il est annulable).
event.preventBubble
Empêche l'évènement de se propager. Cette méthode est déconseillée en faveur de la méthode standard stopPropagation et a été retirée dans Gecko 1.9.
event.preventCapture
Cette méthode est déconseillée en faveur de la méthode standard stopPropagation et a été retirée dans Gecko 1.9.
event.stopPropagation
Arrête la propagation ultérieure d'évènements dans le DOM.


Étiquettes et contributeurs liés au document

Étiquettes :
Contributeurs ayant participé à cette page : Fredchat, BenoitL, Takenbot, Mgjbot
Dernière mise à jour par : Mgjbot,