WordPress Interactivity API ile Dinamik Blok Nasıl?

WordPress Interactivity API, WordPress 6.5 ile çekirdeğe eklenen; bloklara ön yüzde reaktif, deklaratif ve paylaşılabilir bir etkileşim katmanı kazandıran standarttır. Daha önce jQuery veya ayrı bir React kurulumuyla yazdığınız sayaçlar, açılır paneller, sekmeler ve filtreler artık data-wp-* direktifleriyle, ek bir çalışma zamanı indirmeden çalışır.

Bu rehberde kurulumu, block.json yapılandırmasını, direktif listesini, store mantığını (state, actions, callbacks), sunucu tarafında ilk değer atamayı ve istemci tarafı navigasyonu örneklerle ele alıyoruz. Amaç, ilk etkileşimli bloğunuzu kısa sürede ve sunucu tarafında da doğru render edilecek biçimde ayağa kaldırmaktır.

Interactivity API nedir ve neden tercih edilmelidir?

API, blokların HTML çıktısına eklenen direktifleri tarayıcıda okur ve bunları bir store üzerindeki state, context ve actions değerlerine bağlar. State değiştiğinde yalnızca ilgili DOM düğümleri güncellenir. Preact tabanlı çalışma zamanı çekirdekle birlikte geldiği için ayrıca kurulum gerekmez.

Üç temel gerekçe bu API’yi varsayılan tercih hâline getirir. Birincisi birlikte çalışabilirlik: Arama, Sorgu Döngüsü, Gezinme ve Dosya blokları zaten aynı standardı kullanır. İkincisi sunucu tarafı render uyumu: ilk değerleri PHP’den atayabildiğiniz için sayfa kaynağı dolu gelir, SEO ve ilk yükleme performansı korunur. Üçüncüsü kararlı bağımlılık zinciri: harici bir kütüphaneye ve ağır bir derleme zincirine ihtiyaç duymazsınız.

Sözdizimi uyarısı: Türev direktiflerde iki tireli eski yazım yerine üç tireli yazımı (örneğin data-wp-watch---id) kullanın. Bu rehberdeki tüm örnekler güncel sözdizimini temel alır.

Hangi durumlarda kullanılır?

• Sayaç, beğeni, oylama gibi küçük durum değişiklikleri
• Açılır panel, sekme, modal ve açılır menü gibi arayüz bileşenleri
• Sayfa yenilemeden filtreleme ve sıralama
• Sepete ekleme, favoriye alma gibi kullanıcı etkileşimleri
• Bloklar arası paylaşılan durum gerektiren senaryolar

Kurulum: block.json, view modülü ve store

İlk adım blok tanımında etkileşim desteğini açmaktır:

{
  "apiVersion": 3,
  "name": "ornek/sayac",
  "supports": { "interactivity": true },
  "render": "file:./render.php",
  "viewScriptModule": "file:./view.js"
}

Ardından store dosyasını yazarsınız. Store; okunabilir değerleri state, kullanıcı eylemlerini actions, yan etkileri ise callbacks altında toplar:

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

store( 'ornek', {
  state: {
    get ikiKati() {
      return getContext().sayi * 2;
    },
  },
  actions: {
    artir() {
      getContext().sayi += 1;
    },
  },
  callbacks: {
    kaydet() {
      window.localStorage.setItem( 'sayi', getContext().sayi );
    },
  },
} );

Şablon tarafında ise direktifler devreye girer:

<div data-wp-interactive="ornek" data-wp-context='{"sayi":0}'>
  <p data-wp-text="context.sayi"></p>
  <p data-wp-text="state.ikiKati"></p>
  <button data-wp-on--click="actions.artir">Artır</button>
</div>

Derleme için wp-scripts modül desteğiyle çalışmanız yeterlidir; ek bir paketleyici yapılandırmasına gerek kalmaz.

Direktif rehberi: hangi direktif ne işe yarar?

Sunucu tarafı: ilk değer ataması ve SSR

Etkileşimin görünür içeriği geciktirmemesi için başlangıç değerlerini sunucuda atamak gerekir. Böylece kullanıcı JavaScript yüklenmeden önce de doğru içeriği görür:

wp_interactivity_state( 'ornek', array(
    'baslangic' => 0,
    'etiket'    => __( 'Artır', 'ornek' ),
) );

Blok render dosyasında ise bağlamı PHP tarafında üretip elemana yazabilirsiniz. Bu yaklaşım, dinamik listelerde her öğe için ayrı bağlam tanımlamayı kolaylaştırır ve sayfa kaynağının arama motorları tarafından eksiksiz okunmasını sağlar. Blok çıktısını özel alanlara bağlamak istiyorsanız Block Bindings API yazısındaki yöntemi bu yapıyla birlikte kullanabilirsiniz.

