动态配置表单

动态表单通过一个 JSON 文件描述节点的参数面板，渲染引擎根据配置自动生成对应的表单 UI。本文档说明如何编写这份配置文件。表单文件在 Bundle 中的存放位置与加载方式见 Bundle 节点开发。

一、文件结构

json

{
  "triggerPanel": { ... },  // 可选，触发面板提示信息
  "properties": [ ... ]     // 必填，字段定义列表
}

绝大多数节点只需关注 properties。

二、字段定义（properties 子项）

每个字段是 properties 数组中的一个对象，可配置的属性如下：

属性	类型	必填	说明
`name`	String	✅	字段唯一标识，同级不可重复，使用 camelCase
`label`	String		表单项标签文字
`uiComponent`	String	✅	渲染组件类型（见第三章）
`placeholder`	String		输入框占位提示
`hint`	String		字段下方小字说明
`description`	String		附加描述
`required`	Boolean		是否必填，默认 `false`
`default`	any		字段默认值
`expression`	Boolean		是否支持切换表达式模式（）
`options`	Array		选项列表或子字段定义（见各组件说明）
`typeOptions`	Object		组件专有配置（见各组件说明）
`displayOptions`	Object		条件显示规则（见第四章）
`rules`	Array		校验规则（见第五章）
`emptyText`	String		列表为空时的提示（FixedCollection 使用）
`addText`	String		添加按钮文字（FixedCollection 使用）

三、uiComponent 组件类型

3.1 基础输入类

`Input` — 单行文本

json

{
  "name": "host",
  "label": "主机地址",
  "uiComponent": "Input",
  "placeholder": "请输入主机地址",
  "required": true,
  "typeOptions": {
    "maxlength": 255
  }
}

typeOptions 可选项：

属性	说明
`maxlength`	最大输入字符数
`type`	设为 `"textarea"` 切换为多行文本域
`rows`	文本域行数，`type=textarea` 时有效

`Password` — 密码输入

json

{
  "name": "password",
  "label": "密码",
  "uiComponent": "Password",
  "placeholder": "请输入密码",
  "required": true
}

`InputNumber` — 数字输入

json

{
  "name": "port",
  "label": "端口",
  "uiComponent": "InputNumber",
  "default": 3306,
  "typeOptions": {
    "min": 1,
    "max": 65535,
    "style": "width:200px"
  }
}

typeOptions 可选项：min、max、step、precision、controls、style

`Switch` — 开关

json

{
  "name": "enableSsl",
  "label": "启用 SSL",
  "uiComponent": "Switch",
  "default": false
}

`DatePicker` / `TimePicker` — 日期/时间选择

json

{ "name": "expireAt", "label": "过期时间", "uiComponent": "DatePicker" }

3.2 选择类

`Select` — 下拉选择

静态选项：

json

{
  "name": "charset",
  "label": "字符集",
  "uiComponent": "Select",
  "options": [
    { "label": "utf8mb4", "value": "utf8mb4" },
    { "label": "utf8",    "value": "utf8" }
  ]
}

远程动态加载：

json

{
  "name": "database",
  "label": "数据库",
  "uiComponent": "Select",
  "typeOptions": {
    "loadOptions": {
      "method": "getDatabases",
      "provider": "credentials",
      "trigger": "auto",
      "dependsOn": ["host", "port", "username", "password"],
      "credentialsName": "mysql"
    }
  }
}

loadOptions 字段说明：

属性	说明
`method`	后端调用的方法名
`provider`	`"bundle"`（默认）或 `"credentials"`
`trigger`	`"auto"` 依赖满足后自动加载，省略则手动点刷新
`dependsOn`	依赖字段 name 列表，全部有值才触发
`credentialsName`	`provider=credentials` 时必填

`CheckboxGroup` — 复选框组（多选，值为数组）

json

{
  "name": "methods",
  "label": "允许方法",
  "uiComponent": "CheckboxGroup",
  "options": [
    { "label": "GET",  "value": "GET" },
    { "label": "POST", "value": "POST" }
  ]
}

`RadioButtonGroup` — 单选按钮组（按钮样式）

json

