Siirry sisältöön

Vuorovaikutteisten komponenttien rakentaminen

WordPress-lohkot ovat oletuksena staattisia. Muokkain tallentaa HTML tietokantaan, käyttöliittymä renderöi sen, ja siihen tarina päättyy. Monille lohkoille tämä on juuri oikein. Jotkin komponentit kuitenkin tarvitsevat käyttäjän vuorovaikutukseen reagoimista: sisällön avaamista ja sulkemista, välilehtien vaihtamista, valintaikkunoiden avaamista ja laskurien päivittämistä.

WordPress Interactivity API lisää lohkoihin reaktiivisen, asiakaspuolen toiminnan käyttämällä HTML-attribuutteja, joita kutsutaan direktiiveiksi. Kirjoitat data-wp-on--click etkä addEventListener, data-wp-bind--hidden etkä element.hidden = true. API huolehtii automaattisesti reaktiivisuudesta, kontekstin eristämisestä ja nesteytyksestä.

Blockstudio hoitaa kytkennät. Aseta "interactivity": true tiedostossasi block.json, niin Blockstudio luo importmapin, lataa API sekä muokkaimessa että käyttöliittymässä ja ratkaisee ES-moduulien tuonnit. Ei rakennusvaihetta, paketoijaa tai webpack-asetuksia. Katso Interactivity-viite saadaksesi lisätietoja määrityksistä.

Tämä opas käy läpi neljä täydellistä komponenttia, joista jokainen esittelee uusia käsitteitä. Lopuksi sinulla on toimivat mallit yleisimpiin vuorovaikutteisiin UI-elementteihin.

Näin se toimii

Direktiivit

Direktiivit ovat data-wp-*-attribuutteja, jotka määrittävät reaktiivisen toiminnan suoraan HTML-elementeissäsi. Yleisimmin käytetyt:

Direktiivi Tarkoitus Esimerkki
data-wp-interactive Määritä kaupan nimiavaruus data-wp-interactive="myBlock"
data-wp-context Paikallinen reaktiivinen tila kutakin esiintymää kohden data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Tapahtumankäsittelijä data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Sido HTML-attribuutti data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Ota CSS-luokka käyttöön tai poista se käytöstä data-wp-class--is-active="context.isActive"
data-wp-text Aseta tekstisisältö data-wp-text="state.count"
data-wp-style--[prop] Aseta sisäinen tyyli data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Dokumentin yleinen tapahtuma data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Suorita takaisinkutsu, kun tila muuttuu data-wp-watch="callbacks.log"
data-wp-each Käy taulukon arvot läpi data-wp-each="state.items"

Kauppa

Jokaisella vuorovaikutteisella lohkolla on kauppa, joka luodaan kutsumalla store() nimiavaruudella ja objektilla, joka sisältää actions, callbacks ja halutessasi state:

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

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

Toimintojen sisällä getContext() palauttaa lähimmän data-wp-context-objektin DOM-puussa ylöspäin. getElement() palauttaa viitteen toiminnon käynnistäneeseen DOM-elementtiin, mikä on hyödyllistä data-*-attribuuttien lukemiseen.

Konteksti ja tila

Konteksti (data-wp-context) on paikallinen kullekin lohkon esiintymälle. Jos sivulla on kolme haitarivalikkoa, jokaisella on oma isOpen-arvonsa. Yhden vaihtaminen ei vaikuta muihin.

Tila (wp_interactivity_state()) on yleinen ja jaettu lohkon kaikkien esiintymien kesken. Käytä sitä palvelimelta tuleville tiedoille (kuten kommenttimäärälle) tai arvoille, joiden pitäisi olla kaikkialla samoja.

Konteksti toimii sekä muokkaimessa että käyttöliittymässä. Tila on käytettävissä vain käyttöliittymässä, koska WordPress sarjoittaa sen skriptitunnisteeseen, jota ei sisällytetä muokkaimen REST API-vastauksiin.

Haitarivalikko

Yksinkertaisin vuorovaikutteinen malli: napsauta painiketta ja avaa tai sulje sisältöä. Tässä esimerkissä tarvitaan vain kolme direktiiviä ja muutama rivi JavaScript-koodia.

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

Näin se toimii:

  1. data-wp-context='{ "isOpen": false }' luo tälle esiintymälle paikallisen totuusarvon.
  2. Painikkeen napsauttaminen kutsuu actions.toggle-toimintoa, joka vaihtaa arvon context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" piilottaa tai näyttää paneelin.
  4. data-wp-bind--aria-expanded ja data-wp-text päivittävät painikkeen tilan saavutettavuutta ja visuaalista ilmaisinta varten.

Koska jokainen lohkon esiintymä saa oman kontekstinsa, useiden haitarivalikkojen lisääminen sivulle toimii suoraan. Ne avautuvat ja sulkeutuvat toisistaan riippumatta.

Välilehdet

Välilehdet esittelevät kaksi uutta käsitettä: data-wp-class--*-direktiivin CSS-luokkien vaihtamiseen ja getElement()-direktiivin tapahtuman käynnistäneen elementin data-attribuuttien lukemiseen.

Tässä esimerkissä käytetään toistinkenttää, jotta muokkaajat voivat lisätä tarvitsemansa määrän välilehtiä.

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

