鼠标悬停偏移

鼠标悬停偏移 用于把鼠标移动到“元素中心点 + 偏移量”的位置。它适合普通悬停无法触发目标区域时使用，例如图表热区、复杂菜单边缘、卡片内局部区域等。

指令标识：MouseOverOffset
指令类型：网页指令
指令描述：模拟鼠标悬停在指定元素相对位置的操作，可以精确控制悬停的坐标偏移

先选使用方式

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

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

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

什么时候用？

需要悬停到元素边缘或内部某个精确区域。
图表、地图、热力图等组件需要悬停特定点位。
普通鼠标悬停到中心点无法触发目标效果。
悬停区域位于元素内部但不是元素中心。

如果只需要悬停元素中心，优先使用鼠标悬停。

使用前确认

目标元素已经存在并可见。
已确认偏移基准是元素中心点，不是元素左上角。
偏移值单位是像素，X 正值向右，Y 正值向下。
偏移超出元素范围时，鼠标仍会移动到计算出来的位置。

可视化编排：从 0 到跑通

先让页面进入目标状态，例如图表或复杂菜单已经显示。
添加 鼠标悬停偏移 指令。
捕获作为偏移基准的目标元素。
设置 偏移X 和 偏移Y，例如 10、5。
悬停后添加等待节点，确认提示框、菜单或热区信息出现。

最小示例

一个悬停图表数据点的流程可以这样配置：

打开网页：进入报表页面。
等待元素存在：等待图表容器出现。
鼠标悬停偏移：以图表容器为基准，移动到目标数据点。
等待元素存在：等待 tooltip 出现。
获取文本：读取 tooltip 数据。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
元素选择器	`selector`	String	是	-	用于定位偏移基准元素。建议从元素库捕获。
偏移X	`offsetX`	Integer	是	-	相对元素中心点的水平偏移，正值向右、负值向左，单位像素。
偏移Y	`offsetY`	Integer	是	-	相对元素中心点的垂直偏移，正值向下、负值向上，单位像素。
iframe 页面定位器	`frameSelector`	String	否	-	高级选项，目标元素在 iframe 中时填写。
查找元素高级配置	`findElementOptions`	JSON	否	-	高级选项，JSON 格式，可在其中配置查找元素的超时时间等参数（如 `{"timeout": 5000}`），单位毫秒。

输出参数

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

坐标规则

源码会先获取元素边界框，然后移动到：

x = 元素左上角 x + 元素宽度 / 2 + offsetX
y = 元素左上角 y + 元素高度 / 2 + offsetY

也就是说，offsetX=0、offsetY=0 等同于悬停元素中心点。

成功标准

鼠标移动到目标元素中心点加偏移的位置。
页面出现预期 hover 效果，例如 tooltip、热区信息或菜单。
后续等待元素、点击或读取节点能继续执行。

失败排查

现象	可能原因	处理建议
节点报错：找不到目标元素（定位超时 / 元素未找到）	页面未加载完成或定位失效	悬停前先用「等待元素存在」确认元素出现，再重新捕获
报 `元素不可见，无法鼠标悬停`	元素已找到但不可见、没有有效边界框	先滚动到元素、等待可见状态或重新捕获元素
tooltip 没出现	偏移坐标没有落到触发区域	逐步调整 `offsetX` / `offsetY`，并截图确认位置
偏移方向理解错误	把左上角当成了原点	记住偏移原点是元素中心点

Python 代码编排

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

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

# 以图表容器中心为基准，向右 80px、向下 20px 悬停
bots.mouseOverOffset(
    selector="//div[@id='chart']",
    offsetX=80,
    offsetY=20,
)

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

常见问题

Q1：偏移是从哪里开始算？

A：从元素中心点开始算，不是左上角。0,0 表示元素中心。

Q2：偏移值可以是负数吗？

A：可以。offsetX 负数表示向左，offsetY 负数表示向上。

Q3：偏移超出元素范围会怎样？

A：鼠标仍会移动到计算出来的位置，但是否触发页面效果取决于该坐标下的实际元素。