第五章：佈局與欄位 (layout)

layout 陣列是您表單的視覺骨幹。它定義了所有使用者將會看到並與之互動的元素，從標題、段落到各種輸入欄位。它的設計採用了 巢狀樹狀結構 ，這意味著您可以將元素放入其他元素中，從而創建出從簡單到極其複雜的任何佈局。

layout 陣列中的每一個項目都是一個物件，被稱為「元素 (Element)」。每個元素都必須包含一個全域唯一的 id 和一個 type 屬性。

我們可以將元素分為三大類：

1. 容器型元素 (Container Elements): 用於組織和包裹其他元素，構建佈局。
2. 欄位型元素 (Field Elements): 用於收集使用者的輸入，是表單的核心。
3. 內容型元素 (Content Elements): 用於顯示靜態內容，如標題或說明文字。

1. 容器型元素 (Container Elements)

這些元素如同建築中的梁柱和牆壁，它們自身不收集資訊，但為其他元素提供了結構。

type: "step"

• 用途： 專為 formType: "wizard" 的多步驟表單設計。每一個 step 都代表嚮導中的一個獨立頁面或步驟。

• 主要屬性：

  • title (String): 步驟的標題，可用於在進度條或步驟標題中顯示。
  • description (String, 可選): 對此步驟的簡短描述。
  • children (Array): 一個包含此步驟內所有其他元素的陣列。

• 範例： JSON

  {
    "id": "step_personal_info",
    "type": "step",
    "title": "個人資料",
    "children": [
      { "id": "heading_step1", "type": "heading", "content": "請告訴我們關於您的事" },
      { "id": "full_name", "type": "text", "label": "全名" }
    ]
  }
  

type: "group"

• 用途： 將一組相關的欄位包裹在一起，類似 HTML 的 <fieldset>。這對於保持結構清晰、以及後續使用條件邏輯統一控制一組欄位的顯示/隱藏非常有幫助。

• 主要屬性：

  • label (String): 群組的標題，類似 <legend>。
  • children (Array): 群組內的元素陣列。
  • repeatable (Object, 可選): (進階功能) 允許使用者動態地重複這個群組，例如新增多筆工作經歷或多個收件地址。
    • enabled (Boolean): 是否啟用重複功能。
    • min / max (Integer): 最少/最多可重複的次數。
    • addButtonText (String): 「新增一項」按鈕上顯示的文字。

• 範例： JSON

  {
    "id": "address_group",
    "type": "group",
    "label": "收件地址",
    "children": [
      { "id": "country", "type": "text", "label": "國家" },
      { "id": "city", "type": "text", "label": "城市" }
    ]
  }
  

type: "row"

• 用途： 用於創建多欄式佈局，將多個欄位水平排列在同一行。實際的排版效果（如欄位寬度）由 Skin 的 CSS 決定。

• 主要屬性：

  • children (Array): 需要水平排列的元素陣列。

• 範例： JSON

  {
    "id": "name_row",
    "type": "row",
    "children": [
      { "id": "first_name", "type": "text", "label": "名字" },
      { "id": "last_name", "type": "text", "label": "姓氏" }
    ]
  }
  

2. 欄位型元素 (Field Elements)

這些是表單的核心，負責實際的資料收集工作。

通用欄位屬性

以下屬性適用於絕大多數的欄位型元素：

• id (String, 必需): 全表單唯一的機器可讀 ID。
• type (String, 必需): 欄位的類型，例如 "text"。
• label (String, 必需): 顯示給使用者的標籤文字。
• defaultValue (Any, 可選): 欄位的預設值。
• placeholder (String, 可選): 顯示在輸入框中的提示文字。
• validation (Object, 可選): 定義此欄位的驗證規則。
• attributes (Object, 可選): 一個鍵值對物件，用於向最終渲染的 HTML 標籤添加自訂屬性，例如 data-* 或 aria-*。

具體欄位類型

