内置节点

内置节点是工作流引擎的基础能力单元，每种节点类型封装了特定的逻辑操作。节点按功能分为四组：

分组	group	说明	包含节点
基础节点	`model`	工作流入口与页面交互	开始、物料事件、切换页面、流程注释
数据管理	`data`	变量操作与外部通信	赋值变量、合并变量、云函数、HTTP请求
流程控制	`flow`	条件判断与循环	条件分支、循环体、跳出循环、延迟
Ai工具	`ai`	AI 辅助能力	（暂无节点）

节点元数据结构

Snippet（节点片段）

节点片段定义了节点在面板中的展示信息和拖拽生成节点时的默认数据。

snippet: {
  name: '条件分支',              // 面板中显示的名称
  component: 'NodeCondition',    // 节点组件名
  icon: 'icon-panduanshifoucunzai', // 面板中显示的图标类名
  schema: {
    props: {                     // 拖拽生成节点时的默认属性
      conditions: []
    }
  }
}

字段	类型	说明
`name`	`string`	面板中显示的名称
`component`	`string`	节点组件名
`icon`	`string`	面板中显示的图标类名
`schema.props`	`object`	拖拽生成节点时的默认属性值

Component（节点配置）

节点配置定义了属性面板、端口连接和行为约束。

component: {
  schema: {
    properties: [...]           // 属性分组列表
  },
  ports: [...],                 // 端口列表
  configure: {                  // 节点行为配置
    canConfig: true,
    isShow: true
  },
  note: '...'                   // 节点备注说明（可选）
}

schema.properties 属性分组

与物料元数据的 properties 结构一致，按分组折叠展示属性配置项：

properties: [
  {
    label: '基本属性',           // 分组名称
    content: [                  // 分组下的属性项列表
      {
        label: '执行函数',
        description: '需要执行的云函数',
        property: 'code',
        widget: {
          component: 'BindVariable',
          props: { type: 'cloudFuns' }
        },
        labelPosition: 'left'
      }
    ]
  }
]

属性项字段说明：

字段	类型	说明
`label`	`string`	属性标签
`description`	`string`	属性描述
`property`	`string`	属性名
`widget`	`object`	属性编辑器配置（同物料 widget）
`labelPosition`	`'left' \| 'top'`	标签位置

ports 端口列表

端口定义了节点之间的连接关系，是工作流数据流转的通道：

ports: [
  {
    id: 'input',                // 端口标识
    type: 'target',             // 端口方向
    description: '输入端口，接收上一个节点的输出'
  },
  {
    id: 'if-{branchId}',        // 支持模板变量
    type: 'source',
    description: 'IF/ELIF分支端口',
    dynamic: true,              // 是否动态生成
    example: 'if-abc123, if-def456'  // 动态端口示例
  },
  {
    id: 'error',
    type: 'source',
    description: '异常端口',
    conditional: true,          // 是否条件端口
    condition: '当节点的error-branch属性设置为branch时可用'
  }
]

端口字段说明：

字段	类型	说明
`id`	`string`	端口标识，支持模板变量（如 `if-{branchId}`、`event-{branchId}`）
`type`	`'target' \| 'source'`	端口方向，`target` 为输入端口，`source` 为输出端口
`description`	`string`	端口说明
`dynamic`	`boolean`	是否动态生成端口（可选，默认 `false`）
`example`	`string`	动态端口的 ID 示例（可选）
`conditional`	`boolean`	是否为条件端口，满足特定配置时才可用（可选，默认 `false`）
`condition`	`string`	条件端口的启用条件说明（可选）

端口方向说明：

target（输入端口）：接收上游节点的输出，位于节点左侧
source（输出端口）：向下游节点传递数据，位于节点右侧

动态端口：

条件分支和物料事件节点的端口数量不固定，使用模板变量动态生成：

条件分支：if-{branchId} — 每个条件分支对应一个输出端口
物料事件：event-{branchId} — 每个事件绑定对应一个输出端口

configure 节点行为配置

字段	类型	说明
`canConfig`	`boolean`	是否可配置，`false` 时无属性面板
`isShow`	`boolean`	是否在面板中显示，`false` 时不在面板中展示（如开始节点）（可选，默认 `true`）

note 节点备注

note 为可选字段，提供节点的补充说明，如"跳出循环节点没有输出端口"。

节点分组注册

所有节点通过 @catpull/built-in-nodes/src/meta/index.ts 统一注册，按分组组织：

