滚动到位置

滚动到位置 用于按指定像素滚动当前网页：x 为水平方向滚动像素（正数向右、负数向左），y 为垂直方向滚动像素（正数向下、负数向上）。不传元素选择器时滚动整个页面。

指令标识：ScrollToPosition
指令类型：网页指令
指令描述：将页面滚动到指定坐标位置

先选使用方式

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

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「滚动到位置」节点，填写水平和垂直滚动像素	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 `bots.scrollToPosition(x=0, y=800)`	熟悉代码、需要复用脚本或批量生成流程的用户

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

什么时候用？

长页面中跳到指定区域。
滚动到页面底部触发懒加载。
让后续要操作的区域进入视口。
调试页面固定区域或固定定位元素。

如果要滚动到某个具体元素，优先使用滚动到元素类指令（如果你的流程中有该节点）；如果只是悬停或点击元素，通常先等待元素再操作即可。

使用前确认

当前已经有可用的浏览器页面。
你知道目标区域大致在页面的哪个坐标位置。
需要滚动到元素时，坐标方式可能不如按元素定位稳定。
滚动后如果触发懒加载，后面需要等待内容出现。

可视化编排：从 0 到跑通

先打开或跳转到目标页面。
添加 滚动到位置 指令。
填写 水平滚动像素 和 垂直滚动像素，例如：

x = 0
y = 800

运行后确认页面滚动到目标区域。
如果滚动后要读取或点击元素，继续添加等待元素节点。

最小示例

一个滚动后读取内容的流程可以这样配置：

打开网页：进入长页面。
滚动到位置：滚动到 y=800。
等待元素存在：等待目标区域内容出现。
获取文本：读取该区域的标题或内容。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
水平滚动像素	`x`	Integer	是	-	水平方向滚动的像素数，正数向右滚动，负数向左滚动。通常填 `0`。
垂直滚动像素	`y`	Integer	是	-	垂直方向滚动的像素数，正数向下滚动，负数向上滚动。
元素选择器	`selector`	String	否	-	可滚动容器元素的选择器，支持 XPath/CSS；不传则滚动整个页面（高级，可选）。
iframe 页面定位器	`frameSelector`	String	否	-	目标元素在 iframe 中时填写 iframe 的 XPath（高级，可选）。
查找元素高级配置	`findElementOptions`	JSON	否	-	查找元素的高级配置，可包含 `timeout`（超时时间，毫秒）等（高级，可选）。
是否发送消息	`sendMsgFlag`	Boolean	否	True	是否发送通知消息。

输出参数

该指令没有业务输出变量，主要作用是改变当前页面滚动位置。

滚动规则

x=0, y=0 表示不滚动。
y=800 表示向下滚动 800 像素，y=-800 表示向上滚动 800 像素。
x 正数向右、负数向左滚动，通常保持 0。
滚动量超过页面可滚动范围时，会滚动到最大可达位置。

成功标准

页面滚动到目标坐标附近。
目标区域进入视口或懒加载内容被触发。
后续等待、点击、读取节点能继续执行。

失败排查

现象	可能原因	处理建议
页面没有明显滚动	页面高度不足、目标坐标接近当前位置	调大 `y`，或确认页面是否可滚动
滚动后目标内容没出现	懒加载还没完成	滚动后增加等待元素或延迟
滚动位置不稳定	页面内容高度动态变化	优先改用按元素定位的滚动方式
横向滚动无效	页面没有横向滚动区域	通常保持 `x=0` 即可

Python 代码编排

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

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

# 滚动到距离页面顶部 800 像素的位置
bots.scrollToPosition(x=0, y=800)

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

常见问题

Q1：x、y 代表什么？

A： x、y 是水平、垂直方向的滚动像素数。x 正数向右、负数向左；y 正数向下、负数向上。两者都为必填项。

Q2：可以填负数吗？

A：可以。按参数定义，y 为负数表示向上滚动、x 为负数表示向左滚动；超出页面可滚动范围时会被收敛到最大可达位置。

Q3：如何滚动到底部？

A：可以填写一个足够大的 y 值，浏览器会滚动到最大可达位置；更稳妥的做法是结合页面高度或目标元素等待。