event

  • Raccourci de la révision : DOM/event
  • Titre de la révision : event
  • ID de la révision : 182449
  • Créé :
  • Créateur : BenoitL
  • Version actuelle ? Non
  • Commentaire /* Propriétés */ traduction

Contenu de la révision

{{template.DomRef()}} {{template.Traduction_en_cours("DOM:event")}}

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érents 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ènement 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
{{template.Deprecated_inline()}} 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). Consultez nsIDOMNSEvent pour plus d'informations.
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
Initialize the value of an Event created through the DocumentEvent interface.
event.initKeyEvent
Initializes a keyboard event. Gecko-specific.
event.initMouseEvent
Intializes the value of a mouse event once it's been created
event.initUIEvent
Initializes a UI event once it's been created.
event.preventDefault
Cancels the event (if it is cancelable).
event.preventBubble {{template.Obsolete_inline()}}
Prevents the event from bubbling. This method is deprecated in favor of standard stopPropagation and is removed in Gecko 1.9.
event.preventCapture {{template.Obsolete_inline()}}
This method is deprecated in favor of standard stopPropagation and is removed in Gecko 1.9.
event.stopPropagation
Stops the propagation of events further along in the DOM.
{{ wiki.languages( { "en": "en/DOM/event", "pl": "pl/DOM/event" } ) }}

Source de la révision

<p>
{{template.DomRef()}}
{{template.Traduction_en_cours("DOM:event")}}
</p>
<h3 name="Introduction"> Introduction </h3>
<p>Ce chapitre décrit le modèle d'évènement du DOM Level 2 tel qu'implémenté par Gecko. L'interface <a class="external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-Event">Event</a> 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érents interfaces d'évènements sont liées l'une à l'autre.
</p><p>Il existe un très bon diagramme expliquant clairement les trois phases du parcours de <code>event</code> au travers de DOM dans le document <a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-flow">DOM Level 3 Events draft (en)</a>.
</p>
<h4 name="L.27interface_DOM_Event"> L'interface DOM <code>Event</code> </h4>
<p><span class="comment">L'interface DOM &lt;code&gt;event&lt;/code&gt; est exposée dans les objets &lt;code&gt;event&lt;/code&gt; qui sont passés aux gestionnaires d'évènements sur divers éléments du DOM.</span>
</p><p>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 <code>Event</code> est alors accessible par le gestionnaire de fonction, via l'objet évènement passé comme premier (et unique) argument.
</p><p><span class="comment">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 &lt;code&gt;event&lt;/code&gt; object as a parameter, which is passed explicitly to the event handler function.</span>
L'exemple très simple ci-dessous montre la façon dont un objet <code>event</code> peut être référencé et manipulé depuis un tel gestionnaire d'évènement.
</p><p>Notez qu'aucun paramètre « <code>evt</code> » n'est passé à la fonction ci-dessous. L'objet d'évènement est passé automatiquement à la fonction <i>foo</i>. Tout ce qu'il y a à faire est définir un paramètre dans le gestionnaire d'évènement pour recevoir cet objet.
</p>
<pre>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;
</pre>
<p>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 <code>event</code> depuis les fonctions de gestion d'évènements. Une fois que vous avez une référence à l'objet <code>event</code>, vous pouvez accéder à toutes les propriétés et méthodes décrites dans ce chapitre.
</p><p>Voir aussi l'<a href="fr/R%c3%a9f%c3%a9rence_du_DOM_Gecko/Exemples#Exemple_5_:_propagation_d.27.C3.A9v.C3.A8nements">exemple 5 : Propagation des évènements</a> dans le chapitre Exemples pour un exemple plus détaillé de la façon dont les évènement se propagent dans le DOM.
</p>
<h4 name="Liste_des_gestionnaires_d.27.C3.A9v.C3.A8nements_DOM"> Liste des gestionnaires d'évènements DOM </h4>
<p>En plus de l'objet <code>event</code> 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 <a href="fr/DOM/element#.23.C3.89v.C3.A8nements">gestionnaires d'évènements</a> 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 <a href="fr/DOM/element">référence de DOM element</a>.
</p><p>Vous pouvez également passer la référence à l'objet event comme un paramètre prédéfini, appelé <code>event</code>, à la fonction de gestion de cet évènement. Cela ressemble très fort à la manière dont <code>this</code> fonctionne, mais pour des objets d'évènements plutôt que des références à des objets d'éléments.
</p>
<pre>&lt;html&gt;
&lt;head&gt;
&lt;title&gt;Exemple de paramètre d'objet "event"&lt;/title&gt;