export default {
  nodes: [
    {
      group: 'model',           // 分组标识
      label: '基础节点',         // 分组显示名称
      priority: 100,            // 排序优先级（数值越大越靠前）
      children: [NodeStart, NodeComponent, NodeSwitchPage, NodeNote]
    },
    {
      group: 'data',
      label: '数据管理',
      priority: 90,
      children: [VariableAssign, NodeMerging, NodeCode, NodeHttp]
    },
    {
      group: 'flow',
      label: '流程控制',
      priority: 80,
      children: [NodeCondition, NodeLoop, NodeBreakLoop, NodeDelay]
    },
    {
      group: 'ai',
      label: 'Ai工具',
      priority: 70,
      children: []
    }
  ]
}

完整示例

以 NodeCondition（条件分支）为例，展示完整的节点元数据定义：

export default {
  snippet: {
    name: '条件分支',
    component: 'NodeCondition',
    icon: 'icon-panduanshifoucunzai',
    schema: {
      props: {
        conditions: []
      }
    }
  },
  component: {
    schema: {
      properties: [
        {
          label: '基本属性',
          content: [
            {
              label: '条件列表',
              property: 'conditions',
              widget: {
                component: 'Condition',
                children: [
                  {
                    label: '被比较值',
                    property: 'compared-value',
                    widget: { component: 'BindVariable', props: { type: 'state' } },
                    labelPosition: 'left'
                  },
                  {
                    label: '条件类型',
                    property: 'compare',
                    widget: {
                      component: 'Select',
                      props: {
                        options: [
                          { label: '等于', value: 'equal' },
                          { label: '不等于', value: 'notEqual' },
                          { label: '大于', value: 'greaterThan' }
                        ]
                      }
                    },
                    labelPosition: 'left'
                  },
                  {
                    label: '比较值',
                    property: 'comparison-value',
                    widget: { component: 'BindVariable', props: { type: 'state' } },
                    labelPosition: 'left'
                  }
                ],
                props: {}
              },
              labelPosition: 'top'
            }
          ]
        }
      ]
    },
    ports: [
      {
        id: 'input',
        type: 'target',
        description: '输入端口，接收上一个节点的输出'
      },
      {
        id: 'else',
        type: 'source',
        description: 'ELSE分支端口，当所有条件都不满足时执行'
      },
      {
        id: 'if-{branchId}',
        type: 'source',
        description: 'IF/ELIF分支端口，每个条件分支都有一个对应的输出端口',
        dynamic: true,
        example: 'if-abc123, if-def456'
      }
    ],
    configure: {
      canConfig: true
    }
  }
}

开始节点（NodeStart）

工作流的入口节点，每个工作流必须包含一个开始节点。

不可配置 — 无属性面板
端口：1 个输出端口（output），连接到下一个节点

使用方式

开始节点自动创建，无需手动添加。工作流触发时从开始节点沿连线依次执行。

条件分支（NodeCondition）

根据条件判断走不同分支，支持多个 IF/ELIF 分支和一个 ELSE 默认分支。

端口

端口	方向	说明
`input`	输入	接收上游节点输出
`if-{branchId}`	输出	IF/ELIF 分支端口，动态生成，每个条件对应一个
`else`	输出	ELSE 分支，所有条件都不满足时执行

配置项

属性	说明
条件列表	添加多个条件分支，每个条件包含：被比较值、条件类型、比较值
被比较值	要参与比较的数据，绑定状态变量
条件类型	比较运算符
比较值	与被比较值进行对比的参照值

条件类型

运算符	值
包括	`include`
不包括	`exclude`
不为空	`notEmpty`
等于	`equal`
不等于	`notEqual`
大于	`greaterThan`
小于	`lessThan`
大于等于	`greaterThanEqual`
小于等于	`lessThanEqual`

使用方式

添加条件分支，设置被比较值和比较值
从 if-{branchId} 端口连线到条件满足时的执行节点
从 else 端口连线到所有条件都不满足时的执行节点
多个条件按顺序判断，命中第一个满足的条件后执行对应分支

循环体（NodeLoop）

支持三种循环方式：遍历数组、固定次数、条件循环。

端口

端口	方向	说明
`input`	输入	接收上游节点输出
`output`	输出	循环正常完成后继续执行
`breakLoop`	输出	循环体中使用了跳出循环节点时执行
`error`	输出	循环执行过程中发生异常时执行

