Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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

Fontes