Przejdź do treści

Tworzenie interaktywnych komponentów

WordPress bloki są domyślnie statyczne. Edytor zapisuje HTML w bazie danych, frontend je wyświetla i na tym koniec. W przypadku wielu bloków to dokładnie właściwe rozwiązanie. Niektóre komponenty muszą jednak reagować na interakcje użytkownika: przełączać widoczność treści, zmieniać karty, otwierać okna dialogowe i aktualizować liczniki.

WordPress Interactivity API dodaje do bloków reaktywne działanie po stronie klienta za pomocą atrybutów HTML nazywanych dyrektywami. Zamiast data-wp-on--click piszesz addEventListener, zamiast data-wp-bind--hidden — element.hidden = true. API automatycznie obsługuje reaktywność, izolację kontekstu i hydratację.

Blockstudio zajmuje się konfiguracją. Ustaw "interactivity": true w pliku block.json, a Blockstudio wygeneruje importmapę, załaduje API zarówno w edytorze, jak i na frontendzie oraz rozwiąże importy modułów ES. Bez kompilacji, bundlera ani konfiguracji webpacka. Szczegóły konfiguracji znajdziesz w dokumentacji Interactivity.

Ten przewodnik opisuje cztery kompletne komponenty, z których każdy wprowadza nowe zagadnienia. Po jego ukończeniu poznasz sprawdzone wzorce dla najpopularniejszych interaktywnych elementów UI.

Jak to działa

Dyrektywy

Dyrektywy to atrybuty data-wp-*, które bezpośrednio w pliku HTML deklarują reaktywne działanie. Najczęściej używane:

Dyrektywa Cel Przykład
data-wp-interactive Określa przestrzeń nazw magazynu data-wp-interactive="myBlock"
data-wp-context Lokalny stan reaktywny dla każdej instancji data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Obsługa zdarzenia data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Powiązanie atrybutu HTML data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Przełączanie klasy CSS data-wp-class--is-active="context.isActive"
data-wp-text Ustawianie treści tekstowej data-wp-text="state.count"
data-wp-style--[prop] Ustawianie stylu wbudowanego data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Globalne zdarzenie dokumentu data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Wywołanie funkcji zwrotnej po zmianie stanu data-wp-watch="callbacks.log"
data-wp-each Iterowanie po tablicy data-wp-each="state.items"

Magazyn stanu

Każdy interaktywny blok ma magazyn stanu, tworzony przez wywołanie store() z przestrzenią nazw i obiektem zawierającym actions, callbacks oraz opcjonalnie state:

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

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

W akcjach getContext() zwraca najbliższy obiekt data-wp-context w górę drzewa DOM. getElement() zwraca odwołanie do elementu DOM, który wywołał akcję; przydaje się ono do odczytu atrybutów data-*.

Kontekst a stan

Kontekst (data-wp-context) jest lokalny dla każdej instancji bloku. Jeśli umieścisz na stronie trzy akordeony, każdy będzie miał własną wartość isOpen. Przełączenie jednego nie wpływa na pozostałe.

Stan (wp_interactivity_state()) jest globalny i współdzielony przez wszystkie instancje bloku. Używaj go dla danych pochodzących z serwera, takich jak liczba komentarzy, lub wartości, które powinny być wszędzie takie same.

Kontekst działa zarówno w edytorze, jak i na frontendzie. Stan jest dostępny tylko na frontendzie, ponieważ WordPress serializuje go do znacznika skryptu, którego nie ma w odpowiedziach REST API edytora.

Akordeon

Najprostszy interaktywny wzorzec: kliknij przycisk i przełącz widoczność treści. Ten przykład wymaga tylko trzech dyrektyw i kilku wierszy 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;
    },
  },
});

Jak to działa:

  1. data-wp-context='{ "isOpen": false }' tworzy lokalną wartość logiczną dla tej instancji.
  2. Kliknięcie przycisku wywołuje actions.toggle, które przełącza wartość context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" ukrywa panel lub go wyświetla.
  4. data-wp-bind--aria-expanded i data-wp-text aktualizują stan przycisku na potrzeby dostępności oraz wskaźnik wizualny.

Ponieważ każda instancja bloku otrzymuje własny kontekst, kilka akordeonów na stronie działa od razu. Każdy przełącza się niezależnie.

Karty

Karty wprowadzają dwa nowe zagadnienia: data-wp-class--* do przełączania klas CSS oraz getElement() do odczytywania atrybutów danych elementu, który wywołał akcję.

Ten przykład korzysta z pola powtarzalnego, dzięki czemu redaktorzy mogą dodawać dowolną liczbę kart.

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);
}

Co nowego:

  • getElement() zwraca { ref }, gdzie ref jest elementem DOM. Odczytujemy data-index, aby ustalić, która karta została kliknięta. Dzięki temu nie trzeba tworzyć osobnej akcji dla każdej karty.
  • callbacks to wartości pochodne, które są ponownie obliczane po zmianie kontekstu. Zarówno przyciski kart, jak i panele używają callbacks.isActiveTab, aby sprawdzić, czy ich indeks jest zgodny z context.activeTab.
  • data-wp-class--is-active-tab dodaje klasę is-active-tab lub ją usuwa, zależnie od wartości zwróconej przez funkcję zwrotną.

