1# 鼠标事件 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9在鼠标的单个动作触发多个事件时，事件的顺序是固定的，鼠标事件默认透传。 10 11> **说明：** 12> 13> - 从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> - 目前仅支持通过外接鼠标触发。 15 16## onMouse 17 18onMouse(event: (event: MouseEvent) => void): T 19 20当前组件被鼠标按键点击时或者鼠标在组件上悬浮移动时，触发该回调。 21 22**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 23 24**系统能力：** SystemCapability.ArkUI.ArkUI.Full 25 26**参数：** 27 28| 参数名 | 类型 | 必填 | 说明 | 29| ------- | --------------------------------- | ---- | ------------------------------------------------------------ | 30| event | (event: [MouseEvent](#mouseevent对象说明)) => void | 是 | 返回触发事件时的时间戳、鼠标按键、动作、鼠标位置在整个屏幕上的坐标和相对于当前组件的坐标。 | 31 32**返回值：** 33 34| 类型 | 说明 | 35| -------- | -------- | 36| T | 返回当前组件。 | 37 38## MouseEvent对象说明 39 40继承于[BaseEvent](ts-gesture-customize-judge.md#baseevent8)。 41 42**系统能力：** SystemCapability.ArkUI.ArkUI.Full 43 44| 名称 | 类型 | 只读 | 可选 | 说明 | 45| ---------------------- | -------------------------------------- |-------------- |------------- | --------------------------- | 46| x | number | 否 | 否 |鼠标位置相对于当前组件左上角的x轴坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 47| y | number | 否 | 否 |鼠标位置相对于当前组件左上角的y轴坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 48| button | [MouseButton](ts-appendix-enums.md#mousebutton8) | 否 | 否 |鼠标按键。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 49| action | [MouseAction](ts-appendix-enums.md#mouseaction8) | 否 | 否 |鼠标动作。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 50| stopPropagation | () => void | 否 | 否 |阻塞[事件冒泡](../../../ui/arkts-interaction-basic-principles.md#事件冒泡)。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 51| windowX<sup>10+</sup> | number | 否 | 否 |鼠标位置相对于应用窗口左上角的x轴坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 52| windowY<sup>10+</sup> | number | 否 | 否 |鼠标位置相对于应用窗口左上角的y轴坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 53| displayX<sup>10+</sup> | number | 否 | 否 |鼠标位置相对于应用屏幕左上角的x轴坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 54| displayY<sup>10+</sup> | number | 否 | 否 |鼠标位置相对于应用屏幕左上角的y轴坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 55| screenX<sup>(deprecated)</sup> | number | 否 | 否 |鼠标位置相对于应用窗口左上角的x轴坐标。<br>单位：vp<br/>从API version 10开始不再维护，建议使用windowX代替。 | 56| screenY<sup>(deprecated)</sup> | number | 否 | 否 |鼠标位置相对于应用窗口左上角的y轴坐标。<br>单位：vp<br/>从API version 10开始不再维护，建议使用windowY代替。 | 57| rawDeltaX<sup>15+</sup> | number | 否 | 是 |相对于先前上报的鼠标指针位置的X轴偏移量。当鼠标指针处于屏幕边缘时，该值可能小于两次上报的X坐标之差。<br/>单位：vp<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 58| rawDeltaY<sup>15+</sup> | number | 否 | 是 |相对于先前上报的鼠标指针位置的Y轴偏移量。<br/>单位：vp<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 59| pressedButtons<sup>15+</sup> | MouseButton[] | 否 | 是 |所有鼠标上按着的按钮集合。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 60| globalDisplayX<sup>20+</sup> | number | 否 | 是 |鼠标位置相对于全局屏幕的左上角的X坐标。<br/>单位：vp<br/>取值范围：[0, +∞)<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 61| globalDisplayY<sup>20+</sup> | number | 否 | 是 |鼠标位置相对于全局屏幕的左上角的Y坐标。<br/>单位：vp<br/>取值范围：[0, +∞)<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 62 63## 示例 64 65该示例通过按钮设置了鼠标事件，通过鼠标点击按钮可以触发onMouse事件，获取鼠标事件相关参数。 66鼠标滚轮的处理请参考[轴事件示例](ts-universal-events-axis.md#示例)。 67 68```ts 69// xxx.ets 70@Entry 71@Component 72struct MouseEventExample { 73 @State hoverText: string = 'no hover'; 74 @State mouseText: string = ''; 75 @State action: string = ''; 76 @State mouseBtn: string = ''; 77 @State color: Color = Color.Blue; 78 79 build() { 80 Column({ space: 20 }) { 81 Button(this.hoverText) 82 .width(180).height(80) 83 .backgroundColor(this.color) 84 .onHover((isHover: boolean, event: HoverEvent) => { 85 // 通过onHover事件动态修改按钮在是否有鼠标悬浮时的文本内容与背景颜色 86 if (isHover) { 87 this.hoverText = 'hover'; 88 this.color = Color.Pink; 89 } else { 90 this.hoverText = 'no hover'; 91 this.color = Color.Blue; 92 } 93 }) 94 Button('onMouse') 95 .width(180).height(80) 96 .onMouse((event: MouseEvent): void => { 97 if (event) { 98 switch (event.button) { 99 case MouseButton.None: 100 this.mouseBtn = 'None'; 101 break; 102 case MouseButton.Left: 103 this.mouseBtn = 'Left'; 104 break; 105 case MouseButton.Right: 106 this.mouseBtn = 'Right'; 107 break; 108 case MouseButton.Back: 109 this.mouseBtn = 'Back'; 110 break; 111 case MouseButton.Forward: 112 this.mouseBtn = 'Forward'; 113 break; 114 case MouseButton.Middle: 115 this.mouseBtn = 'Middle'; 116 break; 117 } 118 switch (event.action) { 119 case MouseAction.Hover: 120 this.action = 'Hover'; 121 break; 122 case MouseAction.Press: 123 this.action = 'Press'; 124 break; 125 case MouseAction.Move: 126 this.action = 'Move'; 127 break; 128 case MouseAction.Release: 129 this.action = 'Release'; 130 break; 131 } 132 this.mouseText = 'onMouse:\nButton = ' + this.mouseBtn + 133 '\nAction = ' + this.action + '\nXY=(' + event.x + ',' + event.y + ')' + 134 '\nwindowXY=(' + event.windowX + ',' + event.windowY + ')' + 135 '\ntargetDisplayId = ' + event.targetDisplayId + 136 '\nrawDeltaX = ' + event.rawDeltaX + 137 '\nrawDeltaY = ' + event.rawDeltaY + 138 '\nlength = ' + event.pressedButtons?.length; 139 } 140 }) 141 Text(this.mouseText) 142 }.padding({ top: 30 }).width('100%') 143 } 144} 145``` 146 147示意图： 148 149鼠标点击时： 150 151 152
