拖拽到元素

拖拽到元素 用于在移动设备上把源元素拖拽到目标元素位置。它通过源元素选择器和目标元素选择器定位两端，常用于模拟用户拖拽行为、UI 交互测试、元素位置调整等场景。

指令标识：MobileDragAndDrop
指令类型：移动端指令
指令描述：拖动指定元素到目标元素位置

先选使用方式

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

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

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

什么时候用？

拖拽列表项改变其在列表中的位置，实现排序。
将卡片从一个容器拖拽到另一个容器，实现分类或组织。
拖拽元素到新位置，调整页面布局或元素排列。
将文件图标拖拽到上传区域，触发上传功能。
在不同容器或区域之间拖拽元素，实现元素转移。

使用前确认

源元素和目标元素都必须在当前屏幕可见范围内（找不到元素时会按失败处理中止，不会静默跳过）。
若拖拽目标在滚动容器外部，先使用根据方向滑动屏幕将其滚动至可视区域。
部分应用对拖拽手势有特殊要求（如长按后拖拽），必要时先长按源元素。
拖拽路径需在屏幕内，避免越界导致失败。

【图片占位 | command-mobiledraganddrop-config】
截图内容建议： 截一张可视化编排页面，画布选中「拖拽到元素」节点，右侧属性面板展示「源元素选择器」「目标元素选择器」「超时时间」区域。
标注建议： 用 ① 标出源元素选择器，用 ② 标出目标元素选择器，用 ③ 标出超时时间（高级参数），用 ④ 标出运行按钮。
用户看完应能明白： 这个指令需要填写源元素和目标元素两端的选择器，运行后会把源元素拖到目标位置。

可视化编排：从 0 到跑通

下面用一个常见场景演示：把某个按钮拖拽到导航栏的目标位置。按 3 步即可跑起来：

在画布中添加 拖拽到元素 指令。
在 源元素选择器 和 目标元素选择器 中分别填写两端定位器，例如：

源元素：//*[@text='直播中' and @content-desc='直播中']
目标元素：//*[@text='首页' and @content-desc='首页']

点击运行，确认源元素被拖拽到目标位置。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
源元素选择器	`sourceSelector`	String	是	-	要拖拽的源元素，可直接填写 `xpath` / 元素 prompt，或从元素库选择元素 id。
目标元素选择器	`targetSelector`	String	是	-	拖拽结束位置的元素定位，例如 `xpath`。
超时时间	`timeout`	Integer	否	`10000`	高级参数，查找元素的超时时间（毫秒）。

成功标准

源元素被成功拖拽到目标元素位置。
运行日志中没有元素查找失败或越界报错。
拖拽后页面状态符合预期（如排序变化、元素移动）。

失败排查

现象 / 报错原文	可能原因	处理建议
找不到源/目标元素	选择器不正确或元素不在可见区域	校验选择器；先滑动使元素进入可视区域
拖拽无效果	应用要求长按后拖拽等特殊手势	先使用长按坐标长按源元素
拖拽越界失败	拖拽路径超出屏幕范围	确保源和目标都在屏幕内
超时报错	元素加载较慢或超时时间过短	适当调大 `timeout`（最大 `60000ms`）

Python 代码编排

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

# 把源元素拖拽到目标元素位置
bots.mobileDragAndDrop(
    sourceSelector="//*[@text='直播中' and @content-desc='直播中']",
    targetSelector="//*[@text='首页' and @content-desc='首页']",
    timeout=10000,
)

可视化表单里的「源元素选择器」「目标元素选择器」「超时时间」分别对应代码里的 sourceSelector、targetSelector、timeout。

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

常见问题

Q1：元素不在可见区域怎么办？

A：源元素和目标元素必须在当前屏幕可见范围内。若拖拽目标在滚动容器外部，可先使用根据方向滑动屏幕将其滚动至可视区域。

Q2：iOS 和 Android 的拖拽有什么区别？

A： iOS / Harmony 端拖拽时间基于 duration；Android 默认 300ms，如需调整请显式传入 duration。拖拽路径需在屏幕内，避免越界导致失败。

Q3：超时时间如何设置？

A： timeout 为大于 0 的整数，最大不超过 60000ms，默认 10000（10 秒）适用于大多数场景。

Q4：拖拽失败如何排查？

A：部分应用对拖拽手势有特殊要求（如长按后拖拽）。如遇拖拽失败，可尝试先使用长按坐标长按源元素。