Bu rehber; Interactivity API’nin kurulumunu, block.json ve view.js üzerinden yapılandırmasını, data-wp-* direktifi listesini, store mantığını (state, actions, callbacks, derived state), server-side wp_interactivity_state() ile PHP’den ilk değer atamasını ve @wordpress/interactivity-router ile client-side navigasyonu gerçek kod örnekleriyle ele alır. Amaç; “JavaScript bilen ama Preact bilmeyen” bir WordPress geliştiricisinin ilk etkileşimli bloğunu 30 dakikada ayağa kaldırması ve bunu sunucu tarafında da doğru şekilde render edebilmesini sağlamaktır.

WordPress 6.5’in yeni etkileşim standardı ve neden önemlidir?

WordPress Interactivity API, blokların HTML çıktısına data-wp-* öznitelikleri (direktifler) ekleyerek DOM’u reaktif hâle getiren standart bir mekanizmadır. Motor, bu direktifleri tarayıcıda okur, bir “store” üzerindeki state, context ve actions değerlerine bağlar; state değiştiğinde ilgili DOM düğümleri otomatik güncellenir. Preact tabanlı, bağımlılıkları küçük ve @wordpress/interactivity paketi WordPress 6.5+ ile çekirdeğe gömülüdür; ayrıca kurulum gerekmez.

Önemli olmasının üç nedeni var. Birincisi birlikte çalışabilirlik: Search, Query, Navigation, File blokları zaten bu API’yi kullanır; siz de aynı dilde yazarsanız eklentiler arası state paylaşımı (actions.navigate gibi) ve SSR uyumu hazır gelir. İkincisi server-side render: wp_interactivity_state() ile PHP’den ilk değer atarsınız, sayfa kaynağında data-wp-context zaten doldurulmuş gelir; SEO ve ilk yükleme performansı korunur. Üçüncüsü kararlı bağımlılık zinciri: @wordpress/interactivity çekirdekle birlikte gelir, wp-scripts --experimental-modules ile script-module olarak paketlenir; harici bir runtime indirmenize gerek kalmaz.

Deprecation uyarısı: `data-wp-watch–id` ve `data-wp-init–id` iki tireli sözdizimi WordPress 7.1’de çalışmayı durduracak. Yerine üç tireli `data-wp-watch—id` ve `data-wp-init—id` kullanın. Bu rehberdeki tüm örnekler üç tireli sürümü kullanır.

WordPress Interactivity API hangi durumlarda kullanılır?

• Sayaç, açılır panel, sekme, akordeon gibi küçük UI etkileşimleri: jQuery + vanilla JS yazmak yerine deklaratif direktiflerle ifade edilir; geri çağırım yazılmaz, sadece state değiştirilir.
• “Sepete ekle” gibi WooCommerce etkileşimleri: Bir bloktaki tıklama başka bir bloktaki sayacı günceller; iki blok aynı namespace’i paylaştığı için tek store ile çalışır.
• Form state yönetimi: Çok adımlı formlarda hangi adımın aktif olduğu, hata mesajı, yükleniyor durumu store’da tutulur; data-wp-bind--hidden ile input görünürlüğü değiştirilir.
• Anlık arama / filtreleme: data-wp-on--input ile input değeri state.query‘ye bağlanır, data-wp-each ile sonuç listesi reaktif olarak güncellenir.
• Client-side navigasyon: @wordpress/interactivity-router paketi ile sayfa geçişleri fetch + replace ile yapılır; tam sayfa yenileme olmaz.

WordPress Interactivity API için temel kavramlar ve gereksinimler

WordPress Interactivity API nasıl kurulur ve uygulanır?

API, WordPress 6.5 ve üzerinde çekirdeğe dahildir. 6.4 ve altındaki kurulumlar için Gutenberg 17.5 ve üzeri eklentisinin kurulu ve aktif olması gerekir (pitfall: eklenti aktif değilse data-wp-* direktifleri çalışmaz, HTML kaynağı olduğu gibi kalır). Yeni bir blok yazıyorsanız @wordpress/create-block-interactive-template şablonu iskeleti hazır getirir; elle kurulum için npm install @wordpress/interactivity --save komutu yeterlidir.

