拖拽到指定位置

拖拽到指定位置 用于把一个元素从它当前的中心位置，按你给定的横向、纵向偏移量拖动到屏幕上的另一处。它适合滑块验证、画布拖拽、进度条调节等需要按位移拖动的场景。

指令标识：DragAndDropByOffset
指令类型：网页指令
指令描述：按偏移量将元素从其中心拖动到屏幕上指定位置

先选使用方式

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

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「拖拽到指定位置」节点，捕获元素、填写横纵偏移	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 `bots.dragAndDropByOffset(selector="...", offsetX=100, offsetY=0)`	熟悉代码、需要复用脚本或批量生成流程的用户

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

什么时候用？

拖动滑块到某个位置，例如滑块验证、音量/进度调节。
在画布上把元素按位移拖到目标点。
需要按相对位移拖动，而不是拖到另一个具体元素上。

如果你要把元素拖到 另一个元素 上，请使用拖拽到目标元素。

使用前确认

目标元素已经出现并可见，必要时先用等待节点。
已经确认横向、纵向偏移量（单位为像素，向右、向下为正，向左、向上为负）。
拖动落点在页面可视区域内。

可视化编排：从 0 到跑通

下面用一个常见场景演示：把滑块向右拖动 120 像素。

确认页面已经打开，滑块可见。
在拖动前添加等待元素存在，等待滑块出现。
添加 拖拽到指定位置 节点，捕获滑块元素。
在 横向偏移 填 120，纵向偏移 填 0。
运行后观察滑块是否被拖到目标位置、验证是否通过。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
元素选择器	`selector`	String	是	-	要拖动的元素。建议从元素库捕获。
偏移X	`offsetX`	Double	是	-	距元素视图内中心点的水平偏移，单位像素，负值表示向左偏移。
偏移Y	`offsetY`	Double	是	-	距元素视图内中心点的垂直偏移，单位像素，负值表示向上偏移。
拖拽持续时间	`dragDuration`	Integer	否	`0`	高级参数，控制拖拽动作执行时长，单位毫秒。`0` 表示即时拖拽，大于 `0` 会让拖拽更平滑、更慢，推荐 `100-1000`。
移动步数	`moveSteps`	Integer	否	60-100 随机	高级参数，将拖拽过程分解为多少步，默认 `60-100` 步随机，步数越多越平滑。
轨迹抖动	`addTrajectoryJitter`	Boolean	否	`true`	高级参数，是否在拖拽轨迹中添加轻微抖动，模拟真实操作。
垂直抖动范围	`verticalJitterRange`	Double	否	`2.0`	高级参数，垂直方向抖动的最大像素数。
iframe页面定位器	`frameSelector`	String	否	-	高级参数，目标元素在 iframe 内时填写其 xpath。
查找元素高级配置	`findElementOptions`	JSON	否	-	高级参数，查找元素的高级配置（如超时时间等），以 JSON 配置。

输出参数

该指令没有输出变量。拖动结果通过页面是否产生预期变化来判断。

成功标准

拖拽到指定位置 节点运行结束后状态为成功。
运行日志中没有参数缺失、超时或执行失败等错误。
后续节点能够继续执行，流程没有因为该节点异常中断。

失败排查

现象 / 报错原文	可能原因	处理建议
日志报 `DragAndDropByOffset requires "selector" or "selectorId"`	没有指定元素	填写「元素选择器」或选择元素库中的元素
日志报 `DragAndDropByOffset requires numeric "offsetX" and "offsetY"`	偏移量为空或不是数字	横向、纵向偏移都填写数字
日志报 `element not visible, cannot drag by offset`	元素不可见、没渲染或被遮挡	先等待元素出现并滚动到可视区域再拖动
拖动没产生预期效果	偏移量不对或落点超出范围	调整偏移量，确认落点在可视区域内

Python 代码编排

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

# 把滑块向右拖动 120 像素
bots.dragAndDropByOffset(
    selector="//*[@id='slider']/div[@class='handle']",
    offsetX=120,
    offsetY=0,
)

如需更平滑的拖动，可调节时长与步数：

bots.dragAndDropByOffset(
    selector="//*[@id='slider']/div[@class='handle']",
    offsetX=120,
    offsetY=0,
    dragDuration=800,
    moveSteps=40,
)

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

常见问题

Q1：偏移量的方向怎么算？

A：以元素中心为起点，向右、向下为正，向左、向上为负，单位是像素。例如 offsetX=120, offsetY=0 表示向右拖 120 像素。

Q2：和「拖拽到目标元素」有什么区别？

A：本指令按位移拖到屏幕上的某个坐标；拖拽到目标元素是拖到另一个具体元素上。滑块类用本指令更合适。

Q3：拖动看起来太快或太机械怎么办？

A：适当调大「拖动时长」和「移动步数」，并保持「轨迹抖动」开启，可让拖动更平滑、更接近真人。