使用教程

互動表單：JSON 配置指南

前言

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

你是 GoInsight 互動表單 JSON 編排專家。請嚴格按《互動表單 JSON 編排說明書》產生 FormSchema JSON：
1. 根層級使用 FormTitle、FormDescription、ConfirmButtonText、CancelButtonText、CancelButtonConfig、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. 版面配置：LayoutCells 參考 Id；空白佔位符用 ""；ColumnFractionsPerRow 與列對齊；需要樣式時填 CellsChrome 與 ShellPresentation。
6. 只輸出合法 JSON，不要註解，不要編造文件未出現的 Widget 類型或欄位。
7. 使用者需求：【在此描述欄位、是否必填、預設值、說明文案與 tip/placeholder、多行高度、取消二次確認、一列幾欄、選項清單等】

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

標題「到職登記」，說明「請填寫真實資訊」。
取消按鈕需二次確認，彈窗標題「是否確認放棄？」，說明「放棄後不可再提交」。
一列一個欄位：
第一列姓名，單行文字，必填，說明「請填寫真實姓名」，展示為 placeholder。
第二列備註，多行文字，高度 66，說明用問號 tip。
第三列部門，下拉式單選，選項：研發部(rd)、產品部(pm)、行銷部(mkt)，必填。

一、JSON 整體構成

{
  "FormTitle": "",
  "FormDescription": "",
  "ConfirmButtonText": "提交",
  "CancelButtonText": "取消",
  "CancelButtonConfig": {
    "Enabled": true,
    "Title": "",
    "Description": ""
  },
  "Fields": [],
  "Design": null
}

欄位	類型	必填	說明
FormTitle	string	建議	表單標題
FormDescription	string	否	表單說明（顯示在標題下方）
ConfirmButtonText	string	否	確認按鈕文字，預設「提交」
CancelButtonText	string	否	取消按鈕文字，預設「取消」
CancelButtonConfig	object	否	次要按鈕取消前二次確認，見 1.1
Fields	array	是	欄位清單，見第二節
Design	object \| null	否	版面配置與樣式，見第三節；null 為預設縱向排列

1.1 CancelButtonConfig（取消二次確認）

欄位	類型	預設	說明
Enabled	boolean	true	是否在點擊次要按鈕後彈出二次確認；false 則直接進入取消分支
Title	string	系統預設文案	確認彈窗標題；僅 Enabled 為 true 時生效
Description	string	系統預設文案	確認彈窗說明；僅 Enabled 為 true 時生效

省略或未設定時，按 Enabled: true 處理，彈窗使用系統預設文案（與歷史行為一致）。

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

命名規則：

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

二、欄位（Fields）

2.1 欄位物件結構

欄位	類型	必填	說明
Id	string	是	唯一識別碼，供版面配置參考
Widget	int	是	控制項類型，見 2.2
DisplayName	string	建議	介面上顯示的標籤
DisplayDescription	string	否	欄位說明文案；對單行/多行文字、密碼、信箱生效，展示樣式見 2.6
OutputMode	string	否	常用 "overwrite"
Param	object	是	參數與驗證，見 2.3
ParamRef	object \| null	否	參考變數時填寫，否則 null
InputWidgetOption 等	object	視類型	與 Widget 配套，見 2.2、2.6

2.2 控制項類型（Widget）

Widget	控制項	Param.Type	須額外設定
1	單行 / 多行文字	string	InputWidgetOption：WidgetType 0=單行、1=多行；可配 TipShowInPlaceholder、多行可配 InputHeight（見 2.6）
2	密碼	string	InputWidgetOption：可配 TipShowInPlaceholder（見 2.6）
3	信箱	string	建議加信箱 Regex（見 2.4）；InputWidgetOption：可配 TipShowInPlaceholder（見 2.6）
4	日期	string	DateWidgetOption: { "WidgetInputType": 0 }
5	時間	string	TimeWidgetOption: { "WidgetInputType": 0 }
6	數字	number	範圍用 MinNum / MaxNum
7	開關	bool	BoolWidgetOption: { "WidgetType": 0 }
8	單選（下拉式）	string	EnumInputs + SingleSelectWidgetOption: { "WidgetType": 0 }
9	多選	string-array	EnumInputs + MultiSelectWidgetOption: { "WidgetType": 1 }
10	說明文字（富文字）	string	不收集輸入；Param.Name 填 ""，內文寫在 Param.Description

當前 JSON 編排僅支援上表控制項類型，請勿使用未列出的 Widget 取值。

2.3 Param（參數）

