循环控制

循环控制 是工作流中的基础逻辑节点，用于执行重复性任务和流程控制。它支持 For 循环、While 循环 两种循环方式，并配合 Continue（跳过当前循环）和 Break（终止循环）实现复杂的重复执行逻辑，常用于批量数据处理、状态轮询和重试机制。

指令标识：for、while、continue、break
指令类型：循环控制节点
指令描述：提供完整的循环控制逻辑，支持多种循环方式和流程控制

先选使用方式

工作流支持「可视化编排」和「代码编排」两种创建方式。循环控制在两种方式里都能用，核心逻辑一致，区别主要是你通过界面配置循环节点，还是通过 Python 脚本里的原生循环语句实现。

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「For 循环」或「While 循环」节点，在循环体内放置子节点	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中使用原生 for / while 循环，以及 break / continue	熟悉代码、需要复用脚本或复杂逻辑的用户

循环控制是流程逻辑节点，代码编排中直接使用 Python 原生循环语句即可，无需调用专门的指令方法。

什么时候用？

• 需要遍历数组或列表，对每个元素执行相同操作。
• 已知循环次数，需要重复执行固定次数。
• 循环次数不确定，需要根据条件判断是否继续（状态轮询、重试）。
• 需要在满足条件时提前退出循环，或跳过某些元素。

如果只是普通条件判断，请使用 条件分支；如果要遍历页面上的列表元素，请使用 循环遍历元素。

使用前确认

• 使用 While 循环时，必须确保循环条件最终会变为 false，否则会造成死循环；建议设置最大循环次数。
• 遍历数组时，先确认数组变量已正确生成。
• 提前规划好每次循环要收集哪些结果（通过输出变量汇总成数组）。
• Continue 和 Break 必须在 For 或 While 循环体内使用。

可视化编排：从 0 到跑通

下面用一个常见场景演示：遍历数组 [1, 2, 3]，依次输出每个元素和索引。按 4 步即可跑起来：

1. 在画布中添加 For 循环 节点，选择「数组循环」模式。
2. 在 循环数组 中填写 [1,2,3]，系统会自动生成循环变量 element（当前元素）和 index（从 0 开始的索引）。
3. 在循环体内添加发送消息子节点，引用循环变量，例如 For 循环 / element 和 For 循环 / index。
4. 点击运行，确认依次输出了 3 次结果（element 为 1、2、3，index 为 0、1、2）。

For 循环的两种模式：

• 数组循环：遍历数组中的每个元素，循环次数等于数组长度。
• 递增循环：按指定步长从初始值递增到终值，类似 for(i=start; i<=end; i+=step)。例如初始值 1、递增值 1、终值 10 会循环 10 次；递增值为负数可实现递减。

While 循环的两种模式：

• while：先判断条件，条件为 true 才执行循环体，可能一次都不执行。
• do-while：先执行一次循环体，再判断条件，至少执行一次。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
循环数组	list	Array	数组循环时是	-	数组循环模式下要遍历的数组或列表
并发执行	concurrent	Boolean	否	false	是否并发执行循环体，开启后可提升性能
初始值	start	Number	递增循环时是	1	递增循环计数器的起始值
递增值	step	Number	递增循环时是	1	每次循环后计数器的增量（可为负数实现递减）
循环终值	end	Number	递增循环时是	10	递增循环的结束值（包含该值）
条件设置	condition	Boolean	While 循环时是	-	While 循环的继续条件，支持多个条件用「且」「或」组合
最大循环次数	maxLoopTimes	Number	否	20	While 循环防止死循环的保护机制
element	element	Any	/	-	循环变量：当前循环的元素值或计数器值
index	index	Number	/	-	循环变量：当前循环的索引（从 0 开始）

条件设置的配置方式与 条件分支 相同，支持等于、不等于、小于、大于、大于等于、小于等于、包含、不包含等操作符。

输出参数

