element.addEventListener

Résumé

addEventListener permet l'assignation de gestionnaires d'évènements sur un élément cible. La cible d'un évènement peut être un nœud dans un document, le document lui-même, un élément window ou un objet XMLHttpRequest.

Syntaxe

element.addEventListener(type, listener, useCapture);

Paramètres

type: une chaîne représentant le type d'évènement à enregistrer.
listener: l'objet qui recevra une notification lorsqu'un évènement du type spécifié se produit. Il doit s'agir d'un objet implémentant l'interface EventListener interface, ou simplement une fonction JavaScript.
useCapture: si défini à true, useCapture indique que l'utilisateur désire initier la capture. Après avoir initié la capture, tous les évènements du type spécifié seront dispatchés vers l'EventListener avant d'être envoyés à toute cible (EventTarget) plus bas dans l'arbre. Les évènements qui se propagent vers le haut dans l'arbre (bubbling) ne déclencheront pas un EventListener désigné pour utiliser la capture. Consultez DOM Level 3 Events pour une explication détaillée.

Exemple

 <html>
 <head>
   <title>Exemple de DOM Event</title>
   <style type="text/css">
     #t { border: 1px solid red }
     #t1 { background-color: pink; }
   </style>
   <script type="text/javascript">
   // fonction pour modifier le contenu de t2
   function modifieTexte() {
     var t2 = document.getElementById("t2");
     t2.firstChild.nodeValue = "trois";    
   }
   // fonction pour ajouter un écouteur à t
   function load() { 
     var el = document.getElementById("t"); 
     el.addEventListener("click", modifieTexte, false); 
   } 
   </script> 
 </head> 
 <body onload="load();"> 
 <table id="t"> 
   <tr><td id="t1">un</td></tr> 
   <tr><td id="t2">deux</td></tr> 
 </table> 
 </body> 
 </html>

Dans l'exemple ci-dessus, modifieTexte() est un écouteur pour les évènements click enregistré à l'aide de addEventListener(). Un clic n'importe où sur le tableau se propagera jusqu'au gestionnaire et exécutera modifieTexte().

Notes

Raisons d'utiliser `addEventListener`

addEventListener est la manière d'enregistrer un écouteur telle que spécifiée dans le DOM du W3C. Ses avantages sont les suivants :

Elle permet d'ajouter plus d'un seul gestionnaire pour un évènement. Cela peut s'avérer particulièrement utile pour les bibliothèques DHTML ou les extensions de Mozilla qui doivent fonctionner correctement même si d'autres bibliothèques/extensions sont utilisées.
Elle donne un contrôle plus fin sur la phase d'activation de l'écouteur (capture ou propagation)
Elle fonctionne sur tout élément DOM, pas uniquement les éléments HTML.

L'ancienne manière alternative d'enregistrer des évènements est décrite ci-dessous.

Ajout d'un écouteur durant le traitement d'un évènement

Si un écouteur (EventListener) est ajouté à une cible (EventTarget) pendant que celle-ci est en train de traiter un évènement, il ne sera pas déclenché par l'action en cours mais peut être déclenché à un stade ultérieur de l'évènement, par exemple en phase de propagation (bubbling).

Écouteurs multiples et identiques

Si plusieurs écouteurs (EventListeners) sont enregistrés sur la même cible (EventTarget) avec les mêmes paramètres, les instances en double sont ignorées. L'écouteur ne sera pas appelé plusieurs fois, et comme elles seront ignorées elles ne doivent pas être enlevés à l'aide de la méthode removeEventListener.

La valeur de `this`

L'attachement d'une fonction à l'aide de addEventListener() modifie la valeur de this — notez que la valeur de this est passée à une fonction par son appelant.

Dans l'exemple ci-dessus, la valeur de this au sein de modifieTexte() lorsqu'appelée depuis l'évènement onclick est une référence au tableau « t ». Si le gestionnaire onclick est ajouté au code source HTML :

<table id="t" onclick="modifieTexte();">
...
</table>

alors la valeur de this au sein de modifieTexte() lorsqu'appelée depuis l'évènement onclick sera une référence à l'objet global (window).

Internet Explorer

Dans IE, il est nécessaire d'utiliser attachEvent plutôt que la méthode standard addEventListener. Pour que le code fonctionne dans IE, l'exemple ci-dessus peut être adapté en :

if (el.addEventListener){
  el.addEventListener('click', modifieTexte, false);
} else if (el.attachEvent) {
  el.attachEvent('onclick', modifieTexte);
}

Attention, dans attachEvent la valeur de this est une référence à l'objet window, et non à l'élément appelant !

Ancienne manière d'attacher des évènements

La méthode addEventListener() a été ajoutée dans la spécification DOM 2 Events. Avant cela, les évènements étaient attachés de la manière suivante :

// Utilisation d'une référence à une fonction — notez l'absence de parenthèses
el.onclick = modifyText;
 
// Utilisation d'une fonction directe
element.onclick = function() {
  ...instructions...
};

Cette méthode remplace le gestionnaire d'évènement onclick de l'élément le cas échéant. De même pour les autres évènements « on » comme onblur, onkeypress, et ainsi de suite.

Comme elle faisait essentiellement partie du DOM 0, cette méthode est très largement supportée et ne nécessite aucun code spécial pour gérer les différents navigateurs. C'est pourquoi elle est souvent utilisée pour attacher des évènements dynamiquement tant que les fonctionnalités supplémentaires de addEventListener() ne sont pas nécessaires.

Voir également

removeEventListener()

Spécification

Spécification DOM Level 2 Events : addEventListener
Traduction en français (non normative) : addEventListener