第八章：manifest.json 完整參考

我們在「快速上手」章節中已經見過 manifest.json 的基本樣貌，但那只是冰山一角。這個檔案是您的 Skin 與 MoriForms 引擎之間溝通的唯一橋樑，它定義了 Skin 的身份、所需資源、以及可供使用者在後台調整的選項。

一個結構完整、定義清晰的 manifest.json 是打造專業級 Skin 的基礎。本章將作為您未來開發時可隨時查閱的參考手冊。

完整範例

一個功能齊全的 manifest.json 看起來會像這樣：

JSON

{
  "name": "Corporate Pro",
  "skinVersion": "2.1.0",
  "author": "MoriForms Team",
  "authorUri": "https://MoriForms.io",
  "description": "A clean and professional skin, suitable for corporate contact forms and quote requests. Includes customizable colors.",
  "supportedFormType": ["standard", "survey"],
  "textDomain": "corporate-pro",
  "assets": {
    "css": [
      {
        "handle": "corporate-pro-style",
        "src": "assets/css/main.css",
        "dependencies": [],
        "version": "2.1.0"
      }
    ],
    "js": [
      {
        "handle": "corporate-pro-script",
        "src": "assets/js/main.js",
        "dependencies": ["jquery"],
        "version": "2.1.0",
        "in_footer": true
      }
    ]
  },
  "options": [
    {
      "id": "primary_color",
      "label": "主要顏色",
      "description": "設定按鈕和焦點的外框顏色。",
      "type": "colorpicker",
      "default": "#1a73e8"
    },
    {
      "id": "layout_style",
      "label": "佈局風格",
      "type": "select",
      "default": "stacked",
      "options": [
        { "label": "堆疊", "value": "stacked" },
        { "label": "行內標籤", "value": "inline-label" }
      ]
    }
  ]
}

屬性詳解

name

• 類型: String
• 必需: 是
• 說明: Skin 的人類可讀名稱。它將會顯示在 WordPress 後台的 Skin 選擇器下拉選單中。

skinVersion

• 類型: String
• 必需: 是
• 說明: Skin 的版本號。強烈建議遵循「語意化版本 (Semantic Versioning)」格式（MAJOR.MINOR.PATCH，例如 1.2.3）。這個版本號對於 MoriForms 的「更新檢查」機制至關重要。

author & authorUri

• 類型: String
• 必需: 否
• 說明: 分別是作者的名稱和作者的網站連結。這有助於標示版權和來源。

description

• 類型: String
• 必需: 否
• 說明: 對此 Skin 的簡短描述。說明它的設計風格、最佳用途等。這些資訊可能會在後台的預覽或詳情介面中顯示。

supportedFormType

• 類型: String 或 Array
• 必需: 是
• 說明: 極其重要的欄位。它告訴 MoriForms 引擎，這個 Skin 是為哪一種類型（formType）的表單設計的。引擎會使用此資訊來過濾下拉選單，確保使用者不會將一個「測驗 Skin」套用到一個「標準聯絡表單」上，從而避免錯誤。
• 範例:
  • "standard" (僅支援標準表單)
  • ["quiz", "survey"] (同時支援測驗和問卷)

textDomain

• 類型: String
• 必需: 是 (若需翻譯)
• 說明: 用於國際化 (i18n) 的文本域 (Text Domain)。如果您在 Skin 的 functions.php 檔案中（詳見第十章）使用了 WordPress 的翻譯函數 (如 _e(), __())，就需要這個值。為了保持最佳實踐，它的值應與您的 Skin 資料夾名稱保持一致。

assets

• 類型: Object
• 必需: 是 (若有 CSS/JS)
• 說明: 這是 Skin 的「資源管理器」。您必須在此處宣告所有需要載入的 CSS 和 JavaScript 檔案。請勿在 template.php 中手動寫入 <link> 或 <script> 標籤。在此處宣告能讓 MoriForms 使用 WordPress 標準的資源佇列系統 (wp_enqueue_style/script) 來載入它們，這樣能妥善處理檔案依賴、版本控制，並避免與其他插件發生衝突。
• 子屬性:
  • css (Array): 包含數個 CSS 檔案物件。每個物件有：
    • handle (String): WordPress 中此檔案的唯一識別碼。
    • src (String): 相對於 Skin 根目錄的檔案路徑。
    • dependencies (Array): 此 CSS 檔案所依賴的其他 CSS handle 陣列。
    • version (String): 檔案版本號，用於控制瀏覽器快取。
    • media (String): 此 CSS 適用的媒體類型，如 "all", "screen"。
  • js (Array): 包含數個 JS 檔案物件。每個物件有：
    • handle (String): 唯一識別碼。
    • src (String): 檔案路徑。
    • dependencies (Array): 依賴的其他腳本 handle 陣列，例如 ["jquery"]。
    • version (String): 檔案版本號。
    • in_footer (Boolean): 是否在頁面底部 (</body> 前) 載入此腳本。通常設為 true 以提升頁面載入效能。

options

• 類型: Array
• 必需: 否
• 說明: 這是 MoriForms 最強大的功能之一。它允許您定義一組選項，這些選項會 自動在 WordPress 後台的表單編輯頁面生成對應的設定欄位 。這讓非技術使用者也能安全地客製化您的 Skin 外觀，而無需修改任何程式碼。
• 結構： 這是一個「選項物件」的陣列，每個物件定義一個設定欄位：
  • id (String): 此選項的唯一 ID，儲存到資料庫時會使用此 ID 作為鍵 (key)。
  • label (String): 顯示在設定欄位旁邊的標題文字。
  • description (String, 可選): 顯示在設定欄位下方的輔助說明文字。
  • type (String): 您希望生成的 HTML 控制項類型。MoriForms 內建支援以下類型：
    • "text": 單行文字輸入框。
    • "textarea": 多行文字區域。
    • "colorpicker": WordPress 內建的顏色選擇器。
    • "select": 下拉選單。
    • "checkbox": 單一的核取方塊 (開關)。
    • "image_upload": WordPress 媒體庫圖片上傳器。
  • default (Any): 此選項的預設值。
  • options (Array): 只有當 type 為 "select" 時才需要。它是一個包含 {"label": "...", "value": "..."} 物件的陣列。

如何使用這些選項？ 使用者在後台儲存的值，將會被 MoriForms 引擎在後端讀取。它們可以被用來替換 template.html 中的佔位符，或在 Skin 的 functions.php 中使用，並且會被完整地傳遞到 main.js 的 moriformsData.forms[id].skinOptions 物件中，供您在前端腳本中取用，讓您可以輕易地在程式碼中取用並據此改變 Skin 的行為或樣式。

下一步

精通 manifest.json 的配置，意味著您已完全掌握如何將您的 Skin 與 WordPress 和 MoriForms 引擎無縫整合。

在下一章，我們將把焦點轉移到 main.js，深入探討前端 JavaScript 的最佳實踐，學習如何優雅地處理來自引擎的資料、管理複雜的表單狀態，以及處理 API 的各種回應。