コンテンツへスキップ

インタラクティブコンポーネントの構築

WordPressブロックは既定で静的です。エディターがHTMLをデータベースに保存し、フロントエンドで表示したら、それで終わりです。多くのブロックではこれで問題ありません。しかし、コンテンツの切り替え、タブの切り替え、ダイアログの表示、カウンターの更新など、ユーザーの操作に応答する必要があるコンポーネントもあります。

WordPress Interactivity APIは、ディレクティブと呼ばれるHTML属性を使って、ブロックにリアクティブなクライアント側の動作を追加します。addEventListenerの代わりにdata-wp-on--click、element.hidden = trueの代わりにdata-wp-bind--hiddenを記述します。APIがリアクティビティ、コンテキストの分離、ハイドレーションを自動的に処理します。

Blockstudioが連携処理を担当します。block.jsonで"interactivity": trueを設定すると、Blockstudioがimportmapを生成し、エディターとフロントエンドの両方でAPIを読み込み、ESモジュールのインポートを解決します。ビルド工程、バンドラー、webpackの設定は不要です。設定の詳細はInteractivityリファレンスを参照してください。

このガイドでは、4つの完全なコンポーネントを順に解説し、それぞれで新しい概念を紹介します。最後まで読むと、最も一般的なインタラクティブなUI要素を実装するためのパターンが身につきます。

動作の仕組み

ディレクティブ

ディレクティブは、data-wp-*属性であり、HTML内でリアクティブな動作を直接宣言します。よく使われるものは次のとおりです。

ディレクティブ 目的 例
data-wp-interactive ストアの名前空間を定義 data-wp-interactive="myBlock"
data-wp-context インスタンスごとのローカルなリアクティブ状態 data-wp-context='{ "isOpen": false }'
data-wp-on--[event] イベントハンドラー data-wp-on--click="actions.toggle"
data-wp-bind--[attr] HTML属性をバインド data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] CSSクラスを切り替え data-wp-class--is-active="context.isActive"
data-wp-text テキストコンテンツを設定 data-wp-text="state.count"
data-wp-style--[prop] インラインスタイルを設定 data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] ドキュメント全体のイベント data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch 状態の変化時にコールバックを実行 data-wp-watch="callbacks.log"
data-wp-each 配列をループ処理 data-wp-each="state.items"

ストア

すべてのインタラクティブブロックにはストアがあります。名前空間と、actions、callbacks、および任意のstateを含むオブジェクトを指定してstore()を呼び出すと作成されます。

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

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

アクション内でgetContext()を呼び出すと、DOMツリーを上にたどって最も近いdata-wp-contextオブジェクトを返します。getElement()は、アクションを発生させたDOM要素への参照を返し、data-*属性の読み取りに便利です。

コンテキストと状態

コンテキスト(data-wp-context)はブロックの各インスタンスに固有です。ページにアコーディオンを3つ配置した場合、それぞれが独自のisOpen値を持ちます。1つを切り替えても、ほかには影響しません。

状態(wp_interactivity_state())はグローバルで、ブロックのすべてのインスタンス間で共有されます。コメント数のようにサーバーから取得したデータや、どこでも同じ値にする必要がある場合に使います。

コンテキストはエディターとフロントエンドの両方で機能します。状態はフロントエンド専用です。WordPressは状態をスクリプトタグにシリアライズしますが、そのタグはエディターのRESTAPIレスポンスに含まれないためです。

アコーディオン

最もシンプルなインタラクティブパターンです。ボタンをクリックするとコンテンツが切り替わります。この例に必要なのは、3つのディレクティブと数行のJavaScriptだけです。

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

仕組み:

  1. data-wp-context='{ "isOpen": false }'で、このインスタンス用のローカルなブール値を作成します。
  2. ボタンをクリックするとactions.toggleが呼び出され、context.isOpenの値が反転します。
  3. data-wp-bind--hidden="!context.isOpen"でパネルの表示・非表示を切り替えます。
  4. data-wp-bind--aria-expandedとdata-wp-textで、アクセシビリティ向けのボタン状態と視覚的なインジケーターを更新します。

各ブロックインスタンスにはそれぞれ独自のコンテキストがあるため、1つのページにアコーディオンを複数配置しても、そのまま動作します。それぞれ独立して切り替わります。

タブ

タブでは、新たに2つの概念を使います。data-wp-class--*でCSSクラスを切り替え、getElement()でアクションを発生させた要素のデータ属性を読み取ります。

この例ではリピーターフィールドを使っているため、編集者は必要な数だけタブを追加できます。

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

