循环遍历元素

循环遍历元素 用于循环遍历页面上所有匹配选择器的元素，并对每一项执行相同的操作。它适合批量读取商品列表、评论列表、表格行、搜索结果等重复结构，支持滚动加载、点击加载等方式动态加载更多元素。

指令标识：LoopElements
指令类型：网页指令
指令描述：循环遍历页面中所有匹配选择器的元素，支持滚动加载、点击加载等多种方式动态加载更多元素

先选使用方式

工作流支持「可视化编排」和「代码编排」两种创建方式。循环遍历元素 通过在循环体内嵌套子指令工作，主要通过可视化编排使用；代码编排中通常用 Python 原生循环逐项处理元素。

方式	怎么用	适合人群
可视化编排（推荐）	拖入「循环遍历元素」节点，在循环体内放置子指令，配置列表选择器和输出参数	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	用原生 `for` 循环，按索引拼接选择器逐项读取数据	熟悉代码、需要复用脚本的用户

第一次使用建议先用可视化编排跑通。下方「参数说明」同时给出界面字段和代码属性名，方便两种方式对应。

核心使用规则

循环遍历元素具有特殊的用法规则，需要特别注意循环内部的元素定位方式：

本指令的 selector 需匹配到页面上的循环列表元素。

示例：//*[@id="exploreFeeds"]/section
循环内部的子指令（如获取文本）通过 index 变量实现循环定位。

示例：//*[@id='exploreFeeds']/section[@{toolId.index}]/div/div/a/span
配置 outputList 收集数据，value 仅支持引用子指令的输出变量。

示例：[{'name': 'titles', 'value': '${子指令.outKey}' }]
循环外指令引用本指令的输出。

示例：${toolId.outKey}

什么时候用？

页面上有多条结构相同的数据，例如商品卡片、评论、订单行、表格行。
需要逐条读取文本、属性或链接。
页面需要滚动或点击「加载更多」才能拿到更多数据。

如果只是处理一个普通数组，不涉及页面元素，请使用普通循环控制或列表处理指令。

使用前确认

页面已经加载到列表区域，必要时先等待列表容器出现。
列表元素选择器能匹配到多项，而不是只匹配到一个父容器。
循环体内的子指令使用 @{toolId.index} 定位当前项。
已经规划好每次循环要收集哪些结果。
如果列表很长，设置合理的最大循环次数，避免运行时间过长（找不到元素时会按失败处理中止，不会静默跳过）。

可视化编排：从 0 到跑通

下面用一个常见场景演示：遍历示例列表页上所有匹配到的条目，读取每条标题并收集成数组。按 6 步即可跑起来：

打开网页：打开目标列表页。
等待元素存在：等待列表容器出现。
循环遍历元素：在 selector 中填写列表项选择器（如 //*[@id='exploreFeeds']/section）。
在循环体内添加获取文本，选择器中用 @{toolId.index} 定位当前项。
在 outputList 中把标题收集到 titles 数组。
点击运行，确认循环结束后输出变量中包含多个列表项的结果。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
元素选择器	`selector`	String	是	-	匹配要循环的元素列表，支持 CSS 选择器、XPath 等，例如 `//*[@id="exploreFeeds"]/section`。
输出参数	`outputList`	JSON	否	-	收集每次循环的数据，`value` 仅支持引用子指令的输出变量，例如 `[{"name":"titles","type":"array<string>","value":"${子节点输出变量}"}]`。
等待超时	`timeout`	Double	否	`3000`	高级参数，等待元素出现的最大超时时间（毫秒），最小值为 0。
最大循环次数	`maxLoopTimes`	Integer	否	`1000`	高级参数，最大循环次数，不得超过 `1000`。
是否倒序	`reverse`	Boolean	否	`false`	高级参数，是否倒序遍历元素。
加载更多操作	`loadMoreAction`	Enum	否	`NONE`	高级参数，加载更多元素的操作：无操作=`NONE`；点击元素加载更多=`CLICK_ELEMENT`；向上滚动=`SCROLL_UP`；向下滚动=`SCROLL_DOWN`。
加载更多目标选择器	`loadMoreSelector`	String	否	-	高级参数，执行加载更多操作时的目标元素选择器，加载更多操作不为「无操作」时必填。
是否滚动到底部	`scrollToBottom`	Boolean	否	`false`	高级参数，是否滚动到底部。
是否滚动到顶部	`scrollToTop`	Boolean	否	`false`	高级参数，是否滚动到顶部。
加载更多等待时间	`loadMoreWaitTime`	Double	否	`3000`	高级参数，执行加载动作后等待新元素加载的超时时间（毫秒）。
单次遍历出错时是否继续	`keepgoing`	Boolean	否	`false`	高级参数，单次遍历出错时是否继续遍历下一项。
循环变量信息	`loopVariables`	List	否	`[{"name":"index","type":"number"}]`	循环变量信息，默认提供 `index` 索引变量。

