wp_interactivity_state : exposer un état de bloc interactif depuis une extension

wp_interactivity_state( 'mon-extension/panier', array(
    'articles'    => 3,
    'total_ttc'   => 45.90,
) );

Cette seule ligne, placée dans le rendu serveur d’un bloc, suffit à rendre disponibles ces valeurs côté client, dans le store JavaScript associé au même espace de nommage. Depuis que l’Interactivity API est devenue stable avec WordPress 6.5, en avril 2024, cette fonction est le pont principal entre un calcul effectué en PHP et une interface réactive gérée en JavaScript, sans reconstruire l’état par un appel REST supplémentaire au chargement de la page.

Définition

La fonction wp_interactivity_state( string $store_namespace, array $state = array() ) déclare ou complète l’état associé à un espace de nommage donné. Appelée plusieurs fois avec le même espace de nommage, par exemple depuis différentes instances du même bloc sur une page, elle fusionne progressivement les valeurs plutôt que de les écraser, ce qui permet à plusieurs occurrences d’un bloc de contribuer chacune à un état global partagé.

Fonctionnement interne

Au moment du rendu de la page, WordPress sérialise l’ensemble des états déclarés par wp_interactivity_state() dans une balise script type="application/json" injectée automatiquement dans le HTML, avec un identifiant id="wp-interactivity-data". Le module JavaScript de l’Interactivity API lit ce contenu au chargement de la page et le rend disponible à travers la fonction store() côté client :

import { store, getContext } from '@wordpress/interactivity';

store( 'mon-extension/panier', {
    actions: {
        incrementer() {
            const contexte = getContext();
            contexte.articles += 1;
        },
    },
} );

L’état initial défini en PHP via wp_interactivity_state() devient donc directement lisible côté client sans requête réseau supplémentaire : c’est là tout l’intérêt du dispositif par rapport à une approche qui recalculerait cet état via un appel à l’API REST après le premier affichage.

Cas d’usage : un compteur de panier calculé côté serveur

Pour une extension de type boutique légère, le nombre d’articles et le total du panier peuvent être calculés côté serveur, à partir de la session ou d’une métadonnée utilisateur, puis transmis à l’affichage sans exposer de logique de calcul en JavaScript :

function rendre_bloc_panier( $attributs, $contenu, $bloc ) {
    $panier = mon_extension_recuperer_panier();

    wp_interactivity_state( 'mon-extension/panier', array(
        'articles'  => count( $panier ),
        'total_ttc' => mon_extension_calculer_total( $panier ),
    ) );

    return sprintf(
        '<div data-wp-interactive="mon-extension/panier">%d articles — %s €</div>',
        count( $panier ),
        number_format( mon_extension_calculer_total( $panier ), 2 )
    );
}

Le rendu HTML initial affiche déjà les bonnes valeurs, sans dépendre du JavaScript pour un premier affichage correct : c’est un avantage direct pour la performance perçue, puisque l’utilisateur voit un état cohérent avant même que le module JavaScript ne se charge.

Pièges à éviter

• Réutiliser un espace de nommage déjà employé par un autre thème ou une autre extension provoque une fusion d’états potentiellement incohérente : préfixer systématiquement l’espace de nommage avec un identifiant propre à l’extension, comme mon-extension/panier, évite ce risque de collision.
• Appeler wp_interactivity_state() après que le HTML du bloc a déjà été envoyé au navigateur n’a aucun effet : la fonction doit être appelée pendant le rendu du bloc, avant que la sortie ne soit produite.
• Stocker dans l’état des données sensibles, en supposant qu’elles resteront invisibles côté client, est une erreur : l’état sérialisé est visible dans le code source de la page, au même titre que n’importe quelle donnée affichée.
• Confondre wp_interactivity_state(), qui définit un état global à l’espace de nommage, avec wp_interactivity_data_wp_context(), qui attache un contexte local à un élément HTML précis : les deux mécanismes coexistent mais répondent à des besoins différents.

En résumé

La fonction wp_interactivity_state() permet à une extension de préparer, côté serveur, l’état initial consommé par son propre store JavaScript, sans dupliquer la logique de calcul entre PHP et JavaScript ni multiplier les appels réseau au premier affichage. Le respect strict de l’espace de nommage propre à l’extension reste la condition de base pour éviter toute interférence avec d’autres blocs interactifs présents sur la même page.