互動表單：JSON 配置指南

前言

在 互動表單 節點選擇 JSON 編排 後，可根據此文件提供的規則自訂表單的 JSON schema。考量到規則具有一定的複雜度，建議您可將以下整段與下述規則一併提供給 AI：

你是 GoInsight 互動表單 JSON 編排專家。請嚴格按《互動表單：JSON 編排說明書》產生 FormSchema JSON：
1. 根層級使用 FormTitle、FormDescription、ConfirmButtonText、CancelButtonText、Fields、Design（PascalCase）。
2. 每個可填欄位必須有唯一 Id，Param.Name 為英文提交鍵，DisplayName 為中文標籤。
3. 控制項必須用 Widget 列舉（1 文字、2 密碼、3 信箱、4 日期、5 時間、6 數字、7 布林、8 單選、9 多選、10 展示內容），並配上文件要求的 *WidgetOption 與 EnumInputs。
4. 驗證使用 Param.WfParamConstraint，不要使用 validationRules 陣列。
5. 版面配置：Design.CellsLayout 參考欄位 Id；空白佔位符用 ""；ColumnFractionsPerRow 與列對齊；間距寫在 FormLayoutGlobal.Gap；樣式用 CellsStyle 與 FormShellStyle。
6. 只輸出合法 JSON，不要註解，不要編造文件未出現的 Widget 類型或欄位；EnumInputs 只寫 Name 與 Value，不要寫視覺化編輯器匯出的 chosen、selected 等欄位。
7. 使用者需求：【在此描述欄位、是否必填、預設值、一列幾欄、選項清單等】

使用者需求描述範例 （只需寫自然語言）：

標題「到職登記」，說明「請填寫真實資訊」。
一列一個欄位：第一列姓名，必填，無預設值。
第二列部門，下拉式單選，選項：研發部(rd)、產品部(pm)、行銷部(mkt)，必填。

一、JSON 整體構成

{
  "FormTitle": "",
  "FormDescription": "",
  "ConfirmButtonText": "提交",
  "CancelButtonText": "取消",
  "Fields": [ ],
  "Design": null
}

