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