Lewati ke konten

Membangun Komponen Interaktif

WordPress blok bersifat statis secara default. Editor menyimpan HTML ke database, frontend merendernya, dan selesai. Untuk banyak blok, hal ini memang tepat. Namun, beberapa komponen perlu merespons interaksi pengguna: mengubah status tampil konten, berpindah tab, membuka dialog, dan memperbarui penghitung.

WordPress Interactivity API menambahkan perilaku reaktif di sisi klien ke blok menggunakan atribut HTML yang disebut direktif. Anda menulis data-wp-on--click alih-alih addEventListener, data-wp-bind--hidden alih-alih element.hidden = true. API menangani reaktivitas, isolasi konteks, dan hidrasi secara otomatis.

Blockstudio menangani pengaturannya. Atur "interactivity": true di block.json Anda, lalu Blockstudio membuat importmap, memuat API di editor dan frontend, serta menyelesaikan impor modul ES Anda. Tanpa langkah build, bundler, maupun konfigurasi webpack. Lihat referensi Interactivity untuk detail konfigurasi.

Panduan ini membahas empat komponen lengkap, masing-masing memperkenalkan konsep baru. Di akhir panduan, Anda akan memiliki pola yang berfungsi untuk elemen UI paling umum.

Cara Kerjanya

Direktif

Direktif adalah atribut data-wp-* yang mendeklarasikan perilaku reaktif langsung di HTML Anda. Berikut yang paling umum digunakan:

Direktif Tujuan Contoh
data-wp-interactive Menentukan namespace store data-wp-interactive="myBlock"
data-wp-context Status reaktif lokal per instance data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Penangan event data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Mengikat atribut HTML data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Mengubah status kelas CSS data-wp-class--is-active="context.isActive"
data-wp-text Mengatur konten teks data-wp-text="state.count"
data-wp-style--[prop] Mengatur gaya inline data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Event dokumen global data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Menjalankan callback saat status berubah data-wp-watch="callbacks.log"
data-wp-each Melakukan perulangan pada array data-wp-each="state.items"

Store

Setiap blok interaktif memiliki store yang dibuat dengan memanggil store() menggunakan namespace dan objek yang berisi actions, callbacks, dan, secara opsional, state:

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

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

Di dalam action, getContext() mengembalikan objek data-wp-context terdekat di atasnya dalam pohon DOM. getElement() mengembalikan referensi ke elemen DOM yang memicu action, berguna untuk membaca atribut data-*.

Konteks vs. Status

Konteks (data-wp-context) bersifat lokal untuk setiap instance blok. Jika Anda menempatkan tiga accordion di halaman, masing-masing memiliki nilai isOpen sendiri. Mengubah status salah satunya tidak memengaruhi yang lain.

Status (wp_interactivity_state()) bersifat global dan digunakan bersama oleh semua instance sebuah blok. Gunakan untuk data dari server (seperti jumlah komentar) atau nilai yang harus sama di mana-mana.

Konteks berfungsi di editor maupun frontend. Status hanya berfungsi di frontend karena WordPress menserialisasikannya ke dalam tag skrip yang tidak disertakan dalam respons REST API editor.

Accordion

Pola interaktif paling sederhana: klik tombol, ubah status tampil konten. Contoh ini hanya memerlukan tiga direktif dan beberapa baris 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;
    },
  },
});

Cara kerjanya:

  1. data-wp-context='{ "isOpen": false }' membuat nilai boolean lokal untuk instance ini.
  2. Mengeklik tombol memanggil actions.toggle, yang mengubah nilai context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" menyembunyikan atau menampilkan panel.
  4. data-wp-bind--aria-expanded dan data-wp-text memperbarui status tombol untuk aksesibilitas dan indikator visual.

Karena setiap instance blok memiliki konteks sendiri, beberapa accordion dapat langsung digunakan di satu halaman. Masing-masing berubah status secara mandiri.

Tab

Tab memperkenalkan dua konsep baru: data-wp-class--* untuk mengubah kelas CSS, dan getElement() untuk membaca atribut data dari elemen yang memicu action.

Contoh ini menggunakan field repeater agar editor dapat menambahkan tab sebanyak yang diperlukan.

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

Yang baru di sini:

  • getElement() mengembalikan { ref } dengan ref sebagai elemen DOM. Kita membaca data-index untuk mengetahui tab yang diklik. Cara ini menghindari pembuatan action terpisah untuk setiap tab.
  • callbacks adalah nilai turunan yang dievaluasi ulang saat konteks berubah. Tombol tab dan panel menggunakan callbacks.isActiveTab untuk memeriksa apakah indeksnya cocok dengan context.activeTab.
  • data-wp-class--is-active-tab menambahkan atau menghapus kelas is-active-tab berdasarkan nilai yang dikembalikan callback.