配置项

属性	说明	可见条件
循环类型	遍历数组 / 固定次数 / 条件循环	始终可见
循环变量	要遍历的数组变量	循环类型 = 遍历数组
循环次数	固定次数循环的次数（1-999）	循环类型 = 固定次数
说明提示	端口说明	始终可见

循环类型

类型	值	说明
遍历数组	`forEach`	遍历状态变量中的数组
固定次数	`forCount`	按指定次数循环执行
条件循环	`while`	持续循环，通过（NodeBreakLoop）节点跳出

使用方式

选择循环类型并配置对应参数
将需要循环执行的节点拖入循环节点内部
从 output 端口连线到循环完成后的执行节点
从 breakLoop 端口连线到需要跳出循环时的处理节点
从 error 端口连线到异常处理节点（可选）

跳出循环（NodeBreakLoop）

提前终止当前循环，类似 JavaScript 中的 break。

不可配置 — 无属性面板
端口：1 个输入端口（input），无输出端口

使用方式

放置在循环节点内部，执行到此节点时立即终止循环，触发循环体的 breakLoop 端口。

云函数（NodeCode）

执行页面中定义的云函数，支持传入变量和输出返回值。

端口

端口	方向	条件	说明
`input`	输入	—	接收上游节点输出
`output`	输出	—	云函数执行完成后继续执行
`error`	输出	异常分支 = 异常分支	云函数执行失败时执行

配置项

属性	说明
执行函数	绑定需要执行的云函数（从 cloudFuns 中选择）
传入变量	传递给云函数的变量列表，每个变量绑定一个状态值
输出变量	云函数返回数据赋值给该状态变量
异常分支	执行异常后的处理方式：无 / 默认值 / 异常分支
异常返回值	异常时返回的默认数据（JSON 格式，异常分支 = 默认值时可见）

异常分支策略

策略	值	说明
无	`none`	异常时中断执行
默认值	`default`	异常时返回预设的默认值，继续执行
异常分支	`branch`	异常时走 `error` 端口连接的分支

使用方式

在页面的云函数面板中定义函数逻辑
在节点中绑定该云函数
配置传入变量（函数参数）和输出变量（函数返回值）
根据需要配置异常处理策略

HTTP请求（NodeHttp）

发起 HTTP 请求并处理响应数据，支持跨域代理、重试策略、异常处理。

端口

端口	方向	条件	说明
`input`	输入	—	接收上游节点输出
`output`	输出	—	请求成功后继续执行
`error`	输出	异常分支 = 异常分支	请求失败时执行

配置项

属性	说明
数据源	绑定请求数据源（从 dataSource 中选择）
请求参数	配置请求参数列表（参数名 + 参数值）
参数位置	Query / Body / Form
请求超时	超时时间（1000-12000 毫秒）
返回数据绑定	绑定返回数据到状态变量
解构响应数据	是否对响应数据进行解构提取
解构路径	数据解构路径，如 `data.results`

高级配置

属性	说明
跨域代理	是否通过代理服务器发送请求
代理地址	代理服务器 URL
失败时重试	请求失败时是否自动重试
重试次数	最大重试次数（1-3）
重试间隔	重试间隔时间（1000-8000 毫秒）
异常分支	请求异常后的处理方式：无 / 默认值 / 异常分支

使用方式

先在页面的数据源面板中配置接口地址和请求方法
在节点中绑定该数据源
配置请求参数和返回数据绑定变量
如需提取嵌套数据，开启解构并填写路径（如 data.list）
根据需要配置代理、重试和异常处理

延迟（NodeDelay）

暂停指定时间后继续执行后续节点。

端口

端口	方向	说明
`input`	输入	接收上游节点输出
`output`	输出	延迟结束后继续执行

配置项

属性	说明
延迟时间	延迟时长数值
时间单位	毫秒 / 秒 / 分钟

使用方式

常用于等待动画完成、接口轮询间隔等场景。设置延迟时间和单位即可。

物料事件（NodeComponent）

绑定组件的事件触发，当组件触发指定事件时执行对应分支。

端口

端口	方向	说明
`event-{branchId}`	输出	事件分支端口，动态生成，每个事件对应一个

不可配置 — 节点会在物料添加事件时自动生成

使用方式

在画布中选中组件
在右侧事件面板中添加事件并绑定工作流
物料事件节点会自动创建，端口与绑定的事件一一对应
从对应事件端口连线到需要执行的节点

