Pāriet uz saturu

Interaktīvu komponentu veidošana

WordPress bloki pēc noklusējuma ir statiski. Redaktors saglabā HTML datubāzē, priekšgals to attēlo, un ar to viss beidzas. Daudziem blokiem tas ir tieši pareizi. Taču dažiem komponentiem jāreaģē uz lietotāja mijiedarbību: jāpārslēdz saturs, cilnes, jāatver dialogi un jāatjaunina skaitītāji.

WordPress Interactivity API pievieno blokiem reaktīvu darbību klienta pusē, izmantojot HTML atribūtus, ko sauc par direktīvām. Rakstiet data-wp-on--click, nevis addEventListener; data-wp-bind--hidden, nevis element.hidden = true. API automātiski nodrošina reaktivitāti, konteksta izolāciju un hidratāciju.

Blockstudio nodrošina nepieciešamo sasaisti. Iestatiet "interactivity": true savā block.json, un Blockstudio ģenerē importmap, ielādē API gan redaktorā, gan priekšgalā un atrisina jūsu ES moduļu importus. Nav nepieciešama būvēšanas darbība, komplektētājs vai webpack konfigurācija. Konfigurācijas informāciju skatiet Interactivity uzziņu materiālā.

Šajā rokasgrāmatā soli pa solim aplūkoti četri pilnīgi komponenti, katrs iepazīstina ar jauniem jēdzieniem. Beigās jums būs gatavi paraugi visbiežāk izmantotajiem interaktīvajiem UI elementiem.

Kā tas darbojas

Direktīvas

Direktīvas ir data-wp-* atribūti, kas tieši jūsu HTML deklarē reaktīvu darbību. Visbiežāk izmantotās:

Direktīva Nolūks Piemērs
data-wp-interactive Definē krātuves nosaukumtelpu data-wp-interactive="myBlock"
data-wp-context Lokāls reaktīvs stāvoklis katrai instancei data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Notikumu apstrādātājs data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Piesaista HTML atribūtu data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Pārslēdz CSS klasi data-wp-class--is-active="context.isActive"
data-wp-text Iestata teksta saturu data-wp-text="state.count"
data-wp-style--[prop] Iestata iekļauto stilu data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Globāls dokumenta notikums data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Palaiž atzvanes funkciju, kad mainās stāvoklis data-wp-watch="callbacks.log"
data-wp-each Iterē masīva elementus data-wp-each="state.items"

Krātuve

Katram interaktīvajam blokam ir krātuve, ko izveido, izsaucot store() ar nosaukumtelpu un objektu, kurā ir actions, callbacks un, pēc izvēles, state:

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

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

Darbībās getContext() atgriež tuvāko data-wp-context objektu DOM kokā. getElement() atgriež atsauci uz DOM elementu, kas izraisīja darbību; tā noder, lai nolasītu data-* atribūtus.

Konteksts un stāvoklis

Konteksts (data-wp-context) ir lokāls katrai bloka instancei. Ja lapā ievietojat trīs akordeonus, katram ir sava isOpen vērtība. Pārslēdzot vienu, pārējie nemainās.

Stāvoklis (wp_interactivity_state()) ir globāls un kopīgs visām bloka instancēm. Izmantojiet to datiem, kas nāk no servera (piemēram, komentāru skaitam), vai vērtībām, kam visur jābūt vienādām.

Konteksts darbojas gan redaktorā, gan priekšgalā. Stāvoklis darbojas tikai priekšgalā, jo WordPress serializē to skripta tagā, kas nav iekļauts redaktora REST API atbildēs.

Akordeons

Vienkāršākais interaktīvais paraugs: noklikšķiniet uz pogas, lai pārslēgtu saturu. Šajā piemērā vajadzīgas tikai trīs direktīvas un dažas JavaScript rindas.

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

Darbības princips:

  1. data-wp-context='{ "isOpen": false }' izveido lokālu Būla vērtību šai instancei.
  2. Noklikšķinot uz pogas, tiek izsaukts actions.toggle, kas apgriež context.isOpen vērtību.
  3. data-wp-bind--hidden="!context.isOpen" paslēpj vai parāda paneli.
  4. data-wp-bind--aria-expanded un data-wp-text atjaunina pogas stāvokli piekļūstamībai un vizuālajam indikatoram.

Tā kā katrai bloka instancei ir savs konteksts, vairākus akordeonus lapā var izvietot uzreiz. Tie darbojas neatkarīgi cits no cita.

Cilnes

Cilnes ievieš divus jaunus jēdzienus: data-wp-class--* klašu CSS pārslēgšanai un getElement() datu atribūtu nolasīšanai no elementa, kas izraisīja darbību.

Šajā piemērā izmantots atkārtotāja lauks, lai redaktori varētu pievienot vajadzīgo ciļņu skaitu.

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

Kas šeit ir jauns:

  • getElement() atgriež { ref }, kur ref ir DOM elements. Nolasām data-index, lai noteiktu, kura cilne tika noklikšķināta. Tādējādi katrai cilnei nav jāveido atsevišķa darbība.
  • callbacks ir atvasinātas vērtības, kas tiek aprēķinātas no jauna, mainoties kontekstam. Gan ciļņu pogas, gan paneļi izmanto callbacks.isActiveTab, lai pārbaudītu, vai to indekss atbilst context.activeTab.
  • data-wp-class--is-active-tab pievieno vai noņem klasi is-active-tab atkarībā no atzvanes funkcijas atgrieztās vērtības.

