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

CKTIS / JavaScript

Eventos do navegador e propagação

Os eventos permitem reagir a ações do utilizador e a alterações no estado da página. Aprende as fases de captura, alvo e borbulhamento, distingue o cancelamento da ação predefinida da interrupção da propagação e conhece os eventos de ciclo de vida, visibilidade, deslocamento, redimensionamento e entrada.

Versão: Web APIs defined by web standards, not ECMAScript editions. Check support in target browsers; Node 24 in the repository does not establish browser API support.

Sintaxe

target.addEventListener(type, handler, options);
target.removeEventListener(type, handler, options);
target.dispatchEvent(event);

Modelo e âmbito

Os eventos do navegador fazem parte das API do ambiente anfitrião, não da sintaxe de ECMAScript. A norma DOM define o modelo de eventos, o seu envio e propagação e as opções dos ouvintes. A norma HTML define, entre outras coisas, quando são emitidos DOMContentLoaded e load e quando ocorrem input e change nos controlos de formulário. Não associes estas API a uma edição de ECMAScript. Node 24 não comprova o suporte das API do navegador. Verifica a compatibilidade nos navegadores de destino.

Propagação e cancelamento

addEventListener(type, handler, options) regista um tratador. O evento passa pela captura nos antepassados, pelo alvo e, se bubbles for verdadeiro, sobe pelos antepassados. target indica o alvo; currentTarget, o objeto do ouvinte ativo. stopPropagation() trava a propagação sem impedir que sejam chamados os restantes ouvintes da série em curso. No entanto, se um ouvinte de captura no alvo chamar stopPropagation(), a série separada de chamadas aos ouvintes sem captura nesse mesmo alvo não se realiza. stopImmediatePropagation() impede também que sejam chamados os restantes ouvintes da série em curso. preventDefault() cancela a ação predefinida só se o evento for cancelável e o ouvinte não for passivo. Não trava a propagação.

Ciclo de vida e visibilidade

DOMContentLoaded em document: terminam a análise e os scripts que o atrasam, não necessariamente a carga de todos os recursos. load em window espera ainda pelos recursos que o atrasam. pageshow e pagehide abrangem a cache de retrocesso/avanço; verifica persisted. Em visibilitychange em document, lê document.visibilityState. Oculta não quer dizer fechada; unload não garante uma gravação final.

Deslocamento, tamanho e entrada

scroll diz respeito ao alvo deslocado; resize em window, ao tamanho da área visível. Nem tudo sobe. Mantém leves os tratadores frequentes. input indica edição pelo utilizador; change, confirmação conforme o controlo. Atribuir .value não emite nenhum. Distingue keydown, eventos de ponteiro e click semântico; não dependas só do rato.

Gestão de ouvintes

once remove o ouvinte antes de o seu tratador ser chamado pela primeira vez. Se esse tratador emitir de forma síncrona outro evento do mesmo tipo, o ouvinte removido não trata esse evento. passive torna preventDefault() ineficaz e signal permite remover por interrupção. Para removeEventListener, guarda tipo, referência da função e valor de capture. No exemplo, dispatchEvent() é síncrono: false indica cancelamento, não propagação interrompida.

Identificadores de referência abrangidos por esta entrada: Page lifecycle, visibility, scroll/resize and input events.

Exemplos

(() => {
  const parent = document.createElement('div');
  const child = document.createElement('button');
  parent.append(child);
  const log = [];

  parent.addEventListener('demo', () => log.push('capture'), { capture: true });
  child.addEventListener('demo', event => {
    log.push('target');
    event.preventDefault();
  });
  parent.addEventListener('demo', () => log.push('bubble'));

  const accepted = child.dispatchEvent(new Event('demo', {
    bubbles: true,
    cancelable: true
  }));
  console.log(log.join(' > '));
  console.log(accepted);
})();

Resultado

capture > target > bubble
false

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes