MoriForms 說明文件
返回主站

第四章：Schema 頂層結構

FormaCore 的 JSON 結構，其最外層（或稱為「根」）的屬性，定義了整個表單的身份、全域行為、安全性和國際化等基礎設定。理解這些頂層屬性，是掌握表單控制權的第一步。

一份標準的 Schema 2.0 檔案結構如下所示：

JSON

{
  "version": "2.0",
  "minPluginVersion": "3.0.0",
  "formType": "standard",
  "formName": "我的進階表單",
  
  "i18n": { ... },
  "settings": { ... },
  "persistence": { ... },
  "security": { ... },
  
  "layout": [ ... ],
  "conditions": [ ... ],
  "actions": [ ... ],
  "validations": [ ... ],
  "errorHandling": { ... },
  
  "scoring": { ... },
  "outcomes": [ ... ]
}

接下來，我們將逐一解析這些頂層屬性的用途。

屬性詳解

version
  • 類型: String
  • 必需: 是
  • 說明: 定義了您這份 JSON 所遵循的 Schema 版本。為了確保您的表單能被正確解析，這個值必須是 "2.0"。
minPluginVersion
  • 類型: String
  • 必需: 否 (但強烈建議)
  • 說明: 指定了運行此表單所需的 FormaCore 核心插件的最低版本號。這是一個向前相容的保護機制。如果使用者的插件版本過低，FormaCore 會提示其升級，而不是渲染一個可能出錯的表單。
  • 範例: "3.1.0"
formType
  • 類型: String
  • 必需: 是
  • 說明: 這是表單最重要的分類標籤，它決定了表單的基礎行為模式，並且 FormaCore 會根據此類型來篩選可用的 Skin。
  • 可選值:
    • "standard": 標準的單頁表單，如聯絡表單、詢價單。
    • "wizard": 多步驟嚮導式表單，會將 layout 中的 step 元素呈現為獨立的步驟。
    • "quiz": 計分類型的測驗，通常會搭配 scoring 和 outcomes 屬性使用。
    • "survey": 問卷調查，功能上類似 standard 或 wizard，但語意上更清晰。
formName
  • 類型: String
  • 必需: 否 (但強烈建議)
  • 說明: 表單的人類可讀名稱。主要用於在 WordPress 後台列表中進行識別。
i18n

  • 類型: Object

  • 必需: 否

  • 說明: 處理表單國際化的核心設定。當您需要讓一份表單支援多國語言時，就需要用到它。其內部結構包含 defaultLocale 和 locales。 JSON

    "i18n": {
  "defaultLocale": "en-US",
  "locales": {
    "en-US": {
      "fields": { "username": { "label": "Username" } },
      "buttons": { "submit": "Submit" }
    },
    "zh-TW": {
      "fields": { "username": { "label": "使用者名稱" } },
      "buttons": { "submit": "送出" }
    }
  }
}

    設定後，您可以在表單的其他地方（如欄位的 label）使用 "i18n:fields.username.label" 的格式來引用對應的翻譯文本。

settings
  • 類型: Object
  • 必需: 否
  • 說明: 控制表單全域外觀和行為的設定集合。例如，您可以設定送出按鈕的文字、是否顯示重置按鈕、是否為多步驟表單顯示進度條等。
persistence
  • 類型: Object
  • 必需: 否
  • 說明: 對於較長的表單，啟用此功能可以將使用者已填寫的資料暫存在瀏覽器中（localStorage 或 sessionStorage），防止因意外關閉或刷新頁面導致資料遺失。您可以設定是否啟用、儲存方式以及自動儲存的間隔。
security
  • 類型: Object
  • 必需: 否
  • 說明: 定義與表單安全相關的規則。這是保護您的網站免受濫用的重要防線。其內部可設定：
    • requireAuth: 是否要求使用者必須登入才能提交。
    • allowedRoles: 允許提交的 WordPress 使用者角色。
    • captcha: 啟用並設定 reCAPTCHA 或 hCaptcha。
    • rateLimit: 限制單一 IP 在單位時間內的提交次數。
layout, conditions, actions, validations
  • 類型: Array
  • 說明: 這四個陣列是構成表單互動邏輯的核心。
    • layout: 定義所有可見的元素，是表單的「骨架」。(下一章將詳解)
    • conditions: 定義所有「如果...那麼...」的條件規則，是表單的「大腦」。
    • actions: 定義提交成功後的所有後續動作，是表單的「手臂」。
    • validations: 定義需要多個欄位一起判斷的跨欄位驗證規則。
errorHandling
  • 類型: Object
  • 必需: 否
  • 說明: 全域的錯誤處理設定，用來控制當驗證失敗時，錯誤訊息的顯示方式。例如，是在每個欄位下方單獨顯示 (inline)，還是在表單頂部顯示一個總結列表 (summary)。
scoring & outcomes
  • 類型: Object 和 Array
  • 必需: 當 formType 為 quiz 時是必需的。
  • 說明: 這兩個屬性是專為測驗型表單設計的。
    • scoring: 定義分數的計算方式（例如，是簡單加總還是分類計分）。
    • outcomes: 定義不同的分數區間對應到哪一個測驗結果。

下一步

您現在已經掌握了如何配置一份表單的「全域設定」。在下一章中，我們將把焦點放在最核心的 layout 屬性上，深入學習如何使用各種容器和欄位元素來建構出您想要的任何表單佈局。

本頁目錄