CKTIS / JavaScript
Eventos DOMContentLoaded, pointerover, focusin, pagehide e pageshow
Escolhe o evento certo para saber quando o DOM está pronto, delegar eventos de ponteiro e foco ou tratar a navegação e o restauro através da bfcache.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
document.addEventListener("DOMContentLoaded", onReady, { once: true });
container.addEventListener("pointerover", onPointerOver);
container.addEventListener("focusin", onFocusIn);
window.addEventListener("pagehide", onPageHide);
window.addEventListener("pageshow", onPageShow);Regista os ouvintes com addEventListener() e respeita as maiúsculas e minúsculas dos nomes. Estes eventos pertencem à plataforma Web, não ao ECMAScript 2024; o suporte depende do ambiente de execução.
DOMContentLoaded é um Event não cancelável, emitido em document depois de concluída a análise do HTML, executados os scripts clássicos com defer e iniciada a avaliação dos módulos sem async agendados para o fim da análise. Quando o evento ocorre, a avaliação de um módulo pode ainda estar suspensa num await de nível superior. Não espera por imagens, frames incorporadas nem scripts async. Se o código puder começar tarde e só precisar de um DOM já construído, escuta o evento uma única vez se document.readyState === "loading"; caso contrário, executa o código de imediato. "interactive" por si só não indica que o evento já ocorreu.
pointerover (PointerEvent) ocorre quando o ponteiro entra na área de detecção de um elemento; num ecrã táctil, isto pode acontecer ao tocar no ecrã. Passar entre descendentes pode gerar mais eventos. focusin (FocusEvent) ocorre quando um elemento recebe o foco, por exemplo pelo teclado ou via focus(), e não pode ser cancelado. Ambos sobem pela árvore até aos antepassados, ao contrário de pointerenter e focus. Na delegação, event.target identifica o alvo e event.currentTarget o contentor com o ouvinte.
Em window, escuta pagehide ao sair de um documento por navegação e pageshow depois do load inicial e ao restaurar um documento. Ambos são PageTransitionEvent. Em pagehide, persisted === true indica que o navegador tenciona manter o documento na cache de navegação para trás e para a frente (bfcache), sem garantir o restauro. Em pageshow, true indica o restauro a partir da bfcache sem outro DOMContentLoaded, e false indica um novo carregamento do documento. Ao restaurar, retoma o trabalho sem registar novamente os ouvintes já existentes.
Mudar apenas de separador não é navegação, e pageshow não prova que a página está visível. Para observar a visibilidade, usa visibilitychange e document.visibilityState. Guarda os dados importantes à medida que mudam: pagehide pode não ocorrer, por exemplo se o navegador num dispositivo móvel for terminado.
Exemplos
(() => {
const inBrowser = typeof document !== "undefined" && typeof window !== "undefined";
// Node's EventTarget has no DOM tree. Model just the bubbling used here.
class DemoNode extends EventTarget {
#parent = null;
constructor(localName) {
super();
this.localName = localName;
}
append(child) {
child.#parent = this;
}
dispatchEvent(event) {
// Keep the original target while EventTarget supplies currentTarget.
Object.defineProperty(event, "target", { value: this, configurable: true });
for (let node = this; node; node = node.#parent) {
super.dispatchEvent.call(node, event);
if (!event.bubbles || event.cancelBubble) break;
}
return !event.defaultPrevented;
}
}
class DemoPageTransitionEvent extends Event {
constructor(type, { persisted = false } = {}) {
super(type);
this.persisted = Boolean(persisted);
}
}
const doc = inBrowser ? document.implementation.createHTMLDocument() : new DemoNode("#document");
const page = inBrowser ? window : new EventTarget();
const Pointer = inBrowser ? window.PointerEvent : Event;
const Focus = inBrowser ? window.FocusEvent : Event;
const PageTransition = inBrowser ? window.PageTransitionEvent : DemoPageTransitionEvent;
const createElement = (name) => inBrowser ? doc.createElement(name) : new DemoNode(name);
const container = createElement("div");
const button = createElement("button");
container.append(button);
(inBrowser ? doc.body : doc).append(container);
doc.addEventListener("DOMContentLoaded", (event) => {
console.log(event.type);
});
for (const type of ["pointerover", "focusin"]) {
container.addEventListener(type, (event) => {
console.log(`${event.type}: ${event.target.localName} -> ${event.currentTarget.localName}`);
});
}
for (const type of ["pagehide", "pageshow"]) {
page.addEventListener(type, (event) => {
console.log(`${event.type}: persisted=${event.persisted}`);
}, { once: true });
}
doc.dispatchEvent(new Event("DOMContentLoaded", { bubbles: true }));
button.dispatchEvent(new Pointer("pointerover", { bubbles: true }));
button.dispatchEvent(new Focus("focusin", { bubbles: true }));
page.dispatchEvent(new PageTransition("pagehide", { persisted: true }));
page.dispatchEvent(new PageTransition("pageshow", { persisted: true }));
})();Resultado
DOMContentLoaded pointerover: button -> div focusin: button -> div pagehide: persisted=true pageshow: persisted=true
O exemplo emite eventos sintéticos. Mostra a propagação de `button` para `div` e um valor de `persisted` definido explicitamente; não muda o foco, não navega nem usa a bfcache. No navegador usa as APIs nativas e, em Node.js, uma árvore de eventos simplificada.
Lições relacionadas
- JavaScript · Lição 39 · Avançado · Versão: 4
Fontes
- HTML Standard — The end of parsing
- Document: DOMContentLoaded event
- Element: pointerover event
- Pointer events
- Element: focusin event
- Window: pagehide event
- Window: pageshow event
- HTML Standard — The PageTransitionEvent interface
- Document: visibilitychange event
- EventTarget: dispatchEvent() method
- DOMImplementation: createHTMLDocument() method