Liigu sisu juurde

Interaktiivsete komponentide loomine

WordPress plokid on vaikimisi staatilised. Redaktor salvestab HTML andmebaasi, kasutajaliides kuvab selle ja sellega asi piirdub. Paljude plokkide puhul on see täpselt õige. Mõned komponendid peavad aga kasutaja tegevusele reageerima: sisu sisse- ja väljalülitama, vahekaartide vahel liikuma, dialooge avama ja loendureid uuendama.

WordPress Interactivity API lisab plokkidele reaktiivse käitumise kliendis, kasutades HTML atribuute ehk direktiive. Kirjutate data-wp-on--click, mitte addEventListener, ja data-wp-bind--hidden, mitte element.hidden = true. API haldab reaktiivsust, konteksti eraldamist ja hüdratatsiooni automaatselt.

Blockstudio hoolitseb ühendamise eest. Määrake oma block.json-is "interactivity": true ning Blockstudio loob importmapi, laadib API nii redaktoris kui ka kasutajaliideses ja lahendab teie ES-moodulite impordid. Ehitussammu pole, pakendajat pole ega webpacki konfiguratsiooni. Konfiguratsiooni üksikasju vaadake Interactivity viitest.

See juhend käsitleb nelja terviklikku komponenti, millest igaüks tutvustab uusi mõisteid. Lõpuks on teil olemas töötavad mustrid kõige levinumate interaktiivsete UI elementide jaoks.

Kuidas see töötab

Direktiivid

Direktiivid on data-wp-* atribuudid, mis määravad reaktiivse käitumise otse teie HTML-is. Kõige sagedamini kasutatavad:

Direktiiv Eesmärk Näide
data-wp-interactive Määrab poe nimeruumi data-wp-interactive="myBlock"
data-wp-context Iga eksemplari kohalik reaktiivne olek data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Sündmuse töötleja data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Seob atribuudi HTML data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Lülitab klassi CSS sisse või välja data-wp-class--is-active="context.isActive"
data-wp-text Määrab tekstisisu data-wp-text="state.count"
data-wp-style--[prop] Määrab tekstisisese stiili data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Dokumendiülene sündmus data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Käivitab tagasihelistuse oleku muutumisel data-wp-watch="callbacks.log"
data-wp-each Läbib massiivi elemendid data-wp-each="state.items"

Pood

Igal interaktiivsel plokil on pood, mis luuakse store() väljakutsega, andes sellele nimeruumi ja objekti, mis sisaldab actions, callbacks ja soovi korral state:

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

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

Toimingute sees tagastab getContext() DOM-puus lähima ülemise data-wp-context-objekti. getElement() tagastab viite toimingu käivitanud DOM-elemendile; see on kasulik data-* atribuutide lugemiseks.

Kontekst ja olek

Kontekst (data-wp-context) on iga plokieksemplari jaoks kohalik. Kui lisate lehele kolm akordioni, on igal neist oma isOpen väärtus. Ühe lülitamine ei mõjuta teisi.

Olek (wp_interactivity_state()) on üldine ja jagatud ploki kõigi eksemplaride vahel. Kasutage seda serverist pärinevate andmete (nt kommentaaride arvu) või väärtuste jaoks, mis peaksid igal pool samad olema.

Kontekst toimib nii redaktoris kui ka kasutajaliideses. Olek on saadaval ainult kasutajaliideses, sest WordPress serialiseerib selle skriptisildiks, mida redaktori REST API vastused ei sisalda.

Akordion

Lihtsaim interaktiivne muster: klõpsake nuppu ja lülitage sisu sisse või välja. Selles näites on vaja vaid kolme direktiivi ja paari rida JavaScript-i.

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

Kuidas see töötab:

  1. data-wp-context='{ "isOpen": false }' loob selle eksemplari jaoks kohaliku tõeväärtuse.
  2. Nupul klõpsamine käivitab actions.toggle, mis muudab väärtuse context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" peidab või kuvab paneeli.
  4. data-wp-bind--aria-expanded ja data-wp-text uuendavad nupu olekut juurdepääsetavuse ja visuaalse tähise jaoks.

Kuna iga plokieksemplar saab oma konteksti, toimib mitme akordioni lisamine lehele kohe. Need lülituvad üksteisest sõltumatult.

Vahekaardid

Vahekaardid tutvustavad kahte uut mõistet: data-wp-class--* klasside CSS lülitamiseks ja getElement() andmeatribuutide lugemiseks toimingu käivitanud elemendilt.

Selles näites kasutatakse kordusvälja, et toimetajad saaksid lisada vajaliku arvu vahekaarte.

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

