循环

Configure the Loop node, build the loop body, and read its output, with examples and fixes for common issues.

操作

遍历集合，并为每个项目在循环主体中运行节点一次。

何时使用循环

循环用于要处理的项目集合，例如 API 返回的记录列表、文件列表或 ID 列表。该循环为每个项目运行一次，并在集合耗尽时停止。

若要在集合用尽之前退出，请使用符合条件的中断或中断句柄，如下所述。

配置参考

字段	必填	默认	描述
集合	是	无	要迭代的数组。输入解析为数组的表达式，例如$vars.listCustomers1.output 。
并行	否	关闭	同时运行所有迭代，而不是逐个运行。如果关闭，循环将按顺序运行，等待每次迭代完成后再开始下一次迭代。
满足条件时中断	否	无	在迭代完成后，当表达式变为true时提前退出循环。这适用于顺序循环。
显示中断处理程序	否	关闭	Adds a break handle to the loop so nodes inside the body can exit the loop early. Connect a node's output to the break handle to stop iterating from inside the body. Available in sequential and parallel loops.

备注：

顺序迭代可以保留顺序，并且是“按条件中断”发挥作用所必需的，因为系统会在每次迭代完成后检查条件。并行迭代不按有保证的顺序运行。

画布上的循环

循环在画布上显示为容器。右上角的徽章会显示模式（顺序或并行） ，使用属性面板中的“并行”开关即可切换模式。在容器内，左侧的开始句柄开始每次迭代，右侧的继续句柄结束每次迭代。容器内的+按钮可将节点添加到正文，而右边缘的+可添加在循环之后运行的节点。继续句柄接受来自多个节点的边线，因此通过正文的每条路径都可以在此结束。启用“显示中断手柄”时，会显示中断手柄。

“循环”节点支持错误处理，因此其“错误处理”选项卡可以添加“错误”句柄，如“错误处理”所述。

循环主体

放置在“循环”边界内的节点形成“循环体”。正文中的节点可以读取当前项目和迭代，以及循环外作用域内的任何变量。

当前项目和迭代

在正文中，使用以下表达式引用循环的进度：

• $vars.<loopName>.currentItem是当前迭代的项目。使用点标记访问其字段，例如$vars.loop1.currentItem.id 。
• $vars.<loopName>.currentIteration是当前迭代编号，从1开始。
• $vars.<loopName>.collection是正在进行迭代的完整数组。

这些仅在循环主体内可用。

输出

完成所有迭代后，可在$vars.<loopName>.output中获取循环的聚合结果。然后，从循环之后的节点继续运行。

在循环主体之外无法访问currentItem和currentIteration 。

示例

示例 1：为每个项目调用 API

循环对$vars.listCustomers1.output进行迭代。循环正文包含一个 HTTP 请求节点，其 URL 为：

https://api.example.com/customers/{{ $vars.loop1.currentItem.id }}

示例 2：跨迭代构建结果数组

循环主体中的“脚本”节点为每个项目返回一个值。以下循环将每次迭代的结果收集到$vars.loop1.output中：

return { id: $vars.loop1.currentItem.id, processed: true };

在循环后， $vars.loop1.output是这些结果的数组。

示例 3：找到匹配项后尽早停止

循环主体中的“决策”节点会检查当前项目。启用“显示中断句柄”后，决策的匹配分支将连接到循环的中断句柄，以便在找到匹配项后立即停止迭代。

常见问题

循环主体永不运行

集合为空或undefined 。在执行追踪记录中检查上游节点的输出，以确认数组包含项目。空集合会跳过正文，在循环后继续。

永远不会在并行循环中触发符合条件的中断

系统会在每次迭代按顺序完成后评估“符合条件的中断”条件，因此适用于顺序循环。如果需要在运行条件下中断，请关闭“并行” 。

在正文中编辑集合不会更改迭代的内容

循环开始时捕获集合。修改正文中的数组变量不会更改要迭代的项目。这是设计使然。

后续步骤

• 控制流：分支、重复和重新加入路径的节点。
• 决策：根据条件进行分支。
• 变量和数据流：节点如何传递数据。
• 社区：在 UiPath 论坛上与其他构建器一起提问和共享工作流。