{
  "name": "format",
  "label": "响应格式",
  "uiComponent": "RadioButtonGroup",
  "options": [
    { "label": "JSON", "value": "json" },
    { "label": "XML",  "value": "xml" }
  ],
  "typeOptions": { "size": "small" }
}

`RadioGroup` — 单选组（Radio 样式）

json

{
  "name": "mode",
  "label": "模式",
  "uiComponent": "RadioGroup",
  "options": [
    { "label": "自动", "value": "auto" },
    { "label": "手动", "value": "manual" }
  ]
}

`CredentialSelect` — 凭证选择器

json

{
  "name": "credential",
  "label": "数据库凭证",
  "uiComponent": "CredentialSelect",
  "required": true,
  "typeOptions": {
    "credentialsName": "mysql"
  }
}

typeOptions.credentialsName 为凭证类型名，必填。

3.3 编辑器类

组件	适用场景	变量语法
`CodeEditor`	脚本、模板等多语言内容，自动换行
`Editor`	通用多语言内容，可动态切换语言
`JsEditor`	JavaScript 脚本
`JsonEditor`	JSON 数据，token 级变量高亮
`JsonExpressionInput`	JSON 表达式（存储带 `=` 前缀）
`ExpressionInput`	模板表达式（存储带 `=` 前缀）
`BooleanExpressionInput`	逻辑条件（SPEL 语法）	—
`SqlEditor`	SQL 查询语句	`#{变量}`

编辑器共同 typeOptions：

属性	说明
`height`	编辑器高度，如 `"200px"`
`lang`	语言（CodeEditor/Editor 适用），如 `"json"`、`"python"`
`style`	外层内联样式，如 `"margin-top:10px"`

示例（SQL 编辑器）：

json

{
  "name": "query",
  "label": "查询语句",
  "uiComponent": "SqlEditor",
  "typeOptions": { "height": "200px" }
}

3.4 集合/结构类

`Fixed` — 固定字段组（值为 Object，字段不可增删）

适用于一组强相关的嵌套配置，如 SSL 设置、CORS 配置。

json

{
  "name": "ssl",
  "label": "SSL 配置",
  "uiComponent": "Fixed",
  "options": [
    { "name": "enabled",   "label": "启用 SSL",    "uiComponent": "Switch", "default": false },
    { "name": "ca",        "label": "CA 证书",     "uiComponent": "CodeEditor",
      "typeOptions": { "lang": "text", "height": "100px" },
      "displayOptions": { "show": { "enabled": [true] } }
    }
  ]
}

`Collection` — 动态可选字段集合（值为 Object，按需添加字段）

适用于可选附加参数，用户从列表中自由挑选需要的字段。

json

{
  "name": "options",
  "label": "高级配置",
  "uiComponent": "Collection",
  "placeholder": "添加高级配置",
  "options": [
    { "name": "timeout",  "label": "超时（秒）",  "uiComponent": "InputNumber" },
    { "name": "retryCount","label": "重试次数",   "uiComponent": "InputNumber" }
  ]
}

`FixedCollection` — 固定结构多行列表（值为 Array，可增删排序）

适用于请求头列表、映射规则、参数列表等。

json

{
  "name": "headers",
  "label": "请求头",
  "uiComponent": "FixedCollection",
  "emptyText": "暂无请求头",
  "addText": "添加请求头",
  "options": [
    { "name": "name",  "label": "名称", "uiComponent": "Input",    "required": true },
    { "name": "value", "label": "值",   "uiComponent": "Input",    "required": true, "expression": true }
  ]
}

`RelationCollection` — 关系列表（值为 Array，联动画布连接线）

适用于定义节点输出分支，结构与 FixedCollection 相同。

json

{
  "name": "relations",
  "label": "输出分支",
  "uiComponent": "RelationCollection",
  "addText": "添加输出分支",
  "options": [
    { "name": "name",        "label": "分支名称", "uiComponent": "Input", "required": true },
    { "name": "description", "label": "描述",     "uiComponent": "Input" }
  ]
}

四、条件显示（displayOptions）

控制字段根据同级其他字段的值动态显示或隐藏。

json