ここでの新しいポイント:

  • getElement() は、refがDOM要素である{ ref }を返します。クリックされたタブを判別するためにdata-indexを読み取ります。タブごとに個別のアクションを作成する必要はありません。
  • callbacks は、コンテキストが変わると再評価される派生値です。タブボタンとパネルの両方でcallbacks.isActiveTabを使い、それぞれのインデックスがcontext.activeTabと一致するか確認します。
  • data-wp-class--is-active-tab は、コールバックの戻り値に基づいてis-active-tabクラスを追加または削除します。

モーダルでは、data-wp-on-document--keydownによるドキュメントレベルのイベント処理を使ってEscapeキーで閉じる方法と、背景をクリックして閉じる方法を紹介します。ダイアログに適切なアクセシビリティ属性を設定する例も示します。

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

ここでの新しいポイント:

  • data-wp-on-document--keydown は要素自体ではなくdocumentでイベントを監視します。フォーカスがどの要素にあってもハンドラーが実行されるため、どこからでもEscapeキーで閉じられます。
  • 背景クリックで閉じる処理には2つのレイヤーを使います。オーバーレイのdivはactions.backdropClickを呼び出し、内側のダイアログはactions.stopPropagationを呼び出して、ダイアログ内のクリックで閉じないようにします。
  • role="dialog"とaria-modal="true" は、これがモーダルダイアログであることをスクリーンリーダーに伝えます。aria-labelはバインドされており、モーダルが表示されているときだけ適用されます。
  • オーバーレイのhidden属性はモーダルを非表示にするだけでなく、閉じている間はドキュメントのkeydownリスナーが実行されないようにします。非表示の要素に設定されたディレクティブは一時停止されるためです。

サーバー状態を使う「いいね」ボタン

この例では、サーバー側の状態とクライアント側のアクションを組み合わせます。いいね数はPHPからwp_interactivity_state()を使って初期化され、ボタンをクリックすると更新されます。

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

ここでの新しいポイント:

  • wp_interactivity_state() はPHPから件数を初期化します。値はページHTMLにシリアライズされ、ディレクティブとJavaScript内でstate.countとして利用できます。
  • stateとcontextの違い: 件数はstate(グローバルで共有)にあり、likedはcontext(インスタンスごと)にあります。同じ項目に複数の「いいね」ボタンがある場合、件数は共有されますが、「いいね」済みかどうかは各ボタンで個別に管理できます。
  • store()からの分割代入: store()の呼び出しはリアクティブなstateオブジェクトを返し、アクション内から参照できます。

重要な注意点: サーバー状態はフロントエンド専用です。エディターではブロックはRESTAPI経由でレンダリングされるため、wp_interactivity_state()は含まれません。PHPでレンダリングされた代替テキスト(<?php echo esc_html( $count ); ?>)が、エディターのプレビューで初期値として表示されます。エディター内で操作できる状態には、代わりにdata-wp-contextを使ってください。

ヒントとパターン

名前空間の付け方。 テーマ名またはプラグイン名を接頭辞に使います。myTheme/accordion、myPlugin/tabsのようにします。同じページ上の複数のブロックでInteractivity APIを使う際の名前の衝突を防げます。

ビルド工程は不要。 Blockstudioはscript.jsをネイティブESモジュールとして読み込み、@wordpress/interactivityのインポートマップを自動生成します。import文を使った標準のJavaScriptを書けば、すぐに動作します。

ディレクティブだけを使うブロック。 ブロックでdata-wp-bind--hiddenまたはdata-wp-textを使ったdata-wp-contextだけを使用する場合、script.jsは不要です。Interactivity APIが宣言的に処理します。上のアコーディオン例では、チェックボックスを利用すればJavaScriptなしでも動作しますが、スクリプトを使う方法のほうがすっきりします。

data-wp-watchでデバッグ。 開発中にコンテキストの変化をログに記録するには、watchコールバックを追加します。

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

リリース前に削除してください。

コンテキストは最小限に。 実際に変化する値だけをdata-wp-contextに入れます。ラベルやコンテンツなどの静的データはPHPに残してください。コンテキストJSONはブロックのすべてのインスタンスにシリアライズされるため、大きなオブジェクトを入れるとページが重くなります。

次のステップ

  • Interactivityリファレンス: 設定オプション、エディターのサポート詳細、interactivity設定のオブジェクト形式について。
  • アセット: Blockstudioがscript.js、style.css、その他のブロックアセットを読み込む方法について。
  • WordPress Interactivity APIのドキュメント: このガイドで扱っていないdata-wp-each、data-wp-init、data-wp-run、その他のディレクティブを含む、APIの全リファレンス。