• 文字輸入 (Text Inputs)
  • type: "text", "email", "tel", "url", "password"

    • 說明： 各種標準的單行文字輸入框。

    • 範例： JSON

      {
        "id": "customer_email",
        "type": "email",
        "label": "您的 Email",
        "placeholder": "user@example.com"
      }
      

  • type: "textarea"

    • 說明： 多行文字輸入區域。

    • 範例： JSON

      {
        "id": "customer_message",
        "type": "textarea",
        "label": "您的訊息",
        "attributes": { "rows": 5 }
      }
      

  • type: "hidden"

    • 說明： 隱藏欄位。在畫面上不可見，但能儲存並提交資料。

    • 範例： JSON

      {
        "id": "tracking_source",
        "type": "hidden",
        "defaultValue": "campaign_A"
      }
      

• 數字與範圍 (Number & Range)
  • type: "number"

    • 說明： 數字輸入框。可透過 attributes 新增 min, max, step 等屬性。

    • 範例： JSON

      {
        "id": "product_quantity",
        "type": "number",
        "label": "訂購數量",
        "defaultValue": 1,
        "attributes": { "min": 1, "max": 10 }
      }
      

  • type: "range"

    • 說明： 範圍滑塊。用於在一個連續區間內選擇數值。

    • 範例： JSON

      {
        "id": "satisfaction_rating",
        "type": "range",
        "label": "滿意度評分",
        "defaultValue": 8,
        "attributes": { "min": 0, "max": 10, "step": 1 }
      }
      

• 日期與時間 (Date & Time)
  • type: "date", "time", "datetime-local"

    • 說明： 由瀏覽器提供的原生日期、時間或日期時間選擇器，可避免格式錯誤。

    • 範例： JSON

      {
        "id": "appointment_date",
        "type": "date",
        "label": "預約日期",
        "attributes": { "min": "2025-01-01" }
      }
      

• 選擇項 (Choice Inputs)
  • type: "select", "radio"

    • 說明： 分別對應下拉選單和單選按鈕。這兩種類型都需要一個 options 屬性。

    • 專有屬性：

      • options (Array, 必需): 一個選項物件的陣列。每個物件包含 label (顯示文字) 和 value (實際值)。

    • 範例： JSON

      {
        "id": "inquiry_type",
        "type": "select",
        "label": "諮詢類型",
        "options": [
          { "label": "技術支援", "value": "tech_support" },
          { "label": "銷售問題", "value": "sales" }
        ]
      }
      

  • type: "checkbox"

    • 說明： 核取方塊。行為分為兩種：

      1. 單一核取方塊： 若無 options 屬性，其值為 true 或 false。
      2. 核取方塊群組： 若提供 options 屬性，則為一組可多選的選項，其值為一個包含所有選中項目 value 的陣列。

    • 範例 (單一)： JSON

      {
        "id": "agree_terms",
        "type": "checkbox",
        "label": "我同意服務條款"
      }
      

• 開關 (Toggles)
  • type: "switch"

    • 說明： checkbox 的一種視覺變體，提供現代化的「開/關」體驗，其值為 true 或 false。

    • 範例： JSON

      {
        "id": "enable_notifications",
        "type": "switch",
        "label": "啟用電子郵件通知",
        "defaultValue": true
      }
      

• 檔案上傳 (File Upload)
  • type: "file"

    • 說明： 檔案上傳欄位。可透過 attributes 新增 accept (限制檔案類型) 和 multiple (允許多檔上傳)。

    • 範例： JSON

      {
        "id": "resume_upload",
        "type": "file",
        "label": "上傳您的履歷",
        "attributes": { "accept": ".pdf,.doc,.docx" }
      }
      

3. 內容型元素 (Content Elements)

這些元素不收集資料，僅用於在表單中顯示靜態內容，引導和說明使用者。

• type: "heading" : 顯示一個標題。透過 level (1-6) 屬性來控制是 <h1> 到 <h6>。
• type: "paragraph" : 顯示一個文字段落。內容定義在 content 屬性中。
• type: "image" : 顯示一張圖片。透過 src 和 alt 屬性定義。
• type: "divider" : 顯示一條水平分隔線。

下一步

恭喜！您現在已經掌握了使用 layout 陣列來搭建任何靜態表單結構所需的所有知識。

然而，現代化的表單遠不止靜態展示。在下一章，我們將學習如何使用 conditions 屬性，為您的表單注入靈魂，讓它可以根據使用者的輸入動態地改變自己的樣貌和行為。