等待元素不存在

等待元素不存在 用于持续检查指定页面元素是否已从 DOM 中消失，并在元素不存在或等待超时后返回结果。它常用于等待弹窗关闭、加载遮罩移除、删除后的记录从页面消失等场景。

指令标识：WaitForElementNotPresent
指令类型：网页指令
指令描述：等待指定页面元素从 DOM 中消失

先选使用方式

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

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「等待元素不存在」节点，在右侧表单填写元素选择器、等待超时和输出变量	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 bots.waitForElementNotPresent(selector="...", timeout=10000, outKey="notPresent")	熟悉代码、需要复用脚本或批量生成流程的用户

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

什么时候用？

• 等待加载中的动画或进度条从 DOM 中消失，确认加载完成。
• 等待弹窗、对话框或提示消息移除，确认交互完成。
• 等待删除操作后的元素从 DOM 中移除。
• 等待页面遮罩层消失，确认页面可交互。

如果只是要断言元素当前不存在，可以使用 验证元素不存在；如果元素只是不可见但仍在 DOM 中，应使用可见性相关指令。

使用前确认

• 浏览器已打开目标页面（通常先执行 打开网页）。
• 元素选择器（CSS 选择器或 XPath）填写正确。
• 已确认目标状态是“从 DOM 中消失”，而不是仅仅隐藏。
• 如果目标元素在 iframe 中，已准备好 iframe 的定位器（frameSelector）。
• 等待超时足够覆盖页面动画、接口响应或异步渲染耗时。

可视化编排：从 0 到跑通

下面用一个常见场景演示：关闭后台设置弹窗后，等待弹窗节点从页面移除。按 4 步即可跑起来：

1. 先添加 打开网页 打开目标页面，并完成打开、关闭弹窗的操作。
2. 添加 等待元素不存在 节点。
3. 在 元素选择器 中填写弹窗节点定位器，并设置等待超时：

//div[@data-testid='settings-dialog']

4. 点击运行，确认输出变量得到 true。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
元素选择器	selector	String	是	-	用于定位的页面元素选择器，不能为空，支持从元素库选择或手动填写 XPath 等定位器值。
等待超时	timeout	Double	否	10000	高级参数。等待操作的最大超时时间，单位毫秒，超时后停止等待，最小值为 0。
iframe页面定位器	frameSelector	String	否	-	高级参数。iframe 的 XPath，目标元素在 iframe 中时填写，例如 //html/iframe。

输出参数

界面名称	代码属性名	类型	必填	说明
将结果保存至	outKey	Boolean	是	保存等待结果，true 表示元素在超时前消失，false 表示超时仍存在，例如变量名 notPresent。

成功标准

• 节点运行成功，日志中没有异常。
• 输出变量得到布尔结果：true 表示元素在超时时间内不存在于 DOM 中，false 表示等待超时后元素仍存在。
• 如果元素一开始就不存在，指令会立即返回 true。
• 后续节点可以在遮罩、弹窗或目标元素消失后继续执行。

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

• 输出变量 notPresent 的值为 true。
• 弹窗节点已经从 DOM 中移除，后续页面操作不再被弹窗阻挡。

失败排查

现象 / 报错原文	可能原因	处理建议
等待超时，结果为 false	元素仍存在于 DOM 中	确认触发删除、关闭或加载完成的前置操作已成功
元素看不见但仍返回 false	元素只是隐藏，没有从 DOM 中移除	改用可见性相关验证或等待指令
一直等不到 iframe 内元素消失	未填写 iframe 定位器	在 frameSelector 中填写 iframe 的 XPath
偶发失败	页面异步耗时不稳定	适当调大 timeout，并确认选择器足够稳定
选择器定位到多个元素	页面中存在多个匹配节点	使用更精确的 CSS 选择器或 XPath，只定位目标元素

Python 代码编排

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

# 关闭后台设置弹窗后，等待弹窗节点从 DOM 中消失
bots.openUrl(url="https://example.com/settings")
bots.waitForElementNotPresent(
    selector="//div[@data-testid='settings-dialog']",
    timeout=10000,
    outKey="notPresent",
)

如果目标元素在 iframe 中，可以补充 frameSelector：

bots.waitForElementNotPresent(
    selector="//div[@data-testid='settings-dialog']",
    frameSelector="//html/iframe",
    timeout=10000,
    outKey="notPresent",
)

可视化表单里的「元素选择器」「等待超时」「iframe页面定位器」「将结果保存至」分别对应代码里的 selector、timeout、frameSelector、outKey。

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

常见问题

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

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

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

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

Q3：返回 true 表示什么？

A： 返回 true 表示在超时时间内元素从 DOM 中消失；返回 false 表示超时后元素仍存在。

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

A： 检查元素是否从 DOM 中完全移除，而不是仅仅隐藏。隐藏的元素（display:none 或 visibility:hidden）仍存在于 DOM 中，会返回 false。

相关指令

• 等待元素存在
• 验证元素不存在
• 验证元素存在
• 点击元素（推荐）