CKTIS / JavaScript
A opção `passive` de `EventTarget.addEventListener()`
Com `passive: true`, o listener recebe o evento, mas não pode cancelar a sua ação predefinida. Omitir a opção nem sempre é o mesmo que passar `false`.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
target.addEventListener(type, listener)
target.addEventListener(type, listener, useCapture)
target.addEventListener(type, listener, { passive: true })
target.addEventListener(type, listener, { passive: false })passive é uma propriedade booleana opcional do objeto passado como terceiro argumento a target.addEventListener(type, listener, options). Se o terceiro argumento for apenas um valor booleano, configura capture, não passive. Esta é uma API do DOM da plataforma web, não uma funcionalidade da linguagem ECMAScript 2024; confirma se o ambiente de execução de destino a suporta.
Com passive: true, o listener continua a ser executado, mas uma chamada sua a event.preventDefault() não tem efeito e pode gerar um aviso na consola. Isto não altera a propagação do evento. Com passive: false, o listener pode cancelar a ação predefinida com preventDefault(), mas apenas se event.cancelable for true.
Se omitires passive, a norma DOM especifica false como valor predefinido, exceto para wheel, mousewheel, touchstart e touchmove quando o listener é registado em Window, Document, document.documentElement ou document.body: nesses casos, especifica true. O suporte da opção não garante que estes valores predefinidos sejam aplicados: os casos em que true era usado por predefinição variaram consoante o navegador e a versão, incluindo no Safari. Indica false explicitamente se precisares de cancelar a ação. Usa true se só precisares de observar a entrada, para que o navegador possa iniciar o deslocamento sem esperar pelo listener. O evento scroll em si não é cancelável.
Voltar a registar o listener no mesmo alvo com o mesmo tipo, a mesma função de callback e o mesmo valor de capture não altera passive. Remove-o com removeEventListener(), usando o tipo, a função e o valor de capture correspondentes, e volta a adicioná-lo. passive não é usado para identificar o listener na remoção nem controla o seu tempo de vida.
Exemplos
{
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 iteração despacha um novo evento sintético cancelável. `defaultPrevented` indica se foi cancelado e `dispatchEvent()` devolve `false` apenas na iteração em que o cancelamento é bem-sucedido. O navegador pode mostrar um aviso; o exemplo não mede o desempenho do deslocamento.
Lições relacionadas
- JavaScript · Lição 33 · Avançado · Versão: 4
- JavaScript · Lição 36 · Avançado · Versão: 4
- JavaScript · Lição 45 · Avançado · Versão: 4