验证元素存在

验证元素存在 用于检查指定网页元素是否存在于 DOM 中，并输出布尔结果。它只判断元素是否存在，不关心元素是否可见，常用于页面状态验证、操作结果断言和条件判断。

指令标识：VerifyElementPresent
指令类型：网页指令
指令描述：验证指定页面元素是否存在于 DOM 中，不关心元素的可见性状态

先选使用方式

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

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

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

什么时候用？

• 验证关键按钮、链接、表单控件等是否已渲染到页面。
• 断言某个操作后目标元素是否按预期出现。
• 作为条件判断，根据元素是否存在决定后续分支。

如果需要进一步判断元素是否可见，请使用 验证元素可见。

使用前确认

• 已准备好稳定的元素选择器（支持从元素库选择或手动填写 XPath 等）。
• 目标页面已打开；动态内容建议预留查找等待时间。
• 已规划好「将结果保存至」的变量名，用于引用布尔结果。
• 默认 False结果处理 为 输出结果（OUTPUT_RESULT）：验证失败时输出 false 并继续流程；若希望验证失败即中止，可改为 抛出异常（THROW_EXCEPTION）。
• 若元素在 iframe 中，需填写 iframe 页面定位器。

可视化编排：从 0 到跑通

下面用一个常见场景演示：打开页面后，验证标题元素是否存在。按 4 步即可跑起来：

1. 在前序流程中通过 打开网页 打开目标页面。
2. 添加 验证元素存在 节点，在 元素选择器 中选择或填写：

//*[@id='__next']/div[2]/div[2]/section/div[1]/h1

3. 在 将结果保存至 填写变量名（如 verifyResult）。如内容动态加载，可在「查找元素高级配置」设置 timeout。
4. 点击运行，确认元素存在时返回 true。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
元素选择器	selector	String	是	-	用于定位页面元素的选择器，不能为空，支持 CSS、XPath 等格式，例如 #myButton、//div[@id='test']
iframe页面定位器	frameSelector	String	否	-	高级选项。iframe 的 XPath，目标元素在 iframe 中时填写，例如 //html/iframe
查找元素高级配置	findElementOptions	JSON	否	{"timeout":5000}	高级选项。元素查找配置，可设置元素定位超时，单位毫秒，默认 5000，设为 0 表示不等待
False结果处理	falseResultHandling	Enum	否	OUTPUT_RESULT	高级选项。验证为 False 时的行为：OUTPUT_RESULT（输出结果并继续）、THROW_EXCEPTION（抛出异常中断）

输出参数

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

成功标准

• 运行成功，结果变量得到布尔值。
• DOM 中存在匹配元素时返回 true。

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

• 标题元素存在，变量 verifyResult 得到 true，流程继续向下执行。

失败排查

现象 / 报错原文	可能原因	处理建议
返回 false	元素尚未渲染或选择器有误	核对选择器，在 findElementOptions 中增大 timeout
直接抛异常中断	falseResultHandling 设为 THROW_EXCEPTION	如需继续流程，改为 OUTPUT_RESULT
元素隐藏但仍返回 true	该指令只判断存在，不判断可见	如需判断可见性，改用 验证元素可见
iframe 内元素找不到	未填写 iframe 定位器	在「iframe页面定位器」填写对应 XPath

Python 代码编排

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

# 先打开目标页面
bots.openUrl(url="https://example.com")
# 验证元素是否存在，结果保存到 verifyResult
bots.verifyElementPresent(
    selector="//*[@id='__next']/div[2]/div[2]/section/div[1]/h1",
    outKey="verifyResult",
)

如需自定义查找超时，并在验证失败时继续：

bots.verifyElementPresent(
    selector="//*[@id='__next']/div[2]/div[2]/section/div[1]/h1",
    findElementOptions='{"timeout":5000}',
    falseResultHandling="OUTPUT_RESULT",
    outKey="verifyResult",
)

可视化表单里的「元素选择器」「查找元素高级配置」「False结果处理」「将结果保存至」分别对应代码里的 selector、findElementOptions、falseResultHandling、outKey。

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

常见问题

Q1：选择器匹配到多个元素会怎样？

A： 只要存在至少一个匹配元素就返回 true。需要精确匹配单个元素时，请优化选择器确保唯一性。

Q2：返回结果是什么类型？

A： 布尔值。true 表示 DOM 中存在匹配元素，false 表示未找到。

Q3：该指令检查可见性吗？

A： 不检查。即使元素被隐藏（display: none 或 visibility: hidden），只要存在于 DOM 中就返回 true。需要检查可见性请用 验证元素可见。

Q4：验证元素存在和验证元素可见有什么区别？

A： 两者主要区别如下：

特性	验证元素存在	验证元素可见
检查 DOM 存在	是	是
检查可见性	否	是
隐藏元素结果	true	false
使用场景	基本存在性验证	可见性验证

Q5：False结果处理如何使用？

A： 用于控制验证失败时的行为：OUTPUT_RESULT（默认）输出 false 并继续；THROW_EXCEPTION 抛出异常中断流程。

相关指令

• 验证元素可见
• 点击元素（推荐）
• 获取文本
• 等待元素存在