• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 鼠标事件
2
3在鼠标的单个动作触发多个事件时，事件的顺序是固定的，鼠标事件默认透传。
4
5>  **说明：**
6>
7>  - 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8>  - 目前仅支持通过外接鼠标触发。
9
10## onHover
11
12onHover(event: (isHover: boolean, event: HoverEvent) => void): T
13
14鼠标进入或退出组件时触发该回调。
15
16**系统能力：** SystemCapability.ArkUI.ArkUI.Full
17
18**参数：**
19
20| 参数名              | 类型                                | 必填 | 说明                                                         |
21| ------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ |
22| isHover             | boolean                             | 是   | 表示鼠标是否悬浮在组件上，鼠标进入时为true, 退出时为false。 |
23| event<sup>10+</sup> | [HoverEvent](#hoverevent10对象说明) | 是   | 设置阻塞事件冒泡属性。                                       |
24
25**返回值：**
26
27| 类型 | 说明 |
28| -------- | -------- |
29| T | 返回当前组件。 |
30
31## onMouse
32
33onMouse(event: (event: MouseEvent) => void)
34
35当前组件被鼠标按键点击时或者鼠标在组件上悬浮移动时，触发该回调。
36
37**系统能力：** SystemCapability.ArkUI.ArkUI.Full
38
39**参数：**
40
41| 参数名  | 类型                              | 必填 | 说明                                                         |
42| ------- | --------------------------------- | ---- | ------------------------------------------------------------ |
43| onMouse | [MouseEvent](#mouseevent对象说明) | 是   | 返回触发事件时的时间戳、鼠标按键、动作、鼠标位置在整个屏幕上的坐标和相对于当前组件的坐标。 |
44
45
46## MouseEvent对象说明
47
48| 名称                     | 属性类型                                     | 描述                           |
49| ---------------------- | ---------------------------------------- | ---------------------------- |
50| x                      | number                                   | 鼠标位置相对于当前组件左上角的x轴坐标。         |
51| y                      | number                                   | 鼠标位置相对于当前组件左上角的y轴坐标。         |
52| button                 | [MouseButton](ts-appendix-enums.md#mousebutton) | 鼠标按键。                        |
53| action                 | [MouseAction](ts-appendix-enums.md#mouseaction) | 鼠标动作。                        |
54| stopPropagation        | () => void                               | 阻塞事件冒泡。                      |
55| timestamp | number                                   | 事件时间戳。触发事件时距离系统启动的时间间隔，单位纳秒。 |
56| target    | [EventTarget](ts-universal-events-click.md#eventtarget8对象说明) | 触发事件的元素对象显示区域。               |
57| source    | [SourceType](ts-gesture-settings.md#sourcetype枚举说明) | 事件输入设备。                      |
58| windowX<sup>10+</sup> | number                          | 鼠标位置相对于应用窗口左上角的x轴坐标。 |
59| windowY<sup>10+</sup> | number                          | 鼠标位置相对于应用窗口左上角的y轴坐标。 |
60| displayX<sup>10+</sup> | number                         | 鼠标位置相对于应用屏幕左上角的x轴坐标。 |
61| displayY<sup>10+</sup> | number                         | 鼠标位置相对于应用屏幕左上角的y轴坐标。 |
62| screenX<sup>(deprecated)</sup> | number                 | 鼠标位置相对于应用窗口左上角的x轴坐标。<br>从API verdion 10开始不再维护，建议使用windowX代替。 |
63| screenY<sup>(deprecated)</sup> | number                 | 鼠标位置相对于应用窗口左上角的y轴坐标。<br>从API verdion 10开始不再维护，建议使用windowY代替。 |
64
65## HoverEvent<sup>10+</sup>对象说明
66
67| 名称              | 属性类型       | 描述      |
68| --------------- | ---------- | ------- |
69| stopPropagation | () => void | 阻塞事件冒泡。 |
70
71## 示例
72
73```ts
74// xxx.ets
75@Entry
76@Component
77struct MouseEventExample {
78  @State hoverText: string = 'no hover';
79  @State mouseText: string = '';
80  @State action: string = '';
81  @State mouseBtn: string = '';
82  @State color: Color = Color.Blue;
83
84  build() {
85    Column({ space: 20 }) {
86      Button(this.hoverText)
87        .width(180).height(80)
88        .backgroundColor(this.color)
89        .onHover((isHover: boolean, event: HoverEvent) => {
90          // 通过onHover事件动态修改按钮在是否有鼠标悬浮时的文本内容与背景颜色
91          if (isHover) {
92            this.hoverText = 'hover';
93            this.color = Color.Pink;
94          } else {
95            this.hoverText = 'no hover';
96            this.color = Color.Blue;
97          }
98        })
99      Button('onMouse')
100        .width(180).height(80)
101        .onMouse((event?: MouseEvent):void => {
102          if(event){
103            switch (event.button) {
104              case MouseButton.None:
105                this.mouseBtn = 'None';
106                break;
107              case MouseButton.Left:
108                this.mouseBtn = 'Left';
109                break;
110              case MouseButton.Right:
111                this.mouseBtn = 'Right';
112                break;
113              case MouseButton.Back:
114                this.mouseBtn = 'Back';
115                break;
116              case MouseButton.Forward:
117                this.mouseBtn = 'Forward';
118                break;
119              case MouseButton.Middle:
120                this.mouseBtn = 'Middle';
121                break;
122            }
123            switch (event.action) {
124              case MouseAction.Hover:
125                this.action = 'Hover';
126                break;
127              case MouseAction.Press:
128                this.action = 'Press';
129                break;
130              case MouseAction.Move:
131                this.action = 'Move';
132                break;
133              case MouseAction.Release:
134                this.action = 'Release';
135                break;
136            }
137            this.mouseText = 'onMouse:\nButton = ' + this.mouseBtn +
138            '\nAction = ' + this.action + '\nXY=(' + event.x + ',' + event.y + ')' +
139            '\nwindowXY=(' + event.windowX + ',' + event.windowY + ')';
140          }
141        })
142      Text(this.mouseText)
143    }.padding({ top: 30 }).width('100%')
144  }
145}
146```
147
148示意图：
149
150鼠标悬浮时改变文本内容与背景颜色：
151
152 ![mouse](figures/mouse.png)
153
154鼠标点击时：
155
156![mouse1](figures/mouse1.png)
157