Modal memperkenalkan penanganan event tingkat dokumen dengan data-wp-on-document--keydown untuk menutup modal saat tombol Escape ditekan, serta penutupan dengan mengeklik backdrop. Contoh ini juga menunjukkan atribut aksesibilitas dialog yang tepat.

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

Yang baru di sini:

  • data-wp-on-document--keydown mendengarkan event pada document, bukan pada elemennya sendiri. Handler tetap berjalan terlepas dari elemen yang sedang difokuskan, sehingga Escape berfungsi dari mana saja.
  • Penutupan dengan mengeklik backdrop menggunakan dua lapisan: div overlay memanggil actions.backdropClick, sedangkan dialog di dalamnya memanggil actions.stopPropagation agar klik di dalam dialog tidak menutupnya.
  • role="dialog" dan aria-modal="true" memberi tahu pembaca layar bahwa ini adalah dialog modal. aria-label diikat agar hanya berlaku saat modal terlihat.
  • Atribut hidden pada overlay menyembunyikan modal sekaligus mencegah listener keydown dokumen berjalan saat modal tertutup, karena direktif pada elemen tersembunyi dijeda.

Tombol Suka dengan Status Server

Contoh ini menggabungkan status sisi server dengan action sisi klien. Jumlah suka diinisialisasi dari PHP menggunakan wp_interactivity_state(), lalu tombol memperbaruinya saat diklik.

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

Yang baru di sini:

  • wp_interactivity_state() menginisialisasi jumlah dari PHP. Nilainya diserialisasi ke HTML halaman dan tersedia sebagai state.count di direktif dan JavaScript.
  • state vs context: jumlah berada di state (global, digunakan bersama), sedangkan liked berada di context (per instance). Jika terdapat beberapa tombol suka untuk item yang sama, semuanya akan menggunakan jumlah yang sama, tetapi masing-masing dapat melacak status sukanya sendiri.
  • Destructuring dari store(): pemanggilan store() mengembalikan objek state yang dapat Anda rujuk di action.

Catatan penting: Status server hanya tersedia di frontend. Di editor, blok dirender melalui REST API, sehingga wp_interactivity_state() tidak disertakan. Teks fallback yang dirender oleh PHP (<?php echo esc_html( $count ); ?>) ditampilkan sebagai nilai awal di pratinjau editor. Untuk status interaktif di editor, gunakan data-wp-context.

Tips dan Pola

Konvensi namespace. Gunakan nama tema atau plugin Anda sebagai awalan: myTheme/accordion, myPlugin/tabs. Ini mencegah konflik saat beberapa blok di halaman yang sama menggunakan API Interactivity.

Tidak perlu langkah build. Blockstudio memuat script.js sebagai modul ES native dan membuat importmap untuk @wordpress/interactivity secara otomatis. Anda menulis JavaScript standar dengan pernyataan import, dan semuanya langsung berfungsi.

Blok yang hanya menggunakan direktif. Jika blok Anda hanya menggunakan data-wp-context dengan data-wp-bind--hidden atau data-wp-text, Anda sama sekali tidak memerlukan script.js. API Interactivity menanganinya secara deklaratif. Contoh accordion di atas dapat berfungsi tanpa JavaScript jika menggunakan trik checkbox, tetapi pendekatan skrip lebih rapi.

Men-debug dengan data-wp-watch. Tambahkan callback watch untuk mencatat perubahan konteks selama pengembangan:

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

Hapus sebelum dirilis.

Jaga konteks tetap sederhana. Masukkan hanya nilai yang benar-benar berubah ke data-wp-context. Data statis seperti label dan konten sebaiknya tetap di PHP. Konteks JSON diserialisasi ke setiap instance blok, sehingga objek besar menambah ukuran halaman.

Langkah Berikutnya

  • Referensi Interactivity: opsi konfigurasi, detail dukungan editor, dan bentuk objek dari pengaturan interactivity.
  • Aset: cara Blockstudio memuat script.js, style.css, dan aset blok lainnya.
  • Dokumentasi Interactivity WordPressAPI: referensi lengkap API, termasuk data-wp-each, data-wp-init, data-wp-run, dan direktif lain yang tidak dibahas dalam panduan ini.