使用教程

交互表单：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. 布局：LayoutCells 引用 Id；空槽用 ""；ColumnFractionsPerRow 与行对齐；需要样式时填 CellsChrome 与 ShellPresentation。
6. 只输出合法 JSON，不要注释，不要编造文档未出现的 Widget 类型或字段。
7. 用户需求：【在此描述字段、是否必填、默认值、一行几列、选项列表等】

用户需求描述示例（只需写自然语言）：

标题「入职登记」，说明「请填写真实信息」。
一行一个字段：
第一行姓名，必填，无默认值。
第二行部门，下拉单选，选项：研发部(rd)、产品部(pm)、市场部(mkt)，必填。

一、JSON 整体构成

{
  "FormTitle": "",
  "FormDescription": "",
  "ConfirmButtonText": "提交",
  "CancelButtonText": "取消",

  "Fields": [ ],

  "Design": null
}

字段	类型	必填	说明
FormTitle	string	建议	表单标题
FormDescription	string	否	表单说明（显示在标题下方）
ConfirmButtonText	string	否	确认按钮文字，默认提交
CancelButtonText	string	否	取消按钮文字，默认取消
Fields	array	是	字段列表，见第二节
Design	object \| null	否	布局与样式，见第三节；null 为默认纵向排列

变量插值：FormTitle、FormDescription、按钮文案、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	否	字段补充说明
OutputMode	string	否	常用 "overwrite"
Param	object	是	参数与校验，见 2.3
ParamRef	object \| null	否	引用变量时填写，否则 null
InputWidgetOption 等	object	视类型	与 Widget 配套，见 2.2

2.2 控件类型（Widget）

Widget	控件	Param.Type	须额外配置
1	单行文本	string	InputWidgetOption: { "WidgetType": 0 }
2	密码	string	—
3	邮箱	string	建议加邮箱 Regex（见 2.4）
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	是	e.g. 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：提交的实际值

三、布局与样式（Design）

Design 只控制位置、列宽、间距、外层样式、响应式折行；控件类型与校验在 Fields 中定义。

当 Design 为 null 时按字段顺序纵向排列。需要多列、列宽比例或自定义样式时再填写 Design。

3.1 Design 结构一览

字段	说明
LayoutCells	二维数组：行 → 列 → 字段 Id
ColumnFractionsPerRow	与 LayoutCells 逐行对应的列宽权重（等同 CSS fr）
Gap	行、列间距（px）
CellsChrome	以字段 Id 为 key 的单元格外层样式
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"
  }
}

字段	说明
Padding / Margin	四边：Top、Right、Bottom、Left（数字，px）
BackgroundColor	单元格外层背景色
TitleFontWeight	"500" 或 "600"
TitleColor	字段标题颜色

推荐默认：

{
  "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 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	按钮文字颜色

四、完整示例

示例需求：一行一个字段；第一行「姓名」必填、无默认值；第二行「部门」下拉单选、必填。

{
  "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": 0 }
    }
  ],
  "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"
      }
    },
    "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 }
}