欄位	類型	必填	說明
Name	string	視控制項	提交參數名；說明區塊（Widget 10）填 ""
Description	string	否	參數說明；Widget 10 時寫展示內容（支援 Markdown/HTML）
Type	string	是	string、number、bool、string-array 等
Required	boolean	否	是否必填，預設 false
Default	string	否	預設值，統一用字串；複雜值用 JSON 字串
Protected	boolean	否	是否保護（如密碼）
WfParamConstraint	object	否	驗證規則，見 2.4
EnumInputs	array	否	單選/多選選項，見 2.5

預設值規則：

有輸入框的欄位：預設值會預填在控制項中。
使用者未填寫時：string 為空字串；其他類型視為無值。
僅在 Required 為 false 且無有效輸入時，才使用 Default。

參考變數（ParamRef）：

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

不參考時寫 null。

2.4 驗證（WfParamConstraint）

欄位	適用於	說明
MinNum / MaxNum	number	數值最小/最大
MinLen / MaxLen	string、number	長度最小/最大
MinItems / MaxItems	陣列（多選）	選項個數最小/最大
Regex	string、number	正規表示式
FileType	file	檔案類型
FileCount	file-array	檔案數量上限

信箱範例：

"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：提交的實際值

2.6 文字類說明與多行高度（InputWidgetOption）

適用於 Widget 1（單行/多行文字）、2（密碼）、3（信箱）。

欄位	類型	適用	說明
WidgetType	int	Widget 1	0 = 單行；1 = 多行
TipShowInPlaceholder	boolean	Widget 1/2/3	說明文案展示方式。true = 輸入框內 placeholder；省略或 false = 顯示名稱旁問號 tip。文案取自 DisplayDescription
InputHeight	number	Widget 1 且 WidgetType: 1	多行輸入框高度，單位 px；合法區間 [34, 500]，預設 84。單行、密碼、信箱及其他控制項忽略

單行 + placeholder 範例：

"DisplayDescription": "請填寫真實姓名",
"InputWidgetOption": {
  "WidgetType": 0,
  "TipShowInPlaceholder": true
}

多行 + 問號 tip + 自訂高度範例：

"DisplayDescription": "可填寫補充說明",
"InputWidgetOption": {
  "WidgetType": 1,
  "InputHeight": 66
}

高度雙寫同步：多行高度同時存在於：

欄位側：InputWidgetOption.InputHeight
版面配置側：Design.CellsChrome[<欄位Id>].InputHeight

兩側會同步更新。JSON 編排時若同時寫 Fields 與 Design.CellsChrome，同一欄位的 InputHeight 必須一致；Design 為 null 時僅寫欄位側即可。

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

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

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

3.1 Design 結構一覽

欄位	說明
LayoutCells	二維陣列：列 → 欄 → 欄位 Id
ColumnFractionsPerRow	與 LayoutCells 逐列對應的欄寬權重（等同 CSS fr）
Gap	列、欄間距（px）
CellsChrome	以欄位 Id 為 key 的儲存格外層樣式（含多行 InputHeight）
CustomSizeWidthRules	按容器寬度限制每列最大欄數（響應式換行）
ShellPresentation	標題區（HeadingChrome）與底部欄（FooterChrome）樣式

3.2 LayoutCells

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

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

3.3 ColumnFractionsPerRow

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

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

3.4 Gap

列、欄間距（px）。

3.5 CellsChrome

"CellsChrome": {
  "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",
    "InputHeight": 84
  }
}

欄位	說明
Padding / Margin	四邊：Top、Right、Bottom、Left（數字，px）
BackgroundColor	儲存格外層背景色
TitleFontWeight	"500" 或 "600"
TitleColor	欄位標題顏色
InputHeight	多行文字輸入高度（px），區間 [34, 500]，預設 84；僅多行生效，並與欄位側 InputWidgetOption.InputHeight 同步

推薦預設：

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

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

3.6 CustomSizeWidthRules

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

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

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

3.7 ShellPresentation

HeadingChrome（標題與說明區域）：

欄位	說明
Padding / Margin / BackgroundColor	標題區外層
TitleFontWeight / TitleColor	標題文字
TitleTextAlign	left / center / right

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

欄位	說明
Padding / Margin / BackgroundColor	底部欄外層
PrimaryButtonBackgroundColor	確認按鈕背景色
SecondaryButtonColor	取消按鈕背景色
PrimaryButtonTextColor / SecondaryButtonTextColor	按鈕文字顏色

四、完整範例

需求：一列一個欄位；姓名為單行、必填、說明展示為 placeholder；備註為多行、高度 66、說明為問號 tip；開啟取消二次確認。

