Nextora 區塊
擁有區塊的完整程式碼契約：中繼資料、註冊、編輯器 UI、動態轉譯、檢視腳本、建置輸出消費。外觀規則由 nextora-design-system 負責；模板與型版由 nextora-site-composition 處理；子佈景主題腳手架則歸 nextora-child-themes。每當需求涉及區塊的外觀時，請載入設計系統技能；當區塊必須遵循預設或訪客切換功能時，則兩個技能都需載入。
優先載入這些參考文件
僅根據任務需求，從此檔案的相對路徑讀取內容：
| 檔案 | 用途 |
|---|---|
references/block-contract.md | 資料夾結構、block.json 鍵值、註冊器行為、類別強制轉換、產生器、esbuild/window.wp shim 及其 14 個控制代碼依賴清單、save 語義、轉譯與檢視契約。 |
references/editor-and-repeaters.md | 兩個真實的列表編輯器（team-section 與子項 repeater.tsx）、它們的精確提交/取消語義、富文字與媒體輔助函式。 |
../nextora-ecosystem/references/source-map.md | 每條規則的來源以及如何重新檢查；根解析詞彙。 |
../nextora-ecosystem/references/quality-gates.md | 資料、一致性、資產、安全性、國際化、無障礙門檻以及共享的下游驗收配方（第 8 節）。 |
切勿將參考文件中引用的值視為最新：在編輯前，請重新讀取目標主題本身的檔案。
有序工作流程
1. 解析目標與區塊的宿主主題
從實際安裝或提供的儲存庫中識別父佈景主題根目錄和活躍（子）佈景主題根目錄——即 get_template_directory() 和 get_stylesheet_directory()，或 style.css 的標頭。子區塊僅在子佈景主題註冊它時才存在；父註冊器僅讀取模板目錄。如果沒有真實的 Nextora 原始碼，請勿聲稱 Nextora 相容性。
2. 讀取目標本身的證據
按此順序，優先使用實際值而非此處書寫的內容：
blocks/blocks.php——註冊器、其 glob、是否檢查可讀性、類別篩選器以及引入哪些每個區塊的 PHP 檔案。blocks/*/block.json——現有名稱、類別、supports、資產指標。- 最接近的現有區塊的
edit.tsx、render.php、可選的view.ts、save.tsx、register-styles.php/register-editor.php。 scripts/build-blocks.mjs——確切的入口 glob 和 shim。package.json+.nvmrc——實際存在的指令和 Node 版本。theme.json——調色盤、字型、漸層、字型大小和間距別名，區塊應參考這些。
3. 在建立前決定重用
當請求的編輯結構已存在時（另一個標題欄位、另一個列表、另一個切換開關），擴展現有區塊。僅當請求的行為或編輯結構無法由現有區塊、核心區塊、型版或區塊樣式變體表達時，才建立新的區塊。在交付物中說明你重用了哪個現有區塊，或為什麼沒有合適的——並且在交付物中而非僅在對話中說明：在區塊的編輯器入口中加入文件區塊，並在主題的 README 中加入一行（列出你拒絕的最接近的候選者以及每個缺少的內容）。一個只讀取儲存庫的記錄者必須能夠找到這個決定。
4. 先撰寫中繼資料
block.json 使用 apiVersion: 3、命名空間/文字網域/類別（父主題中為 nextora + nextora；子主題中為 <child-slug>）、帶有實際預設值的型別屬性、用於包裝外觀的 supports，以及指向已建置檔案的資產指標：editorScript: "file:./index.js"、render: "file:./render.php"、viewScript: "file:./view.js"。中繼資料中的類別僅用於顯示——PHP 與編輯器都會強制使用命名空間類別——因此切勿依賴 theme 或其他別名來放置區塊。
5. 決定 save，然後建構編輯器
- 動態（PHP 從屬性轉譯）：
render+save: () => null。 - 保留巢狀區塊：
save必須回傳useBlockProps.save()包裹<InnerBlocks.Content />。 - 靜態：精確儲存解析器期望的內容。
然後撰寫 edit.tsx，使用原生欄位——RichText 用於可見文字、InnerBlocks 用於巢狀內容、媒體 API 用於附件、核心連結控制項用於 URL——以及用於設定的 InspectorControls/PanelBody，重用現有的面板詞彙。重複資料遵循 references/editor-and-repeaters.md。不保留 UI 狀態。
6. 撰寫 render.php（動態區塊）
在根元素上使用 get_block_wrapper_attributes()；你自己的 data-*/樣式合併到其參數陣列中；根據上下文進行跳脫（esc_html、esc_attr、esc_url、wp_kses_post）；透過主題輔助函式解析範圍色彩；每個字串都使用目標主題的文字網域進行翻譯。保持 render.php 的類別名稱與區塊樣式表一致。
7. 連接行為與樣式
僅在區塊需要前端行為時才加入 view.ts：由狀態屬性保護的冪等初始化、載入→就緒切換、保留佈局空間、減少動畫與無 JS 路徑。前端 CSS 在區塊的 style.css（或檢視腳本的 CSS 匯入）中撰寫，並透過 style/editorStyle 引用；檢查器與畫布預覽 CSS 應限定在區塊範圍內，絕不影響 wp-admin 外觀。
8. 建置，然後在真實表面驗證
從主題根目錄執行目標自身的腳本（npm run build:blocks，或 npm run build，或子主題的 npm run build:blocks）。切勿手動編輯 index.js、index.asset.php、view.js 或 view.css。然後套用 ../nextora-ecosystem/references/quality-gates.md 及其第 8 節的區塊配方，以及 references/block-contract.md 第 11 節中區塊專屬的步驟。
嚴格限制
- 不得引入第二套 React 執行環境、不得使用全域性的
@wordpress/scripts管線、不得使用第二套打包工具。重用主題的 esbuild 設定。 - 加入未列出的
@wordpress/*匯入雖然可以建置，但可能讀取未定義的window.wp.*全域變數：資產清單僅列出固定的 14 個套件控制代碼。在匯入前檢查該全域變數及其控制代碼，或避免匯入。 - 不要加入區塊未使用的函式庫；
package.json中已有的函式庫是範圍版本，因此在使用 API 前請先讀取 lockfile。 - 未提供
deprecated項目或一次性遷移時，不得更改持久化屬性的結構；絕不要為了方便編輯器輔助函式而將索引鍵值的列表結構轉換為 ID 鍵值的結構（或反向轉換）。 - 不得加入 REST 路由、快取、遙測、管理頁面或不相關的抽象層來滿足區塊請求。
- 在提供技能或文件時，不得修改來源主題。
完成檢查清單
- 目標主題與區塊宿主已從其自身檔案識別；沒有任何聲明建立在未讀取的來源上。
- 已說明重用決策，或區塊必須為新的具體理由。
block.json指定了真實的命名空間/類別/文字網域配對，且僅指向已建置的資產；區塊在插入器中顯示於命名空間類別下。save與區塊的儲存類型相符，並透過儲存→重新載入→重新儲存驗證，無區塊驗證警告。- 可見文字、巢狀內容、媒體和 URL 使用原生編輯控制項；項目編輯器為單一對話框；未保留 UI 狀態。
render.php根據上下文跳脫並在目標文字網域中翻譯；範圍色彩透過主題輔助函式解析，空值遵循主題預設值。- 檢視行為是冪等的、保留佈局、並尊重減少動畫與無 JS。
- 使用目標自身的腳本重新產生建置輸出；產生的檔案未經手動觸摸。
- 已執行相關的第 8 節驗收步驟，或已清楚報告未經驗證的表面。
邊界
僅包含 Markdown 指令與來源支援的參考文件。此技能不提供執行時期腳本、產生器、複製的主題樹、套件管理或安裝自動化，並且不會修改父或子佈景主題的原始碼。