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:
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.
{
"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." }
]
}
}
<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>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/accordion', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Çalışma şekli:
data-wp-context='{ "isOpen": false }'bu örnek için yerel bir boole değeri oluşturur.- Düğmeye tıklamak,
context.isOpendeğerini değiştirenactions.toggleişlevini çağırır. data-wp-bind--hidden="!context.isOpen"paneli gizler veya gösterir.data-wp-bind--aria-expandedvedata-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.
{
"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." }
]
}
]
}
}
<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>
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);
},
},
});
.is-active-tab {
border-bottom-color: currentColor !important;
color: var(--wp--preset--color--primary, #111);
}
Buradaki yenilikler:
getElement(),refDOM öğesi olduğu{ ref }değerini döndürür. Hangi sekmeye tıklandığını anlamak içindata-indexdeğ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, dizinlerinincontext.activeTabile eşleşip eşleşmediğini denetlemek içincallbacks.isActiveTabkullanır.data-wp-class--is-active-tab, geri çağrımın dönüş değerine göreis-active-tabsınıfını ekler veya kaldırır.
Modal Pencere
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.
{
"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." }
]
}
}
<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>
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 yerinedocumentü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çinactions.stopPropagationçağırır. role="dialog"vearia-modal="true", ekran okuyuculara bunun modal bir iletişim kutusu olduğunu bildirir.aria-labelyalnızca modal görünür olduğunda geçerli olacak şekilde bağlanır.- Kaplama üzerindeki
hiddenniteliğ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.
{
"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
$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>
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++;
}
},
},
});
.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çindestate.countolarak kullanılabilir.statevecontextkarşılaştırması: Sayıstateiçindedir (genel, paylaşımlı);likedisecontextiç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 birstatenesnesi 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:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<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
interactivityayarının nesne biçimi. - Varlıklar: Blockstudio’in
script.js,style.cssve diğer blok varlıklarını nasıl yüklediği. - WordPress Interactivity API belgeleri:
data-wp-each,data-wp-init,data-wp-runve bu kılavuzda ele alınmayan diğer yönergeler dahil olmak üzere eksiksiz API başvurusu.