{
  "FormTitle": "歡迎你加入我們！",
  "FormDescription": "請簡要填寫你的個人資訊。",
  "ConfirmButtonText": "提交",
  "CancelButtonText": "取消",
  "CancelButtonConfig": {
    "Enabled": true,
    "Title": "是否確認放棄本次表單填寫？",
    "Description": "放棄表單填寫後將不可再次提交"
  },
  "Fields": [
    {
      "Id": "clientField_1",
      "Widget": 1,
      "OutputMode": "overwrite",
      "Param": {
        "Name": "name",
        "Description": "",
        "Type": "string",
        "Required": true,
        "Default": ""
      },
      "ParamRef": null,
      "DisplayName": "姓名",
      "DisplayDescription": "請填寫真實姓名",
      "InputWidgetOption": {
        "WidgetType": 0,
        "TipShowInPlaceholder": true
      }
    },
    {
      "Id": "clientField_2",
      "Widget": 1,
      "OutputMode": "overwrite",
      "Param": {
        "Name": "remark",
        "Description": "",
        "Type": "string",
        "Required": false,
        "Default": ""
      },
      "ParamRef": null,
      "DisplayName": "備註",
      "DisplayDescription": "可填寫補充說明",
      "InputWidgetOption": {
        "WidgetType": 1,
        "InputHeight": 66
      }
    }
  ],
  "Design": {
    "LayoutCells": [
      ["clientField_1"],
      ["clientField_2"]
    ],
    "ColumnFractionsPerRow": [
      [1],
      [1]
    ],
    "Gap": 8,
    "CellsChrome": {
      "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",
        "InputHeight": 66
      }
    },
    "CustomSizeWidthRules": [
      { "MinWidthPx": 780, "MaxCols": 6, "Breakpoint": "lg" },
      { "MinWidthPx": 500, "MaxCols": 3, "Breakpoint": "md" },
      { "MinWidthPx": 0, "MaxCols": 1, "Breakpoint": "sm" }
    ],
    "ShellPresentation": {
      "HeadingChrome": {
        "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"
      },
      "FooterChrome": {
        "Padding": { "Top": 12, "Right": 16, "Bottom": 12, "Left": 16 },
        "Margin": { "Top": 12, "Right": 0, "Bottom": 0, "Left": 0 },
        "BackgroundColor": "#FFFFFF",
        "PrimaryButtonBackgroundColor": "#4584EF",
        "SecondaryButtonColor": "#FFFFFF",
        "PrimaryButtonTextColor": "#FFFFFF",
        "SecondaryButtonTextColor": "#111827"
      }
    }
  }
}

4.1 常用片段

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

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

說明文字（不提交）

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

數字帶範圍

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

關閉取消二次確認

"CancelButtonConfig": {
  "Enabled": false
}

信箱 + 問號 tip 說明

{
  "Id": "clientField_mail",
  "Widget": 3,
  "OutputMode": "overwrite",
  "Param": {
    "Name": "mail",
    "Description": "",
    "Type": "string",
    "Required": true,
    "Default": "",
    "WfParamConstraint": {
      "Regex": "[\\w!#$%&'*+/=?^`{|}~-]+(?:\\.[\\w!#$%&'*+/=?^`{|}~-]+)*@(?:\\w(?:[\\w-]*\\w)?\\.)+\\w(?:[\\w-]*\\w)?"
    }
  },
  "DisplayName": "信箱",
  "DisplayDescription": "請使用公司信箱",
  "InputWidgetOption": {
    "TipShowInPlaceholder": false
  }
}

密碼 + placeholder 說明

{
  "Id": "clientField_pwd",
  "Widget": 2,
  "OutputMode": "overwrite",
  "Param": {
    "Name": "password",
    "Description": "",
    "Type": "string",
    "Required": true,
    "Protected": true,
    "Default": ""
  },
  "DisplayName": "密碼",
  "DisplayDescription": "至少 8 位",
  "InputWidgetOption": {
    "TipShowInPlaceholder": true
  }
}

五、編寫時注意

Fields 不能為空；每個可填項要有唯一 Id 和非空 Param.Name。
Widget 與 Param.Type、EnumInputs、*WidgetOption 要相符。
文字類（單行/多行、密碼、信箱）的說明文案寫在 DisplayDescription；用 TipShowInPlaceholder 選擇 tip 或 placeholder。
多行高度：InputWidgetOption.InputHeight 與 Design.CellsChrome[<Id>].InputHeight 須一致；勿給非多行欄位配高度。
使用 Design 時，LayoutCells 裡的每個 Id 都必須在 Fields 中存在。
ColumnFractionsPerRow 與 LayoutCells 列數欄數一致。
空白佔位符必須寫 ""，不能省略。
輸出必須是合法 JSON；鍵名大小寫與本文一致。
儲存前在節點中點擊 預覽表單 檢查渲染與必填驗證。

更新於: 2026-08-05

這個頁面有用嗎？

討論

發佈評論取消回覆

產品相關的問題？聯繫我們的支援團隊以獲取快速解決方案>

加載中...

查無結果