CKTIS / JavaScript
EventTarget.addEventListener — registar ouvintes de eventos
EventTarget.addEventListener regista uma função de callback para um evento. As opções capture, once e passive controlam a sua invocação e se o ouvinte pode cancelar o evento.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
target.addEventListener(type, callback, options);
// options: boolean capture, or { capture, once, passive, signal }EventTarget.addEventListener regista um callback para o tipo de evento type. O terceiro argumento é um objeto de opções ou um valor booleano que representa capture. Esta API pertence à norma DOM, não ao próprio ECMAScript.
capture: true seleciona a fase de captura em vez da propagação por bubbling nos antepassados; ambas as definições permitem a invocação no próprio alvo. capture e once têm o valor predefinido false. Com once: true, o registo é removido antes de se invocar callback. Se callback disparar um evento durante essa invocação, o disparo aninhado não pode voltar a invocar callback através do mesmo registo. passive: true impede o cancelamento através de preventDefault(), mas não interrompe a propagação. Para cancelar um evento cancelável, define explicitamente passive: false: omitir a opção nem sempre significa false.
Os duplicados são identificados por type, pela identidade de callback e por capture; registar novamente não atualiza as opções. removeEventListener requer os mesmos três valores. O exemplo usa um alvo autónomo, pelo que não demonstra a propagação entre elementos.
Exemplos
const target = new EventTarget();
let calls = 0;
target.addEventListener('demo', (event) => {
calls++;
event.preventDefault();
}, { capture: false, once: true, passive: false });
const first = new Event('demo', { cancelable: true });
target.dispatchEvent(first);
target.dispatchEvent(new Event('demo'));
console.log(calls, first.defaultPrevented);Resultado
1 true
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.