Uutta tässä:

  • getElement() palauttaa { ref }-arvon, jossa ref on DOM-elementti. Luemme data-index-arvon saadaksemme selville, mitä välilehteä napsautettiin. Näin jokaiselle välilehdelle ei tarvitse luoda erillistä toimintoa.
  • callbacks ovat johdettuja arvoja, jotka lasketaan uudelleen kontekstin muuttuessa. Sekä välilehtipainikkeet että paneelit tarkistavat callbacks.isActiveTab-arvon avulla, vastaako niiden indeksi arvoa context.activeTab.
  • data-wp-class--is-active-tab lisää is-active-tab-luokan tai poistaa sen takaisinkutsun palautusarvon perusteella.

Modaali esittelee dokumenttitason tapahtumien käsittelyn data-wp-on-document--keydown-direktiivillä, jolla se suljetaan Escape-näppäimellä, sekä napsauttamalla taustaa. Lisäksi esimerkissä näytetään dialogin asianmukaiset saavutettavuusattribuutit.

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

Uutta tässä:

  • data-wp-on-document--keydown kuuntelee document-elementtiä itse elementin sijaan. Käsittelijä suoritetaan riippumatta siitä, mikä elementti on kohdistettuna, joten Escape toimii kaikkialla.
  • Taustaa napsauttamalla sulkeminen käyttää kahta tasoa: peittävän div-elementin kutsu actions.backdropClick, kun taas sisäinen dialogi kutsuu actions.stopPropagation estääkseen dialogin sisällä olevia napsautuksia sulkemasta sitä.
  • role="dialog" ja aria-modal="true" ilmoittavat näytönlukijoille, että kyseessä on modaalinen dialogi. aria-label sidotaan niin, että se on käytössä vain modaalin ollessa näkyvissä.
  • Peittävän elementin hidden-attribuutti sekä piilottaa modaalin että estää dokumenttitason keydown-kuuntelijaa suorittumasta modaalin ollessa suljettuna, sillä piilotettujen elementtien direktiivit on keskeytetty.

Tykkäyspainike palvelintilalla

Tässä esimerkissä yhdistetään palvelinpuolen tila asiakaspuolen toimintoihin. Tykkäysmäärä alustetaan arvosta PHP käyttäen wp_interactivity_state()-toimintoa, ja painike päivittää sen napsautettaessa.

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

Uutta tässä:

  • wp_interactivity_state() alustaa määrän arvosta PHP. Arvo sarjoitetaan sivun HTML-tunnisteeseen, ja se on käytettävissä direktiiveissä ja state.count-elementeissä muodossa JavaScript.
  • state ja context: määrä on arvossa state (yleinen, jaettu), kun taas liked on arvossa context (esiintymäkohtainen). Jos samalla kohteella olisi useita tykkäyspainikkeita, ne jakaisivat määrän, mutta jokainen voisi seurata omaa tykkäystilaansa.
  • Purkaminen osiin kohteesta store(): kutsu store() palauttaa reaktiivisen state-objektin, johon voit viitata toiminnoissasi.

Tärkeä huomio: Palvelintila on käytettävissä vain käyttöliittymässä. Muokkaimessa lohko renderöidään REST API -mallin kautta, joten wp_interactivity_state() ei sisälly siihen. PHP-renderöity varateksti (<?php echo esc_html( $count ); ?>) näkyy muokkaimen esikatselussa alkuarvona. Käytä sen sijaan arvoa data-wp-context, jos haluat tilan toimivan vuorovaikutteisesti muokkaimessa.

Vinkkejä ja malleja

Nimiavaruuksien käytännöt. Käytä teeman tai lisäosan nimeä etuliitteenä: myTheme/accordion, myPlugin/tabs. Näin vältät törmäykset, kun useat saman sivun lohkot käyttävät Interactivity API-toimintoa.

Rakennusvaihetta ei tarvita. Blockstudio lataa script.js-moduulin natiivina ES-moduulina ja luo @wordpress/interactivity-importmapin automaattisesti. Kirjoitat tavallista JavaScript-koodia import-lausekkeilla, ja se toimii heti.

Vain direktiivejä käyttävät lohkot. Jos lohkossasi käytetään vain data-wp-context-direktiiviä yhdessä data-wp-bind--hidden– tai data-wp-text-direktiivin kanssa, et tarvitse lainkaan script.js-skriptiä. Interactivity API hoitaa nämä deklaratiivisesti. Yllä oleva haitarivalikkoesimerkki toimisi ilman JavaScript-skriptiä, jos käyttäisit valintaruutukikkaa, mutta skriptilähestymistapa on siistimpi.

Virheenkorjaus data-wp-watch-toiminnolla. Lisää watch-takaisinkutsu, jolla voit kirjata kontekstin muutokset kehityksen aikana:

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

Poista se ennen julkaisua.

Pidä konteksti suppeana. Lisää arvoon data-wp-context vain tosiasiassa muuttuvia arvoja. Staattisten tietojen, kuten otsikoiden ja sisällön, pitäisi pysyä arvossa PHP. Kontekstin JSON sarjoitetaan lohkon jokaiseen esiintymään, joten suuret objektit kasvattavat sivun kokoa.

Seuraavat vaiheet

  • Interactivity-viite: määritysasetukset, editorin tukitiedot ja interactivity-asetuksen objektimuoto.
  • Resurssit: miten Blockstudio lataa script.js-, style.css– ja muut lohkoresurssit.
  • WordPress Interactivity API -dokumentaatio: kattava API-viite, joka sisältää data-wp-each-, data-wp-init-, data-wp-run– ja muita tässä oppaassa käsittelemättömiä direktiivejä.