CKTIS / JavaScript
Eventos `scroll` e `resize` e a opção `passive`
Escolhe o alvo certo para os eventos de deslocamento e redimensionamento e percebe quando um listener passivo impede o cancelamento da ação predefinida.
Versão: Current web platform; runtime support varies
Sintaxe
// ECMAScript 2024 identifies the JavaScript language reference, not the version of these browser APIs.
// The DOM Standard defines the passive listener option, CSSOM View defines scroll and resize,
// and the Resize Observer specification defines ResizeObserver.
document.addEventListener("scroll", onPageScroll);
scrollContainer.addEventListener("scroll", onElementScroll);
window.addEventListener("resize", onViewportResize);
scrollContainer.addEventListener("wheel", onWheel, { passive: true });
scrollContainer.removeEventListener("wheel", onWheel);
const observer = new ResizeObserver(onElementResize);
observer.observe(element);
// When observation is no longer needed:
observer.disconnect();Escuta scroll em document para acompanhar o deslocamento da página ou diretamente no elemento que se desloca para acompanhar alterações num contentor. scroll assinala uma mudança de posição, quer seja provocada pelo utilizador, quer pelo código. wheel assinala uma entrada que não provoca necessariamente deslocamento. Escuta resize em window para detetar alterações no tamanho da área de visualização; este evento não se propaga na fase ascendente. Usa ResizeObserver para observar o tamanho de um elemento.
Passa { passive: true } no objeto de opções, como terceiro argumento de addEventListener(); um booleano isolado nessa posição define capture, não passive. Num listener passivo, preventDefault() não tem efeito e pode gerar um aviso. { passive: false } só permite cancelar a ação predefinida se event.cancelable for true. Os eventos scroll do documento ou de um elemento e os eventos resize da janela gerados pelo navegador não são canceláveis; a opção não altera esse comportamento.
Para entradas como wheel ou touchmove, um listener passivo permite que o navegador comece a deslocar a página ou o contentor sem esperar que esse listener termine. Se omitires a opção, o valor predefinido pode depender do evento, do alvo e do navegador. Define passive: true se apenas observares a entrada. Se precisares de cancelar a ação, define passive: false e verifica event.cancelable.
passive não reduz a frequência das chamadas nem o seu custo. Mantém curtos os handlers de eventos frequentes e usa um temporizador para limitar a frequência de operações dispendiosas, se necessário. requestAnimationFrame() ajuda a sincronizar as atualizações visuais com os fotogramas, mas, por si só, não garante uma frequência inferior à de scroll.
Para remover o listener, chama removeEventListener() no mesmo alvo, com o mesmo tipo, a mesma função e o mesmo valor de capture; passive não conta para a correspondência. Estas APIs pertencem à plataforma Web, não ao ECMAScript 2024. Verifica o suporte no ambiente de execução de destino.
Exemplos
{
const cases = [
["scroll", false, false],
["resize", false, false],
["wheel", true, true],
["wheel", true, false],
];
for (const [type, cancelable, passive] of cases) {
const target = new EventTarget();
target.addEventListener(type, (event) => event.preventDefault(), { passive });
const event = new Event(type, { cancelable });
target.dispatchEvent(event);
console.log(`${type} cancelable=${event.cancelable} passive=${passive} defaultPrevented=${event.defaultPrevented}`);
}
}Resultado
scroll cancelable=false passive=false defaultPrevented=false resize cancelable=false passive=false defaultPrevented=false wheel cancelable=true passive=true defaultPrevented=false wheel cancelable=true passive=false defaultPrevented=true
Executa o código na consola do navegador. Os eventos sintéticos não deslocam a página nem redimensionam a janela. Só o último caso define `defaultPrevented` como `true`: o evento é cancelável e o listener não é passivo. A tentativa de cancelamento no listener passivo pode gerar um aviso separado.
Lições relacionadas
- JavaScript · Lição 11 · Avançado · Versão: 4
Fontes
- Document: scroll event
- Element: scroll event
- Window: resize event
- ResizeObserver
- EventTarget: addEventListener() method
- EventTarget: removeEventListener() method
- Event: preventDefault() method
- Element: wheel event
- Event: Event() constructor
- EventTarget: dispatchEvent() method
- HTML Standard: Processing model
- ECMAScript 2024 Language Specification: Hosts and Implementations