wp-block-development

WP 區塊開發 (WP Block Development)

使用時機

在進行以下區塊相關工作時使用此 Skill：

• 建立新區塊或更新既有區塊
• 修改 block.json（scripts/styles/supports/attributes/render/viewScriptModule）
• 排解「區塊無效 / 無法儲存 / 屬性未持久化」等問題
• 新增動態渲染 (render.php / render_callback)
• 區塊版本棄用與舊版遷移（deprecated 版本處理）
• 區塊建置工具鏈 (@wordpress/scripts、@wordpress/create-block、wp-env)

必要輸入資訊

• 專案根目錄與目標類別（外掛 vs 佈景主題 vs 完整網站）。
• 區塊名稱/命名空間及其儲存位置（若已知，提供 block.json 的路徑）。
• 目標 WordPress 版本範圍（特別是若有使用模組 / viewScriptModule）。

執行流程

0) 診斷與定位區塊

1. 執行診斷程序：
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. 掃描並列出所有區塊（確定性掃描）：
   • node skills/wp-block-development/scripts/list_blocks.mjs
3. 確認您正在修改的區塊根目錄（即包含 block.json 的目錄）。

如果此儲存庫是一個完整網站（存在 wp-content/），請明確指出區塊屬於哪一個外掛或佈景主題。

1) 建立新區塊（若需要）

如果要建立新區塊，建議優先採用腳手架工具自動生成，而非從零手寫架構：

• 使用 @wordpress/create-block 來建置現代化的區塊/外掛基礎架構。
• 若一開始就需要使用 Interactivity API，請選擇互動式範本 (interactive template)。

請閱讀：

• references/creating-new-blocks.md

完成腳手架建立後：

1. 重新執行區塊列表指令碼，確認新的區塊根目錄。
2. 繼續執行後續步驟（選擇區塊模型、設定中繼資料、註冊、序列化）。

2) 確保使用 apiVersion 3 (WordPress 6.9+)

WordPress 6.9 開始在 block.json schema 中強制規範使用 apiVersion: 3。若區塊仍採用 apiVersion 2 或更低版本，在開啟 SCRIPT_DEBUG 時會在控制台跳出警告訊息。

為什麼這點很重要：

• 從 WordPress 7.0 開始，無論區塊的 apiVersion 為何，文章編輯器都將預設放在 iframe 中執行。
• 設定 apiVersion 3 可確保您的區塊在 iframe 編輯器內運作正常（包含樣式隔離、視埠單位 Viewport units、媒體查詢 Media queries）。

遷移方式： 將版本從 2 升級至 3 通常只需要在 block.json 中更新 apiVersion 欄位即可。不過仍需注意：

• 請在開啟 iframe 編輯器的本機環境中進行測試。
• 確保所有樣式代號 (style handles) 均已包含在 block.json 中（若未包含在 iframe 內，樣式將無法生效）。
• 掛載在特定 window 物件上的第三方指令碼可能會遇到作用域問題。

請閱讀：

• references/block-json.md（包含 apiVersion 與 schema 詳細資訊）

3) 選擇合適的區塊模型

• 靜態區塊 (Static block)（標記直接寫入文章內容）：實作 save()；確保屬性序列化穩定一致。
• 動態區塊 (Dynamic block)（伺服器端渲染）：在 block.json 中指定 render（或在 PHP 中設定 render_callback），並保持 save() 最簡化或設為 null。
• 前端互動行為 (Interactive frontend behavior)：
  • 在支援的環境下，優先使用 viewScriptModule 來載入現代化的 JavaScript 模組視圖指令碼。
  • 若主要針對 data-wp-* 指令或狀態庫 (stores) 進行開發，請同時配合 wp-interactivity-api 使用。

4) 安全地更新 block.json

在區塊的 block.json 中進行修改，隨後確認程式碼中的區塊註冊資訊與中繼資料保持一致。

如需逐欄位的詳細指引，請閱讀：

• references/block-json.md

常見陷阱：

• 變更 name 會破壞向下相容性（請將其視為不可隨意更動的穩定 API）
• 修改已儲存的 HTML 標記卻未加入 deprecated 舊版記錄，會導致「Invalid block」警告
• 新增屬性時若未正確定義來源 (source) 或序列化方式，會導致「屬性無法儲存」

5) 註冊區塊（優先選擇伺服器端註冊）

建議優先使用 PHP 讀取中繼資料來註冊區塊，尤其在以下情況：

• 需要動態渲染時
• 需要語系翻譯時 (wp_set_script_translations)
• 需要條件式載入資產檔案 (assets) 時

請閱讀並套用：

• references/registration.md

6) 實作 edit / save / render 設計模式

請遵循容器屬性 (wrapper attributes) 的最佳實踐：

• 編輯器端：useBlockProps()
• 靜態儲存端：useBlockProps.save()
• 動態渲染 (PHP)：get_block_wrapper_attributes()

請閱讀：

• references/supports-and-wrappers.md
• references/dynamic-rendering.md（若為動態區塊）

7) 內嵌區塊 (Inner blocks / 區塊組合)

若您的區塊屬於可巢狀包覆其他區塊的「容器區塊」，請將 Inner Blocks 視為一等公民特性處理：

• 使用 useInnerBlocksProps() 將內嵌區塊與容器屬性整合。
• 若更動了內嵌結構的 HTML 標記，請記得做好版本遷移準備。

請閱讀：

• references/inner-blocks.md

8) 屬性與序列化

修改屬性前：

• 確認屬性值的儲存位置（HTML 註解分隔符、HTML 內容、或是 Context 上下文）
• 避免使用已棄用的 meta 屬性來源 (attribute source)

請閱讀：

• references/attributes-and-serialization.md

9) 版本遷移與棄用處理（避免跳出「Invalid block」）

如果修改了儲存的 HTML 標記或屬性：

1. 建立 deprecated 陣列項目（排序由新到舊）。
2. 為舊版本提供對應的 save 實作，並可選擇性提供 migrate 函式以正規化屬性。

請閱讀：

• references/deprecations.md

10) 建置工具與驗證指令

優先使用專案現有的工具鏈：

• @wordpress/scripts（最常見）→ 執行專案既有的 npm scripts
• wp-env（最常見）→ 用於本機 WordPress 環境與 E2E 測試

請閱讀：

• references/tooling-and-testing.md

驗證步驟

• 區塊順利顯示在區塊新增器中，且能正常插入頁面。
• 儲存頁面並重新整理後，不會觸發「Invalid block」警告。
• 前端輸出符合預期（靜態區塊：輸出已儲存的 HTML 標記；動態區塊：輸出伺服器端渲染結果）。
• 資產檔案在預期的位置正確載入（編輯器端 vs 前端）。
• 執行診斷程序所建議的專案 lint / build / 測試指令。

故障模式與除錯

若遭遇失敗或錯誤，請從這裡開始排查：

• references/debugging.md（常見錯誤與最快排查方法）
• references/attributes-and-serialization.md（屬性無法儲存問題）
• references/deprecations.md（修改後出現無效區塊問題）

進階求助與參考

若對上游行為或版本支援度存有疑慮，請先查閱官方權威文件：

• WordPress 開發者資源（區塊編輯器手冊 Block Editor Handbook、佈景主題手冊 Theme Handbook、外掛手冊 Plugin Handbook）
• Gutenberg 官方 GitHub 儲存庫文件（了解最新或前瞻特性）