输出参数

界面名称	代码属性名	类型	必填	说明
将结果保存至	`outKey`	Object	否	存储循环结果的变量，默认为 `toolId`。

成功标准

循环节点能匹配到预期数量的元素。
循环体内子指令能拿到当前项的数据。
outputList 输出为数组，且数量与处理项数一致。
如果使用加载更多，日志中能看到加载动作和新增元素。

失败排查

现象	可能原因	处理建议
循环次数为 0	列表选择器没有匹配到元素	先等待列表容器，再重新校验列表项选择器
每次都读到同一项	子指令没有使用 `@{toolId.index}`	调整循环体内选择器，按当前索引定位
输出数组为空	`outputList` 没有引用子指令输出	检查 `value` 是否引用循环体内变量
运行中途失败	单项数据结构不同或元素缺失	评估是否开启「单次遍历出错时是否继续」
运行时间过长	没有限制循环次数或加载更多过多	设置最大循环次数或分页处理

Python 代码编排

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

循环遍历元素通过在循环体内嵌套子指令工作，主要通过可视化编排使用。在代码编排中，通常用 Python 原生 for 循环，按索引拼接选择器逐项读取数据，并把结果收集到列表中：

# 按索引遍历列表项，逐项读取标题并收集成数组
titles = []
for index in range(1, 11):  # 根据实际列表长度调整范围
    selector = f"//*[@id='exploreFeeds']/section[{index}]/div/div/a/span"
    title = bots.getText(selector=selector, outKey="title")
    titles.append(title)
# 循环结束后 titles 即为收集到的标题数组

如果你想在工作流中通过节点动态编排指令，可使用执行指令（XML）来配置循环遍历元素节点及其子指令。

常见问题

Q1：循环遍历元素与普通循环有什么区别？

A：它是专门用于网页元素循环遍历的指令，可自动处理动态加载（滚动、点击加载等），支持 index 变量定位元素并自动收集结果到数组。

Q2：index 变量需要手动创建吗？可以在循环外使用吗？

A：会自动创建 index 变量，用于定位当前循环的元素，且只能在循环内部的子指令中使用。

Q3：如何获取循环收集的数据？

A：配置 outputList 自动收集循环结果到数组，循环外可引用输出变量获取收集的数据。

Q4：单个元素处理失败会影响整个循环吗？

A：默认情况下单个元素失败会中断整个循环；如需继续处理其他元素，请设置 keepgoing="true"。

Q5：loadMoreAction 有哪些选项？

A：支持 NONE（无操作，默认）、CLICK_ELEMENT（点击加载更多）、SCROLL_DOWN（向下滚动加载）、SCROLL_UP（向上滚动加载）。

Q6：maxLoopTimes 的最大值是多少？

A：最大值是 1000。如果需要处理超过 1000 个元素，建议分页处理或优化选择器。

Q7：outputList 中的 value 可以任意设置吗？

A： value 只能引用循环体内指令的输出变量，不能引用循环外的变量。