&lt;script type="text/javascript"&gt;

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

&lt;/script&gt;
&lt;/head&gt;

&lt;body onmousedown="afficheCoords(event)"&gt;
&lt;p&gt;Pour afficher les coordonnées de la souris, cliquez n'importe où dans la page.&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<p>L'utilisation du paramètre prédéfini de l'objet <code>event</code> vous permet de passer également d'autres paramètres au gestionnaire d'évènements DOM, si nécessaire :
</p>
<pre>&lt;html&gt;
&lt;head&gt;
&lt;title&gt;Pour afficher les coordonnées de la souris, cliquez n'importe où dans la page.&lt;/title&gt;

&lt;script type="text/javascript"&gt;

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"
  );
}

&lt;/script&gt;
&lt;/head&gt;

&lt;body onmousedown="afficheCoords(event, par2, par3)"&gt;
&lt;p&gt;Pour afficher les coordonnées de la souris, cliquez n'importe où dans la page.&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<h3 name="Propri.C3.A9t.C3.A9s"> Propriétés </h3>
<dl><dt> <a href="fr/DOM/event.altKey">event.altKey</a>
</dt><dd> Renvoie une valeur booléenne indiquant si la touche <code>&lt;alt&gt;</code> était enfoncée au cours de l'évènement.
</dd><dt> <a href="fr/DOM/event.bubbles">event.bubbles</a>
</dt><dd> Renvoie une valeur booléenne indiquant si l'évènement se propage vers le haut dans le DOM ou non.
</dd><dt> <a href="fr/DOM/event.button">event.button</a>
</dt><dd> Renvoie le bouton de la souris.
</dd><dt> <a href="fr/DOM/event.cancelBubble">event.cancelBubble</a> 
</dt><dd> {{template.Deprecated_inline()}} Renvoie une valeur booléenne indiquant si la propagation vers le haut de l'évènement a été annulée ou non.
</dd><dt> <a href="fr/DOM/event.cancelable">event.cancelable</a>
</dt><dd> Renvoie une valeur booléenne indiquant si l'évènement est annulable.
</dd><dt> <a href="fr/DOM/event.charCode">event.charCode</a>
</dt><dd> Renvoie la valeur Unicode de la touche caractère qui a été enfoncée dans le cadre d'un évènement <a href="fr/DOM/event/keypress">keypress</a>.
</dd><dt> <a href="fr/DOM/event.clientX">event.clientX</a>
</dt><dd> Renvoie la position horizontale de l'évènement.
</dd><dt> <a href="fr/DOM/event.clientY">event.clientY</a>
</dt><dd> Renvoie la position verticale de l'évènement.
</dd><dt> <a href="fr/DOM/event.ctrlKey">event.ctrlKey</a>
</dt><dd> Renvoie une valeur booléenne indiquant si la touche <code>&lt;ctrl&gt;</code> était enfoncée au cours de l'évènement.
</dd><dt> <a href="fr/DOM/event.currentTarget">event.currentTarget</a>
</dt><dd> Renvoie une référence vers la cible actuellement enregistrée pour l'évènement.
</dd><dt> <a href="fr/DOM/event.detail">event.detail</a>
</dt><dd> Renvoie des détails concernant l'évènement, selon le type d'évènement.
</dd><dt> <a href="fr/DOM/event.eventPhase">event.eventPhase</a>
</dt><dd> Utilisée pour indiquer dans quelle phase de l'évènement on se trouve actuellement.
</dd><dt> <a href="fr/DOM/event.explicitOriginalTarget">event.explicitOriginalTarget</a>
</dt><dd> La cible explicite originale de l'évènement (spécifique à Mozilla). Consultez <a class="external" href="http://lxr.mozilla.org/seamonkey/source/dom/public/idl/events/nsIDOMNSEvent.idl">nsIDOMNSEvent</a> pour plus d'informations.
</dd><dt> <a href="fr/DOM/event.isChar">event.isChar</a>
</dt><dd> Renvoie une valeur booléenne indiquant si l'évènement a produit une touche de caractère ou non.
</dd><dt> <a href="fr/DOM/event.keyCode">event.keyCode</a>
</dt><dd> Renvoie la valeur Unicode de toute touche non caractère dans un évènement <a href="fr/DOM/event/keypress">keypress</a> ou de toute touche dans les autres types d'évènement clavier.
</dd><dt> <a href="fr/DOM/event.layerX">event.layerX</a>
</dt><dd> Renvoie la coordonnée horizontale de l'évènement, relativement au calque courant.
</dd><dt> <a href="fr/DOM/event.layerY">event.layerY</a>
</dt><dd> Renvoie la coordonnée verticale de l'évènement, relativement au calque courant.
</dd><dt> <a href="fr/DOM/event.metaKey">event.metaKey</a>
</dt><dd> Renvoie une valeur booléenne indiquant si la touche <code>meta</code> était enfoncée lors de l'évènement.
</dd><dt> <a href="fr/DOM/event.originalTarget">event.originalTarget</a>
</dt><dd> La cible originale de l'évènement, avant toute modification de celle-ci (spécifique à Mozilla).
</dd><dt> <a href="fr/DOM/event.pageX">event.pageX</a>
</dt><dd> Renvoie la coordonnée horizontale de l'évènement relativement à la page.
</dd><dt> <a href="fr/DOM/event.pageY">event.pageY</a>
</dt><dd> Renvoie la coordonnée verticale de l'évènement relativement à la page.
</dd><dt> <a href="fr/DOM/event.relatedTarget">event.relatedTarget</a>
</dt><dd> Identifie une cible secondaire pour l'évènement.
</dd><dt> <a href="fr/DOM/event.screenX">event.screenX</a>
</dt><dd> Renvoie la position horizontale de l'évènement sur l'écran.
</dd><dt> <a href="fr/DOM/event.screenY">event.screenY</a>
</dt><dd> Renvoie la position verticale de l'évènement sur l'écran.
</dd><dt> <a href="fr/DOM/event.shiftKey">event.shiftKey</a>
</dt><dd> Renvoie une valeur booléenne indiquant si la touche <code>&lt;shift&gt;</code> était enfoncée lors du déclenchement de l'évènement.
</dd><dt> <a href="fr/DOM/event.target">event.target</a>
</dt><dd> Renvoie une référence à la cible vers laquelle l'évènement était originellement destiné.
</dd><dt> <a href="fr/DOM/event.timeStamp">event.timeStamp</a>
</dt><dd> Renvoie le moment de création de l'évènement.
</dd><dt> <a href="fr/DOM/event.type">event.type</a>
</dt><dd> Renvoie le nom de l'évènement (insensible à la casse).
</dd><dt> <a href="fr/DOM/event.view">event.view</a>
</dt><dd> Identifie l'<code>AbstractView</code> dont est originaire l'évènement.
</dd><dt> <a href="fr/DOM/event.which">event.which</a>
</dt><dd> Renvoie la valeur Unicode de la touche dans un évènement clavier, qu'elle soit ou non un caractère.
</dd></dl>
<h3 name="M.C3.A9thodes"> Méthodes </h3>
<dl><dt> <a href="fr/DOM/event.initEvent">event.initEvent</a>
</dt><dd> Initialize the value of an Event created through the <code>DocumentEvent</code> interface.
</dd><dt> <a href="fr/DOM/event.initKeyEvent">event.initKeyEvent</a>
</dt><dd> Initializes a keyboard event. Gecko-specific.
</dd><dt> <a href="fr/DOM/event.initMouseEvent">event.initMouseEvent</a>
</dt><dd> Intializes the value of a mouse event once it's been created
</dd><dt> <a href="fr/DOM/event.initUIEvent">event.initUIEvent</a>
</dt><dd> Initializes a UI event once it's been created.
</dd><dt> <a href="fr/DOM/event.preventDefault">event.preventDefault</a>
</dt><dd> Cancels the event (if it is cancelable).
</dd><dt> <a href="fr/DOM/event.preventBubble">event.preventBubble</a> {{template.Obsolete_inline()}}
</dt><dd> Prevents the event from bubbling. This method is deprecated in favor of standard <a href="fr/DOM/event.stopPropagation">stopPropagation</a> and is <a href="fr/Gecko_1.9_Changes_affecting_websites">removed in Gecko 1.9</a>.
</dd><dt> <a href="fr/DOM/event.preventCapture">event.preventCapture</a> {{template.Obsolete_inline()}}
</dt><dd> This method is deprecated in favor of standard <a href="fr/DOM/event.stopPropagation">stopPropagation</a> and is <a href="fr/Gecko_1.9_Changes_affecting_websites">removed in Gecko 1.9</a>.
</dd><dt> <a href="fr/DOM/event.stopPropagation">event.stopPropagation</a>
</dt><dd> Stops the propagation of events further along in the DOM.
</dd></dl>
{{ wiki.languages( { "en": "en/DOM/event", "pl": "pl/DOM/event" } ) }}
Revenir à cette révision