"displayOptions": {
  "show": {
    "fieldName": ["value1", "value2"]   // 值在列表中时 → 显示
  },
  "hide": {
    "fieldName": ["value3"]             // 值在列表中时 → 隐藏
  }
}

规则：

show / hide 可同时存在
同一对象内多个字段为与逻辑（全部满足才生效）
数组内多个值为或逻辑（任一匹配即可）
引用的字段必须是同层级已定义的 name

示例： 仅当 enableSecret 为 true 时显示密钥字段：

json

{
  "name": "appSecret",
  "label": "App Secret",
  "uiComponent": "Password",
  "required": true,
  "displayOptions": {
    "show": { "enableSecret": [true] }
  }
}

五、校验规则（rules）

json

"rules": [
  { "required": true, "message": "此项必填" },
  { "format": "path" },             // 内置格式：路径（必须以 / 开头）
  { "type": "json" },               // 内置类型：合法 JSON 字符串
  { "min": 1, "max": 100 },         // 数值或长度范围
  { "pattern": "^[a-z]+$", "message": "只允许小写字母" }
]

简单必填也可直接在字段上用 "required": true，无需写 rules。

六、完整示例

示例 1：飞书凭证（含条件显示）

json

{
  "properties": [
    {
      "name": "appId",
      "label": "App ID",
      "uiComponent": "Input",
      "placeholder": "请输入飞书应用的 App ID",
      "required": true,
      "typeOptions": { "maxlength": 128 }
    },
    {
      "name": "enableSecret",
      "label": "是否开启密钥",
      "uiComponent": "Switch",
      "default": false
    },
    {
      "name": "appSecret",
      "label": "App Secret",
      "uiComponent": "Password",
      "placeholder": "请输入飞书应用的 App Secret",
      "required": true,
      "displayOptions": {
        "show": { "enableSecret": [true] }
      }
    }
  ]
}

示例 2：HTTP 请求头列表（FixedCollection）

json

{
  "properties": [
    {
      "name": "headers",
      "label": "请求头",
      "uiComponent": "FixedCollection",
      "emptyText": "暂无请求头",
      "addText": "添加请求头",
      "options": [
        {
          "name": "name",
          "label": "名称",
          "uiComponent": "Input",
          "placeholder": "如 Content-Type",
          "required": true,
          "typeOptions": { "maxlength": 128 }
        },
        {
          "name": "key",
          "label": "值",
          "uiComponent": "Input",
          "required": true,
          "expression": true,
          "typeOptions": { "maxlength": 1024 }
        }
      ]
    }
  ]
}

示例 3：MySQL 连接（远程加载 + Collection 嵌套）

json

{
  "properties": [
    { "name": "host",     "label": "主机地址", "uiComponent": "Input",       "required": true },
    { "name": "port",     "label": "端口",     "uiComponent": "InputNumber", "required": true, "default": 3306,
      "typeOptions": { "min": 1, "max": 65535, "style": "width:200px" } },
    { "name": "username", "label": "用户名",   "uiComponent": "Input",       "required": true },
    { "name": "password", "label": "密码",     "uiComponent": "Password",    "required": true },
    {
      "name": "database",
      "label": "数据库名称",
      "uiComponent": "Select",
      "placeholder": "请选择数据库",
      "typeOptions": {
        "loadOptions": {
          "method": "getDatabases",
          "provider": "credentials",
          "trigger": "auto",
          "dependsOn": ["host", "port", "username", "password"],
          "credentialsName": "mysql"
        }
      }
    },
    {
      "name": "options",
      "label": "可选配置",
      "uiComponent": "Collection",
      "placeholder": "添加可选配置",
      "options": [
        { "name": "connectTimeout", "label": "连接超时（秒）", "uiComponent": "InputNumber",
          "default": 10, "typeOptions": { "min": 1, "max": 300, "style": "width:200px" } },
        {
          "name": "ssl",
          "label": "SSL 配置",
          "uiComponent": "Fixed",
          "options": [
            { "name": "enabled",             "label": "启用 SSL",       "uiComponent": "Switch", "default": false },
            { "name": "rejectUnauthorized",  "label": "验证服务器证书", "uiComponent": "Switch", "default": true,
              "displayOptions": { "show": { "enabled": [true] } } },
            { "name": "ca", "label": "CA 证书", "uiComponent": "CodeEditor",
              "typeOptions": { "lang": "text", "height": "100px" },
              "displayOptions": { "show": { "enabled": [true] } } }
          ]
        },
        { "name": "charset",  "label": "字符集", "uiComponent": "Select",
          "options": [{ "label": "utf8mb4", "value": "utf8mb4" }, { "label": "utf8", "value": "utf8" }] },
        { "name": "timezone", "label": "时区",   "uiComponent": "Input", "placeholder": "如：+08:00" }
      ]
    }
  ]
}

