Ugrás a tartalomhoz

Interaktív komponensek építése

A WordPress blokkok alapértelmezés szerint statikusak. A szerkesztő elmenti a HTML értéket az adatbázisba, a frontend megjeleníti, és ezzel véget is ér a történet. Sok blokk esetében ez pontosan így helyes. Egyes komponenseknek azonban reagálniuk kell a felhasználói interakciókra: tartalmak ki- és bekapcsolására, lapok közötti váltásra, párbeszédablakok megnyitására, számlálók frissítésére.

A WordPress Interaktivitás API reaktív, kliensoldali viselkedést ad a blokkokhoz a direktíváknak nevezett HTML attribútumok segítségével. data-wp-on--click-t írsz addEventListener helyett, data-wp-bind--hidden-t pedig element.hidden = true helyett. A API automatikusan kezeli a reaktivitást, a kontextus elkülönítését és a hidratálást.

A Blockstudio gondoskodik az összekötésről. Állítsd be a "interactivity": true értékét a block.json fájlban, és a Blockstudio létrehozza az importtérképet, betölti a API modult a szerkesztőben és a frontendben is, valamint feloldja az ES-modulok importjait. Nincs szükség fordítási lépésre, csomagolóra vagy webpack-konfigurációra. A konfiguráció részleteiért lásd az Interaktivitási referenciát.

Ez az útmutató négy teljes komponensen vezet végig, és mindegyik új fogalmakat mutat be. A végére kész megoldásmintáid lesznek a leggyakoribb interaktív UI elemekhez.

Működés

Direktívák

A direktívák data-wp-* attribútumok, amelyek közvetlenül a HTML-ben határozzák meg a reaktív viselkedést. A leggyakrabban használtak:

Direktíva Cél Példa
data-wp-interactive A tároló névterének meghatározása data-wp-interactive="myBlock"
data-wp-context Példányonkénti helyi reaktív állapot data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Eseménykezelő data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Egy HTML attribútum kötése data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Egy CSS osztály be- és kikapcsolása data-wp-class--is-active="context.isActive"
data-wp-text Szöveges tartalom beállítása data-wp-text="state.count"
data-wp-style--[prop] Inline stílus beállítása data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Globális dokumentumesemény data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Visszahívás futtatása állapotváltozáskor data-wp-watch="callbacks.log"
data-wp-each Tömb elemeinek bejárása data-wp-each="state.items"

A tároló

Minden interaktív blokknak van tárolója. Ezt a store() hívásával hozhatod létre: meg kell adnod egy névteret, valamint egy objektumot, amely actions-t, callbacks-t és opcionálisan state-t tartalmaz:

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

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

A műveleteken belül a getContext() a DOM-fában legközelebb eső data-wp-context objektumot adja vissza. A getElement() hivatkozást ad vissza a műveletet kiváltó DOM-elemre; ez hasznos a data-* attribútumok kiolvasásához.

Kontextus és állapot

A kontextus (data-wp-context) minden blokkpéldányban helyi. Ha három harmonikát helyezel el egy oldalon, mindegyiknek saját isOpen értéke lesz. Az egyik átkapcsolása nincs hatással a többire.

Az állapot (wp_interactivity_state()) globális, és egy blokk minden példánya megosztja. Olyan adatokhoz használd, amelyek a szerverről érkeznek, például a hozzászólások számához, vagy olyan értékekhez, amelyeknek mindenhol azonosnak kell lenniük.

A kontextus a szerkesztőben és a frontendben egyaránt működik. Az állapot csak a frontendben érhető el, mert a WordPress egy olyan scriptcímkébe szerializálja, amely nem szerepel a szerkesztői REST API válaszaiban.

Harmonika

A legegyszerűbb interaktív megoldásminta: kattints egy gombra, és kapcsold át a tartalom láthatóságát. Ehhez a példához mindössze három direktíva és néhány sor JavaScript szükséges.

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

Működése:

  1. A data-wp-context='{ "isOpen": false }' helyi logikai értéket hoz létre ehhez a példányhoz.
  2. A gombra kattintva meghívódik a actions.toggle, amely megfordítja a context.isOpen értékét.
  3. A data-wp-bind--hidden="!context.isOpen" elrejti vagy megjeleníti a panelt.
  4. A data-wp-bind--aria-expanded és a data-wp-text frissíti a gomb állapotát a kisegítő lehetőségek és a vizuális jelzés érdekében.

Mivel minden blokkpéldány saját kontextust kap, több harmonika elhelyezése az oldalon azonnal működik. Egymástól függetlenül kapcsolhatók át.

Lapfülek

A lapfülek két új fogalmat vezetnek be: a data-wp-class--* direktívát a CSS osztályok kapcsolgatásához, valamint a getElement() direktívát az eseményt kiváltó elem adatattribútumainak kiolvasásához.

Ez a példa ismétlőmezőt használ, hogy a szerkesztők tetszőleges számú lapfület adhassanak hozzá.

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

