Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

DOMContentLoaded et l’option d’écoute once

Utilisez `DOMContentLoaded` pour attendre la fin de l’analyse du HTML et `{ once: true }` pour limiter un écouteur à un appel par inscription. Consultez `document.readyState` si votre code peut démarrer tard.

Version : HTML Living Standard and DOM Standard; runtime support varies

Syntaxe

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();
}

Le navigateur déclenche DOMContentLoaded sur document après avoir analysé le HTML et exécuté les scripts prévus pour cette étape : les scripts avec defer et les modules sans async. Il n’attend pas le travail qui reprend après un await au niveau supérieur d’un module. Contrairement à load, cet événement n’attend ni les images, ni les sous-cadres, ni les scripts async. Les feuilles de style peuvent le retarder indirectement si elles bloquent des scripts qu’il attend.

Dans document.addEventListener("DOMContentLoaded", init, { once: true }), once supprime automatiquement cette inscription avant que l’événement appelle init pour la première fois. Sa valeur par défaut est false. Passer true seul comme troisième argument active capture, pas once. L’option ne rejoue pas un événement passé et ne limite ni les appels manuels ni les inscriptions ultérieures.

Si init n’a besoin que du DOM analysé, consultez document.readyState : s’il vaut "loading", inscrivez l’écouteur ; sinon, appelez init() immédiatement. Le navigateur ne peut pas déclencher l’événement entre cette vérification synchrone et l’inscription. "interactive" indique que l’analyse est terminée, pas que DOMContentLoaded a déjà eu lieu. Si l’initialisation dépend d’un autre script, synchronisez-la explicitement avec celui-ci.

L’événement, la propriété d’état et l’option d’écoute font partie des API du Web, pas d’ECMAScript. La prise en charge d’ECMAScript 2024 ne garantit pas leur disponibilité dans un environnement d’exécution donné.

Exemples

(() => {
  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}`);
})();

Résultat

After first dispatch: 1
After second dispatch: 1

Exécutez le code dans la console d’un navigateur. Deux événements synthétiques de même nom sont envoyés à un `EventTarget` distinct, et non à `document`. Ils illustrent `once`, pas le moment où la page est prête.

Leçons associées

  • JavaScript · Leçon 39 · Intermédiaire · Version : 3

Sources