變數插值：FormTitle、FormDescription、按鈕文案、Param.Default 等字串中可寫 {{#節點ID.參數名#}}，執行時替換為工作流程變數。

命名規則：

• 所有鍵名使用 PascalCase（如 FormTitle，不要寫成 formTitle）。
• 每個欄位必須有唯一 Id（如 clientField_1）；Param.Name 為提交後的參數名（英文，如 userName）。
• 使用 Design 時，CellsLayout 裡填寫的非空字串必須與某個欄位的 Id 一致。

二、欄位（Fields）

2.1 欄位物件結構

選用欄位說明：Widget 10（展示內容）的最小結構只需 Id、Widget、Param；DisplayName、DisplayDescription、OutputMode、ParamRef 等可省略。Widget 1–9 建議寫全 DisplayName、OutputMode: "overwrite"、ParamRef: null（未參考變數時）。

2.2 控制項類型（Widget）

當前 JSON 編排 僅支援 Widget 1–10（見上表），請勿使用未列出的 Widget 取值，也不要自行新增檔案上傳等上表未提供的控制項。

Param.Type 與 Widget 對應關係（JSON 編排中實際會用到的類型）：

伺服器端參數體系還支援 object、file、file-array 等類型，但 當前互動表單 JSON 編排不提供對應控制項；請勿為 JSON 表單編造這些 Widget / Param.Type 組合。

2.2.1 WidgetType 子類型

部分控制項透過 *WidgetOption.WidgetType 區分介面形態：

2.3 Param（參數）

預設值規則：

• 有輸入方塊的欄位：預設值會預填在控制項中。
• 使用者未填寫時：string 為空字串；其他類型視為無值。
• 僅在 Required 為 false 且無有效輸入時，才使用 Default。
• bool 類型： Default 寫 "true" 或 "false" 字串，例如 "Default": "false"。
• Widget 10（展示內容）例外： Param.Default 為頁面展示的內文，不是使用者輸入控制項的預設值；不參與上述第三條邏輯。

參考變數（ParamRef）：

"ParamRef": {
  "NodeId": "節點ID",
  "Name": "參數名"
}

不參考時寫 null。

2.4 驗證（WfParamConstraint）

下列約束用於 JSON 編排支援的控制項。當前無檔案上傳控制項，請勿使用與 file 相關的約束。

信箱範例：

"WfParamConstraint": {
  "Regex": "[\\w!#$%&'*+/=?^`{|}~-]+(?:\\.[\\w!#$%&'*+/=?^`{|}~-]+)*@(?:\\w(?:[\\w-]*\\w)?\\.)+\\w(?:[\\w-]*\\w)?"
}

2.5 選項（EnumInputs）

用於 Widget 8 和 9：

"EnumInputs": [
  { "Name": "研發部", "Value": "rd" },
  { "Name": "產品部", "Value": "pm" }
]

• Name：介面顯示文字
• Value：提交的實際值

只寫上述兩個欄位。若從視覺化編排複製 JSON，請手動刪除 chosen、selected 等編輯器內部欄位，不要寫入最終 schema。

三、版面配置與樣式（Design）

Design 只控制位置、欄寬比例、間距、外層樣式、響應式換行。控制項類型與驗證在 Fields 中定義。

Design 為 null 時按欄位順序縱向排列。需要多欄、欄寬比例或自訂樣式時再填寫 Design。

3.1 Design 結構一覽

3.2 CellsLayout

"CellsLayout": [
  ["clientField_1"],
  ["clientField_2", "clientField_3"],
  ["clientField_4", ""]
]

• 外層陣列 = 列；內層陣列 = 欄。
• 非空值為欄位 Id。
• "" = 空白佔位符；必須保留，不能刪除，否則欄寬會亂。
• 標題、底部按鈕不在此陣列中。

3.3 ColumnFractionsPerRow

"ColumnFractionsPerRow": [
  [1],
  [1, 1],
  [2, 1, 1]
]

• 與 CellsLayout 列數、欄數一一對應。
• 不一致或缺失時，該列改為等寬欄。
• 權重只影響同一列內的相對寬度。

3.4 FormLayoutGlobal

"FormLayoutGlobal": {
  "Gap": 8,
  "FormWidthPercent": 100
}

3.5 CellsStyle

"CellsStyle": {
  "clientField_1": {
    "Padding": { "Top": 8, "Right": 8, "Bottom": 8, "Left": 8 },
    "Margin": { "Top": 0, "Right": 0, "Bottom": 0, "Left": 0 },
    "BackgroundColor": "#FFFFFF",
    "TitleFontWeight": "500",
    "TitleColor": "#464F60"
  }
}

推薦預設：

{
  "Padding": { "Top": 8, "Right": 8, "Bottom": 8, "Left": 8 },
  "Margin": { "Top": 0, "Right": 0, "Bottom": 0, "Left": 0 },
  "BackgroundColor": "#FFFFFF",
  "TitleFontWeight": "500",
  "TitleColor": "#464f60"
}

樣式依欄位 Id 設定，不要按「第幾列第幾欄」設定。

3.6 AdaptiveRules

按表單容器寬度（不是整個瀏覽器視窗）決定一列最多幾欄；超出時由左至右拆成多列，並同步拆分 ColumnFractionsPerRow。

"AdaptiveRules": [
  { "MinWidthPx": 780, "MaxCols": 6, "Size": "lg" },
  { "MinWidthPx": 500, "MaxCols": 3, "Size": "md" },
  { "MinWidthPx": 0, "MaxCols": 1, "Size": "sm" }
]

規則：按 MinWidthPx 由大到小比對，取第一條滿足容器寬度 >= MinWidthPx 的規則，使用其 MaxCols。

3.7 FormShellStyle

HeadingStyle（標題與說明區域）：

FooterStyle（確認、取消按鈕區域）：

四、完整範例

需求：一列一個欄位；第一列「姓名」必填、無預設值；第二列「部門」單選、必填。

{
  "FormTitle": "歡迎你加入我們！",
  "FormDescription": "請簡要填寫你的個人資訊。",
  "ConfirmButtonText": "提交",
  "CancelButtonText": "取消",
  "Fields": [
    {
      "Id": "clientField_1",
      "Widget": 1,
      "OutputMode": "overwrite",
      "Param": {
        "Name": "name",
        "Description": "",
        "Type": "string",
        "Required": true,
        "Default": ""
      },
      "ParamRef": null,
      "DisplayName": "姓名",
      "DisplayDescription": "",
      "InputWidgetOption": { "WidgetType": 0 }
    },
    {
      "Id": "clientField_2",
      "Widget": 8,
      "OutputMode": "overwrite",
      "Param": {
        "Name": "department",
        "Description": "",
        "Type": "string",
        "Required": true,
        "Default": "",
        "EnumInputs": [
          { "Name": "研發部", "Value": "rd" },
          { "Name": "產品部", "Value": "pm" },
          { "Name": "行銷部", "Value": "mkt" }
        ]
      },
      "ParamRef": null,
      "DisplayName": "部門",
      "DisplayDescription": "",
      "SingleSelectWidgetOption": { "WidgetType": 1 }
    }
  ],
  "Design": {
    "CellsLayout": [
      ["clientField_1"],
      ["clientField_2"]
    ],
    "ColumnFractionsPerRow": [
      [1],
      [1]
    ],
    "FormLayoutGlobal": {
      "Gap": 8,
      "FormWidthPercent": 100
    },
    "CellsStyle": {
      "clientField_1": {
        "Padding": { "Top": 8, "Right": 8, "Bottom": 8, "Left": 8 },
        "Margin": { "Top": 0, "Right": 0, "Bottom": 0, "Left": 0 },
        "BackgroundColor": "#FFFFFF",
        "TitleFontWeight": "500",
        "TitleColor": "#464F60"
      },
      "clientField_2": {
        "Padding": { "Top": 8, "Right": 8, "Bottom": 8, "Left": 8 },
        "Margin": { "Top": 0, "Right": 0, "Bottom": 0, "Left": 0 },
        "BackgroundColor": "#FFFFFF",
        "TitleFontWeight": "500",
        "TitleColor": "#464F60"
      }
    },
    "AdaptiveRules": [
      { "MinWidthPx": 780, "MaxCols": 6, "Size": "lg" },
      { "MinWidthPx": 500, "MaxCols": 3, "Size": "md" },
      { "MinWidthPx": 0, "MaxCols": 1, "Size": "sm" }
    ],
    "FormShellStyle": {
      "HeadingStyle": {
        "Padding": { "Top": 8, "Right": 8, "Bottom": 8, "Left": 8 },
        "Margin": { "Top": 0, "Right": 0, "Bottom": 0, "Left": 0 },
        "BackgroundColor": "#FFFFFF",
        "TitleFontWeight": "600",
        "TitleColor": "#1f2937",
        "TitleTextAlign": "left"
      },
      "FooterStyle": {
        "Padding": { "Top": 12, "Right": 16, "Bottom": 12, "Left": 16 },
        "Margin": { "Top": 12, "Right": 0, "Bottom": 0, "Left": 0 },
        "BackgroundColor": "#FFFFFF",
        "PrimaryButtonBackgroundColor": "#4584EF",
        "SecondaryButtonBackgroundColor": "#FFFFFF",
        "PrimaryButtonTextColor": "#FFFFFF",
        "SecondaryButtonTextColor": "#111827"
      }
    }
  }
}

4.1 常用程式碼片段

同一列三欄（1:1:1）

"CellsLayout": [["clientField_a", "clientField_b", "clientField_c"]],
"ColumnFractionsPerRow": [[1, 1, 1]]

展示內容（不提交）

{
  "Id": "clientField_intro",
  "Widget": 10,
  "Param": {
    "Name": "",
    "Description": "",
    "Type": "string",
    "Required": false,
    "Default": "請如實填寫以下資訊。"
  }
}

數字帶範圍

"Widget": 6,
"Param": {
  "Name": "age",
  "Type": "number",
  "Required": true,
  "Default": "",
  "WfParamConstraint": { "MinNum": 1, "MaxNum": 120 }
}

五、編寫時注意

1. Fields 不能為空；每個可收集輸入的欄位要有唯一 Id、非空 Param.Name 和 "OutputMode": "overwrite"；Widget 10 的 Param.Name 填 "" 且不寫 OutputMode。
2. Widget 與 Param.Type、EnumInputs、*WidgetOption 要匹配；單選/多選/文字/布林按 2.2.1 選擇正確的 WidgetType。
3. 使用 Design 時，CellsLayout 裡的每個 Id 都必須在 Fields 中存在。
4. ColumnFractionsPerRow 與 CellsLayout 列數欄數一致。
5. 空白佔位符必須寫 ""，不能省略。
6. 輸出必須是合法 JSON；鍵名大小寫與本文一致。
7. EnumInputs 每項僅保留 Name、Value；不要複製視覺化匯出裡的 chosen、selected 等欄位。
8. 僅使用 Widget 1–10 及本文列出的 Param.Type；不要編造檔案上傳等未提供的控制項類型。
9. 根層級只需 FormTitle、FormDescription、ConfirmButtonText、CancelButtonText、Fields、Design；不要寫入執行時欄位（如 InvokerName、InvokerToolName 等）。
10. 儲存前在節點中點擊 預覽表單 檢查渲染與必填驗證。