拖拽到元素

拖拽到元素 用于把源元素拖拽到目标元素位置。它常用于可拖拽列表排序、看板任务移动、可视化编辑器组件放置、拖拽上传区域等交互场景。

指令标识：DragAndDropByObject
指令类型：网页指令
指令描述：实现将源元素拖拽到目标元素的位置

先选使用方式

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

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「拖拽到元素」节点，分别捕获源元素和目标元素	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 bots.dragAndDropByObject(sourceSelector="...", targetSelector="...")	熟悉代码、需要复用脚本或批量生成流程的用户

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

什么时候用？

• 拖拽排序列表项。
• 将看板卡片从一个状态列移动到另一个状态列。
• 在可视化编辑器中拖放组件。
• 将页面元素拖到指定区域触发 drop 事件。

如果只是鼠标移动或悬停，请使用 鼠标悬停；如果只是点击某个按钮，请使用 点击元素。

使用前确认

• 源元素和目标元素都已经出现，必要时先等待元素存在。
• 源元素确实支持拖拽，目标区域能接收拖拽。
• 源元素和目标元素在 iframe 中时，需要分别配置对应 iframe。
• 拖拽后页面可能有动画或异步更新，后面需要等待目标状态出现。

可视化编排：从 0 到跑通

1. 先让页面进入包含源元素和目标区域的状态。
2. 添加 拖拽到元素 指令。
3. 捕获 源元素，例如要移动的卡片。
4. 捕获 目标元素，例如目标列或目标区域。
5. 运行后添加等待节点，确认拖拽后的状态变化。

最小示例

一个看板任务移动流程可以这样配置：

1. 打开网页：进入看板页面。
2. 等待元素存在：等待任务卡片和目标列出现。
3. 拖拽到元素：把任务卡片拖到目标列。
4. 等待元素存在：等待目标列中出现该任务。
5. 获取文本：读取任务状态或列表数量。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
源元素选择器	sourceSelector	String	是	-	要拖拽的源元素选择器，建议从元素库捕获，支持 XPath/CSS。
目标元素选择器	targetSelector	String	是	-	拖拽目标位置的元素选择器，建议从元素库捕获，支持 XPath/CSS。
源 iframe 定位器	sourceFrameSelector	String	否	-	源元素在 iframe 中时填写 iframe 的 XPath（高级，可选）。
目标 iframe 定位器	targetFrameSelector	String	否	-	目标元素在 iframe 中时填写 iframe 的 XPath（高级，可选）。
源查找元素高级配置	sourceFindElementOptions	JSON	否	-	源元素查找的高级配置，可包含定位方式、timeout（超时时间，毫秒）等（高级，可选）。
目标查找元素高级配置	targetFindElementOptions	JSON	否	-	目标元素查找的高级配置，可包含定位方式、timeout（超时时间，毫秒）等（高级，可选）。
拖拽选项	dragToOptions	JSON	否	-	拖拽的高级配置，可配置 sourcePosition、targetPosition、dragDuration、useMouseEvents 等（高级，可选）。
是否发送消息	sendMsgFlag	Boolean	否	True	是否发送通知消息。

输出参数

该指令没有业务输出变量，主要副作用是触发页面拖拽交互。是否成功应通过页面状态、运行日志和后续等待节点判断。

执行方式说明

源码默认会优先模拟页面拖拽事件；如果显式配置 useMouseEvents=true，会使用真实鼠标轨迹从源元素拖到目标元素；如果关闭事件模拟，也会尝试 Playwright 的 dragTo 并在失败时回退到鼠标拖拽。

大多数用户不需要配置这些高级选项，只有目标页面对拖拽事件非常敏感时再调整。

成功标准

• 源元素被拖到目标区域，页面出现预期状态变化。
• 后续等待节点能在目标区域找到拖拽后的元素。
• 运行日志中没有源元素、目标元素或拖拽事件错误。

失败排查

现象 / 报错原文	可能原因	处理建议
DragAndDrop requires "sourceSelector" or "sourceSelectorId"	未配置源元素	捕获或填写源元素选择器
DragAndDrop requires "targetSelector" or "targetSelectorId"	未配置目标元素	捕获或填写目标元素选择器
源元素或目标元素找不到	页面未加载、定位失效或 iframe 未配置	先等待元素，重新捕获，并检查 iframe
拖拽后页面没变化	页面不响应当前拖拽方式	尝试高级选项 useMouseEvents=true，或确认目标区域是否支持拖放
拖拽后状态更新慢	页面有动画或异步保存	拖拽后增加等待元素或等待页面状态

Python 代码编排

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

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

# 将任务卡片拖到目标列
bots.dragAndDropByObject(
    sourceSelector="//*[@id='task-1001']",
    targetSelector="//*[@id='done-column']",
)

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

常见问题

Q1：源元素和目标元素都必须配置吗？

A： 是的。缺少源元素或目标元素时，源码会直接报错。

Q2：拖拽一定能触发页面业务逻辑吗？

A： 不一定。不同网站监听拖拽事件的方式不同。默认方式不生效时，可以尝试启用鼠标事件拖拽，或调整源/目标位置。

Q3：拖拽后为什么要加等待？

A： 拖拽常常触发动画、异步保存或列表重新渲染。拖拽节点成功不代表业务状态已经完成，建议等待目标区域出现预期元素。

相关指令

• 浏览器自动化指令入门
• 鼠标悬停
• 点击元素（推荐）
• 等待元素存在