wp-scripts tarafında script module desteği için package.json‘daki build script’lerine --experimental-modules flag’i eklenmelidir. Şablonla oluşturulan projelerde bu flag zaten ekli gelir; manuel projede unutulursa viewScriptModule çıktısı tarayıcı tarafından yüklenmez ve window.wp üzerinden @wordpress/interactivity erişilemez.

WordPress Interactivity API adım adım uygulama rehberi

Aşağıdaki akış, sıfırdan çalışan bir “aç-kapa panelli soru-cevap” bloğunun tamamını gösterir. Kod, wp-content/plugins/interactivity-faq/interactivity-faq.php (ana dosya), src/block.json, src/render.php ve src/view.js altında durur.

Adım 1 — Eklenti başlığı:

```php
<?php
/**
 * Plugin Name: Interactivity FAQ
 * Version: 1.0.0
 * Requires at least: 6.5
 * Requires PHP: 7.4
 */

Adım 2 — block.json (interaktif blok kaydı):

```json
{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "interactivity-faq/faq",
    "title": "FAQ",
    "category": "widgets",
    "icon": "list-view",
    "supports": {
        "interactivity": true
    },
    "textdomain": "interactivity-faq",
    "render": "file:./render.php",
    "viewScriptModule": "file:./view.js"
}

"supports": { "interactivity": true } satırı blok düzeyinde API desteğini açar; bu satır olmadan data-wp-* direktifleri çalışmaz.

Adım 3 — render.php (server-side render + ilk state):

```php
<?php
wp_interactivity_state( 'interactivityFaq', array(
    'items' => array(
        array( 'id' => 1, 'question' => 'Interactivity API nedir?', 'answer' => 'WordPress 6.5 ile gelen reaktif blok standardı.' ),
        array( 'id' => 2, 'question' => 'Hangi sürümlerde çalışır?', 'answer' => 'WordPress 6.5+ veya Gutenberg 17.5+.' ),
    ),
) );

$context = array( 'openId' => 0 );
?>

<div
    <?php echo wp_interactivity_data_wp_context( $context ); ?>
    data-wp-interactive="interactivityFaq"
    class="wp-block-interactivity-faq"
>
    <template
        data-wp-each="state.items"
        data-wp-each-key="context.item.id"
    >
        <details
            data-wp-bind--open="context.item.id === context.openId"
            data-wp-on--toggle="actions.toggle"
        >
            <summary data-wp-text="context.item.question"></summary>
            <p data-wp-text="context.item.answer"></p>
        </details>
    </template>
</div>

wp_interactivity_data_wp_context() fonksiyonu, data-wp-context özniteliğini güvenli bir şekilde (escape edilmiş JSON) basar; elle data-wp-context='' yazmak XSS riski taşır.

Adım 4 — view.js (store + action):

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

store( 'interactivityFaq', {
    actions: {
        toggle: () => {
            const context = getContext();
            // <details> öğesinin açık olup olmadığını oku.
            const isOpen = context.item.id === context.openId;
            context.openId = isOpen ? 0 : context.item.id;
        },
    },
} );

getContext() içinde context.item her zaman geçerli olur çünkü data-wp-each template’i her öğeyi item bağlamına sarar.

WordPress Interactivity API için gerekli ayarlar ve ön hazırlık

Üretim ortamında --experimental-modules flag’i ile derlenmiş view.js mutlaka viewScriptModule üzerinden yüklenmelidir. Eski wp-scripts sürümlerinde (17.5 öncesi) script module desteği yoktur; bu durumda blok yine de render edilir ama interaktif kısım çalışmaz, kaynak kodda data-wp-* öznitelikleri ölü kalır. Buna ek olarak, build çıktısı tarayıcıya ulaşmadan önce modül yükleyicisinin etkin olması gerekir; aksi hâlde viewScriptModule dosyası