@wordpress/dom-ready

Définition : @wordpress/dom-ready est un paquet JavaScript WordPress qui exécute une fonction une fois que la structure du document HTML est disponible. Il aide à initialiser des comportements sans courir après des éléments absents.

Comprendre et utiliser

À quoi sert ce terme ?

Il rend l’initialisation de certains composants plus prévisible lorsque les scripts sont chargés à différents endroits de la page. Les traitements peuvent cibler des éléments déjà présents dans le DOM.

Fonctionnement technique

Le paquet expose un callback domReady(). Celui-ci s’exécute lorsque le DOM est prêt ou immédiatement si cet état est déjà atteint ; il ne garantit pas le chargement de toutes les images ou polices.

Dans quels contextes l’utiliser ?

À employer pour attacher des écouteurs à une interface serveur HTML, par exemple un formulaire ou des filtres. Pour une application React, le cycle de vie des composants constitue souvent le bon contexte.

Cas concret : ATOOLPHA

ATOOLPHA souhaite attacher une fonction à son champ de recherche après création de la page, sans employer un temporisateur arbitraire.

Exemple de code commenté

Extrait JavaScript destiné à un fichier de ressources enregistré avec ses dépendances dans WordPress ; pas à coller dans le contenu public.

// Dans un fichier JS géré par un build WordPress.
import domReady from '@wordpress/dom-ready';

domReady(() => {
  const field = document.querySelector('[data-atoolpha-search]');
  if (!field) return;
  field.addEventListener('input', () => {
    console.log('Recherche modifiée');
  });
});

Décryptage de l’exemple

Le callback attend la disponibilité de la structure HTML. Le sélecteur data-atoolpha-search est une convention de démonstration et doit réellement exister dans le template.

Résultat attendu

Le composant reçoit un écouteur input lorsque le champ correspondant est présent ; une page sans ce champ ne produit pas d’erreur.

Exercice pratique et vérification

Charger un script en tête et en pied de page dans deux essais. Observer que le composant reçoit bien un seul écouteur.

Précautions et limites

Éviter les écouteurs ajoutés plusieurs fois sur un même élément, notamment lors de navigations partielles ou d’actualisations de composants.

À ne pas confondre

domReady() attend la préparation du DOM ; window.load attend aussi certaines ressources, ce qui répond à un besoin différent.

Diagnostic avancé

Si le callback fonctionne mais que le champ n’est pas trouvé, vérifier le sélecteur et le moment où le composant est injecté dynamiquement.

Choix d’architecture et déploiement

L’initialisation liée au DOM doit suivre le cycle de vie réel de la page. Les applications utilisant des navigations partielles peuvent remonter plusieurs fois le même composant : prévoir un mécanisme de désabonnement ou de déduplication des écouteurs lorsque nécessaire.