CKTIS / JavaScript
Os eventos DOMContentLoaded, hashchange, mouseover e focusin
Escolhe onde escutar a disponibilidade do DOM, a mudança de fragmento do URL, a entrada do ponteiro e o foco. Delega os eventos dos descendentes num contentor comum.
Versão: Current web platform; runtime support varies
Sintaxe
document.addEventListener("DOMContentLoaded", onReady, { once: true });
window.addEventListener("hashchange", onHashChange);
container.addEventListener("mouseover", onMouseOver);
container.addEventListener("focusin", onFocusIn);Estes quatro eventos assinalam situações diferentes: disponibilidade do documento, navegação por fragmentos, movimento do ponteiro e mudança de foco. São API da plataforma Web. No campo de versão, ECMAScript 2024 refere-se apenas à linguagem JavaScript e não indica se estes eventos são suportados. Verifica o suporte nos navegadores de destino: um ambiente JavaScript, por si só, não garante a existência de um DOM.
Escuta DOMContentLoaded em document. O navegador dispara este Event não cancelável depois de analisar o HTML e executar os scripts clássicos com defer e os módulos sem async. Não espera por imagens nem por scripts async; as folhas de estilo podem atrasá-lo indiretamente se bloquearem um script. Se a inicialização só precisar do DOM já construído pelo analisador, regista um listener com { once: true } quando document.readyState === "loading"; caso contrário, inicializa de imediato. O estado "interactive" não prova que o evento já tenha ocorrido.
Escuta hashchange em window quando uma navegação alterar o fragmento do URL no mesmo documento, por exemplo ao atribuir um valor a location.hash. O HashChangeEvent contém os URL completos em oldURL e newURL. Chamar history.pushState() ou history.replaceState() não dispara, por si só, hashchange, mesmo que o fragmento mude.
mouseover é um MouseEvent disparado no elemento em que o ponteiro entra. Propaga-se para os antepassados, pelo que mover o ponteiro entre descendentes também pode ativar o listener do contentor. relatedTarget indica o elemento que o ponteiro deixou, ou vale null se não houver um alvo secundário. Para detetar apenas entradas a partir do exterior do contentor, escuta diretamente mouseenter, que não se propaga para os antepassados.
focusin é um FocusEvent não cancelável disparado quando um elemento recebe o foco, por exemplo ao premir Tab. Ao contrário de focus, focusin propaga-se para os antepassados. Ao delegar focusin ou mouseover numa árvore DOM normal, usa event.target para identificar o elemento afetado e event.currentTarget para identificar o contentor cujo listener está a ser executado.
Exemplos
(() => {
const { document, window, HashChangeEvent, MouseEvent, FocusEvent } =
typeof globalThis.document === "undefined" ? createNodeDemo() : globalThis;
const container = document.createElement("div");
const button = document.createElement("button");
container.append(button);
document.addEventListener("DOMContentLoaded", (event) => {
console.log(`${event.type}: document=${event.target === document}`);
}, { once: true });
window.addEventListener("hashchange", (event) => {
console.log(`${event.type}: ${new URL(event.oldURL).hash} -> ${new URL(event.newURL).hash}`);
}, { once: true });
for (const type of ["mouseover", "focusin"]) {
container.addEventListener(type, (event) => {
console.log(`${event.type}: button=${event.target === button}, container=${event.currentTarget === container}`);
});
}
document.dispatchEvent(new Event("DOMContentLoaded", { bubbles: true }));
window.dispatchEvent(new HashChangeEvent("hashchange", {
oldURL: "https://example.com/#before",
newURL: "https://example.com/#after",
}));
button.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
button.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
// Node.js fallback: model only the detached tree and event data used here.
function createNodeDemo() {
class DemoElement extends EventTarget {
parentNode = null;
append(child) {
child.parentNode = this;
}
dispatchEvent(event) {
let current = this;
Object.defineProperties(event, {
target: { configurable: true, value: this },
currentTarget: { configurable: true, get: () => current },
});
try {
for (; current; current = current.parentNode) {
EventTarget.prototype.dispatchEvent.call(current, event);
if (!event.bubbles || event.cancelBubble) break;
}
} finally {
current = null;
}
return !event.defaultPrevented;
}
}
class DemoHashChangeEvent extends Event {
constructor(type, { oldURL, newURL }) {
super(type);
this.oldURL = oldURL;
this.newURL = newURL;
}
}
return {
document: Object.assign(new EventTarget(), {
createElement: () => new DemoElement(),
}),
window: new EventTarget(),
HashChangeEvent: DemoHashChangeEvent,
MouseEvent: Event,
FocusEvent: Event,
};
}
})();Resultado
DOMContentLoaded: document=true hashchange: #before -> #after mouseover: button=true, container=true focusin: button=true, container=true
Executa o código na consola do navegador em `about:blank` ou guarda-o como `main.js` e executa `node main.js`. O navegador usa o seu DOM nativo; em Node.js, o código usa um modelo simplificado da árvore e dos eventos, não um DOM. `dispatchEvent()` dispara eventos sintéticos de forma síncrona: não recarrega o documento, não altera o URL e não desloca o ponteiro nem o foco. As últimas duas linhas mostram a propagação do botão para um contentor que não está ligado ao documento.
Lições relacionadas
- JavaScript · Lição 38 · Avançado · Versão: 4
Fontes
- HTML Standard — The end
- Document: DOMContentLoaded event
- Window: hashchange event
- HTML Standard — The HashChangeEvent interface
- Element: mouseover event
- Element: mouseenter event
- MouseEvent: relatedTarget property
- Element: focusin event
- Element: focus event
- EventTarget: addEventListener() method
- EventTarget: dispatchEvent() method