合并变量（NodeMerging）

将多个变量合并为一个对象，赋值给输出变量。

端口

端口	方向	说明
`input`	输入	接收上游节点输出
`output`	输出	变量合并完成后继续执行

配置项

属性	说明
变量列表	要参与合并的变量列表，每个变量绑定一个状态值
输出变量	合并后的数据赋值给该状态变量

使用方式

添加需要合并的变量到列表中
指定输出变量接收合并结果
合并结果为 { 变量1名: 变量1值, 变量2名: 变量2值, ... } 格式的对象

切换页面（NodeSwitchPage）

切换到指定页面，支持页面切换动画。

端口

端口	方向	说明
`input`	输入	接收上游节点输出

无输出端口 — 执行后切换到目标页面

配置项

属性	说明
目标页面	选择需要跳转到的页面（自动排除当前页面）
动画类型	页面切换动画

动画类型

动画	值
无	`none`
右滑入	`slide-in-right`
左滑入	`slide-in-left`
淡入	`fade-in`
缩放	`zoom-out`
淡入缩放	`zoom-fade-out`

使用方式

选择目标页面（页面列表从项目页面中动态获取）
选择动画类型（仅 UniApp 环境支持动画）
执行到此节点时自动跳转到目标页面

赋值变量（NodeVariableAssign）

修改页面状态变量的值，支持覆盖、清空、设置三种赋值方式。

端口

端口	方向	说明
`input`	输入	接收上游节点输出
`output`	输出	变量赋值完成后继续执行

配置项

属性	说明
变量列表	变量赋值列表，每项包含：变量、赋值类型、赋值内容
变量	需要赋值的状态变量
赋值类型	覆盖 / 清空 / 设置
赋值内容	赋值的 JSON 内容（赋值类型 ≠ 清空时可见）

赋值类型

类型	值	说明
覆盖	`override`	完全替换变量值
清空	`clear`	将变量置为空值
设置	`set`	设置变量的部分属性

使用方式

选择需要修改的状态变量
选择赋值类型
填写赋值内容（JSON 格式）
可同时修改多个变量，按顺序依次执行

流程注释（NodeNote）

为工作流添加说明文字，不影响执行逻辑。

不可配置 — 无属性面板
无端口 — 不参与流程连线

使用方式

编辑注释文本。用于标注复杂逻辑的用途、注意事项等，类似代码中的注释。

内置节点 ​

节点元数据结构 ​

Snippet（节点片段） ​

Component（节点配置） ​

schema.properties 属性分组 ​

ports 端口列表 ​

configure 节点行为配置 ​

note 节点备注 ​

节点分组注册 ​

完整示例 ​

开始节点（NodeStart） ​

条件分支（NodeCondition） ​

端口 ​

配置项 ​

条件类型 ​

循环体（NodeLoop） ​

端口 ​

配置项 ​

循环类型 ​

跳出循环（NodeBreakLoop） ​

云函数（NodeCode） ​

端口 ​

配置项 ​

异常分支策略 ​

HTTP请求（NodeHttp） ​

端口 ​

配置项 ​

高级配置 ​

延迟（NodeDelay） ​

端口 ​

配置项 ​

物料事件（NodeComponent） ​

端口 ​

合并变量（NodeMerging） ​

端口 ​

配置项 ​

切换页面（NodeSwitchPage） ​

端口 ​

配置项 ​

动画类型 ​

赋值变量（NodeVariableAssign） ​

端口 ​

配置项 ​

赋值类型 ​

流程注释（NodeNote） ​

内置节点

节点元数据结构

Snippet（节点片段）

Component（节点配置）

schema.properties 属性分组

ports 端口列表

configure 节点行为配置

note 节点备注

节点分组注册

完整示例

开始节点（NodeStart）

条件分支（NodeCondition）

端口

配置项

条件类型

循环体（NodeLoop）

端口

配置项

循环类型

跳出循环（NodeBreakLoop）

云函数（NodeCode）

端口

配置项

异常分支策略

HTTP请求（NodeHttp）

端口

配置项

高级配置

延迟（NodeDelay）

端口

配置项

物料事件（NodeComponent）

端口

合并变量（NodeMerging）

端口

配置项

切换页面（NodeSwitchPage）

端口

配置项

动画类型

赋值变量（NodeVariableAssign）

端口

配置项

赋值类型

流程注释（NodeNote）