wp-interactivity-api

WP Interactivity API

使用するタイミング

ユーザーが次の内容に言及した場合に、このスキルを使用します。

• Interactivity API、@wordpress/interactivity、
• data-wp-interactive、data-wp-on--*、data-wp-bind--*、data-wp-context、
• ブロックの viewScriptModule ／モジュールベースのビュー・スクリプト、
• ハイドレーションの問題、または「ディレクティブが動作しない」。

必要な入力

• リポジトリのルートとトリアージの出力（wp-project-triage）。
• 影響を受けるブロック／テーマ／プラグインの対象範囲（フロントエンド、エディター、または両方）。
• 制約事項：WP のバージョン、ビルドでモジュールがサポートされているかどうか。

手順

1) 既存の使用状況と統合方法を確認する

次の項目を検索します。

• data-wp-interactive
• @wordpress/interactivity
• viewScriptModule

次の点を判断します。

• block.json のビュースクリプトモジュールを使って、ブロックがインタラクティビティを提供していますか？
• テーマレベルのインタラクティビティですか？
• プラグイン側で既存のマークアップを拡張する使い方ですか？

新しいインタラクティブブロックを作成する場合（単なるデバッグではない場合）は、公式のスキャフォールドテンプレートを使用してください。

• @wordpress/create-block-interactive-template（@wordpress/create-block 経由）

2) ストアを特定する

ストアの定義を見つけ、次の点を確認します。

• state の構造、
• アクション（ミューテーション）、
• data-wp-on--* で使われるコールバック／イベントハンドラー。

3) サーバーサイドレンダリング（ベストプラクティス）

出力前にサーバーで HTML を事前レンダリングし、次の点を確保します。

• JavaScript の読み込み前に、HTML に正しい初期状態が反映される（レイアウトシフトが発生しない）。
• SEO の効果と、体感的な読み込み時間の短縮。
• クライアントサイドの JavaScript が引き継ぐ際のシームレスなハイドレーション。

サーバーディレクティブ処理を有効にする

block.json を使うコンポーネントでは、supports.interactivity を追加します。

{
  "supports": {
    "interactivity": true
  }
}

block.json のないテーマ／プラグインでは、wp_interactivity_process_directives() を使ってディレクティブを処理します。

PHP で state／context を初期化する

wp_interactivity_state() を使って初期のグローバル state を定義します。

wp_interactivity_state( 'myPlugin', array(
  'items'    => array( 'Apple', 'Banana', 'Cherry' ),
  'hasItems' => true,
));

ローカル context には、wp_interactivity_data_wp_context() を使います。

<?php
$context = array( 'isOpen' => false );
?>
<div <?php echo wp_interactivity_data_wp_context( $context ); ?>>
  ...
</div>

PHP で派生 state を定義する

派生 state が初期 HTML のレンダリングに影響する場合は、そのロジックを PHP でも再現します。

wp_interactivity_state( 'myPlugin', array(
  'items'    => array( 'Apple', 'Banana' ),
  'hasItems' => function() {
    $state = wp_interactivity_state();
    return count( $state['items'] ) > 0;
  }
));

これにより、data-wp-bind--hidden="!state.hasItems" のようなディレクティブが初回読み込み時に正しくレンダリングされます。

詳しい例やパターンについては、references/server-side-rendering.md を参照してください。

4) ディレクティブを安全に実装または変更する

マークアップのディレクティブを扱う場合は、次の点に注意します。

• ディレクティブの使用を最小限に抑え、適用範囲を限定する。
• ストアの state との対応が明確な、安定したデータ属性を優先する。
• サーバーでレンダリングされたマークアップとクライアント側のハイドレーションが一致するようにする。

WordPress 6.9 の変更点：

• data-wp-ignore は非推奨となり、今後のバージョンで削除されます。context の継承が壊れ、クライアントサイドナビゲーションで問題が発生していました。使用しないでください。
• ディレクティブ ID の一意性：--- 区切り文字を使って、同じ要素に同じ種類のディレクティブを複数指定できるようになりました（例：data-wp-on--click---plugin-a="..." および data-wp-on--click---plugin-b="..."）。
• 新しい TypeScript 型：AsyncAction<ReturnType> と TypeYield<T> により、非同期アクションの型付けがしやすくなります。

ディレクティブの簡単な確認には、references/directives-quickref.md を参照してください。

5) ビルド／ツールとの整合性を確認する

リポジトリが必要なモジュールビルドの経路をサポートしていることを確認します。

• @wordpress/scripts を使用している場合は、その規約に従うことを優先します。
• カスタムバンドルを使用している場合は、モジュール出力がサポートされていることを確認します。

6) よくある失敗要因をデバッグする

操作しても「何も起こらない」場合は、次の点を確認します。

• viewScriptModule がエンキューされ、読み込まれていること。
• DOM 要素に data-wp-interactive があること。
• ストアの名前空間がディレクティブの値と一致していること。
• ハイドレーション前に JavaScript エラーが発生していないこと。

references/debugging.md を参照してください。

検証

• 変更後（該当する場合）、wp-project-triage に signals.usesInteractivityApi: true と表示される。
• 手動のスモークテストで、ディレクティブが実行され、state が期待どおりに更新されることを確認する。
• テストがある場合は、操作の流れを対象とする Playwright E2E テストを追加／拡張する。

失敗のパターン／デバッグ

• ディレクティブが記述されているのに機能しない：
  • ビュースクリプトが読み込まれていない、モジュールのエントリーポイントが間違っている、または data-wp-interactive が設定されていない。
• ハイドレーションの不一致／ちらつき：
  • サーバーのマークアップがクライアントの想定と異なっています。初期状態を単純化するか、クライアントと一致させてください。
  • 派生状態が PHP で定義されていません。クロージャーとともに wp_interactivity_state() を使用してください。
• 初期コンテンツが表示されない、または誤っている：
  • （ブロックの場合）block.json で supports.interactivity が設定されていません。
  • （テーマ／プラグインの場合）wp_interactivity_process_directives() が呼び出されていません。
  • レンダリング前に PHP で状態／コンテキストが初期化されていません。
• 読み込み時にレイアウトがずれる：
  • state.hasItems などの派生状態がサーバーに存在せず、hidden 属性が出力されていません。
• パフォーマンスの低下：
  • インタラクティブなルートの範囲が広すぎます。インタラクティビティの適用範囲をより小さなサブツリーに絞ってください。
• クライアントサイドナビゲーションの問題（WordPress 6.9）：
  • getServerState() と getServerContext() はページ遷移の間にリセットされるようになりました。コードが古い値の保持を前提としていないことを確認してください。
  • ルーターリージョンで、オーバーレイ（モーダル、ポップアップ）を動的にレンダリングするための attachTo がサポートされるようになりました。

エスカレーション

• リポジトリのビルドに関する制約が不明な場合は、「これは @wordpress/scripts を使用していますか、それともカスタムバンドラー（webpack/vite）を使用していますか？」と尋ねてください。
• 次を参照してください：
  • references/server-side-rendering.md
  • references/directives-quickref.md
  • references/debugging.md