等待元素存在

等待元素存在 用于在后续操作前确认目标元素已经出现在页面 DOM 中。商业 RPA 产品通常都会把等待动作作为网页自动化的稳定性基础：先等待，再点击、输入或读取。

指令标识：WaitForElementPresent
指令类型：网页指令
指令描述：等待指定页面元素在DOM中出现，支持动态内容的等待检测

先选使用方式

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

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「等待元素存在」节点，捕获目标元素、设置超时	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 bots.waitForElementPresent(selector="...", timeout=10000)	熟悉代码、需要复用脚本或批量生成流程的用户

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

什么时候用？

• 打开网页后，等待页面关键区域加载完成。
• 点击按钮后，等待新页面、新弹窗或列表区域出现。
• 获取文本前，确认目标文本已经渲染到页面上。
• 输入文本前，确认输入框已经存在。

新手建议：只要下一步要操作页面元素，就先考虑是否需要等待。

使用前确认

• 浏览器已经打开，并处在目标页面或目标页面即将出现的状态。
• 元素选择器来自稳定元素，例如按钮文本、标题、列表容器。
• 等待的是“存在于 DOM”，不是“可见”。如果需要判断可见性，请使用 验证元素可见。
• 如果目标在 iframe 中，需要配置 iframe 页面定位器。

可视化编排：从 0 到跑通

1. 在打开网页、页面跳转或点击按钮之后添加 等待元素存在。
2. 捕获要等待的目标元素，例如页面标题、列表容器、按钮或输入框。
3. 设置合理的定位超时，例如 10000ms。
4. 将等待结果保存到变量，例如 is_page_ready。

成功时，指令会输出 true；超时仍未找到元素时，会输出 false。

最小示例

一个常见组合是：

1. 打开网页：打开目标网站。
2. 等待元素存在：等待页面关键按钮出现，输出 is_page_ready。
3. 点击元素：点击该按钮。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
元素选择器	selector / target	String	是	-	用于定位页面元素。建议从元素库捕获，或填写稳定 XPath/文本定位。
iframe 页面定位器	frameSelector	String	否	-	目标元素在 iframe 内时填写。
定位超时	timeout / findElementOptions.timeout	Number	否	10000	等待元素出现的最长时间，单位毫秒。

输出参数

界面名称	代码属性名	类型	必填	说明
将结果保存至	outKey	Boolean	否	保存等待结果。找到元素为 true，超时未找到为 false。

成功标准

• 输出变量为 true。
• 后续点击、输入或获取文本节点能继续执行。
• 日志中没有定位超时或 iframe 上下文错误。

失败排查

现象	可能原因	处理建议
返回 false	页面没有进入预期状态	先确认上一步是否真的打开或跳转成功
一直超时	元素定位不稳定或页面加载慢	重新捕获元素，适当调大定位超时
明明看得到但等不到	元素在 iframe、新窗口或弹窗里	配置 iframe，或先切换到正确窗口
返回 true 但点击失败	元素存在但不可见或被遮挡	改用等待可见、滚动到元素或重新捕获

Python 代码编排

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

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

# 等待元素出现，返回值即 True / False
is_ready = bots.waitForElementPresent(
    selector="//*[@id='root']/div/div/div[2]/div[2]",
    timeout=10000,
    outKey="isReady",
)

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

常见问题

Q1：该指令会阻塞执行吗？

A： 是的。该指令会阻塞执行，直到元素出现或超时。等待过程中会持续检查元素是否存在，一旦出现立即返回。

Q2：如果元素一开始就存在会怎样？

A： 如果元素一开始就存在于DOM中，指令会立即返回true，不会等待。

Q3：返回true表示什么？

A： 返回true表示在超时时间内元素出现在DOM中。返回false表示等待超时元素仍未出现。

Q4：该指令检查的是什么？

A： 该指令检查元素是否在DOM中存在，不关心元素的可见性状态。隐藏的元素（display:none或visibility:hidden）仍然存在于DOM中，会返回true。

相关指令

• 浏览器自动化指令入门
• 等待元素不存在
• 验证元素存在
• 验证元素可见
• 点击元素（推荐）