EventTarget.removeEventListener()

This translation is incomplete. Please help translate this article from English

El método EventTarget.removeEventListener() remueve del EventTarget un detector de evento previamente registrado con EventTarget.addEventListener. El detector de evento a ser removido es identificado usando una combinación de de tipos de eventos, la misma funcion del detector de eventos, y muchas opciones adicionales que pueden afectar

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 Optional
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.
  • mozSystemGroup: Sólo disponible ejecutando XBL o Firefox' chrome, es un Boolean que define si el detector es añadido al grupo del sistema.
useCapture Optional
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 removeEventListener  en algún EventTarget que no contenga el EventListener especificado será un acción sin efecto, es decir, se podrá llamar removeEventListener 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

Especificación Estado Comentario
DOM
La definición de 'EventTarget.removeEventListener()' en esta especificación.
Living Standard
DOM4
La definición de 'EventTarget.removeEventListener()' en esta especificación.
Obsolete
Document Object Model (DOM) Level 2 Events Specification
La definición de 'EventTarget.removeEventListener()' en esta especificación.
Obsolete Definición inicial

Compatibilidad de los navegadores

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome para AndroidFirefox para AndroidOpera para AndroidSafari en iOSSamsung Internet
removeEventListenerChrome Soporte completo 1Edge Soporte completo 12Firefox Soporte completo 1IE Soporte completo 9
Soporte completo 9
Sin soporte 6 — 11
Notas Nombre alternativo
Notas Older versions of IE supported an equivalent, proprietary EventTarget.detachEvent() method.
Nombre alternativo Usa un nombre no estandar : detachEvent
Opera Soporte completo 7Safari Soporte completo 1WebView Android Soporte completo 1Chrome Android Soporte completo 18Firefox Android Soporte completo 4Opera Android Soporte completo 10.1Safari iOS Soporte completo 1Samsung Internet Android Soporte completo 1.0
type and listener parameters optional.Chrome Sin soporte 1 — 49Edge Soporte completo SiFirefox Soporte completo SiIE Soporte completo SiOpera Soporte completo SiSafari Soporte completo SiWebView Android Sin soporte 1 — 49Chrome Android Sin soporte 18 — 49Firefox Android Soporte completo SiOpera Android Soporte completo SiSafari iOS Soporte completo SiSamsung Internet Android Sin soporte 1.0 — 5.0
useCapture parameter optionalChrome Soporte completo 1Edge Soporte completo SiFirefox Soporte completo 6IE Soporte completo 9Opera Soporte completo 11.6Safari Soporte completo SiWebView Android Soporte completo 1Chrome Android Soporte completo 18Firefox Android Soporte completo 6Opera Android Soporte completo 12Safari iOS Soporte completo SiSamsung Internet Android Soporte completo 1.0
Form with options object supported (third parameter can be either options or a Boolean, for backwards compatibility)Chrome Soporte completo 49Edge Soporte completo SiFirefox Soporte completo 49IE Sin soporte NoOpera Soporte completo SiSafari Soporte completo 10WebView Android Soporte completo 49Chrome Android Soporte completo 49Firefox Android Soporte completo 49Opera Android Soporte completo SiSafari iOS Soporte completo 10Samsung Internet Android Soporte completo 5.0

Leyenda

Soporte completo  
Soporte completo
Sin soporte  
Sin soporte
Ver notas de implementación.
Ver notas de implementación.
Usa un nombre no estandar.
Usa un nombre no estandar.

Polyfill to support older browsers

addEventListener() and removeEventListener() are not present in older browsers. You can work around this by inserting the following code at the beginning of your scripts, allowing use of addEventListener() and removeEventListener() in implementations which do not natively support it. However, this method will not work on Internet Explorer 7 or earlier, since extending the Element.prototype was not supported until Internet Explorer 8.

if (!Element.prototype.addEventListener) {
  var oListeners = {};
  function runListeners(oEvent) {
    if (!oEvent) { oEvent = window.event; }
    for (var iLstId = 0, iElId = 0, oEvtListeners = oListeners[oEvent.type]; iElId < oEvtListeners.aEls.length; iElId++) {
      if (oEvtListeners.aEls[iElId] === this) {
        for (iLstId; iLstId < oEvtListeners.aEvts[iElId].length; iLstId++) { oEvtListeners.aEvts[iElId][iLstId].call(this, oEvent); }
        break;
      }
    }
  }
  Element.prototype.addEventListener = function (sEventType, fListener /*, useCapture (will be ignored!) */) {
    if (oListeners.hasOwnProperty(sEventType)) {
      var oEvtListeners = oListeners[sEventType];
      for (var nElIdx = -1, iElId = 0; iElId < oEvtListeners.aEls.length; iElId++) {
        if (oEvtListeners.aEls[iElId] === this) { nElIdx = iElId; break; }
      }
      if (nElIdx === -1) {
        oEvtListeners.aEls.push(this);
        oEvtListeners.aEvts.push([fListener]);
        this["on" + sEventType] = runListeners;
      } else {
        var aElListeners = oEvtListeners.aEvts[nElIdx];
        if (this["on" + sEventType] !== runListeners) {
          aElListeners.splice(0);
          this["on" + sEventType] = runListeners;
        }
        for (var iLstId = 0; iLstId < aElListeners.length; iLstId++) {
          if (aElListeners[iLstId] === fListener) { return; }
        }     
        aElListeners.push(fListener);
      }
    } else {
      oListeners[sEventType] = { aEls: [this], aEvts: [ [fListener] ] };
      this["on" + sEventType] = runListeners;
    }
  };
  Element.prototype.removeEventListener = function (sEventType, fListener /*, useCapture (will be ignored!) */) {
    if (!oListeners.hasOwnProperty(sEventType)) { return; }
    var oEvtListeners = oListeners[sEventType];
    for (var nElIdx = -1, iElId = 0; iElId < oEvtListeners.aEls.length; iElId++) {
      if (oEvtListeners.aEls[iElId] === this) { nElIdx = iElId; break; }
    }
    if (nElIdx === -1) { return; }
    for (var iLstId = 0, aElListeners = oEvtListeners.aEvts[nElIdx]; iLstId < aElListeners.length; iLstId++) {
      if (aElListeners[iLstId] === fListener) { aElListeners.splice(iLstId, 1); }
    }
  };
}

Ver también