İçeriğe geç

Etkileşimli Bileşenler Oluşturma

WordPress blokları varsayılan olarak statiktir. Düzenleyici, HTML’i veritabanına kaydeder, ön yüz bunu görüntüler ve konu kapanır. Birçok blok için bu tam da istenen davranıştır. Ancak bazı bileşenlerin kullanıcı etkileşimine yanıt vermesi gerekir: içeriği açıp kapatma, sekmeler arasında geçiş yapma, iletişim kutularını açma, sayaçları güncelleme.

WordPress Interactivity API, HTML yönergeler adı verilen nitelikleri kullanarak bloklara tepkisel, istemci taraflı davranış ekler. data-wp-on--click yerine addEventListener, data-wp-bind--hidden yerine element.hidden = true yazarsınız. API tepkiselliği, bağlam yalıtımını ve hidrasyonu otomatik olarak yönetir.

Bağlantıların kurulmasını Blockstudio sağlar. "interactivity": true‘i block.json dosyanızda ayarladığınızda Blockstudio importmap’i oluşturur, API’i hem düzenleyiciye hem de ön yüze yükler ve ES modülü içe aktarımlarınızı çözümler. Derleme adımı, paketleyici veya webpack yapılandırması gerekmez. Yapılandırma ayrıntıları için Interactivity başvuru kaynağına bakın.

Bu kılavuz, her biri yeni kavramları tanıtan dört eksiksiz bileşeni adım adım ele alır. Kılavuzun sonunda, en yaygın etkileşimli UI öğeleri için çalışan kalıplara sahip olacaksınız.

Nasıl Çalışır

Yönergeler

Yönergeler, data-wp-* içinde tepkisel davranışı doğrudan bildiren HTML nitelikleridir. En sık kullanılanlar:

Yönerge Amaç Örnek
data-wp-interactive Depo ad alanını tanımlama data-wp-interactive="myBlock"
data-wp-context Her örneğe özgü yerel tepkisel durum data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Olay işleyicisi data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Bir HTML niteliğini bağlama data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Bir CSS sınıfını açıp kapatma data-wp-class--is-active="context.isActive"
data-wp-text Metin içeriğini ayarlama data-wp-text="state.count"
data-wp-style--[prop] Satır içi stili ayarlama data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Genel belge olayı data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Durum değiştiğinde geri çağrım çalıştırma data-wp-watch="callbacks.log"
data-wp-each Bir dizi üzerinde döngü oluşturma data-wp-each="state.items"

Depo

Her etkileşimli bloğun, bir ad alanı ve actions, callbacks ile isteğe bağlı olarak state içeren bir nesneyle store() çağrılarak oluşturulan bir deposu vardır:

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

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

Eylemlerin içinde getContext(), DOM ağacında en yakın üstteki data-wp-context nesnesini döndürür. getElement(), eylemi tetikleyen DOM öğesine başvuru döndürür; bu, data-* niteliklerini okumak için kullanışlıdır.

Bağlam ve Durum Karşılaştırması

Bağlam (data-wp-context) her blok örneğine özgüdür. Bir sayfaya üç akordeon yerleştirirseniz her birinin kendi isOpen değeri olur. Birini açıp kapatmak diğerlerini etkilemez.

Durum (wp_interactivity_state()) geneldir ve bir bloğun tüm örnekleri arasında paylaşılır. Sunucudan gelen veriler (yorum sayısı gibi) veya her yerde aynı olması gereken değerler için kullanın.

Bağlam hem düzenleyicide hem de ön yüzde çalışır. Durum yalnızca ön yüze özgüdür; çünkü WordPress, bunu düzenleyici REST API yanıtlarına eklenmeyen bir betik etiketine serileştirir.

Akordeon

En basit etkileşimli kalıp: bir düğmeye tıklayıp içeriği açıp kapatma. Bu örnek için yalnızca üç yönerge ve birkaç satır JavaScript gerekir.

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

Çalışma şekli:

  1. data-wp-context='{ "isOpen": false }' bu örnek için yerel bir boole değeri oluşturur.
  2. Düğmeye tıklamak, context.isOpen değerini değiştiren actions.toggle işlevini çağırır.
  3. data-wp-bind--hidden="!context.isOpen" paneli gizler veya gösterir.
  4. data-wp-bind--aria-expanded ve data-wp-text, erişilebilirlik ve görsel gösterge için düğmenin durumunu günceller.

Her blok örneği kendi bağlamına sahip olduğundan, bir sayfaya birden çok akordeon yerleştirmek hemen çalışır. Her biri bağımsız olarak açılıp kapanır.

Sekmeler

Sekmeler iki yeni kavramı tanıtır: CSS sınıflarını açıp kapatmak için data-wp-class--* ve eylemi tetikleyen öğeden veri niteliklerini okumak için getElement().

Bu örnek, düzenleyicilerin ihtiyaç duydukları kadar sekme ekleyebilmesi için bir yineleyici alan kullanır.

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

