WordPress Etkileşim API’si ne işe yarar? Gutenberg bloklarına canlı sayaç, açılır içerik ve durum yönetimi eklemek için gerekli yapıyı öğrenin.
Bir Gutenberg bloğuna sayaç, açılır alan veya sepete ekleme özelliği eklediğinizde sayfanın tamamının yenilenmesi, kullanıcı deneyimini gereksiz yere kesintiye uğratabilir. Farklı JavaScript kütüphanelerini projeye dahil etmek ise dosya boyutunu, bağımlılıkları ve bakım yükünü artırabilir.
WordPress Etkileşim API’si, blokların ziyaretçi hareketlerine anlık tepki vermesini WordPress’in kendi yapısı içinde mümkün kılar. Böylece butona basıldığında içeriğin açılması, ürün miktarının güncellenmesi veya başka bir bloğun durumunun değişmesi için baştan ayrı bir ön yüz sistemi kurmak gerekmez.
İçerik üretimi ile ziyaretçi etkileşimini farklı kanallarda birlikte yürütmeyi planlayanlar, önce Substack Nedir, Ne İşe Yarar ve Nasıl Kullanılır konusunu inceleyerek yayın modelleri arasındaki farkları değerlendirebilir. Substack daha çok abonelik ve e-posta dağıtımına odaklanırken WordPress, özel bloklar üzerinden sayfa içindeki davranışları ayrıntılı biçimde kontrol etmeye imkân tanır.
WordPress Etkileşim API’si Ne İşe Yarar?
WordPress Etkileşim API’si, Gutenberg bloklarının tıklama, durum değişikliği ve veri güncelleme gibi kullanıcı hareketlerine sayfa yenilenmeden tepki vermesini sağlar. Global durum, yerel bağlam, eylemler ve HTML direktifleri birlikte kullanılarak sayaç, açılır içerik, canlı arama ve alışveriş sepeti gibi bileşenler oluşturulabilir.
API, WordPress 6.5 ile çekirdek sisteme eklendi. Resmî belgelerde Arama, Sorgu, Navigasyon ve Dosya gibi bazı çekirdek blokların da bu altyapıdan yararlandığı belirtiliyor. Bloklar arasında veri, eylem ve geri çağırma işlevlerinin paylaşılabilmesi, birbirine bağlı bileşenlerin daha düzenli kurulmasını sağlıyor.
Örneğin bir ürün bloğunda miktar artırıldığında ayrı bir sepet bloğundaki toplam tutar da güncellenebilir. Bu işlem için her bileşende birbirinden kopuk olay dinleyicileri oluşturmak yerine ortak bir store kullanılabilir.
Başlamadan Önce Neler Gerekiyor?
Geliştirme ortamında WordPress 6.5 veya daha yeni bir sürümün bulunması gerekir. Ayrıca Node.js, npm, bir kod editörü ve yerel WordPress kurulumu hazırlanmalıdır. WordPress’in resmî başlangıç belgesi, etkileşimli blok oluşturmak için güncel @wordpress/create-block paketini öneriyor.
Temel proje şu komutla oluşturulabilir:
npx @wordpress/create-block@latest etkilesimli-blok --template @wordpress/create-block-interactive-template2026 itibarıyla şablonda varsayılan yapı dışında TypeScript ve istemci tarafı gezinme seçenekleri de bulunuyor. Seçenekler paket sürümüne göre değişebileceği için komutu çalıştırmadan önce resmî paket sayfasını kontrol etmek yararlı olur.
Kurulum tamamlandığında proje dizinine geçerek geliştirme süreci başlatılır:
cd etkilesimli-blok
npm startArdından WordPress yönetim panelindeki Eklentiler bölümünden oluşturulan eklenti etkinleştirilir. Blok, içerik düzenleyicide eklenebilir; etkileşim davranışı ise yayımlanan sayfanın ön yüzünde test edilir.
Etkileşimli Bir Bloğun Temel Dosyaları
Standart Gutenberg yapısındaki block.json, edit.js ve stil dosyaları kullanılmaya devam eder. Bunlara sunucu tarafındaki HTML çıktısını hazırlayan render.php ile ziyaretçi etkileşimlerini yöneten view.js eklenir.
block.json Ayarları
block.json içinde aşağıdaki alanların doğru tanımlanması gerekir:
{
"supports": {
"interactivity": true
},
"render": "file:./render.php",
"viewScriptModule": "file:./view.js"
}interactivity desteği bloğun API direktiflerini kullanacağını bildirir. render alanı PHP çıktısını, viewScriptModule ise yalnızca ön yüzde çalışacak JavaScript modülünü gösterir. WordPress, @wordpress/interactivity paketini çekirdek sistem içinde sunduğu için kod Script Modules yapısıyla yüklenir.
Direktifler Nasıl Çalışır?
Etkileşim davranışı, HTML elemanlarına eklenen data-wp-* nitelikleriyle tanımlanır.
data-wp-interactive ilgili alanı etkinleştirir. data-wp-on--click tıklama olayında çalışacak eylemi belirler. data-wp-text bir metni reaktif veriye bağlarken data-wp-bind--hidden, içeriğin görünürlük durumunu yönetebilir.
<div data-wp-interactive="ornek-blok">
<button data-wp-on--click="actions.toggleOpen">
İçeriği göster
</button>
<p data-wp-bind--hidden="!context.isOpen">
Etkileşimli içerik
</p>
</div>Sunucudan gelen başlangıç değerlerinin wp_interactivity_state() ve wp_interactivity_data_wp_context() gibi WordPress işlevleriyle hazırlanması, elle JSON yazarken oluşabilecek kaçış ve biçimlendirme hatalarını azaltır.
Global State ile Local Context Arasındaki Fark Nedir?
Global state, aynı ad alanını kullanan blokların ortak erişebildiği verileri tutar. Sepet toplamı, tema tercihi veya ürün listesi bu alanda saklanabilir. Local context ise yalnızca belirli bir blok örneğine ve onun alt elemanlarına ait değerleri içerir.
Bir sayfada üç ayrı açılır alan varsa her alanın açık veya kapalı durumu local context içinde yönetilebilir. Sepetteki genel tutar ise bütün ürün bileşenlerini ilgilendirdiği için global state içinde tutulabilir.
view.js tarafında store() global yapıyı kaydeder, getContext() ise işlemi başlatan bloğun yerel verisine erişir:
import { store, getContext } from '@wordpress/interactivity';
const { state } = store('ornek-blok', {
actions: {
toggleOpen() {
const context = getContext();
context.isOpen = !context.isOpen;
}
}
});İncelediğim örnek projelerde en sık karşılaşılan sorunlardan biri, render.php ile view.js dosyalarında farklı namespace kullanılmasıydı. data-wp-interactive, wp_interactivity_state() ve store() içinde aynı ad alanı yazılmadığında blok ekranda görünse bile etkileşimler çalışmayabilir.
Etkileşimler Çalışmıyorsa Neler Kontrol Edilmeli?
Önce WordPress ve Node.js ortamının güncelliği doğrulanmalıdır. Daha sonra tarayıcı konsolunda modül yükleme hatası olup olmadığına bakılmalı ve viewScriptModule yolunun doğru yazıldığı kontrol edilmelidir.
npm start yalnızca geliştirme sırasında dosyaları izler. Canlı ortama aktarılacak paketin hazırlanması için npm run build komutu çalıştırılmalıdır. Ayrıca JavaScript tarafındaki store adıyla PHP tarafındaki namespace değeri birebir aynı olmalıdır.
Sorun koddan değil bilgisayar, tarayıcı veya WordPress kurulumundan kaynaklanıyorsa 11858 üzerinden profesyonel teknik destek alınabilir. 2011 yılından bu yana 7/24 hizmet sunan 11858, TeamViewer ve AnyDesk gibi lisanslı araçlarla uzaktan bağlantı sağlar. Dakika bazlı şeffaf ücretlendirmeyle çalışan uzman ekip, yüzde 95 memnuniyet oranına ve 500.000’den fazla başarılı işlem deneyimine sahiptir.
WordPress dışında daha hafif ve derleme odaklı bir yapı araştırıyorsanız Astro Nedir, Hızlı ve Esnek Statik Siteler Oluşturmanın Modern Yolu içeriği farklı bir yaklaşım sunabilir. Astro statik çıktı üretimine yönelirken WordPress Etkileşim API’si, yönetilebilir içeriklerle dinamik kullanıcı davranışlarını aynı blok altyapısında birleştirir.
WordPress Etkileşim API’si yalnızca hareketli bileşenler hazırlamak için değil, bloklar arasındaki veri akışını daha anlaşılır hâle getirmek için de değerlidir. Siz bu yapıyı sayaç, açılır içerik veya sepet gibi hangi özellikte kullanmayı düşünüyorsunuz? Deneyiminizi yorumlarda paylaşabilirsiniz.
