1# 无障碍悬浮事件 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @zhanghangkai10241--> 5<!--Designer: @lmleon--> 6<!--Tester: @fredyuan0912--> 7<!--Adviser: @HelloCrease--> 8 9在开启无障碍模式后，Touch事件会转换为无障碍悬浮事件。 10 11> **说明：** 12> 13> - 从API version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> - 目前仅支持通过开启无障碍模式触发。 15 16## onAccessibilityHover 17 18onAccessibilityHover(callback: AccessibilityCallback): T 19 20开启无障碍模式后，单指触摸绑定该回调的组件时触发该回调。 21 22**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 23 24**系统能力：** SystemCapability.ArkUI.ArkUI.Full 25 26**参数：** 27 28| 参数名 | 类型 | 必填 | 说明 | 29| ---------- | -------------------------- | ------- | ----------------------------- | 30| callback | [AccessibilityCallback](#accessibilitycallback) | 是 | 提供开启无障碍模式后的无障碍悬浮回调事件，当开启无障碍模式后，单指触摸绑定该回调的组件时触发该回调。 | 31 32**返回值：** 33 34| 类型 | 说明 | 35| -------- | -------- | 36| T | 返回当前组件。 | 37 38## AccessibilityCallback 39 40type AccessibilityCallback = (isHover: boolean, event: AccessibilityHoverEvent) => void 41 42提供开启无障碍模式后的无障碍悬浮回调事件类型。 43 44**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 45 46**系统能力：** SystemCapability.ArkUI.ArkUI.Full 47 48**参数：** 49 50| 参数名 | 类型 | 必填 | 说明 | 51| ------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 52| isHover | boolean | 是 | 表示开启无障碍模式后，手指在组件上触发由Touch事件转换成的无障碍悬浮事件，手指进入时为true，退出时为false。 | 53| event | [AccessibilityHoverEvent](#accessibilityhoverevent对象说明) | 是 | 获得AccessibilityHoverEvent对象。 | 54 55## AccessibilityHoverEvent对象说明 56 57继承于[BaseEvent](ts-gesture-customize-judge.md#baseevent8)。 58 59**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 60 61**系统能力：** SystemCapability.ArkUI.ArkUI.Full 62 63| 名称 | 类型 | 只读 | 可选 | 说明 | 64| --------------- | ---------- | ------- | ------- | ------- | 65| type | [AccessibilityHoverType](ts-appendix-enums.md#accessibilityhovertype12) | 否 | 否 | 无障碍悬浮动作。 | 66| x | number | 否 | 否 | 手指位置相对于当前组件左上角的x轴坐标。<br/>单位：vp<br/> | 67| y | number | 否 | 否 | 手指位置相对于当前组件左上角的y轴坐标。<br/>单位：vp<br/> | 68| windowX | number | 否 | 否 | 手指位置相对于应用窗口左上角的x轴坐标。<br/>单位：vp<br/> | 69| windowY | number | 否 | 否 | 手指位置相对于应用窗口左上角的y轴坐标。<br/>单位：vp<br/> | 70| displayX | number | 否 | 否 | 手指位置相对于应用屏幕左上角的x轴坐标。<br/>单位：vp<br/> | 71| displayY | number | 否 | 否 | 手指位置相对于应用屏幕左上角的y轴坐标。<br/>单位：vp<br/> | 72| globalDisplayX<sup>20+</sup> | number | 否 | 是 | 手指位置相对于全局屏幕的左上角的X坐标。<br/>单位：vp<br/>取值范围：[0, +∞)<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 73| globalDisplayY<sup>20+</sup> | number | 否 | 是 | 手指位置相对于全局屏幕的左上角的Y坐标。<br/>单位：vp<br/>取值范围：[0, +∞)<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 74 75## onAccessibilityHoverTransparent<sup>20+</sup> 76 77onAccessibilityHoverTransparent(callback: AccessibilityTransparentCallback): T 78 79当前触摸位置处于注册了回调接口的组件区域，但未能响应无障碍悬浮事件。仅支持手指触摸。不支持如下组件在触摸位置中的场景，包括[UIExtension](../../apis-arkui/js-apis-arkui-uiExtension.md)、[Web](../../apis-arkweb/arkts-basic-components-web.md)、<!--Del-->[FormComponent](ts-basic-components-formcomponent-sys.md)、<!--DelEnd-->[XComponent](ts-basic-components-xcomponent.md)与第三方UI框架对接。在上述场景下，该回调接口无法生效。 80 81**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 82 83**系统能力：** SystemCapability.ArkUI.ArkUI.Full 84 85**参数：** 86| 参数名 | 类型 | 必填 | 说明 | 87| ---------- | -------------------------- | ------- | ----------------------------- | 88| callback | [AccessibilityTransparentCallback](ts-universal-accessibility-hover-event.md#accessibilitytransparentcallback20) | 是 | 提供开启无障碍模式后未能响应的用户输入的触摸事件，当开启无障碍模式后，单指触摸未能响应无障碍悬浮事件位置时触发该回调。 | 89 90**返回值：** 91 92| 类型 | 说明 | 93| -------- | -------- | 94| T | 返回当前组件。 | 95 96## AccessibilityTransparentCallback<sup>20+</sup> 97 98type AccessibilityTransparentCallback = (event: TouchEvent) => void 99 100提供开启无障碍模式后未能响应的用户输入的触摸事件。 101 102**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 103 104**系统能力：** SystemCapability.ArkUI.ArkUI.Full 105 106**参数：** 107 108| 参数名 | 类型 | 必填 | 说明 | 109| ------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 110| event | [TouchEvent](ts-universal-events-touch.md#touchevent对象说明)| 是 | 原始touch事件。 <br/>**说明：** TouchEvent对象的触摸事件的类型[TouchType](ts-appendix-enums.md#touchtype)为四种无障碍悬浮事件类型中的一种，四种无障碍悬浮事件类型为HOVER_ENTER、HOVER_MOVE、HOVER_EXIT和HOVER_CANCEL。 111 112## 示例 113 114### 示例1 (使用onAccessibilityHover事件) 115 116该示例主要演示通过使用onAccessibilityHover事件，对无障碍模式下的按钮进行设置。 117 118```ts 119// xxx.ets 120@Entry 121@Component 122struct OnAccessibilityHoverEventExample { 123 @State hoverText: string = 'no hover'; 124 @State color: Color = Color.Blue; 125 126 build() { 127 Column({ space: 20 }) { 128 Button(this.hoverText) 129 .width(180).height(80) 130 .backgroundColor(this.color) 131 .onAccessibilityHover((isHover: boolean, event: AccessibilityHoverEvent) => { 132 // 通过onAccessibilityHover事件动态修改按钮在是否有鼠标悬浮时的文本内容与背景颜色 133 if (isHover) { 134 this.hoverText = 'hover'; 135 this.color = Color.Pink; 136 } else { 137 this.hoverText = 'no hover'; 138 this.color = Color.Blue; 139 } 140 }) 141 }.padding({ top: 30 }).width('100%') 142 } 143} 144``` 145 146### 示例2 (捕获无法无障碍聚焦的组件的触摸事件) 147 148该示例代码会在无障碍模式下捕获无法无障碍聚焦的组件的触摸事件，并将事件信息显示在组件下方的文本中。 149 150```ts 151@Entry 152@Component 153struct TestExample { 154 @State text: string = ''; 155 @State eventType: string = ''; 156 157 build() { 158 Column({ space: 50 }) { 159 Column() { 160 Button("Test Button") 161 .accessibilityLevel("no") 162 }.margin({ top: 20 }) 163 164 Text(this.text) 165 } 166 .width('100%') 167 .height('100%') 168 .onAccessibilityHoverTransparent((event?: TouchEvent) => { 169 if (event) { 170 if (event.type === TouchType.HOVER_ENTER) { 171 this.eventType = 'HOVER_ENTER'; 172 } 173 if (event.type === TouchType.HOVER_MOVE) { 174 this.eventType = 'HOVER_MOVE'; 175 } 176 if (event.type === TouchType.HOVER_EXIT) { 177 this.eventType = 'HOVER_EXIT'; 178 } 179 if (event.type === TouchType.HOVER_CANCEL) { 180 this.eventType = 'HOVER_CANCEL'; 181 } 182 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 183 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 184 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 185 + event.target.area.width + '\nheight:' + event.target.area.height; 186 } 187 }) 188 } 189} 190``` 191 192