Créer des composants interactifs
WordPressLes blocs sont statiques par défaut. L’éditeur enregistre HTML dans la base de données, l’interface publique l’affiche, et l’histoire s’arrête là. Pour beaucoup de blocs, c’est exactement ce qu’il faut. Mais certains composants doivent réagir aux interactions de l’utilisateur : afficher ou masquer du contenu, changer d’onglet, ouvrir des boîtes de dialogue, mettre à jour des compteurs.
Le WordPress Interactivity API ajoute aux blocs un comportement réactif côté client à l’aide d’attributs HTML appelés directives. Vous écrivez data-wp-on--click plutôt que addEventListener, data-wp-bind--hidden plutôt que element.hidden = true. Le API gère automatiquement la réactivité, l’isolation du contexte et l’hydratation.
Blockstudio s’occupe de la configuration. Définissez "interactivity": true dans votre block.json et Blockstudio génère l’importmap, charge le API dans l’éditeur comme sur l’interface publique, puis résout vos imports de modules ES. Aucune étape de compilation, aucun bundler, aucune configuration webpack. Consultez la référence Interactivity pour les détails de configuration.
Ce guide présente quatre composants complets, chacun introduisant de nouveaux concepts. À la fin, vous disposerez de modèles fonctionnels pour les éléments interactifs UI les plus courants.
Fonctionnement
Directives
Les directives sont des attributs data-wp-* qui déclarent directement un comportement réactif dans votre HTML. Voici les plus utilisées :
| Directive | Rôle | Exemple |
|---|---|---|
data-wp-interactive |
Définir l’espace de noms du magasin | data-wp-interactive="myBlock" |
data-wp-context |
État réactif local à chaque instance | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Gestionnaire d’événement | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Associer un attribut HTML | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Activer ou désactiver une classe CSS | data-wp-class--is-active="context.isActive" |
data-wp-text |
Définir le contenu textuel | data-wp-text="state.count" |
data-wp-style--[prop] |
Définir un style en ligne | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Événement global du document | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Exécuter un rappel lorsque l’état change | data-wp-watch="callbacks.log" |
data-wp-each |
Parcourir un tableau | data-wp-each="state.items" |
Le magasin
Chaque bloc interactif possède un magasin, créé en appelant store() avec un espace de noms et un objet contenant actions, callbacks et, éventuellement, state :
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Dans les actions, getContext() renvoie l’objet data-wp-context le plus proche dans l’arborescence DOM. getElement() renvoie une référence à l’élément DOM qui a déclenché l’action, utile pour lire ses attributs data-*.
Contexte et état
Le contexte (data-wp-context) est propre à chaque instance de bloc. Si vous placez trois accordéons sur une page, chacun possède sa propre valeur isOpen. L’activation de l’un n’affecte pas les autres.
L’état (wp_interactivity_state()) est global et partagé entre toutes les instances d’un bloc. Utilisez-le pour les données provenant du serveur (comme le nombre de commentaires) ou les valeurs qui doivent être identiques partout.
Le contexte fonctionne dans l’éditeur comme sur l’interface publique. L’état est réservé à l’interface publique, car WordPress le sérialise dans une balise script qui n’est pas incluse dans les réponses REST API de l’éditeur.
Accordéon
Le modèle interactif le plus simple : cliquer sur un bouton pour afficher ou masquer du contenu. Cet exemple ne nécessite que trois directives et quelques lignes de JavaScript.
{
"name": "my-theme/accordion",
"title": "Accordion",
"category": "text",
"icon": "arrow-down-alt2",
"description": "Expandable content section.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "Accordion heading" },
{ "id": "body", "type": "textarea", "label": "Body", "default": "Accordion content goes here." }
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/accordion"
data-wp-context='{ "isOpen": false }'>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen"
aria-controls="accordion-panel"
style="all: unset; cursor: pointer; display: flex; justify-content: space-between; align-items: center; width: 100%; padding: 1rem; font-weight: 600; font-size: 1.125rem;">
<?php echo esc_html( $a['heading'] ); ?>
<span aria-hidden="true" data-wp-text="context.isOpen ? '−' : '+'">+</span>
</button>
<div
id="accordion-panel"
role="region"
data-wp-bind--hidden="!context.isOpen"
style="padding: 0 1rem 1rem;">
<p><?php echo esc_html( $a['body'] ); ?></p>
</div>
</div>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/accordion', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Fonctionnement :
data-wp-context='{ "isOpen": false }'crée un booléen local à cette instance.- Un clic sur le bouton appelle
actions.toggle, qui inverse la valeur decontext.isOpen. data-wp-bind--hidden="!context.isOpen"masque ou affiche le panneau.data-wp-bind--aria-expandedetdata-wp-textmettent à jour l’état du bouton pour l’accessibilité et l’indicateur visuel.
Comme chaque instance de bloc possède son propre contexte, plusieurs accordéons peuvent être placés sur une même page sans configuration supplémentaire. Ils s’ouvrent et se ferment indépendamment.
Onglets
Les onglets introduisent deux nouveaux concepts : data-wp-class--* pour activer ou désactiver des classes CSS, et getElement() pour lire les attributs de données de l’élément qui a déclenché une action.
Cet exemple utilise un champ répétiteur pour que les éditeurs puissent ajouter autant d’onglets que nécessaire.
{
"name": "my-theme/tabs",
"title": "Tabs",
"category": "text",
"icon": "table-row-after",
"description": "Tabbed content switcher.",
"blockstudio": {
"interactivity": true,
"attributes": [
{
"id": "tabs",
"type": "repeater",
"label": "Tabs",
"min": 1,
"max": 8,
"attributes": [
{ "id": "label", "type": "text", "label": "Tab Label", "default": "Tab" },
{ "id": "content", "type": "textarea", "label": "Content", "default": "Tab content goes here." }
]
}
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/tabs"
data-wp-context='{ "activeTab": 0 }'>
<div role="tablist" style="display: flex; gap: 0; border-bottom: 2px solid #e5e7eb;">
<?php foreach ( $a['tabs'] as $i => $tab ) : ?>
<button
role="tab"
data-index="<?php echo esc_attr( $i ); ?>"
data-wp-on--click="actions.selectTab"
data-wp-class--is-active-tab="callbacks.isActiveTab"
data-wp-bind--aria-selected="callbacks.isActiveTab"
style="padding: 0.75rem 1.5rem; background: none; border: none; cursor: pointer; font-weight: 500; border-bottom: 2px solid transparent; margin-bottom: -2px;">
<?php echo esc_html( $tab['label'] ); ?>
</button>
<?php endforeach; ?>
</div>
<?php foreach ( $a['tabs'] as $i => $tab ) : ?>
<div
role="tabpanel"
data-index="<?php echo esc_attr( $i ); ?>"
data-wp-bind--hidden="!callbacks.isActiveTab"
style="padding: 1.5rem 0;">
<p><?php echo esc_html( $tab['content'] ); ?></p>
</div>
<?php endforeach; ?>
</div>
import { store, getContext, getElement } from '@wordpress/interactivity';
store('myTheme/tabs', {
actions: {
selectTab: () => {
const context = getContext();
const { ref } = getElement();
context.activeTab = parseInt(ref.dataset.index, 10);
},
},
callbacks: {
isActiveTab: () => {
const context = getContext();
const { ref } = getElement();
return context.activeTab === parseInt(ref.dataset.index, 10);
},
},
});
.is-active-tab {
border-bottom-color: currentColor !important;
color: var(--wp--preset--color--primary, #111);
}
Nouveautés :
getElement()renvoie{ ref }, oùrefdésigne l’élément DOM. Nous lisonsdata-indexpour déterminer quel onglet a été cliqué. Cela évite de créer une action distincte pour chaque onglet.callbackssont des valeurs dérivées qui sont réévaluées lorsque le contexte change. Les boutons d’onglet et les panneaux utilisent tous deuxcallbacks.isActiveTabpour vérifier si leur index correspond àcontext.activeTab.data-wp-class--is-active-tabajoute ou retire la classeis-active-tabselon la valeur renvoyée par la fonction de rappel.
Fenêtre modale
La fenêtre modale présente la gestion des événements au niveau du document avec data-wp-on-document--keydown pour la fermer avec Échap, ainsi que sa fermeture au clic sur l’arrière-plan. Elle montre aussi les attributs d’accessibilité appropriés pour une boîte de dialogue.
{
"name": "my-theme/modal",
"title": "Modal",
"category": "text",
"icon": "external",
"description": "Button that opens a modal dialog.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "buttonText", "type": "text", "label": "Button Text", "default": "Open Modal" },
{ "id": "title", "type": "text", "label": "Modal Title", "default": "Modal Title" },
{ "id": "body", "type": "textarea", "label": "Modal Body", "default": "Modal content goes here." }
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/modal"
data-wp-context='{ "isOpen": false }'>
<button
data-wp-on--click="actions.open"
style="padding: 0.75rem 1.5rem; background: #111; color: #fff; border: none; border-radius: 6px; cursor: pointer; font-size: 1rem;">
<?php echo esc_html( $a['buttonText'] ); ?>
</button>
<div
data-wp-bind--hidden="!context.isOpen"
data-wp-on--click="actions.backdropClick"
data-wp-on-document--keydown="actions.onKeydown"
style="position: fixed; inset: 0; z-index: 9999; display: flex; align-items: center; justify-content: center; background: rgba(0,0,0,0.5);">
<div
role="dialog"
aria-modal="true"
data-wp-bind--aria-label="context.isOpen ? '<?php echo esc_attr( $a['title'] ); ?>' : false"
data-wp-on--click="actions.stopPropagation"
style="background: #fff; border-radius: 12px; padding: 2rem; max-width: 32rem; width: 100%; margin: 1rem; position: relative;">
<h2 style="margin: 0 0 1rem; font-size: 1.25rem;"><?php echo esc_html( $a['title'] ); ?></h2>
<p style="margin: 0 0 1.5rem; color: #555;"><?php echo esc_html( $a['body'] ); ?></p>
<button
data-wp-on--click="actions.close"
style="padding: 0.5rem 1rem; background: #f3f4f6; border: none; border-radius: 6px; cursor: pointer;">
Close
</button>
</div>
</div>
</div>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/modal', {
actions: {
open: () => {
const context = getContext();
context.isOpen = true;
},
close: () => {
const context = getContext();
context.isOpen = false;
},
backdropClick: () => {
const context = getContext();
context.isOpen = false;
},
stopPropagation: (event) => {
event.stopPropagation();
},
onKeydown: (event) => {
if (event.key === 'Escape') {
const context = getContext();
context.isOpen = false;
}
},
},
});
Nouveautés :
data-wp-on-document--keydownécoute l’événement surdocumentplutôt que sur l’élément lui-même. Le gestionnaire se déclenche quel que soit l’élément qui a le focus, donc Échap fonctionne partout.- Fermeture au clic sur l’arrière-plan : deux couches sont utilisées. Le div de superposition appelle
actions.backdropClick, tandis que la boîte de dialogue interne appelleactions.stopPropagationpour empêcher les clics dans la boîte de la fermer. role="dialog"etaria-modal="true"indiquent aux lecteurs d’écran qu’il s’agit d’une boîte de dialogue modale.aria-labelest associé pour ne s’appliquer que lorsque la fenêtre modale est visible.- L’attribut
hiddensur la superposition masque la fenêtre modale et empêche le gestionnaire d’événements keydown du document de se déclencher lorsqu’elle est fermée, car les directives des éléments masqués sont mises en pause.
Bouton J’aime avec état côté serveur
Cet exemple combine un état côté serveur avec des actions côté client. Le nombre de J’aime est initialisé à partir de PHP avec wp_interactivity_state(), puis le bouton le met à jour au clic.
{
"name": "my-theme/like-button",
"title": "Like Button",
"category": "text",
"icon": "heart",
"description": "A like button with a count.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "itemId", "type": "text", "label": "Item ID", "default": "post-1" }
]
}
}
<?php
$item_id = $a['itemId'];
$count = (int) get_option( "likes_{$item_id}", 0 );
wp_interactivity_state( 'myTheme/likeButton', array(
'count' => $count,
) );
?>
<div useBlockProps
data-wp-interactive="myTheme/likeButton"
data-wp-context='{ "liked": false }'>
<button
data-wp-on--click="actions.like"
data-wp-class--is-liked="context.liked"
style="display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.5rem 1rem; border: 2px solid #e5e7eb; border-radius: 999px; background: none; cursor: pointer; font-size: 1rem; transition: all 0.2s;">
<span data-wp-text="context.liked ? '❤️' : '🤍'">🤍</span>
<span data-wp-text="state.count"><?php echo esc_html( $count ); ?></span>
</button>
</div>
import { store, getContext } from '@wordpress/interactivity';
const { state } = store('myTheme/likeButton', {
actions: {
like: () => {
const context = getContext();
if (context.liked) {
context.liked = false;
state.count--;
} else {
context.liked = true;
state.count++;
}
},
},
});
.is-liked {
border-color: #ef4444 !important;
background: #fef2f2 !important;
}
Nouveautés :
wp_interactivity_state()initialise le compteur à partir de PHP. La valeur est sérialisée dans le HTML de la page et est disponible sous forme destate.countdans les directives et de JavaScript.stateetcontext: le compteur se trouve dansstate(global, partagé), tandis quelikedse trouve danscontext(propre à chaque instance). Si plusieurs boutons J’aime concernaient le même élément, ils partageraient le compteur, mais chacun pourrait suivre son propre état « J’aime ».- Déstructuration depuis
store(): l’appelstore()renvoie un objet réactifstateauquel vous pouvez faire référence dans vos actions.
Attention : l’état côté serveur est réservé à l’interface publique. Dans l’éditeur, le bloc est rendu via le REST API, donc wp_interactivity_state() n’est pas inclus. Le texte de remplacement affiché par PHP (<?php echo esc_html( $count ); ?>) apparaît comme valeur initiale dans l’aperçu de l’éditeur. Pour un état interactif dans l’éditeur, utilisez plutôt data-wp-context.
Conseils et modèles
Conventions d’espace de noms. Utilisez le nom de votre thème ou extension comme préfixe : myTheme/accordion, myPlugin/tabs. Cela évite les conflits lorsque plusieurs blocs d’une même page utilisent API Interactivity.
Aucune étape de compilation requise. Blockstudio charge script.js en tant que module ES natif et génère automatiquement l’importmap pour @wordpress/interactivity. Vous écrivez du JavaScript standard avec des instructions import, et tout fonctionne immédiatement.
Blocs utilisant uniquement des directives. Si votre bloc utilise uniquement data-wp-context avec data-wp-bind--hidden ou data-wp-text, vous n’avez pas du tout besoin de script.js. Le API Interactivity les gère de manière déclarative. L’exemple d’accordéon ci-dessus pourrait fonctionner sans JavaScript avec une astuce utilisant une case à cocher, mais l’approche par script est plus propre.
Déboguer avec data-wp-watch. Ajoutez une fonction de rappel watch pour consigner les changements de contexte pendant le développement :
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Supprimez-la avant la mise en production.
Gardez le contexte minimal. Placez dans data-wp-context uniquement les valeurs qui changent réellement. Les données statiques, comme les libellés et le contenu, doivent rester dans PHP. Le contexte JSON est sérialisé dans chaque instance du bloc ; les objets volumineux alourdissent donc la page.
Étapes suivantes
- Référence Interactivity : options de configuration, détails de la prise en charge dans l’éditeur et forme objet du réglage
interactivity. - Ressources : comment Blockstudio charge
script.js,style.csset les autres ressources de bloc. - Documentation Interactivity de WordPressAPI : référence complète de API, y compris
data-wp-each,data-wp-init,data-wp-runet les autres directives non abordées dans ce guide.