Okno modalne wprowadza obsługę zdarzeń na poziomie dokumentu za pomocą data-wp-on-document--keydown, aby można je było zamknąć klawiszem Escape, oraz zamykanie po kliknięciu tła. Pokazuje też prawidłowe atrybuty dostępności okna dialogowego.

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;
      }
    },
  },
});

Co nowego:

  • data-wp-on-document--keydown nasłuchuje na document zamiast na samym elemencie. Procedura obsługi wywołuje się niezależnie od tego, który element ma fokus, więc Escape działa z dowolnego miejsca.
  • Zamykanie po kliknięciu tła wykorzystuje dwie warstwy: nakładka div wywołuje actions.backdropClick, a wewnętrzne okno dialogowe wywołuje actions.stopPropagation, aby kliknięcia wewnątrz okna go nie zamykały.
  • role="dialog" i aria-modal="true" informują czytniki ekranu, że jest to modalne okno dialogowe. Atrybut aria-label jest powiązany tak, aby obowiązywał tylko wtedy, gdy okno jest widoczne.
  • Atrybut hidden nakładki zarówno ukrywa okno modalne, jak i zapobiega wywołaniu nasłuchiwacza zdarzenia keydown dokumentu, gdy okno jest zamknięte, ponieważ dyrektywy na ukrytych elementach są wstrzymywane.

Przycisk polubienia ze stanem serwera

Ten przykład łączy stan po stronie serwera z akcjami po stronie klienta. Licznik polubień jest inicjowany z PHP za pomocą wp_interactivity_state(), a przycisk aktualizuje go po kliknięciu.

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;
}

Co nowego:

  • wp_interactivity_state() inicjuje licznik na podstawie PHP. Wartość jest serializowana w HTML strony i dostępna jako state.count w dyrektywach oraz w JavaScript.
  • state a context: licznik znajduje się w state (globalny, współdzielony), a liked — w context (dla każdej instancji). Gdyby przyciski polubienia dotyczyły tego samego elementu, współdzieliłyby licznik, ale każdy mógłby osobno zapamiętywać, czy został polubiony.
  • Destrukturyzacja z store(): wywołanie store() zwraca reaktywny obiekt state, do którego można się odwołać w akcjach.

Ważne zastrzeżenie: Stan serwera jest dostępny tylko na frontendzie. W edytorze blok jest renderowany przez REST API, więc wp_interactivity_state() nie jest dołączane. Tekst zastępczy renderowany przez PHP (<?php echo esc_html( $count ); ?>) wyświetla się jako wartość początkowa w podglądzie edytora. Aby stan był interaktywny w edytorze, użyj data-wp-context.

Wskazówki i wzorce

Konwencje nazewnictwa przestrzeni. Używaj nazwy motywu lub wtyczki jako prefiksu: myTheme/accordion, myPlugin/tabs. Zapobiega to kolizjom, gdy wiele bloków na tej samej stronie korzysta z Interactivity API.

Bez konieczności kompilacji. Blockstudio ładuje script.js jako natywny moduł ES i automatycznie generuje importmapę dla @wordpress/interactivity. Piszesz standardowy JavaScript z instrukcjami import i wszystko działa od razu.

Bloki korzystające wyłącznie z dyrektyw. Jeśli blok używa tylko data-wp-context z data-wp-bind--hidden lub data-wp-text, nie potrzebuje żadnego script.js. Interactivity API obsługuje je deklaratywnie. Przykład akordeonu powyżej mógłby działać bez JavaScript przy użyciu sztuczki z polem wyboru, ale rozwiązanie ze skryptem jest czytelniejsze.

Debugowanie za pomocą data-wp-watch. Dodaj funkcję zwrotną watch, aby podczas pracy nad projektem rejestrować zmiany kontekstu:

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<div data-wp-watch="callbacks.debug" ...>

Usuń ją przed wdrożeniem.

Ogranicz kontekst do minimum. W data-wp-context umieszczaj tylko wartości, które faktycznie się zmieniają. Dane statyczne, takie jak etykiety i treść, powinny pozostać w PHP. Kontekst JSON jest serializowany w każdej instancji bloku, więc duże obiekty zwiększają rozmiar strony.

Następne kroki

  • Dokumentacja Interactivity: opcje konfiguracji, szczegóły obsługi w edytorze i obiektowa forma ustawienia interactivity.
  • Zasoby: sposób, w jaki Blockstudio ładuje script.js, style.css i inne zasoby bloków.
  • WordPress Dokumentacja Interactivity API: pełna dokumentacja API, w tym data-wp-each, data-wp-init, data-wp-run i inne dyrektywy nieomówione w tym przewodniku.