CKTIS / JavaScript
Événements DOMContentLoaded, pointerover, focusin, pagehide et pageshow
Choisissez l’événement adapté à la disponibilité du DOM, à la délégation des interactions de pointeur ou de focus, ou à la navigation et à la restauration via le bfcache.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
document.addEventListener("DOMContentLoaded", onReady, { once: true });
container.addEventListener("pointerover", onPointerOver);
container.addEventListener("focusin", onFocusIn);
window.addEventListener("pagehide", onPageHide);
window.addEventListener("pageshow", onPageShow);Enregistrez les gestionnaires avec addEventListener() en respectant la casse des noms. Ces événements relèvent de la plateforme web, pas d’ECMAScript 2024 ; leur prise en charge dépend de l’environnement d’exécution.
DOMContentLoaded est un Event non annulable envoyé à document une fois l’analyse du HTML terminée, les scripts classiques avec defer exécutés et l’évaluation des modules sans async prévus pour la fin de l’analyse entamée. À ce moment, l’évaluation d’un module peut encore être suspendue à un await au niveau supérieur. Il n’attend ni les images, ni les cadres intégrés, ni les scripts async. Si le code peut démarrer tard et a seulement besoin d’un DOM déjà construit, écoutez l’événement une seule fois si document.readyState === "loading" ; sinon, exécutez le code immédiatement. L’état "interactive" ne suffit pas à dire que l’événement a déjà été émis.
pointerover (PointerEvent) se produit lorsqu’un pointeur entre dans la zone de détection d’un élément, ce qui peut arriver au contact d’un écran tactile. Le passage d’un descendant à un autre peut produire d’autres événements. focusin (FocusEvent) se produit lorsqu’un élément reçoit le focus, par exemple au clavier ou via focus(), et n’est pas annulable. Les deux remontent vers les ancêtres, contrairement à pointerenter et focus. En délégation, event.target indique la cible et event.currentTarget le conteneur sur lequel le gestionnaire est enregistré.
Sur window, écoutez pagehide lorsque la navigation quitte le document, et pageshow après le premier load ainsi qu’à la restauration du document. Tous deux sont des PageTransitionEvent. Pour pagehide, persisted === true indique que le navigateur compte garder le document dans le cache de navigation arrière/avant (bfcache), sans garantir sa restauration. Pour pageshow, true indique une restauration depuis le bfcache sans nouveau DOMContentLoaded, et false un nouveau chargement du document. À la restauration, reprenez le travail sans réenregistrer les gestionnaires déjà présents.
Changer d’onglet n’est pas en soi une navigation, et pageshow ne prouve pas que la page est visible. Pour suivre la visibilité, utilisez visibilitychange et document.visibilityState. Enregistrez les données importantes au fil des modifications : pagehide peut manquer, par exemple si un navigateur mobile est arrêté.
Exemples
(() => {
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 }));
})();Résultat
DOMContentLoaded pointerover: button -> div focusin: button -> div pagehide: persisted=true pageshow: persisted=true
L’exemple émet des événements synthétiques. Il montre la remontée de `button` vers `div` et une valeur `persisted` fournie explicitement ; il ne déplace pas le focus, ne navigue pas et n’utilise pas le bfcache. Il utilise les API natives dans un navigateur et un arbre d’événements simplifié dans Node.js.
Leçons associées
- JavaScript · Leçon 39 · Avancé · Version : 4
Sources
- 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