# 悬浮事件

光标滑动或手写笔在屏幕上悬浮移动扫过组件时触发。

*   从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
    
*   目前支持通过外接鼠标以及触控板触发。部分手写笔（当前在华为智慧屏MateTV、MateTV Pro中使用灵犀手写笔时无法响应悬浮事件）不支持悬浮事件，具体取决于硬件能力。
    

#### onHover

onHover(event: (isHover: boolean, event: HoverEvent) => void): T

鼠标或手写笔进入或退出组件时，触发hover事件。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | (isHover: boolean, event: HoverEvent) => void | 是 | 鼠标的状态信息。 event表示设置阻塞事件冒泡属性，并获取鼠标或手写笔悬浮的位置坐标，从API version 11开始支持。 isHover表示鼠标或手写笔是否悬浮在组件上，进入时为true， 离开时为false。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| T | 返回当前组件。 |

#### onHoverMove15+

onHoverMove(event: Callback<HoverEvent>): T

手写笔悬浮于组件上方时触发悬浮移动事件。

**元服务API：** 从API version 15开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | Callback<HoverEvent> | 是 | 设置阻塞事件冒泡属性，并获取手写笔悬浮的位置坐标。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| T | 返回当前组件。 |

#### HoverEvent10+对象说明

继承于BaseEvent。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| x15+ | number | 否 | 是 | 鼠标光标或手写笔位置在当前组件为基准的组件坐标系中的X坐标。 单位：vp 取值范围：[0, +∞) 元服务API： 从API version 15开始，该接口支持在元服务中使用。 |
| y15+ | number | 否 | 是 | 鼠标光标或手写笔位置在当前组件为基准的组件坐标系中的Y坐标。 单位：vp 取值范围：[0, +∞) 元服务API： 从API version 15开始，该接口支持在元服务中使用。 |
| windowX15+ | number | 否 | 是 | 鼠标光标或手写笔位置在当前应用窗口坐标系中的X坐标。 单位：vp 取值范围：[0, +∞) 元服务API： 从API version 15开始，该接口支持在元服务中使用。 |
| windowY15+ | number | 否 | 是 | 鼠标光标或手写笔位置在当前应用窗口坐标系中的Y坐标。 单位：vp 取值范围：[0, +∞) 元服务API： 从API version 15开始，该接口支持在元服务中使用。 |
| displayX15+ | number | 否 | 是 | 鼠标光标或手写笔位置在当前应用屏幕坐标系中的X坐标。 单位：vp 取值范围：[0, +∞) 元服务API： 从API version 15开始，该接口支持在元服务中使用。 |
| displayY15+ | number | 否 | 是 | 鼠标光标或手写笔位置在当前应用屏幕坐标系中的Y坐标。 单位：vp 取值范围：[0, +∞) 元服务API： 从API version 15开始，该接口支持在元服务中使用。 |
| stopPropagation | () => void | 否 | 否 | 阻塞事件冒泡。 元服务API： 从API version 11开始，该接口支持在元服务中使用。 |
| globalDisplayX20+ | number | 否 | 是 | 鼠标光标或手写笔位置在全局坐标系中的X坐标。 单位：vp 取值范围：(-∞, +∞) 元服务API： 从API version 20开始，该接口支持在元服务中使用。 |
| globalDisplayY20+ | number | 否 | 是 | 鼠标光标或手写笔位置在全局坐标系中的Y坐标。 单位：vp 取值范围：(-∞, +∞) 元服务API： 从API version 20开始，该接口支持在元服务中使用。 |

#### 示例

#### 示例1（使用onHover）

该示例通过按钮设置了悬浮事件onHover，鼠标悬浮可触发该事件修改按钮颜色。

```
// xxx.ets
@Entry
@Component
struct HoverEventExample {
  @State hoverText: string = 'no hover';
  @State color: Color = Color.Blue;

  build() {
    Column({ space: 20 }) {
      Button(this.hoverText, { type: ButtonType.Capsule })
        .width(180).height(80)
        .backgroundColor(this.color)
        .onHover((isHover: boolean, event: HoverEvent) => {
          // 通过onHover事件动态修改按钮在是否有鼠标或手写笔悬浮时的文本内容与背景颜色
          // 通过event.sourceTool区分设备是鼠标还是手写笔
          if (isHover) {
            if (event.sourceTool == SourceTool.Pen) {
              this.hoverText = 'pen hover';
              this.color = Color.Pink;
            } else if (event.sourceTool == SourceTool.MOUSE) {
              this.hoverText = 'mouse hover';
              this.color = Color.Red;
            }
          } else {
            this.hoverText = 'no hover';
            this.color = Color.Blue;
          }
        })
    }.padding({ top: 30 }).width('100%')
  }
}
```

示意图：

未悬浮时的文本内容与背景颜色：

手写笔悬浮时改变文本内容与背景颜色：

#### 示例2（使用onHoverMove）

从API version 15开始，该示例设置了按钮的onHoverMove事件。当手写笔悬浮在按钮时，UI界面会显示当前手写笔悬浮状的位置。

```
// xxx.ets
@Entry
@Component
struct OnHoverMoveEventExample {
  @State hoverMoveText: string = '';

  build() {
    Column({ space: 20 }) {
      Button('onHoverMove', { type: ButtonType.Capsule })
        .width(180).height(80)
        .onHoverMove((event: HoverEvent) => {
          this.hoverMoveText = 'onHoverMove:\nXY = (' + event.x + ', ' + event.y + ')' +
                               '\nwindowXY = (' + event.windowX + ', ' + event.windowY + ')' +
                               '\ndisplayXY = (' + event.displayX + ', ' + event.displayY + ')';
        })

      Text(this.hoverMoveText)
    }.padding({ top: 30 }).width('100%')
  }
}
```

示意图：

手写笔悬浮在Button组件上时，UI不断刷新笔尖的位置信息：