Modālais logs iepazīstina ar dokumenta līmeņa notikumu apstrādi: data-wp-on-document--keydown aizver logu, nospiežot Escape, un klikšķis uz fona to aizver. Piemērā parādīti arī pareizi dialoga piekļūstamības atribūti.

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

Kas šeit ir jauns:

  • data-wp-on-document--keydown klausās notikumus uz document, nevis pašā elementā. Apstrādātājs tiek izpildīts neatkarīgi no tā, kuram elementam ir fokuss, tāpēc Escape darbojas jebkurā vietā.
  • Aizvēršana, noklikšķinot uz fona, izmanto divus slāņus: pārklājuma div izsauc actions.backdropClick, bet iekšējais dialoga logs izsauc actions.stopPropagation, lai novērstu tā aizvēršanu, noklikšķinot dialoga iekšpusē.
  • role="dialog" un aria-modal="true" informē ekrāna lasītājus, ka tas ir modāls dialogs. aria-label ir piesaistīts tā, lai darbotos tikai tad, kad modālais logs ir redzams.
  • hidden atribūts pārklājumā gan paslēpj modālo logu, gan neļauj dokumenta taustiņa nospiešanas klausītājam darboties, kamēr logs ir aizvērts, jo direktīvas paslēptos elementos tiek apturētas.

Poga “Patīk” ar servera stāvokli

Šajā piemērā apvienots servera puses stāvoklis ar klienta puses darbībām. Patīk skaits tiek inicializēts no PHP, izmantojot wp_interactivity_state(), un, noklikšķinot uz pogas, tas tiek atjaunināts.

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

Kas šeit ir jauns:

  • wp_interactivity_state() inicializē skaitu no PHP. Vērtība tiek serializēta lapas HTML un ir pieejama kā state.count direktīvās un JavaScript.
  • state un context: skaits atrodas state (globālā, koplietojamā stāvoklī), bet liked atrodas context (katrai instancei atsevišķā kontekstā). Ja vienam elementam būtu vairākas pogas “Patīk”, tās koplietotu skaitu, bet katra varētu atsevišķi uzskaitīt, vai tai ir atzīmēts “Patīk”.
  • Destrukturēšana no store(): izsaukums store() atgriež reaktīvu state objektu, uz kuru varat atsaukties savās darbībās.

Svarīga piebilde: servera stāvoklis darbojas tikai priekšgalā. Redaktorā bloks tiek attēlots ar REST API, tāpēc wp_interactivity_state() nav iekļauts. Teksts PHP attēlotajā rezerves variantā (<?php echo esc_html( $count ); ?>) redaktora priekšskatījumā tiek rādīts kā sākotnējā vērtība. Redaktorā interaktīvam stāvoklim izmantojiet data-wp-context.

Padomi un paraugi

Nosaukumtelpu veidošanas ieteikumi. Izmantojiet savas tēmas vai spraudņa nosaukumu kā prefiksu: myTheme/accordion, myPlugin/tabs. Tas novērš sadursmes, ja vairākos vienas lapas blokos tiek izmantots Interactivity API.

Nav nepieciešama būvēšanas darbība. Blockstudio ielādē script.js kā iebūvētu ES moduli un automātiski ģenerē @wordpress/interactivity paredzēto importmap. Rakstiet standarta JavaScript ar import priekšrakstiem, un tas uzreiz darbosies.

Bloki, kuros izmanto tikai direktīvas. Ja jūsu blokā izmanto tikai data-wp-context kopā ar data-wp-bind--hidden vai data-wp-text, script.js nav vajadzīgs. Interactivity API to nodrošina deklaratīvi. Iepriekš redzamais akordeona piemērs darbotos arī bez JavaScript, izmantojot izvēles rūtiņas paņēmienu, taču pieeja ar skriptu ir vienkāršāka.

Atkļūdošana ar data-wp-watch. Izstrādes laikā pievienojiet novērošanas atzvanes funkciju, lai reģistrētu konteksta izmaiņas:

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

Pirms publicēšanas noņemiet to.

Saglabājiet kontekstu minimālu. Ievietojiet data-wp-context tikai tās vērtības, kas tiešām mainās. Statiskiem datiem, piemēram, etiķetēm un saturam, jāpaliek PHP. Konteksts JSON tiek serializēts katrā bloka instancē, tāpēc lieli objekti palielina lapas izmēru.

Nākamie soļi

  • Interactivity uzziņu materiāls: konfigurācijas opcijas, informācija par redaktora atbalstu un iestatījuma interactivity objekta forma.
  • Resursi: kā Blockstudio ielādē script.js, style.css un citus bloku resursus.
  • WordPress Interactivity API dokumentācija: pilna API uzziņu informācija, tostarp par data-wp-each, data-wp-init, data-wp-run un citām direktīvām, kas nav aplūkotas šajā rokasgrāmatā.