Buradaki yenilikler:

  • getElement(), ref DOM öğesi olduğu { ref } değerini döndürür. Hangi sekmeye tıklandığını anlamak için data-index değerini okuruz. Bu sayede her sekme için ayrı bir eylem oluşturmaya gerek kalmaz.
  • callbacks, bağlam değiştiğinde yeniden değerlendirilen türetilmiş değerlerdir. Sekme düğmeleri ve paneller, dizinlerinin context.activeTab ile eşleşip eşleşmediğini denetlemek için callbacks.isActiveTab kullanır.
  • data-wp-class--is-active-tab, geri çağrımın dönüş değerine göre is-active-tab sınıfını ekler veya kaldırır.

Modal pencere örneği, Escape tuşuyla kapatmak için data-wp-on-document--keydown ile belge düzeyinde olay işlemeyi ve arka plana tıklayınca kapatmayı tanıtır. Ayrıca iletişim kutularının erişilebilirlik niteliklerinin doğru kullanımını gösterir.

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

Buradaki yenilikler:

  • data-wp-on-document--keydown, öğenin kendisi yerine document üzerinde dinleme yapar. İşleyici, odak hangi öğede olursa olsun çalışır; böylece Escape tuşu her yerden çalışır.
  • Arka plana tıklayınca kapatma, iki katman kullanır: kaplama div’i actions.backdropClick çağırırken iç iletişim kutusu, içindeki tıklamaların pencereyi kapatmasını önlemek için actions.stopPropagation çağırır.
  • role="dialog" ve aria-modal="true", ekran okuyuculara bunun modal bir iletişim kutusu olduğunu bildirir. aria-label yalnızca modal görünür olduğunda geçerli olacak şekilde bağlanır.
  • Kaplama üzerindeki hidden niteliği hem modal pencereyi gizler hem de kapalıyken belge keydown dinleyicisinin çalışmasını önler; çünkü gizli öğelerdeki yönergeler duraklatılır.

Sunucu Durumuna Bağlı Beğeni Düğmesi

Bu örnek, sunucu tarafı durumunu istemci tarafı eylemlerle birleştirir. Beğeni sayısı, wp_interactivity_state() kullanılarak PHP üzerinden başlatılır ve düğmeye tıklanınca güncellenir.

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

Buradaki yenilikler:

  • wp_interactivity_state(), sayıyı PHP üzerinden başlatır. Değer sayfanın HTML içine serileştirilir ve yönergelerde ve JavaScript içinde state.count olarak kullanılabilir.
  • state ve context karşılaştırması: Sayı state içindedir (genel, paylaşımlı); liked ise context içindedir (örneğe özgü). Aynı öğe için birden çok beğeni düğmesi olsaydı sayıyı paylaşırlar, ancak her biri kendi beğeni durumunu izleyebilirdi.
  • store() üzerinden parçalama: store() çağrısı, eylemlerinizde başvurabileceğiniz tepkisel bir state nesnesi döndürür.

Önemli uyarı: Sunucu durumu yalnızca ön yüze özgüdür. Düzenleyicide blok, API REST üzerinden görüntülenir; bu nedenle wp_interactivity_state() dahil edilmez. PHP tarafından görüntülenen yedek metin (<?php echo esc_html( $count ); ?>), düzenleyici önizlemesinde başlangıç değeri olarak gösterilir. Düzenleyicide etkileşimli durum için bunun yerine data-wp-context kullanın.

İpuçları ve Kalıplar

Ad alanı kuralları. Önek olarak temanızın veya eklentinizin adını kullanın: myTheme/accordion, myPlugin/tabs. Böylece aynı sayfadaki birden çok blok Interactivity API kullandığında çakışmalar önlenir.

Derleme adımı gerekmez. Blockstudio, script.js‘i yerel ES modülü olarak yükler ve @wordpress/interactivity için importmap’i otomatik oluşturur. import ifadeleriyle standart JavaScript yazmanız yeterlidir; hemen çalışır.

Yalnızca yönerge kullanan bloklar. Bloğunuz yalnızca data-wp-bind--hidden veya data-wp-text ile data-wp-context kullanıyorsa script.js hiç gerekmez. Interactivity API bunları bildirimsel olarak yönetir. Yukarıdaki akordeon örneği, onay kutusu hilesi kullansaydınız JavaScript olmadan çalışabilirdi; ancak betik yaklaşımı daha temizdir.

data-wp-watch ile hata ayıklama. Geliştirme sırasında bağlam değişikliklerini kaydetmek için bir izleme geri çağrımı ekleyin:

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

Yayımlamadan önce kaldırın.

Bağlamı yalın tutun. data-wp-context içine yalnızca gerçekten değişen değerleri koyun. Etiketler ve içerik gibi statik veriler PHP içinde kalmalıdır. Bağlam JSON, bloğun her örneğine serileştirildiğinden büyük nesneler sayfanın ağırlığını artırır.

Sonraki Adımlar

  • Interactivity başvuru kaynağı: yapılandırma seçenekleri, düzenleyici desteği ayrıntıları ve interactivity ayarının nesne biçimi.
  • Varlıklar: Blockstudio’in script.js, style.css ve diğer blok varlıklarını nasıl yüklediği.
  • WordPress Interactivity API belgeleri: data-wp-each, data-wp-init, data-wp-run ve bu kılavuzda ele alınmayan diğer yönergeler dahil olmak üzere eksiksiz API başvurusu.