鼠标悬停

鼠标悬停 用于把鼠标移动到指定网页元素的中心位置，触发页面上的 hover 效果，例如显示下拉菜单、工具提示、操作按钮或悬停卡片。

指令标识：MouseOver
指令类型：网页指令
指令描述：模拟鼠标悬停在指定元素上的操作，会将鼠标移动到元素中心位置

先选使用方式

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

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

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

什么时候用？

悬停导航菜单，显示二级菜单。
悬停图标或按钮，显示工具提示。
悬停列表项，显示隐藏操作按钮。
触发页面上的 mouseover / mouseenter 交互。

如果需要悬停到元素的特定位置，请使用鼠标悬停偏移；如果要点击元素，请使用点击元素。

使用前确认

目标元素已经存在，必要时先使用等待元素存在。
目标元素可见并有可计算的边界框。
悬停后如果页面有动画或延迟，后面需要等待目标菜单或提示出现。
如果目标元素在 iframe 中，需要配置 iframe 页面定位器。

可视化编排：从 0 到跑通

先让页面进入目标状态，例如导航栏已经显示。
添加 鼠标悬停 指令。
捕获要悬停的目标元素，例如导航菜单入口。
悬停后添加等待元素存在，等待下拉菜单或提示出现。
后续再点击、读取或继续操作悬停后出现的元素。

最小示例

一个打开下拉菜单的流程可以这样配置：

打开网页：进入后台首页。
等待元素存在：等待导航菜单入口出现。
鼠标悬停：悬停在菜单入口上。
等待元素存在：等待二级菜单出现。
点击元素：点击二级菜单项。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
元素选择器	`selector`	String	是	-	用于定位要悬停的网页元素，不能为空，支持 CSS 选择器、XPath 等。建议从元素库捕获。
iframe 页面定位器	`frameSelector`	String	否	-	高级参数，目标元素在 iframe 中时填写其 xpath。
查找元素高级配置	`findElementOptions`	JSON	否	-	高级参数，查找元素的高级配置，可在其中设置定位超时时间（`timeout`）等，以 JSON 配置。

输出参数

该指令没有业务输出变量，主要副作用是触发鼠标悬停相关交互。是否成功应通过页面状态、运行日志和后续等待节点判断。

成功标准

鼠标移动到目标元素中心位置。
页面出现预期 hover 效果，例如菜单、提示或隐藏按钮。
后续等待元素、点击或读取节点能继续执行。

失败排查

现象	可能原因	处理建议
节点报错：找不到目标元素（定位超时 / 元素未找到）	页面未加载完成或定位失效	悬停前先用「等待元素存在」确认元素出现，再重新捕获
报 `元素不可见，无法鼠标悬停`	元素不可见或没有有效边界框	先滚动到元素、等待可见状态或重新捕获元素
悬停后菜单没出现	页面有动画延迟或目标元素不对	悬停后增加等待元素存在，并确认捕获的是触发 hover 的父元素
需要悬停到边缘区域	默认悬停在元素中心点	改用鼠标悬停偏移

Python 代码编排

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

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

# 悬停在菜单入口上
bots.mouseOver(
    selector="//nav//span[text()='商品管理']",
    findElementOptions={"timeout": 5000},
)

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

常见问题

Q1：鼠标会移动到元素的哪个位置？

A：默认移动到元素中心位置。需要精确偏移时，使用鼠标悬停偏移。

Q2：悬停会触发点击吗？

A：不会。它只移动鼠标并触发 hover 相关事件，不会点击元素。

Q3：为什么悬停后看不到效果？

A：常见原因是目标元素不对、页面有动画延迟、菜单需要悬停父级元素，或后续节点执行太快。建议悬停后等待菜单元素出现。