Újdonságok:

  • getElement() a ref DOM-elemmel együtt visszaadja a { ref } értéket. A data-index kiolvasásával megtudhatjuk, melyik lapfülre kattintottak. Így nem kell minden lapfülhöz külön műveletet létrehozni.
  • A callbacks származtatott értékek, amelyek a kontextus változásakor újra kiértékelődnek. A lapfülgombok és a panelek is a callbacks.isActiveTab segítségével ellenőrzik, hogy az indexük megegyezik-e a context.activeTab értékével.
  • A data-wp-class--is-active-tab a visszahívás visszatérési értéke alapján hozzáadja vagy eltávolítja a is-active-tab osztályt.

A modális ablak bemutatja a dokumentumszintű eseménykezelést: a data-wp-on-document--keydown az Escape billentyű lenyomására bezárja az ablakot, és a háttérre kattintva is bezárható. A példa a párbeszédablakok akadálymentességi attribútumainak helyes használatát is bemutatja.

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

Újdonságok:

  • A data-wp-on-document--keydown a document-en figyeli az eseményt az elem helyett. A kezelő a fókuszban lévő elemtől függetlenül lefut, így az Escape bárhonnan működik.
  • A háttérre kattintva bezárás két réteget használ: a fedőréteg divje meghívja a actions.backdropClick-t, míg a belső párbeszédablak a actions.stopPropagation-t, így a belső kattintások nem zárják be az ablakot.
  • A role="dialog" és a aria-modal="true" jelzi a képernyőolvasóknak, hogy ez modális párbeszédablak. A aria-label kötése biztosítja, hogy csak akkor legyen érvényes, amikor a modális ablak látható.
  • A fedőrétegen lévő hidden attribútum elrejti a modális ablakot, és megakadályozza, hogy a dokumentum keydown-eseményfigyelője lefusson, amikor az ablak zárva van, mert a rejtett elemeken lévő direktívák szünetelnek.

Tetszésgomb szerveroldali állapottal

Ez a példa szerveroldali állapotot és kliensoldali műveleteket kombinál. A tetszések száma a PHP értékéből, a wp_interactivity_state() segítségével inicializálódik, a gomb pedig kattintáskor frissíti.

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

Újdonságok:

  • A wp_interactivity_state() a PHP értékéből inicializálja a számlálót. Az érték a lap HTML részébe szerializálódik, és state.count formájában érhető el a direktívákban és a JavaScript-ben.
  • state és context: a számláló a state-ban található (globális, megosztott), míg a liked a context-ben (példányonként). Ha ugyanahhoz az elemhez több tetszésgomb tartozna, megosztanák a számlálót, de mindegyik külön követhetné a saját tetszésállapotát.
  • Kibontás a store()-ből: a store() hívása egy reaktív state objektumot ad vissza, amelyre hivatkozhatsz a műveleteidben.

Fontos tudnivaló: A szerveroldali állapot csak a frontendben érhető el. A szerkesztőben a blokk a REST API segítségével jelenik meg, így a wp_interactivity_state() nincs benne. A PHP által megjelenített tartalék szöveg (<?php echo esc_html( $count ); ?>) jelenik meg kezdeti értékként a szerkesztő előnézetében. A szerkesztőben is interaktív állapothoz használd inkább a data-wp-context-t.

Tippek és minták

Névtér-konvenciók. Előtagként használd a témád vagy bővítményed nevét: myTheme/accordion, myPlugin/tabs. Ezzel elkerülhetők az ütközések, ha ugyanazon az oldalon több blokk használja az Interaktivitás API-t.

Nincs szükség fordítási lépésre. A Blockstudio natív ES-modulként tölti be a script.js-t, és automatikusan létrehozza a @wordpress/interactivity importtérképét. Szabványos JavaScript-t írsz import utasításokkal, és azonnal működik.

Csak direktívákat használó blokkok. Ha a blokkod csak data-wp-bind--hidden-et vagy data-wp-text-t használó data-wp-context-kat tartalmaz, egyáltalán nincs szükséged script.js-ra. Az Interaktivitás API deklaratív módon kezeli ezeket. A fenti harmonikapélda JavaScript nélkül is működhetne, ha jelölőnégyzetes trükköt használnál, de a szkriptalapú megoldás tisztább.

Hibakeresés data-wp-watch segítségével. Fejlesztés közben naplózd a kontextus változásait egy figyelő-visszahívás hozzáadásával:

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

Élesítés előtt távolítsd el.

Tartsd minimálisan a kontextust. Csak azokat az értékeket tedd a data-wp-context-be, amelyek valóban változnak. Az olyan statikus adatokat, mint a címkék és a tartalom, hagyd a PHP-ben. A kontextus JSON minden blokkpéldányba szerializálódik, ezért a nagy objektumok növelik az oldal méretét.

Következő lépések

  • Interaktivitási referencia: konfigurációs beállítások, a szerkesztő támogatásának részletei és a interactivity beállítás objektumalakja.
  • Eszközök: hogyan tölti be a Blockstudio a script.js, a style.css és más blokk-eszközöket.
  • WordPress Interaktivitás API dokumentáció: a teljes API referencia, beleértve a data-wp-each, a data-wp-init, a data-wp-run és az ebben az útmutatóban nem tárgyalt további direktívákat.