等待元素存在

等待元素存在 用于在移动端通过元素选择器定位目标元素，等待它出现在当前屏幕中，返回结果（True / False）后继续执行。常用于等待页面加载、弹窗出现、列表数据就绪等需要等待的场景。

指令标识：MobileWaitForElementPresent
指令类型：移动端指令
指令描述：等待手机当前屏幕中的特定 UI 元素存在，返回结果（True 或 False），成功后继续执行

先选使用方式

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

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

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

什么时候用？

等待页面关键元素出现，确认页面加载完成后再操作。
等待弹窗、Toast 提示出现。
等待列表项或动态内容加载完成。

如果要等待元素消失，请使用等待元素不存在。

使用前确认

已准备好稳定的元素选择器（推荐 xpath）。
已规划好「将结果保存至」的变量名，用于引用布尔结果。
该指令属于元素定位类，默认失败即中止（报错中止）：超时仍未出现会抛出异常。
对异步动画后才出现的元素，应设置合理的超时时间。

【图片占位 | command-mobilewaitforelementpresent-config】
截图内容建议： 截一张可视化编排页面，画布选中本节点，右侧属性面板展示「元素选择器」「将结果保存至」与高级区的「超时时间」。
标注建议： 用 ① 标出节点，用 ② 标出元素选择器，用 ③ 标出结果变量名，用 ④ 标出超时时间。
用户看完应能明白： 主要填选择器 + 结果变量名，超时时间为高级项。

可视化编排：从 0 到跑通

下面用一个常见场景演示：等待底部「我的」入口出现后再点击。按 4 步即可跑起来：

在前序流程中打开 App 并进入目标页面。
添加 等待元素存在 节点，在 元素选择器 中选择或填写：

//*[@content-desc='我的']

在 将结果保存至 填写变量名（如 appeared），按需设置 超时时间（默认 10000）。
点击运行，确认元素出现后返回 true，再接点击等后续操作。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
元素选择器	`selector`	String	是	-	元素定位方式，推荐 `xpath`，不能为空
超时时间	`timeout`	Integer	否	`10000`	高级选项。查找元素的最大等待时间（毫秒），为大于 0 的整数，最大不超过 `60000`

输出参数

界面名称	代码属性名	类型	必填	说明
将结果保存至	`outKey`	Boolean	否	保存结果：`true` 表示元素存在，`false` 表示元素不存在；不填则结果无法被后续节点引用

成功标准

在超时时间内元素出现，结果变量得到 true。
流程在元素出现后继续执行。

运行后你会看到（以上面场景为例）：

「我的」入口出现，变量 appeared 得到 true，可继续点击进入下一步。

失败排查

现象 / 报错原文	可能原因	处理建议
等待超时报错	元素始终未出现或超时过短	适当调大 `timeout`，确认前序操作已触达目标页面
选择器匹配不到	选择器有误	核对选择器是否能正确定位目标元素
元素异步出现后才匹配	动画 / 异步加载较慢	在 `0` 到 `60000` 范围内合理增大 `timeout`

Python 代码编排

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

# 等待「我的」入口出现，结果保存到 appeared
bots.mobileWaitForElementPresent(
    selector="//*[@content-desc='我的']",
    outKey="appeared",
)

如元素出现较慢，可调大超时时间：

bots.mobileWaitForElementPresent(
    selector="//*[@content-desc='我的']",
    timeout=10000,
    outKey="appeared",
)

可视化表单里的「元素选择器」「超时时间」「将结果保存至」分别对应代码里的 selector、timeout、outKey。

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

常见问题

Q1：返回值是什么类型？

A：返回布尔值，true 表示元素确实存在 / 可见。

Q2：元素在异步动画后才出现怎么办？

A：请合理设置 timeout。其为大于 0 的整数，最大不超过 60000 毫秒。

Q3：该指令何时使用？

A：当需要断言某元素将要出现于当前页面、并在其出现后再继续时使用。

Q4：超时时间如何设置？

A：根据实际场景设置合适的超时，避免过长或过短；动态加载元素建议预留足够等待时间。