CKTIS / JavaScript
DOMContentLoaded e a opção once do listener
Usa `DOMContentLoaded` para aguardar pela análise do HTML e `{ once: true }` para limitar cada registo do listener a uma chamada. Consulta `document.readyState` se o código puder arrancar mais tarde.
Versão: HTML Living Standard and DOM Standard; runtime support varies
Sintaxe
document.addEventListener("DOMContentLoaded", init, { once: true });
// Instead, if init only needs the parsed DOM and may be set up late:
if (document.readyState === "loading") {
document.addEventListener("DOMContentLoaded", init, { once: true });
} else {
init();
}O navegador dispara DOMContentLoaded em document depois de analisar o HTML e executar os scripts previstos para depois da análise: os scripts com defer e os módulos sem async. Não espera pelo trabalho retomado após um await ao nível superior de um módulo. Ao contrário de load, o evento não espera pelas imagens, pelas molduras incorporadas nem pelos scripts async. As folhas de estilo podem atrasá-lo indiretamente se bloquearem scripts pelos quais o evento espera.
Em document.addEventListener("DOMContentLoaded", init, { once: true }), once remove automaticamente esse registo antes da primeira chamada de init pelo evento. O valor predefinido é false. Passar apenas true como terceiro argumento ativa capture, não once. A opção não repete um evento passado nem limita chamadas manuais ou registos posteriores.
Se init só precisar do DOM já analisado, consulta document.readyState: se for "loading", regista o listener; caso contrário, chama logo init(). O navegador não pode disparar o evento entre esta verificação síncrona e o registo. "interactive" significa que a análise terminou, não que DOMContentLoaded já tenha ocorrido. Se a inicialização depender de outro script, faz a sincronização explicitamente com esse script.
O evento, a propriedade de estado e a opção do listener fazem parte das API da plataforma Web, não de ECMAScript. O suporte de ECMAScript 2024 não garante a sua disponibilidade num dado ambiente de execução.
Exemplos
(() => {
const target = new EventTarget();
let calls = 0;
target.addEventListener("DOMContentLoaded", () => {
calls += 1;
}, { once: true });
target.dispatchEvent(new Event("DOMContentLoaded"));
console.log(`After first dispatch: ${calls}`);
target.dispatchEvent(new Event("DOMContentLoaded"));
console.log(`After second dispatch: ${calls}`);
})();Resultado
After first dispatch: 1 After second dispatch: 1
Executa o código na consola do navegador. Os dois eventos sintéticos com o mesmo nome são enviados para um `EventTarget` separado, não para `document`. Mostram o efeito de `once`, não quando a página fica pronta.
Lições relacionadas
- JavaScript · Lição 39 · Intermédio · Versão: 3