EventTarget.removeEventListener()

Sintaxis

target.removeEventListener(type, listener[, options]);
target.removeEventListener(tipo, listener[, useCapture])

Parámetros

tipo

Un string representando el tipo de evento del que se está removiendo un detector de evento.

detector (listener)

La función EventListener del manejador de evento a eliminar del objetivo del evento.

options Opcional

Un objeto que especifíca diversas características acerca del detector de eventos. Las opciones disponibles son:

• capture: Un Boolean que indica que eventos de este tipo serán enviados al listener antes de ser enviado a cualquier EventTarget debado de éste en el DOM.

useCapture Opcional

Especifíca si el EventListener que se está eliminando fue registrado como un detector de captura o no. Si no se indica, por defecto useCapture asumirá el valor false.

Si un detector se registro dos veces, uno con captura y otro sin, cada uno debe ser eliminado por separado. La eliminación de un detector de captura no afecta a una versión de "no-captura" del mismo detector, y viceversa.

Valor de retorno

undefined.

Coincidiendo disparadores de evento para su eliminación

Habiendose añadido detector de evento llamando addEventListener(), puede llegar un punto donde se requiera eliminar. Obviamente, se necesita especificar los mismos parámetros de tipo y listener a removeEventListener(), pero que hay acerca de los parámetros de options o de useCapture?

Mientras addEventListener() permite añadir el mismo detector más de una vez para el mismo tipo, si la opción es diferente, la única opción que removeEventListener() revisará es la bandera de capture/useCapture. Su valor debe coincidir con removeEventListener() para coincidir, pero otros valores no necesitan corresponder.

Por ejemplo, considerar la siguiente llamada a addEventListener():

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

Ahora, considera removeEventListener():

element.removeEventListener("mousedown", handleMouseDown, false); // Fallo
element.removeEventListener("mousedown", handleMouseDown, true); // Éxito

La primera llamada falla porque el valor de useCapture no coincide. El segundo valor funciona, puesto que useCapture es igual a su valor cuando se añadió el detector.

Ahora considera lo siguiente:

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

Aqui, especificamos un objeto options en el cual passive esta definido como true, mientras que otras opciones son dejados con su valor por defecto de false.

Vea consecutivamente, cada una de las siguientes llamadas a removeEventListener(). Cualquiera de éstas donde capture o useCapture es true falla; en todas las demás funciona. Solo la configuración capture importa a removeEventListener().

element.removeEventListener("mousedown", handleMouseDown, { passive: true }); // Funciona
element.removeEventListener("mousedown", handleMouseDown, { capture: false }); // Funciona
element.removeEventListener("mousedown", handleMouseDown, { capture: true }); // Falla
element.removeEventListener("mousedown", handleMouseDown, { passive: false }); // Funciona
element.removeEventListener("mousedown", handleMouseDown, false); // Funciona
element.removeEventListener("mousedown", handleMouseDown, true); // Falla

Vale la pena mencionar que algunos navegadores tienen un comportamiento inconsistente, y a menos que se tengan razones específicas, es probablemente una buena idea usar los mismos valores usados por la llamada a addEventListener() al momento de utilizar removeEventListener().

Notas

Si un EventListener es removido de un EventTarget cuando aún se está procesando el evento, no será ejecutado. Después de ser removido, un EventListener no será invocado por el evento al cual se registró, sin embargo se podrá adjuntar de nuevo a dicho evento.

Llamar <code>removeEventListener</code> en algún EventTarget que no contenga el EventListener especificado será un acción sin efecto, es decir, se podrá llamar <code>removeEventListener</code> sin efectos negativos en los scripts.

Ejemplo

Este es un ejemplo en donde se agrega y después se elimina un EventListener

var body = document.querySelector("body"),
  clickTarget = document.getElementById("click-target"),
  mouseOverTarget = document.getElementById("mouse-over-target"),
  toggle = false;

function makeBackgroundYellow() {
  "use strict";

  if (toggle) {
    body.style.backgroundColor = "white";
  } else {
    body.style.backgroundColor = "yellow";
  }

  toggle = !toggle;
}

clickTarget.addEventListener("click", makeBackgroundYellow, false);

mouseOverTarget.addEventListener("mouseover", function () {
  "use strict";

  clickTarget.removeEventListener("click", makeBackgroundYellow, false);
});

Especificaciones

Compatibilidad con navegadores

Ver también

• EventTarget.addEventListener().
• No estándar EventTarget.detachEvent().