FSWP 區塊開發者 是做什麼的？
基礎（始終套用）： fswp-developer/references/lean-coding.md（先簡潔再寫、重複使用）、fswp-developer/references/coding-standards.md（編碼標準、文件、國際化、無障礙）以及 fswp-security-engineer（輸入、輸出、授權）。
優先使用核心區塊；僅在核心區塊與樣板無法表達需求時才編寫自訂區塊。官方參考：fswp-developer/references/official-docs.md 中的區塊編輯器手冊連結。請針對每個 API 檢查其最低 WordPress 版本，並比對專案所宣告的最低版本。
結構
blocks/my-block/
block.json name, title, category, attributes, supports, render, editorScript, viewScriptModule, style
edit.js 編輯器 UI（使用 useBlockProps）
save.js 靜態標記，或動態區塊可省略
render.php 動態區塊的伺服器端渲染
view.js 前端行為（模組）
style.scss / editor.scss
從 metadata 註冊：在 init 掛載點使用 register_block_type( __DIR__ . '/build/my-block' )（為 init 回呼命名一個函式）。設定 "apiVersion": 3（自 WordPress 6.3 起為現行版本）並加入 "$schema": "https://schemas.wp.org/trunk/block.json"。逐欄位參考，並對照區塊編輯器手冊：references/block-json.md。
決策
| 問題 | 選擇 |
|---|---|
| 輸出僅取決於已儲存的屬性 | 靜態區塊（save.js） |
| 輸出取決於即時資料、需在未重新儲存的情況下變更，或包含邏輯 | 動態區塊（render.php）；save 回傳 null 或僅回傳 InnerBlocks |
| 巢狀內容 | 使用 InnerBlocks 搭配 allowedBlocks 和 template |
| 將屬性綁定到資料（文章 meta、自訂來源） | 區塊綁定 API（register_block_bindings_source），前提是最低 WordPress 版本允許 |
| 現有區塊的替代預設值 | 使用區塊變體或樣式，而非新區塊 |
| 可重複使用的佈局 | 使用樣板，而非區塊 |
規則
- 屬性：為每個屬性指定
type和default；從標記或註解中一致地取得來源；在render.php中驗證。 - 使用
supports（顏色、間距、排版、對齊、錨點）而非自行編寫控制項。 - 編輯器標記必須使用
useBlockProps()；動態 PHP 使用get_block_wrapper_attributes()。 render.php（block.json 中的render，WordPress 6.1+）接收$attributes、$content與$block（一個WP_Block）。它在頁面上每個區塊實例只載入一次，因此絕對不要在裡面宣告函式或類別；應從其他檔案呼叫共享程式碼。- 腳本 vs 模組：
viewScript用於傳統腳本（以及任何依賴 WordPress 腳本的項目）；viewScriptModule（6.5+）用於腳本模組，例如 Interactivity API。兩者不可互換，因此不要在兩者之間混合依賴。 - 在
render.php中跳脫所有內容（fswp-security-engineer）；屬性屬於使用者輸入。 - 變更已發佈靜態區塊的已儲存標記會破壞現有內容。請加入包含舊版
save、屬性和migrate函式的deprecated項目，然後變更區塊。 - 在 JS 與 PHP 中翻譯字串（使用文字域的
__()）；使用wp_set_script_translations或 block.json 中的textdomain。 - 僅在區塊渲染的位置載入前端腳本（block.json 中的
viewScriptModule/script會自動處理此項）。
樣板
關於樣板、變體、區塊掛鉤與綁定的更多細節：references/patterns-variations.md。Interactivity API 深入探討（伺服器端渲染、非同步動作、data-wp-each、監看器、效能）：references/interactivity.md。
在 PHP 中使用 register_block_pattern()（以及 register_block_pattern_category()）註冊，或作為主題中 patterns/ 目錄下的檔案。樣板使用預設值與翻譯文字；不要使用遠端圖片；為它們提供清晰的標題、類別與關鍵字。
Interactivity API
伺服器端渲染的標記加上小型響應式行為，無需框架。
- 啟用方式：
"supports": { "interactivity": true }及"viewScriptModule": "file:./view.js"。 - 標記指令：
data-wp-interactive="namespace"、data-wp-context='{"open":false}'、data-wp-on--click="actions.toggle"、data-wp-bind--hidden="!context.open"、data-wp-class--is-open="context.open"、data-wp-text="state.label"。 - 在
view.js中的 store：import { store, getContext } from '@wordpress/interactivity'; store( 'namespace', { state: {...}, actions: { toggle() { const c = getContext(); c.open = ! c.open; } } } ); - 使用
wp_interactivity_state( 'namespace', array(...) )植入伺服器狀態，以確保首次渲染正確且無閃爍。保持狀態可序列化。 - 為所有項目加上命名空間以避免衝突；切勿將秘密資料放入 state 或 context（兩者都會輸出到頁面中）。
- 為確保無障礙性，請將
aria-expanded與焦點處理綁定到狀態，並測試鍵盤操作。
建置與測試
使用 npx @wordpress/create-block 作為起點；使用 @wordpress/scripts 進行 build、start、lint-js、lint-style、test-unit-js。將建置後的檔案與 src/、package.json 及鎖定檔一起交付（編譯程式碼的目錄規則）。在編輯器中測試（插入、編輯、儲存、重新載入、切換到程式碼檢視）以及前端測試。交給 fswp-qa-engineer。