Router ile sayfa yenilemeden gezinme

Interactivity Router paketi, bağlantı tıklamalarını yakalayıp içeriği sayfa yenilemeden değiştirmenizi sağlar. Sorgu Döngüsü bloğundaki sayfalama ve filtreleme senaryolarında ilk tercih budur. Router kullanırken üç noktaya dikkat edin: gezinme sonrası odak yönetimi, tarayıcı geçmişinin doğru güncellenmesi ve erişilebilirlik için ekran okuyucu bildirimi. Ön yüz performansını bütünsel olarak ele almak isterseniz WordPress hız optimizasyonu yazısındaki önbellek başlıkları tamamlayıcıdır.

Sık yapılan hatalar

• Kök elemanda ad alanı tanımlamamak: data-wp-interactive olmadan diğer direktifler çalışmaz.
• State ile context’i karıştırmak: Paylaşılan değerler state, öğeye özel değerler context içinde tutulmalıdır.
• Store ad alanının tutarsız yazılması: PHP ve JavaScript tarafındaki ad alanı birebir aynı olmalıdır.
• Doğrudan DOM’a müdahale etmek: Değerleri elle değiştirmek yerine state güncellenmelidir.
• Sunucu tarafı ilk değeri atlamak: İçerik geç görünür ve arama motoru boş çıktı görebilir.
• Erişilebilirliği unutmak: Açılır panellerde aria-expanded gibi öznitelikler de bağlanmalıdır.

Yayın öncesi kontrol listesi

• Blok tanımında interactivity desteği ve view modülü tanımlı mı?
• Store ad alanı PHP ve JavaScript tarafında aynı mı?
• Başlangıç değerleri sunucu tarafında atandı mı?
• JavaScript devre dışıyken içerik okunabilir kalıyor mu?
• Klavye ile gezinme ve odak yönetimi test edildi mi?
• Konsolda direktif uyarısı veya hata kaldı mı?
• Router kullanılan sayfalarda geçmiş ve geri tuşu doğru çalışıyor mu?

Sıkça Sorulan Sorular

Interactivity API için React bilmem gerekir mi?
Hayır. Bileşen yazmak yerine HTML üzerinde direktif tanımlarsınız; JavaScript tarafında yalnızca store nesnesini yazmanız yeterlidir.

Klasik temalarda kullanılabilir mi?
Evet. API blok tabanlı temalarla sınırlı değildir; blok çıktısı üreten her yapıda çalışır.

state ile context arasındaki fark nedir?
State store genelinde paylaşılır, context ise bulunduğu DOM alt ağacına özeldir. Liste öğelerinde her öğenin kendi değeri context ile tutulur.

Derleme adımı zorunlu mu?
Modül olarak yazılan view dosyaları için derleme önerilir; ancak yapı, ağır bir paketleyici yapılandırması gerektirmez.

Eski jQuery kodlarımı taşımalı mıyım?
Çalışan kodları aceleyle taşımak gerekmez. Yeni geliştirmelerde bu API’yi tercih etmek, uzun vadede bakım maliyetini düşürür.

Sunucudan veri çekmek için ne kullanmalıyım?
Action içinden REST uç noktalarına istek gönderebilirsiniz. Kendi uç noktanızı yazmak için özel REST endpoint rehberine bakabilirsiniz.

Yeni sürümlerde başka hangi API’ler öne çıkıyor?
Çekirdeğe eklenen diğer başlıklar için WordPress 7.0 yenilikleri ve AI Client API yazılarını inceleyebilirsiniz.

Kaynaklar

• WordPress Block Editor Handbook — Interactivity API
• Interactivity API — Direktif referansı
• Block API — block.json metadata referansı
• Make WordPress Core — geliştirme duyuruları

Sonuç

WordPress Interactivity API, küçük etkileşimler için ağır kütüphanelere ihtiyaç duymadan standart ve sunucu tarafı render ile uyumlu bir yol sunar. Ad alanını tutarlı kurun, başlangıç değerlerini PHP tarafında atayın ve DOM’a doğrudan müdahale etmek yerine state üzerinden ilerleyin; bu üç kural bloklarınızın büyük kısmını sorunsuz çalıştırır.

İlgili rehberler:

• WordPress Block Bindings API ile Özel Alanları Bağlama
• WordPress REST API’de Özel Endpoint Nasıl Yazılır?
• WordPress 7.0 Yenilikleri
• WordPress AI Client API Nedir?
• WordPress Hız Optimizasyonu Nasıl Yapılır?