验证元素可见

验证元素可见 用于验证网页指定元素是否对用户可见（元素既存在又未被隐藏）。它常用于页面状态验证、元素可见性检查和自动化测试断言等场景。

指令标识：VerifyElementVisible
指令类型：网页指令
指令描述：验证指定页面元素是否对用户可见，包括元素存在且未被隐藏

先选使用方式

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

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「验证元素可见」节点，填写元素选择器和输出变量	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 `result = bots.verifyElementVisible(selector="...", outKey="result")`	熟悉代码、需要复用脚本或批量生成流程的用户

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

什么时候用？

检查页面上的关键元素（按钮、表单等）是否对用户可见。
验证 UI 组件的显示状态，确保页面布局符合预期。
在自动化测试中验证元素可见性，确保测试准确性。
验证通过 JavaScript 动态显示或隐藏的元素是否可见。
根据元素可见性执行不同的操作逻辑。

使用前确认

目标元素已经出现，必要时先使用等待元素存在。
已规划好用于保存验证结果的输出变量名。
如果目标元素在 iframe 中，需要配置 iframe 页面定位器。
明确验证失败时希望「输出结果继续」还是「抛出异常中断」。

可视化编排：从 0 到跑通

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

先用打开网页打开目标页面，并确认目标元素已出现。
在工作流画布中添加 验证元素可见 节点。
在 元素选择器 填写目标元素。
在 将结果保存至 中填写变量名，点击运行后查看结果（true/false）。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
元素选择器	`selector`	String	是	-	用于定位的页面元素选择器，不能为空，支持从元素库选择元素或手动填写 XPath 等定位器值。
False结果处理	`falseResultHandling`	Enum	否	`OUTPUT_RESULT`	高级参数，验证结果为 False 时的处理方式：`OUTPUT_RESULT`（输出结果，默认）、`THROW_EXCEPTION`（抛出异常）。
iframe页面定位器	`frameSelector`	String	否	-	高级参数，目标元素在 iframe 内时填写其 xpath，`eg：//html/iframe`。
查找元素高级配置	`findElementOptions`	JSON	否	-	高级参数，查找元素的高级配置（JSON），可在其中设置定位超时时间（`timeout`，单位毫秒）等。

输出参数

界面名称	代码属性名	类型	必填	说明
将结果保存至	`outKey`	Boolean	否	填写变量名称（`eg：isVisible`），保存验证结果（`true`/`false`）。

成功标准

运行日志中节点为成功状态。
输出变量中为布尔值，符合对元素可见性的预期判断。
选择 OUTPUT_RESULT 时，验证为 False 也会输出结果并继续后续流程。

失败排查

现象 / 报错原文	可能原因	处理建议
验证失败时流程中断	`falseResultHandling` 设为 `THROW_EXCEPTION`	如需继续流程，改为默认的 `OUTPUT_RESULT`
结果为 `false` 但元素应可见	元素未渲染完成或被隐藏	在 `findElementOptions` 中增大 `timeout`，或先等待元素存在
元素存在但读不到	目标在 iframe 中	配置 `frameSelector` 后重试
被遮挡仍判定可见	可见性基于渲染状态	被其他元素遮挡的情况可能不会被检测为不可见，需结合业务判断

Python 代码编排

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

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

# 验证元素是否可见，返回值即布尔结果
# 该指令无独立的顶层超时参数，定位超时通过 findElementOptions 配置
result = bots.verifyElementVisible(
    selector="//h1[@class='page-title']",
    findElementOptions={"timeout": 5000},
    falseResultHandling="OUTPUT_RESULT",
    outKey="result",
)
print(result)

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

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

常见问题

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

A：该指令检查元素的可见性状态，包括 display、visibility、opacity 等 CSS 属性的影响。元素必须存在且对用户可见才会返回 true。

Q2：如果元素不存在会怎样？

A：如果元素不存在，会认为元素不可见，返回 false，不会抛出异常。

Q3：可见性判断基于什么？

A：可见性判断基于浏览器的渲染状态。被其他元素遮挡的情况可能不会被检测为不可见。

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

A：验证元素存在只检查元素是否存在于 DOM 中，不关心可见性；验证元素可见则要求元素既存在又对用户可见。

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

A：该参数用于控制验证失败时的执行行为（括号内为需传入的参数值）：

输出结果（OUTPUT_RESULT，默认）：验证失败时输出 false 结果到 outKey，继续执行后续流程。

抛出异常（THROW_EXCEPTION）：验证失败时抛出异常，中断当前流程执行。