Mis on uut:

  • getElement() tagastab { ref }, kus ref on DOM-element. Loeme data-index, et teada saada, millisel vahekaardil klõpsati. Nii ei pea iga vahekaardi jaoks eraldi toimingut looma.
  • callbacks on tuletatud väärtused, mis arvutatakse konteksti muutumisel uuesti. Nii vahekaardinupud kui ka paneelid kasutavad callbacks.isActiveTab, et kontrollida, kas nende indeks vastab väärtusele context.activeTab.
  • data-wp-class--is-active-tab lisab või eemaldab klassi is-active-tab vastavalt tagasihelistuse tagastatud väärtusele.

Modaalaken tutvustab dokumenditaseme sündmuste käsitlemist: data-wp-on-document--keydown abil saab selle Escape-klahviga sulgeda ning taustal klõpsates sulgemise. Näide demonstreerib ka dialoogi korrektseid juurdepääsetavuse atribuute.

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

Mis on uut:

  • data-wp-on-document--keydown kuulab document-il, mitte elemendil endal. Töötleja käivitub fookuses olevast elemendist olenemata, nii et Escape toimib kõikjal.
  • Taustal klõpsates sulgemine kasutab kahte kihti: ülekate kutsub välja actions.backdropClick, sisemine dialoog aga kutsub välja actions.stopPropagation, et dialoogis tehtud klõpsud seda ei sulgeks.
  • role="dialog" ja aria-modal="true" annavad ekraanilugejatele teada, et tegemist on modaalaknaga. aria-label seotakse nii, et seda rakendatakse ainult siis, kui modaalaken on nähtaval.
  • Ülekatte atribuut hidden peidab modaalakna ja takistab dokumendi klahvivajutuse kuulaja käivitumist, kui modaalaken on suletud, sest peidetud elementide direktiivide töö peatatakse.

Meeldimisnupp serveri olekuga

See näide ühendab serveripoolse oleku kliendipoolsete toimingutega. Meeldimiste arv lähtestatakse väärtuse PHP alusel, kasutades wp_interactivity_state(), ning nupp uuendab seda klõpsamisel.

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

Mis on uut:

  • wp_interactivity_state() lähtestab loenduri väärtuse PHP alusel. Väärtus serialiseeritakse lehe HTML-i ja on direktiivides ning JavaScript-is saadaval kujul state.count.
  • state ja context: loendur asub state-is (üldine, jagatud), samas kui liked asub context-is (eksemplaripõhine). Kui samale üksusele oleks mitu meeldimisnuppu, jagaksid need loendurit, kuid igaüks saaks jälgida eraldi meeldimise olekut.
  • store() lahtipakkimine: väljakutse store() tagastab reaktiivse objekti state, millele saate toimingutes viidata.

Oluline piirang: serveri olek on saadaval ainult kasutajaliideses. Redaktoris renderdatakse plokk REST API abil, seega wp_interactivity_state() puudub. PHP-iga renderdatud asendustekst (<?php echo esc_html( $count ); ?>) kuvatakse redaktori eelvaates algväärtusena. Redaktoris interaktiivse oleku jaoks kasutage selle asemel data-wp-context.

Nõuanded ja mustrid

Nimeruumi kokkulepped. Kasutage eesliitena teema või plugina nime: myTheme/accordion, myPlugin/tabs. Nii väldite kokkupõrkeid, kui mitu sama lehe plokki kasutavad Interactivity API-i.

Ehitussammu pole vaja. Blockstudio laadib script.js natiivse ES-moodulina ja loob @wordpress/interactivity impordimapi automaatselt. Kirjutate standardset JavaScript-i import-lausetega ja see töötab kohe.

Ainult direktiive kasutavad plokid. Kui teie plokk kasutab ainult data-wp-context koos data-wp-bind--hidden või data-wp-text-ga, pole script.js-i üldse vaja. Interactivity API käsitleb neid deklaratiivselt. Ülaltoodud akordioninäide toimiks ka ilma JavaScript-ita, kui kasutaksite märkeruudu nippi, kuid skriptilahendus on puhtam.

Silumine data-wp-watch abil. Lisage arenduse ajaks vaatlusfunktsioon, mis logib konteksti muutusi:

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

Eemaldage see enne väljalaset.

Hoidke kontekst minimaalne. Lisage data-wp-context-i ainult väärtused, mis tegelikult muutuvad. Staatilised andmed, nagu sildid ja sisu, peaksid jääma PHP-i. Konteksti JSON serialiseeritakse ploki iga eksemplari jaoks, seega suurendavad suured objektid lehe mahtu.

Järgmised sammud