Name: wp-interactivity-api
Author: wordpress

WP Interactivity API

使用時機

當使用者提及以下內容時使用此 Skill：

Interactivity API、@wordpress/interactivity
data-wp-interactive、data-wp-on--*、data-wp-bind--*、data-wp-context
區塊 viewScriptModule / 基於模組的檢視腳本（module-based view scripts）
Hydration（水合/狀態復原）問題或「指令未觸發」

前置需求（Inputs required）

專案根目錄 + 排查分析輸出（wp-project-triage）
受影響的區塊/佈景主題/外掛範圍（前端、編輯器或兩者皆有）
相關限制條件：WP 版本、建置流程是否支援 JavaScript 模組（modules）

操作流程

1) 偵測現有使用方式與整合風格

搜尋以下關鍵字：

data-wp-interactive
@wordpress/interactivity
viewScriptModule

判斷：

這是否為透過 block.json 的 view script module 提供互動能力的區塊？
這是否為佈景主題層級的互動功能？
這是否為外掛端「增強現有標記（enhance existing markup）」的使用情境？

若要建立新的互動區塊（而非僅是偵錯），優先使用官方的腳手架範本：

@wordpress/create-block-interactive-template（透過 @wordpress/create-block）

2) 確認 Store 定義

定位 Store 定義並確認：

state 的結構（shape）
actions（狀態變更函式）
data-wp-on--* 所使用的 callbacks / 事件處理常式（event handlers）

3) 伺服器端轉譯（最佳實踐）

在輸出 HTML 前先於伺服器端進行預轉譯（Pre-render），以確保：

在 JavaScript 載入前，HTML 已具備正確的初始狀態（避免版面位移 Layout Shift）。
帶來 SEO 優勢並提供更快的感知載入速度。
用戶端 JavaScript 接管時能順暢完成 Hydration。

啟用伺服器端指令處理

使用 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（Derived 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) 安全地實作或變更指令

修改 HTML 標記中的指令時：

保持指令的使用精簡且作用域明確。
優先使用能明確對應至 Store state 的穩定資料屬性（data attributes）。
確保伺服器轉譯的 HTML 標記與用戶端 Hydration 結果一致。

WordPress 6.9 變更說明：

data-wp-ignore 已廢棄，並將在未來版本中移除。它會破壞 Context 的繼承機制並導致用戶端導覽出現問題，請避免使用。
唯一指令 ID（Unique directive IDs）：同一個元素上現在可透過 --- 分隔符存在多個同類型指令（例如 data-wp-on--click---plugin-a="..." 與 data-wp-on--click---plugin-b="..."）。
全新 TypeScript 型別：提供 AsyncAction<ReturnType> 與 TypeYield<T> 輔助非同步 Action 的型別定義。

如需指令速查，請參閱 references/directives-quickref.md。

5) 建置與工具鏈對齊

確認專案庫支援所需的模組建置路徑：

若使用 @wordpress/scripts，請遵循其預設慣例。
若使用自訂打包工具（custom bundling），請確認支援 JavaScript 模組輸出。

6) 排查常見故障模式（Failure Modes）

若互動時「完全沒有反應」：

確認 viewScriptModule 已正確引入/載入。
確認 DOM 元素帶有 data-wp-interactive。
確認 Store 的命名空間（namespace）與指令的值相符。
確認在 Hydration 執行前沒有任何 JavaScript 錯誤。

詳情請參閱 references/debugging.md。

驗證方式

變更後（若適用），wp-project-triage 顯示 signals.usesInteractivityApi: true。
手動冒煙測試（Smoke test）：指令能正常觸發且 State 如預期更新。
若專案包含測試：在互動路徑上新增或擴充 Playwright E2E 測試。

故障模式與排查（Failure modes / debugging）

指令存在但無效：
- view script 未載入、模組進入點（entrypoint）錯誤，或缺少 data-wp-interactive。
Hydration 不符合 / 畫面閃爍：
- 伺服器端轉譯的 HTML 與用戶端預期不一致；請簡化或對齊初始 State。
- 未在 PHP 中定義衍生 State：請使用帶有閉包（closure）的 wp_interactivity_state()。
初始內容缺失或錯誤：
- block.json 中未設定 supports.interactivity（區塊情境）。
- 未呼叫 wp_interactivity_process_directives()（佈景主題/外掛情境）。
- 在轉譯前未於 PHP 中初始化 State/Context。
載入時發生版面位移（Layout Shift）：
- 伺服器端缺少衍生 State（例如 state.hasItems），導致 hidden 屬性未被加入。
效能下降（Performance regressions）：
- 互動根節點（interactive root）範圍過大；請將互動作用域縮小至更小的子樹狀結構。
用戶端頁面切換問題（WordPress 6.9）：
- getServerState() 與 getServerContext() 現在會在頁面切換時重設 — 請確保程式碼不會假設舊值持續存在。
- 路由器區域（Router regions）現在支援 attachTo，可用於動態轉譯覆蓋層（如對話盒 Modal、彈出視窗 Pop-up）。

問題回報與升級（Escalation）

若專案建置限制不明確，請詢問：「專案是使用 @wordpress/scripts 還是自訂打包工具（webpack/vite）？」
參考文件：
- references/server-side-rendering.md
- references/directives-quickref.md
- references/debugging.md

wp-interactivity-api

相關技能