Creare componenti interattivi
I blocchi WordPress sono statici per impostazione predefinita. L’editor salva HTML nel database, il frontend lo visualizza e la storia finisce qui. Per molti blocchi è proprio ciò che serve. Alcuni componenti, però, devono reagire alle interazioni dell’utente: alternare la visibilità dei contenuti, passare da una scheda all’altra, aprire finestre di dialogo e aggiornare contatori.
L’API WordPress Interactivity API aggiunge ai blocchi comportamenti reattivi lato client tramite attributi HTML chiamati direttive. Si scrive data-wp-on--click invece di addEventListener, data-wp-bind--hidden invece di element.hidden = true. L’API gestisce automaticamente la reattività, l’isolamento del contesto e l’hydration.
Blockstudio gestisce il collegamento. Impostate "interactivity": true nel vostro block.json e Blockstudio genera la importmap, carica API sia nell’editor sia nel frontend e risolve le importazioni dei vostri moduli ES. Niente compilazione, bundler o configurazione di webpack. Consultate il riferimento di Interactivity per i dettagli di configurazione.
Questa guida illustra quattro componenti completi, ognuno dei quali introduce nuovi concetti. Al termine, avrete a disposizione modelli funzionanti per gli elementi UI interattivi più comuni.
Come funziona
Direttive
Le direttive sono attributi data-wp-* che dichiarano comportamenti reattivi direttamente nel vostro HTML. Ecco quelle più usate:
| Direttiva | Scopo | Esempio |
|---|---|---|
data-wp-interactive |
Definire lo spazio dei nomi dello store | data-wp-interactive="myBlock" |
data-wp-context |
Stato reattivo locale per ogni istanza | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Gestore di eventi | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Associare un attributo HTML | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Attivare o disattivare una classe CSS | data-wp-class--is-active="context.isActive" |
data-wp-text |
Impostare il contenuto testuale | data-wp-text="state.count" |
data-wp-style--[prop] |
Impostare uno stile inline | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Evento globale del documento | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Eseguire una callback quando cambia lo stato | data-wp-watch="callbacks.log" |
data-wp-each |
Scorrere un array | data-wp-each="state.items" |
Lo store
Ogni blocco interattivo ha uno store, creato chiamando store() con uno spazio dei nomi e un oggetto contenente actions, callbacks e, facoltativamente, state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
All’interno delle azioni, getContext() restituisce l’oggetto data-wp-context più vicino risalendo l’albero DOM. getElement() restituisce un riferimento all’elemento DOM che ha attivato l’azione, utile per leggere gli attributi data-*.
Contesto e stato
Contesto (data-wp-context) è locale a ogni istanza del blocco. Se inserite tre accordion in una pagina, ognuno ha il proprio valore isOpen. Attivarne uno non influisce sugli altri.
Stato (wp_interactivity_state()) è globale e condiviso tra tutte le istanze di un blocco. Usatelo per i dati provenienti dal server, come il conteggio dei commenti, o per valori che devono essere uguali ovunque.
Il contesto funziona sia nell’editor sia nel frontend. Lo stato è disponibile solo nel frontend perché WordPress lo serializza in un tag script che non è incluso nelle risposte REST API dell’editor.
Accordion
Il modello interattivo più semplice: fare clic su un pulsante per mostrare o nascondere un contenuto. Questo esempio richiede solo tre direttive e poche righe di 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;
},
},
});
Come funziona:
data-wp-context='{ "isOpen": false }'crea un booleano locale per questa istanza.- Facendo clic sul pulsante si chiama
actions.toggle, che invertecontext.isOpen. data-wp-bind--hidden="!context.isOpen"nasconde o mostra il pannello.data-wp-bind--aria-expandededata-wp-textaggiornano lo stato del pulsante per l’accessibilità e l’indicatore visivo.
Ogni istanza del blocco ha un proprio contesto, quindi è possibile inserire più accordion nella pagina senza ulteriori configurazioni. Si attivano indipendentemente.
Schede
Le schede introducono due nuovi concetti: data-wp-class--* per attivare o disattivare classi CSS e getElement() per leggere gli attributi data dell’elemento che ha attivato un’azione.
Questo esempio usa un campo ripetitore, così gli editor possono aggiungere tutte le schede che servono.
{
"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);
}
Novità:
getElement()restituisce{ ref }, doverefè l’elemento DOM. Leggiamodata-indexper sapere quale scheda è stata selezionata. In questo modo non serve creare un’azione distinta per ogni scheda.callbackssono valori derivati che vengono ricalcolati quando cambia il contesto. Sia i pulsanti delle schede sia i pannelli usanocallbacks.isActiveTabper verificare se il proprio indice corrisponde acontext.activeTab.data-wp-class--is-active-tabaggiunge o rimuove la classeis-active-tabin base al valore restituito dalla callback.
Modale
La modale introduce la gestione degli eventi a livello di documento con data-wp-on-document--keydown per chiudersi premendo Escape e al clic sullo sfondo. Mostra anche gli attributi di accessibilità corretti per le finestre di dialogo.
{
"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;
}
},
},
});
Novità:
data-wp-on-document--keydownascolta gli eventi suldocumentinvece che sull’elemento stesso. Il gestore viene attivato indipendentemente dall’elemento che ha lo stato attivo, quindi Escape funziona da qualsiasi punto.- Chiusura al clic sullo sfondo usa due livelli: il div sovrapposto chiama
actions.backdropClick, mentre la finestra di dialogo interna chiamaactions.stopPropagationper impedire che i clic al suo interno la chiudano. role="dialog"earia-modal="true"comunicano agli screen reader che si tratta di una finestra di dialogo modale.aria-labelè associato in modo da applicarsi solo quando la modale è visibile.- L’attributo
hiddensull’elemento sovrapposto nasconde la modale e impedisce al listener keydown del documento di attivarsi quando la modale è chiusa, perché le direttive sugli elementi nascosti sono in pausa.
Pulsante Mi piace con stato lato server
Questo esempio combina lo stato lato server con le azioni lato client. Il conteggio dei Mi piace viene inizializzato da PHP usando wp_interactivity_state() e il pulsante lo aggiorna al 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;
}
Novità:
wp_interactivity_state()inizializza il conteggio da PHP. Il valore viene serializzato nel HTML della pagina ed è disponibile comestate.countnelle direttive e JavaScript.statevscontext: il conteggio si trova instate(globale, condiviso), mentrelikedsi trova incontext(per istanza). Se aveste più pulsanti Mi piace per lo stesso elemento, condividerebbero il conteggio, ma ognuno potrebbe tenere traccia del proprio stato Mi piace.- Destructuring da
store(): la chiamatastore()restituisce un oggetto reattivostatea cui potete fare riferimento nelle vostre azioni.
Avvertenza importante: lo stato del server è disponibile solo nel frontend. Nell’editor, il blocco viene visualizzato tramite REST API, quindi wp_interactivity_state() non è incluso. Il testo di ripiego visualizzato da PHP (<?php echo esc_html( $count ); ?>) compare come valore iniziale nell’anteprima dell’editor. Per uno stato interattivo nell’editor, usate invece data-wp-context.
Suggerimenti e modelli
Convenzioni per gli spazi dei nomi. Usate il nome del tema o del plugin come prefisso: myTheme/accordion, myPlugin/tabs. In questo modo si evitano conflitti quando più blocchi nella stessa pagina usano l’API Interactivity API.
Non serve compilare. Blockstudio carica script.js come modulo ES nativo e genera automaticamente la importmap per @wordpress/interactivity. Scrivete codice JavaScript standard con istruzioni import e funziona subito.
Blocchi con sole direttive. Se il vostro blocco usa solo data-wp-context con data-wp-bind--hidden o data-wp-text, non serve affatto un script.js. L’API Interactivity API gestisce questi casi in modo dichiarativo. L’esempio dell’accordion qui sopra potrebbe funzionare senza JavaScript usando un trucco con una casella di controllo, ma l’approccio con uno script è più pulito.
Debug con data-wp-watch. Aggiungete una callback watch per registrare le modifiche al contesto durante lo sviluppo:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Rimuovetela prima di distribuire.
Mantenete il contesto essenziale. Inserite in data-wp-context solo i valori che cambiano davvero. I dati statici, come etichette e contenuti, dovrebbero restare in PHP. Il contesto JSON viene serializzato in ogni istanza del blocco, quindi gli oggetti grandi appesantiscono la pagina.
Passaggi successivi
- riferimento di Interactivity: opzioni di configurazione, dettagli sul supporto nell’editor e forma oggetto dell’impostazione
interactivity. - Risorse: come Blockstudio carica
script.js,style.csse altre risorse dei blocchi. - Documentazione dell’APIWordPress Interactivity API: il riferimento completo API, inclusi
data-wp-each,data-wp-init,data-wp-rune altre direttive non trattate in questa guida.