界面名称	代码属性名	类型	必填	说明
自定义输出	outKey	String	否	引用循环体内子节点的输出，循环结束后汇总成一个数组

异常处理： For 循环可配置「单次遍历出错时」（终止执行 / 继续执行）和「节点运行出错时」（终止 / 继续）的策略，并可选择发生错误时是否自动回复用户。批量转账等必须完整的场景建议「终止执行」；批量发送通知等允许部分失败的场景可选「继续执行」。

成功标准

• 循环按预期的次数执行（数组长度、递增范围或条件控制）。
• 循环体内子节点能正确引用 element、index 等循环变量。
• 配置了输出变量时，循环结束后输出为汇总数组，数量与处理项数一致。
• Break 能在满足条件时提前退出，Continue 能跳过当前项继续下一次。

失败排查

现象	可能原因	处理建议
While 循环停不下来	条件始终为 true，且没有设置最大循环次数	确保条件最终会变为 false，并设置最大循环次数
循环一次都没执行	while 模式条件初始就为 false，或数组为空	检查条件与数组；需要至少执行一次可改用 do-while
输出数组为空	输出变量没有引用循环体内子节点的输出	检查输出变量的字段值是否引用了循环体内变量
Break/Continue 不生效	没有放在循环体内，或作用层级不符合预期	确认放在 For/While 循环体内；嵌套循环中只影响当前层级
循环中途整体中断	单次遍历出错且策略为「终止执行」	按业务需要调整异常处理策略为「继续执行」

Python 代码编排

代码编排以 Python 为主。运行上下文由代码编排模板创建，示例里只需要关注业务逻辑本身。

循环控制是流程逻辑节点，在代码编排中直接使用 Python 原生的循环语句即可，无需调用专门的指令方法。

For 循环（遍历数组）：

# 遍历数组，依次处理每个元素
fruits = ["苹果", "香蕉", "橙子"]
for index, element in enumerate(fruits):
    bots.message(message=f"第 {index} 项：{element}", sendMsgFlag=False)

For 循环（递增）：

# 从 1 递增到 5
for i in range(1, 6):
    bots.message(message=f"当前计数：{i}", sendMsgFlag=False)

While 循环：

# 条件满足时持续执行，注意设置最大次数防止死循环
counter = 1
max_loop_times = 5
while counter <= max_loop_times:
    bots.message(message=f"当前计数：{counter}", sendMsgFlag=False)
    counter += 1

Break（提前退出）与 Continue（跳过当前项）：

numbers = [1, 2, 3, 4, 5]
for num in numbers:
    if num == 3:
        continue          # 跳过 3，继续下一次
    if num == 5:
        break             # 遇到 5 立即退出循环
    bots.message(message=f"处理：{num}", sendMsgFlag=False)

收集循环结果： 用 Python 列表在循环中追加结果，循环结束后统一处理：

results = []
for item in ["a", "b", "c"]:
    results.append(item.upper())
# 循环结束后 results = ["A", "B", "C"]

如果你想在工作流中通过节点动态编排指令，可使用 执行指令（XML）来组织循环逻辑。

常见问题

Q1：如何防止死循环？

A： 使用 While 循环时，必须确保循环条件最终会变为 false，并建议设置最大循环次数作为保护。

Q2：For 循环和 While 循环有什么区别？

A： For 循环用于遍历已知数量的集合，适合批量处理；While 循环根据条件判断是否继续，适合状态轮询和重试。

Q3：Break 和 Continue 有什么区别？

A： Break 立即终止整个循环，Continue 跳过当前循环的剩余步骤进入下一次迭代。

Q4：嵌套循环中 Break 和 Continue 如何工作？

A： 在嵌套循环中，Break 和 Continue 只影响当前所在的循环层级，不会影响外层循环。

Q5：如何在循环中收集结果？

A： 可视化编排中配置输出变量汇总成数组；代码编排中用 Python 列表在循环里追加结果。

相关指令

• 条件分支
• 循环遍历元素
• try-catch
• 延迟执行