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