Cette page a été traduite à partir de l'anglais par la communauté. Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.

View in English Always switch to English

EventTarget : méthode removeEventListener()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨juillet 2015⁩.

Note : Cette fonctionnalité est disponible via les Web Workers.

La méthode removeEventListener() de l'interface EventTarget permet de supprimer un écouteur d'événement précédemment enregistré avec EventTarget.addEventListener() sur la cible. L'écouteur à supprimer est identifié par une combinaison du type d'événement, de la fonction d'écoute elle-même, et de diverses options qui peuvent influencer la correspondance (voir Correspondance des écouteurs à supprimer).

Si les arguments passés à removeEventListener() ne correspondent à aucun écouteur d'événement actuellement enregistré sur l'EventTarget, cela n'a aucun effet.

Si un écouteur d'événement est supprimé d'un EventTarget pendant qu'un autre écouteur traite un événement, il ne sera pas déclenché par cet événement. Il peut cependant être réattaché par la suite.

Attention : Si un écouteur est enregistré deux fois, une fois avec l'option capture et une fois sans, il faut supprimer chaque version séparément. Supprimer un écouteur en mode capture n'affecte pas la version sans capture du même écouteur, et inversement.

Les écouteurs d'événements peuvent aussi être supprimés en passant un objet AbortSignal à addEventListener(), puis en appelant abort() sur le contrôleur propriétaire du signal.

Syntaxe

js
removeEventListener(type, listener)
removeEventListener(type, listener, options)
removeEventListener(type, listener, useCapture)

Paramètres

type

Chaîne de caractères qui précise le type d'événement pour lequel supprimer un écouteur.

listener

La fonction écouteur d'événement à supprimer de la cible.

options Facultatif

Objet d'options qui précise les caractéristiques de l'écouteur d'événement.

Les options disponibles sont :

  • capture : Booléen qui indique si l'écouteur d'événement à supprimer a été enregistré en mode capture ou non. Si ce paramètre est absent, la valeur par défaut est false.
useCapture Facultatif

Booléen qui indique si l'écouteur d'événement à supprimer a été enregistré en mode capture ou non. Si ce paramètre est absent, la valeur par défaut est false.

Valeur de retour

Aucune (undefined).

Correspondance des écouteurs à supprimer

Lorsqu'un écouteur d'événement a été ajouté avec addEventListener(), il peut arriver que vous deviez le supprimer. Il faut alors spécifier les mêmes paramètres type et listener à removeEventListener(). Mais qu'en est-il des paramètres options ou useCapture ?

Bien que addEventListener() permette d'ajouter plusieurs fois le même écouteur pour un même type si les options diffèrent, la seule option prise en compte par removeEventListener() est le drapeau capture/useCapture. Sa valeur doit correspondre pour que la suppression fonctionne, les autres options n'ont pas d'importance.

Par exemple :

js
element.addEventListener("mousedown", handleMouseDown, true);

Considérez ces deux appels à removeEventListener() :

js
element.removeEventListener("mousedown", handleMouseDown, false); // Échec
element.removeEventListener("mousedown", handleMouseDown, true); // Succès

Le premier échoue car la valeur de useCapture ne correspond pas. Le second réussit car la valeur correspond.

Autre exemple :

js
element.addEventListener("mousedown", handleMouseDown, { passive: true });

Ici, on spécifie un objet d'options où passive vaut true, les autres options restant à false par défaut.

Considérez ces appels à removeEventListener() : tous ceux où capture ou useCapture vaut true échouent ; les autres réussissent.

Seule l'option capture compte pour removeEventListener().

js
element.removeEventListener("mousedown", handleMouseDown, { passive: true }); // Succès
element.removeEventListener("mousedown", handleMouseDown, { capture: false }); // Succès
element.removeEventListener("mousedown", handleMouseDown, { capture: true }); // Échec
element.removeEventListener("mousedown", handleMouseDown, { passive: false }); // Succès
element.removeEventListener("mousedown", handleMouseDown, false); // Succès
element.removeEventListener("mousedown", handleMouseDown, true); // Échec

À noter : certains navigateurs ont pu être incohérents sur ce point. Sauf raison particulière, il est conseillé d'utiliser les mêmes valeurs que lors de l'appel à addEventListener().

Exemple

Cet exemple montre comment ajouter un écouteur d'événement basé sur mouseover qui supprime un écouteur basé sur click.

js
const body = document.querySelector("body");
const clickTarget = document.getElementById("click-target");
const mouseOverTarget = document.getElementById("mouse-over-target");

let toggle = false;
function makeBackgroundYellow() {
  body.style.backgroundColor = toggle ? "white" : "yellow";

  toggle = !toggle;
}

clickTarget.addEventListener("click", makeBackgroundYellow);

mouseOverTarget.addEventListener("mouseover", () => {
  clickTarget.removeEventListener("click", makeBackgroundYellow);
});

Spécifications

Specification
DOM
# ref-for-dom-eventtarget-removeeventlistener②

Compatibilité des navigateurs

Voir aussi