WordPress Interactivity APIの使い方｜stateとactionを実働デモで理解する

WordPress Interactivity APIは、ブロックのHTMLへ宣言的な属性を付け、共有stateとactionでフロント側の操作を組み立てる仕組みです。カウンター、絞り込み、カート、アコーディオンなどを、WordPressが管理する共通ランタイム上で実装できます。

情報確認日：2026年8月20日

先に結論：APIを使う判断基準

stateとactionの同期を触って理解する

必要な4要素を整理する

サイト全体で共有する値をすべてcontextへ入れたり、各カード固有の値をglobal stateへ入れたりすると、更新範囲が分かりにくくなります。「共有するか、その要素だけか」で分けます。

最小ブロックを作る手順

1. block.jsonでInteractivity APIを有効にする

{
  "apiVersion": 3,
  "name": "devsakaso/counter",
  "title": "Interactive Counter",
  "category": "widgets",
  "supports": {
    "interactivity": true
  },
  "render": "file:./render.php",
  "viewScriptModule": "file:./view.js"
}

viewScriptModuleは公開画面で使うScript Moduleを登録します。通常のviewScriptと混同せず、公式ドキュメントで対象WordPressバージョンを確認してください。

2. PHPでディレクティブ付きHTMLを出す

<div
  <?php echo get_block_wrapper_attributes(); ?>
  data-wp-interactive="devsakaso/counter"
>
  <button data-wp-on--click="actions.increment">
    追加
  </button>
  <output data-wp-text="state.count"></output>
</div>

data-wp-interactiveでnamespaceを宣言し、data-wp-on--clickでクリックをactionへ結び、data-wp-textでstateを表示します。初期HTMLをPHPで出しておけば、JavaScriptの読込前にもページ構造を保てます。

3. view.jsでstoreを登録する

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

const { state } = store('devsakaso/counter', {
  state: {
    count: 0,
  },
  actions: {
    increment() {
      state.count += 1;
    },
  },
});

同じnamespaceを使う領域はstateを共有できます。外部APIを呼ぶactionは待機中・失敗・再試行の状態も設計し、連打や二重送信を防ぎます。

contextを使う場面

一覧に複数のアコーディオンがあり、各項目の開閉を個別に持つならcontextが適します。PHP側でwp_interactivity_data_wp_context()を使い、項目固有の初期値を安全にJSON化できます。JavaScript側ではgetContext()で現在の要素に対応する値を取得します。

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

store('devsakaso/accordion', {
  actions: {
    toggle() {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

アクセシビリティはAPI任せにしない

stateが変わっても、意味のあるHTMLやフォーカス管理が自動で完成するわけではありません。開閉ボタンならaria-expandedと対象の関連付け、非同期結果なら適切な通知、メニューならキーボード操作を設計します。divへクリックを付けるのではなく、操作にはbuttonを使うのが出発点です。

つまずきやすい点と解決策

クリックしてもactionが呼ばれない

namespaceの不一致、supports.interactivity、Script Moduleの登録、ディレクティブ名を確認します。ブラウザのConsoleだけでなく、生成されたHTMLに属性が残っているかを見ます。

複数ブロックの値が意図せず同期する

global stateへ置いた値はnamespace内で共有されます。各ブロック固有ならcontextへ移し、共有が必要な値だけstateに残します。

古いWordPressでも動かしたい

Interactivity APIはWordPress 6.5で導入されました。対応バージョンをプラグイン要件へ明記し、古い環境が対象なら従来のJavaScript実装を別ビルドとして用意するか、機能を静的表示へ縮退させます。

導入前チェックリスト

• 静的HTMLだけでも内容が理解できる
• stateとcontextの境界を説明できる
• actionの連打、失敗、待機中を処理している
• キーボードとスクリーンリーダーで操作できる
• 対象WordPressバージョンをテストしている

まとめ

Interactivity APIは、WordPressブロックの公開画面へ状態と操作を追加する共通基盤です。共有値はstate、局所値はcontext、操作はactionへ分け、PHPの初期HTMLを残して段階的に対話化してください。単純な処理を無理に移行するのではなく、複数領域の同期や再利用性が必要になった時点で採用するのが現実的です。

関連記事

• JavaScriptのイベント伝播を理解する
• WordPressブログの始め方

参照した公式資料

• WordPress Developer Resources：Interactivity API
• WordPress Developer Resources：@wordpress/interactivity