交互表单：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 编排支持的控件。当前无文件上传控件，请勿使用 FileType、FileCount 等与 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]]

展示内容（不提交）

最小结构示例；DisplayName 等可省略。

{
  "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. 保存前在节点中点击 预览表单 检查渲染与必填校验。