Vai al contenuto

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:

JavaScript
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.

JSON
{
  "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." }
    ]
  }
}
PHP
<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>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myTheme/accordion', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

Come funziona:

  1. data-wp-context='{ "isOpen": false }' crea un booleano locale per questa istanza.
  2. Facendo clic sul pulsante si chiama actions.toggle, che inverte context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" nasconde o mostra il pannello.
  4. data-wp-bind--aria-expanded e data-wp-text aggiornano 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.

JSON
{
  "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." }
        ]
      }
    ]
  }
}
PHP
<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>
JavaScript
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);
    },
  },
});
CSS
.is-active-tab {
  border-bottom-color: currentColor !important;
  color: var(--wp--preset--color--primary, #111);
}

Novità:

  • getElement() restituisce { ref }, dove ref è l’elemento DOM. Leggiamo data-index per sapere quale scheda è stata selezionata. In questo modo non serve creare un’azione distinta per ogni scheda.
  • callbacks sono valori derivati che vengono ricalcolati quando cambia il contesto. Sia i pulsanti delle schede sia i pannelli usano callbacks.isActiveTab per verificare se il proprio indice corrisponde a context.activeTab.
  • data-wp-class--is-active-tab aggiunge o rimuove la classe is-active-tab in base al valore restituito dalla callback.

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.

JSON
{
  "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." }
    ]
  }
}
PHP
<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>
JavaScript
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--keydown ascolta gli eventi sul document invece 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 chiama actions.stopPropagation per impedire che i clic al suo interno la chiudano.
  • role="dialog" e aria-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 hidden sull’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.

JSON
{
  "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
<?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>
JavaScript
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++;
      }
    },
  },
});
CSS
.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 come state.count nelle direttive e JavaScript.
  • state vs context: il conteggio si trova in state (globale, condiviso), mentre liked si trova in context (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 chiamata store() restituisce un oggetto reattivo state a 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:

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<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