• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 无障碍控制操作
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @zhanghangkai10241-->
5<!--Designer: @lmleon-->
6<!--Tester: @fredyuan0912-->
7<!--Adviser: @HelloCrease-->
8
9在开启无障碍模式后，需要判断是否拦截无障碍控制操作。
10
11>**说明：**
12>
13>  - 本模块首批接口从API version 18开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。
14>  - 目前仅支持通过开启无障碍模式触发。
15
16## onAccessibilityFocus
17
18onAccessibilityFocus(callback: AccessibilityFocusCallback): T
19
20设置无障碍节点获焦、失焦状态的回调函数。当状态发生变化时，触发回调函数。
21
22**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。
23
24**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
25
26**系统能力：** SystemCapability.ArkUI.ArkUI.Full
27
28**参数：**
29
30| 参数名   | 类型    | 必填 | 说明                                                         |
31| -------- | ------- | ---- | ------------------------------------------------------------ |
32| callback | [AccessibilityFocusCallback](ts-universal-accessibility-event.md#accessibilityfocuscallback) | 是   | 向注册回调函数方通知当前获焦、失焦状态。 |
33
34**返回值：**
35
36| 类型    | 说明              |
37| ------ | ---------------- |
38| T | 返回当前组件。 |
39
40## AccessibilityFocusCallback
41
42type AccessibilityFocusCallback = (isFocus: boolean) => void
43
44定义onAccessibilityFocus中使用的回调类型。
45
46**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。
47
48**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
49
50**系统能力：** SystemCapability.ArkUI.ArkUI.Full
51
52**参数：**
53
54| 参数名  | 类型    | 必填 | 说明              |
55| ------ | ------ | ---- | ---------------- |
56| isFocus | boolean | 是 | 用于表示组件是否获焦。<br/>true：当前组件获焦。<br/>false：当前组件失焦。|
57
58## onAccessibilityActionIntercept<sup>20+</sup>
59
60onAccessibilityActionIntercept(callback: AccessibilityActionInterceptCallback): T
61
62该接口在无障碍模式下，可在无障碍控制操作触发前通知注册的回调函数，由注册方决定是否拦截该次无障碍动作，对不支持Click的组件注册也无法触发回调。
63
64**卡片能力：** 从API version 20开始，该接口支持在ArkTS卡片中使用。
65
66**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。
67
68**系统能力：** SystemCapability.ArkUI.ArkUI.Full
69
70**参数：**
71
72| 参数名   | 类型    | 必填 | 说明                                                         |
73| -------- | ------- | ---- | ------------------------------------------------------------ |
74| callback | [AccessibilityActionInterceptCallback](ts-universal-accessibility-event.md#accessibilityactioninterceptcallback20) | 是   | 在无障碍控制操作触发前，向注册回调函数方通知，由注册方决定是否拦截该次无障碍控制操作。<br> 入参设置undefined时取消回调注册。 |
75
76**返回值：**
77
78| 类型    | 说明              |
79| ------ | ---------------- |
80| T | 返回当前组件。 |
81
82## AccessibilityActionInterceptCallback<sup>20+</sup>
83
84type AccessibilityActionInterceptCallback = (action: AccessibilityAction) => AccessibilityActionInterceptResult
85
86提供onAccessibilityActionIntercept中使用的回调函数参数类型。
87
88**卡片能力：** 从API version 20开始，该接口支持在ArkTS卡片中使用。
89
90**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。
91
92**系统能力：** SystemCapability.ArkUI.ArkUI.Full
93
94**参数：**
95
96| 参数名  | 类型    | 必填 | 说明              |
97| ------ | ------ | ---- | ---------------- |
98| action | [AccessibilityAction](ts-universal-accessibility-event.md#accessibilityaction20枚举说明) | 是 | 当前触发的无障碍控制操作类型。 |
99
100**返回值：**
101
102| 类型    | 说明              |
103| ------ | ---------------- |
104| [AccessibilityActionInterceptResult](ts-universal-accessibility-event.md#accessibilityactioninterceptresult20枚举说明) | 无障碍控制操作拦截结果。 |
105
106## AccessibilityAction<sup>20+</sup>枚举说明
107
108定义组件当前触发的无障碍控制操作类型。
109
110**卡片能力：** 从API version 20开始，该接口支持在ArkTS卡片中使用。
111
112**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。
113
114**系统能力：** SystemCapability.ArkUI.ArkUI.Full
115
116| 名称 | 值  | 说明             |
117| ---- | ---- | ------------------ |
118| UNDEFINED_ACTION | 0 | 未定义的无障碍操作。 |
119| ACCESSIBILITY_CLICK | 1 | 无障碍点击操作。 |
120
121## AccessibilityActionInterceptResult<sup>20+</sup>枚举说明
122
123定义AccessibilityActionInterceptCallback的无障碍控制操作拦截结果。
124
125**卡片能力：** 从API version 20开始，该接口支持在ArkTS卡片中使用。
126
127**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。
128
129**系统能力：** SystemCapability.ArkUI.ArkUI.Full
130
131| 名称 | 值  | 说明             |
132| ---- | ---- | ------------------ |
133| ACTION_INTERCEPT | 0 | 拦截当前组件接收的无障碍控制操作，回调处理结束后，不允许当前组件响应无障碍控制操作。 |
134| ACTION_CONTINUE | 1 | 拦截当前组件接收的无障碍控制操作, 回调处理结束后，仍然需要组件做出响应，执行当前组件的处理逻辑。 |
135| ACTION_RISE | 2 | 拦截执行当前组件接收的无障碍控制操作，回调处理结束后，仍然需要组件做出响应，执行当前组件的处理逻辑，并且将ACTION信息往父组件传递，传递到下一个使用了onAccessibilityActionIntercept的组件，触发当前组件中注册的回调，但不触发组件处理逻辑。处理完成后，可以继续使用RISE向父组件传递ACTION。 |
136
137## 示例
138
139该示例主要演示通过使用onAccessibilityActionIntercept事件实现Toggle组件在无障碍模式下于点击事件发生之前拦截点击事件并确认是否拦截该点击事件的操作。
140
141```ts
142// xxx.ets
143@Entry
144@Component
145struct SwitchBootcamp {
146  @State private isOn: boolean = false;
147
148  build() {
149    NavDestination() {
150      Column() {
151        Text('onTouchIntercept')
152        Row() {
153          Text('Label message')
154          Blank()
155          Toggle({ type: ToggleType.Switch, isOn: $$this.isOn })
156            .onAccessibilityActionIntercept((action : AccessibilityAction) => {
157              if (action === AccessibilityAction.ACCESSIBILITY_CLICK) {
158                this.getUIContext().showAlertDialog({
159                  title: '标题',
160                  message: '内容信息',
161                  primaryButton: {
162                    value: '确认',
163                    action: () => {
164                      this.isOn = !this.isOn;
165                    }
166                  },
167                  secondaryButton: {
168                    value: '取消',
169                    action: () => {
170                    }
171                  }
172                })
173                return AccessibilityActionInterceptResult.ACTION_INTERCEPT;
174              } else {
175                return AccessibilityActionInterceptResult.ACTION_CONTINUE;
176              }
177            })
178        }.width('100%')
179      }
180      .padding(24)
181      .width('100%')
182    }
183  }
184}
185```