API Interactivité WordPress

Quand l'utiliser

Utilisez cette compétence quand l'utilisateur mentionne :

API Interactivité, @wordpress/interactivity,
data-wp-interactive, data-wp-on--*, data-wp-bind--*, data-wp-context,
block viewScriptModule / scripts de vue basés sur des modules,
problèmes d'hydratation ou « les directives ne s'exécutent pas ».

Entrées requises

Racine du repo + résultat du triage (wp-project-triage).
Quelles surfaces de block/thème/plugin sont affectées (frontend, éditeur, les deux).
Toute contrainte : version de WP, si les modules sont supportés dans la build.

Procédure

1) Détecter l'utilisation existante + style d'intégration

Cherchez :

data-wp-interactive
@wordpress/interactivity
viewScriptModule

Décidez :

S'agit-il d'un block fournissant l'interactivité via un module de script de vue dans block.json ?
S'agit-il d'interactivité au niveau du thème ?
S'agit-il d'une utilisation côté plugin « améliorer le markup existant » ?

Si vous créez un nouveau block interactif (pas juste du débogage), préférez le modèle de scaffold officiel :

@wordpress/create-block-interactive-template (via @wordpress/create-block)

2) Identifier le(s) store(s)

Localisez les définitions de store et confirmez :

la forme de l'état,
les actions (mutations),
les callbacks/gestionnaires d'événements utilisés par data-wp-on--*.

3) Rendu côté serveur (bonne pratique)

Pré-rendez le HTML sur le serveur avant la sortie pour assurer :

L'état initial correct dans le HTML avant le chargement de JavaScript (pas de décalage de disposition).
Les avantages SEO et un temps de chargement perçu plus rapide.
Une hydratation transparente quand le JavaScript côté client prend le contrôle.

Activer le traitement des directives côté serveur

Pour les composants utilisant block.json, ajoutez supports.interactivity :

{
  "supports": {
    "interactivity": true
  }
}

Pour les thèmes/plugins sans block.json, utilisez wp_interactivity_process_directives() pour traiter les directives.

Initialiser l'état/contexte en PHP

Utilisez wp_interactivity_state() pour définir l'état global initial :

wp_interactivity_state( 'myPlugin', array(
  'items'    => array( 'Apple', 'Banana', 'Cherry' ),
  'hasItems' => true,
));

Pour le contexte local, utilisez wp_interactivity_data_wp_context() :

<?php
$context = array( 'isOpen' => false );
?>
<div <?php echo wp_interactivity_data_wp_context( $context ); ?>>
  ...
</div>

Définir l'état dérivé en PHP

Quand l'état dérivé affecte le rendu initial du HTML, reproduisez la logique en PHP :

wp_interactivity_state( 'myPlugin', array(
  'items'    => array( 'Apple', 'Banana' ),
  'hasItems' => function() {
    $state = wp_interactivity_state();
    return count( $state['items'] ) > 0;
  }
));

Cela garantit que les directives comme data-wp-bind--hidden="!state.hasItems" s'affichent correctement au premier chargement.

Pour des exemples et modèles détaillés, consultez references/server-side-rendering.md.

4) Implémenter ou modifier les directives en toute sécurité

Lors de la modification des directives de markup :

gardez l'utilisation des directives minimale et limitée,
préférez les attributs de données stables qui correspondent clairement à l'état du store,
assurez-vous que le markup rendu côté serveur + l'hydratation côté client s'alignent.

Changements de WordPress 6.9 :

data-wp-ignore est déprécié et sera supprimé dans les versions futures. Il a cassé l'héritage du contexte et provoqué des problèmes avec la navigation côté client. Évitez de l'utiliser.
IDs de directives uniques : Plusieurs directives du même type peuvent maintenant exister sur un élément en utilisant le séparateur --- (ex. data-wp-on--click---plugin-a="..." et data-wp-on--click---plugin-b="...").
Nouveaux types TypeScript : AsyncAction<ReturnType> et TypeYield<T> aident avec le typage des actions asynchrones.

Pour des rappels rapides sur les directives, consultez references/directives-quickref.md.

5) Alignement de la build/tooling

Vérifiez que le repo supporte le chemin de module requis :

s'il utilise @wordpress/scripts, préférez ses conventions.
s'il utilise un bundling personnalisé, confirmez que la sortie du module est supportée.

6) Déboguer les modes de défaillance courants

Si « rien ne se passe » lors de l'interaction :

confirmez que le viewScriptModule est enregistré/chargé,
confirmez que l'élément DOM a data-wp-interactive,
confirmez que l'espace de noms du store correspond à la valeur de la directive,
confirmez qu'il n'y a pas d'erreurs JS avant l'hydratation.

Voir references/debugging.md.

Vérification

wp-project-triage indique signals.usesInteractivityApi: true après votre changement (si applicable).
Test de smoke manuel : la directive se déclenche et l'état se met à jour comme prévu.
Si des tests existent : ajouter/étendre Playwright E2E autour du chemin d'interaction.

Modes de défaillance / débogage

Directives présentes mais inactives :
- script de vue non chargé, mauvais point d'entrée du module, ou data-wp-interactive manquant.
Incompatibilité d'hydratation / scintillement :
- le markup serveur diffère des attentes du client ; simplifiez ou alignez l'état initial.
- l'état dérivé n'est pas défini en PHP : utilisez wp_interactivity_state() avec des closures.
Contenu initial manquant ou incorrect :
- supports.interactivity non défini dans block.json (pour les blocks).
- wp_interactivity_process_directives() non appelé (pour les thèmes/plugins).
- état/contexte non initialisé en PHP avant le rendu.
Décalage de disposition au chargement :
- l'état dérivé comme state.hasItems manquant côté serveur, causant l'absence de l'attribut hidden.
Régressions de performance :
- racines interactives trop larges ; limitez l'interactivité à des sous-arbres plus petits.
Problèmes de navigation côté client (WordPress 6.9) :
- getServerState() et getServerContext() réinitialisent maintenant entre les transitions de page—assurez-vous que votre code ne suppose pas que les valeurs obsolètes persistent.
- Les régions de routeur supportent maintenant attachTo pour le rendu dynamique des superpositions (modales, pop-ups).

Escalade

Si les contraintes de build du repo ne sont pas claires, demandez : « Utilise-t-on @wordpress/scripts ou un bundler personnalisé (webpack/vite) ? »
Consultez :
- references/server-side-rendering.md
- references/directives-quickref.md
- references/debugging.md

wp-interactivity-api