七、快速选型指南

场景	推荐组件
普通文本、URL、名称	`Input`
密码、Token、密钥	`Password`
整数/浮点数	`InputNumber`
是/否开关	`Switch`
固定选项单选（≤5个）	`RadioButtonGroup`
固定选项单选（>5个）	`Select`
固定选项多选	`CheckboxGroup`
远程动态加载选项	`Select`（配置 `loadOptions`）
数据库/API 凭证	`CredentialSelect`
JSON 数据体/表达式	`JsonExpressionInput`
JavaScript 脚本	`JsEditor`
SQL 语句	`SqlEditor`
逻辑条件表达式	`BooleanExpressionInput`
可增删的列表（如请求头）	`FixedCollection`
可选附加参数包	`Collection`
固定嵌套配置组（如SSL）	`Fixed`
节点输出分支定义	`RelationCollection`

动态配置表单 ​

一、文件结构 ​

二、字段定义（properties 子项） ​

三、uiComponent 组件类型 ​

3.1 基础输入类 ​

Input — 单行文本 ​

Password — 密码输入 ​

InputNumber — 数字输入 ​

Switch — 开关 ​

DatePicker / TimePicker — 日期/时间选择 ​

3.2 选择类 ​

Select — 下拉选择 ​

CheckboxGroup — 复选框组（多选，值为数组） ​

RadioButtonGroup — 单选按钮组（按钮样式） ​

RadioGroup — 单选组（Radio 样式） ​

CredentialSelect — 凭证选择器 ​

3.3 编辑器类 ​

3.4 集合/结构类 ​

Fixed — 固定字段组（值为 Object，字段不可增删） ​

Collection — 动态可选字段集合（值为 Object，按需添加字段） ​

FixedCollection — 固定结构多行列表（值为 Array，可增删排序） ​

RelationCollection — 关系列表（值为 Array，联动画布连接线） ​

四、条件显示（displayOptions） ​

五、校验规则（rules） ​

六、完整示例 ​

示例 1：飞书凭证（含条件显示） ​

示例 2：HTTP 请求头列表（FixedCollection） ​

示例 3：MySQL 连接（远程加载 + Collection 嵌套） ​

七、快速选型指南 ​

动态配置表单

一、文件结构

二、字段定义（properties 子项）

三、uiComponent 组件类型

3.1 基础输入类

`Input` — 单行文本

`Password` — 密码输入

`InputNumber` — 数字输入

`Switch` — 开关

`DatePicker` / `TimePicker` — 日期/时间选择

3.2 选择类

`Select` — 下拉选择

`CheckboxGroup` — 复选框组（多选，值为数组）

`RadioButtonGroup` — 单选按钮组（按钮样式）

`RadioGroup` — 单选组（Radio 样式）

`CredentialSelect` — 凭证选择器

3.3 编辑器类

3.4 集合/结构类

`Fixed` — 固定字段组（值为 Object，字段不可增删）

`Collection` — 动态可选字段集合（值为 Object，按需添加字段）

`FixedCollection` — 固定结构多行列表（值为 Array，可增删排序）

`RelationCollection` — 关系列表（值为 Array，联动画布连接线）

四、条件显示（displayOptions）

五、校验规则（rules）

六、完整示例

示例 1：飞书凭证（含条件显示）

示例 2：HTTP 请求头列表（FixedCollection）

示例 3：MySQL 连接（远程加载 + Collection 嵌套）

七、快速选型指南