Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

La opción `passive` de `EventTarget.addEventListener()`

Con `passive: true`, el escuchador recibe el evento, pero no puede cancelar su acción predeterminada. Omitir la opción no siempre equivale a pasar `false`.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

target.addEventListener(type, listener)
target.addEventListener(type, listener, useCapture)
target.addEventListener(type, listener, { passive: true })
target.addEventListener(type, listener, { passive: false })

passive es una propiedad booleana opcional del objeto que se pasa como tercer argumento a target.addEventListener(type, listener, options). Si el tercer argumento es un booleano, solo configura capture, no passive. Es una API del DOM de la plataforma web, no una función del lenguaje ECMAScript 2024; comprueba la compatibilidad en el entorno de ejecución de destino.

Con passive: true, el escuchador se ejecuta, pero si llama a event.preventDefault(), la llamada no tiene efecto y puede generar un aviso en la consola. Esto no cambia la propagación del evento. Con passive: false, el escuchador puede cancelar la acción predeterminada mediante preventDefault(), pero solo si event.cancelable es true.

Si omites passive, el estándar DOM especifica false como valor predeterminado, salvo para wheel, mousewheel, touchstart y touchmove al registrar el escuchador en Window, Document, document.documentElement o document.body: en esos casos especifica true. Que el navegador admita la opción no garantiza que aplique esos valores predeterminados: los casos en que se ha usado true por defecto han variado entre navegadores y versiones, también en Safari. Indica false explícitamente si necesitas cancelar la acción. Usa true si solo observas la entrada, para que el navegador pueda iniciar el desplazamiento sin esperar a ese escuchador. El propio evento scroll no es cancelable.

Volver a registrar el escuchador en el mismo destino con el mismo tipo, la misma función de escucha y el mismo valor de capture no cambia passive. Elimínalo con removeEventListener() haciendo coincidir el tipo, la función y capture, y luego añádelo de nuevo. passive no se usa para identificar el escuchador al eliminarlo ni controla su duración.

Ejemplos

{
  const target = new EventTarget();
  const type = "passive-demo";
  const listener = (event) => event.preventDefault();

  for (const passive of [true, false]) {
    target.addEventListener(type, listener, { passive });
    const event = new Event(type, { cancelable: true });
    const result = target.dispatchEvent(event);
    console.log(`passive=${passive}, defaultPrevented=${event.defaultPrevented}, dispatchEvent=${result}`);
    target.removeEventListener(type, listener);
  }
}

Resultado

passive=true, defaultPrevented=false, dispatchEvent=true
passive=false, defaultPrevented=true, dispatchEvent=false

Cada iteración despacha un evento sintético nuevo y cancelable. `defaultPrevented` indica si se ha cancelado y `dispatchEvent()` devuelve `false` solo en la iteración en la que se logra cancelar el evento. El navegador puede mostrar un aviso; el ejemplo no mide el rendimiento del desplazamiento.

Lecciones relacionadas

  • JavaScript · Lección 33 · Avanzado · Versión: 4
  • JavaScript · Lección 36 · Avanzado · Versión: 4
  • JavaScript · Lección 45 · Avanzado · Versión: 4

Fuentes