滚动到元素

滚动到元素 用于将页面滚动到指定元素的位置，使该元素出现在浏览器可视区域内。它常用于长页面中定位目标、触发懒加载，或在点击/输入等操作前确保元素可见。

指令标识：ScrollToElement
指令类型：网页指令
指令描述：将页面滚动到指定元素的位置，使该元素在浏览器视窗中可见

先选使用方式

工作流支持「可视化编排」和「代码编排」两种创建方式。滚动到元素 在两种方式里都能用，核心业务参数一致，区别主要是你通过界面配置，还是通过 Python 脚本配置。

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「滚动到元素」节点，捕获或填写目标元素选择器	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 bots.scrollToElement(selector="//*[@id='footer']")	熟悉代码、需要复用脚本或批量生成流程的用户

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

什么时候用？

• 在长页面中快速定位到特定内容区域。
• 在执行点击或其他操作前，确保目标元素在可视区域内。
• 通过滚动触发页面的懒加载，加载更多内容。
• 填写表单前先滚动到表单所在位置。

使用前确认

• 目标页面已经打开，目标元素存在于 DOM 中。
• 你知道目标元素的选择器，建议从元素库捕获。
• 如果目标在 iframe 中，需要配置 iframe 页面定位器。
• 本指令属于页面定位类，默认失败处理为「报错中止」（STOP_ON_FAILURE），元素不存在会抛出异常。

可视化编排：从 0 到跑通

1. 先打开目标网站，并确认目标元素已加载到页面中。
2. 在工作流画布中添加 滚动到元素 节点。
3. 捕获或填写 元素选择器，例如 //*[@id='footer']。
4. 如目标元素加载较慢，在 查找元素高级配置 中增大等待时间，例如 {"timeout":5000}。
5. 运行后确认目标元素已进入可视区域。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
元素选择器	selector	String	是	-	需要滚动到的目标元素选择器，不能为空，支持从元素库选择或手动填写 XPath 等定位器值。
iframe页面定位器	frameSelector	String	否	-	高级参数。iframe 的 XPath，目标元素在 iframe 中时填写，例如 //html/iframe。
查找元素高级配置	findElementOptions	JSON	否	-	高级参数。查找元素的高级配置（JSON），可在其中设置定位超时 timeout（单位毫秒，例如 {"timeout":5000}，设为 0 表示不等待）等。

输出参数

该指令无输出参数。是否成功建议通过页面状态或后续节点判断。

成功标准

• 目标元素已进入浏览器可视区域。
• 后续针对该元素的点击、读取等操作能正常执行。
• 若触发了懒加载，更多内容已加载完成。

失败排查

现象	可能原因	处理建议
节点报错：找不到目标元素	元素不存在或定位失效	先用 验证元素存在 确认，或在 findElementOptions 中增大 timeout
滚动后元素仍不可见	元素在 iframe 或被遮挡	配置 frameSelector，或滚动后增加短暂等待
滚动后懒加载未完成	内容仍在异步加载	滚动后增加适当延迟，等待页面状态更新完成
后续操作位置错乱	页面滚动改变了元素位置	滚动后重新定位目标元素再操作

Python 代码编排

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

bots.openUrl(url="https://example.com")

# 滚动到页脚元素；如需调整定位等待时间，通过 findElementOptions 传入 timeout
bots.scrollToElement(
    selector="//*[@id='footer']",
    findElementOptions={"timeout": 5000},
)

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

常见问题

Q1：滚动操作会改变页面的哪些内容？

A： 滚动操作会改变页面的滚动位置，使目标元素进入可视区域，这可能影响其他依赖页面位置的元素操作。

Q2：如果目标元素不存在会怎样？

A： 会抛出异常（该指令默认报错中止）。建议先使用 验证元素存在 验证，或在 findElementOptions 中增大 timeout 等待时间。

Q3：滚动后是否需要等待？

A： 在动态加载页面中，滚动可能触发懒加载或其他事件。建议滚动后添加适当延迟，等待页面状态更新完成。

Q4：如果目标元素在 iframe 中怎么办？

A： 需要使用 iframe页面定位器（frameSelector）参数指定 iframe 的 XPath，例如 //iframe[@id='myFrame']。

相关指令

• 滚动到位置
• 点击元素（推荐）
• 验证元素存在
• 等待元素存在