1# 通过XComponent接入无障碍 2 3通过XComponent接入的三方平台，NDK提供了对接无障碍的接口函数，实现三方平台的组件在ArkUI中的无障碍能力。 4 5首先，需要使用XComponent的[OH_NativeXComponent_GetNativeAccessibilityProvider](../reference/apis-arkui/_o_h___native_x_component.md#oh_nativexcomponent_getnativeaccessibilityprovider)获得无障碍接入provider。然后，通过[OH_ArkUI_AccessibilityProviderRegisterCallback](../reference/apis-arkui/arkui_native_interface_accessibility.md#oh_arkui_accessibilityproviderregistercallback)注册接入无障碍所需的回调函数[ArkUI_AccessibilityProviderCallbacks](../reference/apis-arkui/arkui_native_interface_accessibility.md#arkui_accessibilityprovidercallbacks)，三方应用需要按照接口要求实现回调函数供无障碍系统调用。 6 7三方应用需要按照要求适配无障碍系统发出的操作[Action](../reference/apis-arkui/arkui_native_interface_accessibility.md#arkui_accessibility_actiontype)，以及针对组件交互行为发送无障碍事件[Event](../reference/apis-arkui/arkui_native_interface_accessibility.md#arkui_accessibilityeventtype)到无障碍子系统，实现无障碍辅助应用的交互体验。 8 9> **说明：** 10> 11> - 实现[OH_ArkUI_AccessibilityProviderRegisterCallback](../reference/apis-arkui/arkui_native_interface_accessibility.md#oh_arkui_accessibilityproviderregistercallback)回调查询接口时，查询到的每个无障碍节点信息通过[OH_ArkUI_AddAndGetAccessibilityElementInfo](../reference/apis-arkui/arkui_native_interface_accessibility.md#oh_arkui_addandgetaccessibilityelementinfo)创建分配element内存，并将其加入到指定的elementList中。 12> - 使用[OH_ArkUI_SendAccessibilityAsyncEvent](../reference/apis-arkui/arkui_native_interface_accessibility.md#oh_arkui_sendaccessibilityasyncevent)发送事件时，需要使用[OH_ArkUI_CreateAccessibilityEventInfo](../reference/apis-arkui/arkui_native_interface_accessibility.md#oh_arkui_createaccessibilityeventinfo)创建[ArkUI_AccessibilityEventInfo](../reference/apis-arkui/arkui_native_interface_accessibility.md#arkui_accessibilityeventinfo)，使用[OH_ArkUI_CreateAccessibilityElementInfo](../reference/apis-arkui/arkui_native_interface_accessibility.md#oh_arkui_createaccessibilityelementinfo)创建[ArkUI_AccessibilityElementInfo](../reference/apis-arkui/arkui_native_interface_accessibility.md#arkui_accessibilityelementinfo)，使用结束后，需要调用[OH_ArkUI_DestoryAccessibilityEventInfo](../reference/apis-arkui/arkui_native_interface_accessibility.md#oh_arkui_destoryaccessibilityeventinfo)以及[OH_ArkUI_DestoryAccessibilityElementInfo](../reference/apis-arkui/arkui_native_interface_accessibility.md#oh_arkui_destoryaccessibilityelementinfo)销毁函数释放内存。 13> - 回调函数打印日志时，携带输入的requestId，用于关联一次交互过程相关的日志，便于索引查询整个流程，协助问题定位。 14 15## 对接无障碍 16 17以下示例提供了对接无障碍能力的实现方法。对接完成后，在开启无障碍功能时，可使XComponent中的三方绘制组件接入，实现无障碍交互。 18 191.按照 [自定义渲染（XComponent）](napi-xcomponent-guidelines.md)创建前置工程。 20 212.根据接口定义实现回调函数。 22 23```c 24int32_t FindAccessibilityNodeInfoById(int64_t elementId, ArkUI_AccessibilitySearchMode mode, int32_t requestId, ArkUI_AccessibilityElementInfoList* elementList) 25{ 26 // 根据mode搜集查询element信息列表 27 if (elementList == nullptr) { 28 return OH_NATIVEXCOMPONENT_RESULT_FAILED; 29 } 30 31 // 调用三方平台的接口搜索查询获得mode符合条件的节点 32 //... 33 // nodes为查询节点结果 34 int size = sizeof(nodes) / sizeof(nodes[0]); 35 for (int i = 0; i < size; i++) { 36 // 获取element结构 37 element = OH_ArkUI_AddAndGetAccessibilityElementInfo(elementList); 38 // 设置element成员内容 39 OH_ArkUI_AccessibilityElementInfoSetElementId(element, nodes[i].id); 40 OH_ArkUI_AccessibilityElementInfoSetComponentType(element, nodes[i].type); 41 // ... 42 } 43 // ... 44} 45``` 46 47 48 49```c 50int32_t FindNextFocusAccessibilityNode(int64_t elementId, ArkUI_AccessibilityFocusType focusType, int32_t requestId, ArkUI_AccessibilityElementInfo* elementinfo) 51{ 52 // 根据mode搜集查询element信息列表，参考接口说明实现 53 if (elementinfo == nullptr) { 54 return OH_NATIVEXCOMPONENT_RESULT_FAILED; 55 } 56 57 // 调用三方平台自身的接口搜索查询获得符合条件的节点 58 //... 59 // node为查询节点结果 60 // 设置element成员内容 61 OH_ArkUI_AccessibilityElementInfoSetElementId(element, nodes[i].id); 62 OH_ArkUI_AccessibilityElementInfoSetComponentType(element, nodes[i].type); 63 // ... 64} 65``` 66 67 68 69```C 70int32_t ExecuteAccessibilityAction(int64_t elementId, ArkUI_Accessibility_ActionType action, ArkUI_AccessibilityActionArguments *actionArguments, int32_t requestId) 71{ 72 // ... 73 // 获取action argument内容，结合action判断当前需要进行的操作处理 74 char* actionArgumentValue; 75 OH_ArkUI_FindAccessibilityActionArgumentByKey(actionArguments, key.c_str(), &actionArgumentValue); 76 77 // 针对指定组件节点进行操作 78 ret = doAction(elementId, action, actionArgumentValue); 79 if (ret != 0) { 80 return; 81 } 82 // 判断当前处理操作类型，返回对应的event结果。每个不同的操作有对应不同的event。参考：ArkUI_AccessibilityEventType定义 83 // ... 84 // 明确当前上报事件的组件节点为node 85 // 1.调用OH_ArkUI_CreateAccessibilityEventInfo创建ArkUI_AccessibilityEventInfo 86 ArkUI_AccessibilityEventInfo *eventInfo = OH_ArkUI_CreateAccessibilityEventInfo(); 87 if (eventInfo == nullptr) { 88 OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, LOG_PRINT_TEXT, "[requestId: %{public}d]DispatchTouchEventCB: Unable to create accessibility eventInfo", requestId); 89 return; 90 } 91 // 2.调用OH_ArkUI_CreateAccessibilityElementInfo创建ArkUI_AccessibilityElementInfo 92 ArkUI_AccessibilityElementInfo *elementInfo = OH_ArkUI_CreateAccessibilityElementInfo(); 93 if (elementInfo == nullptr) { 94 OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, LOG_PRINT_TEXT, "[requestId: %{public}d]DispatchTouchEventCB: Unable to create accessibility elementInfo", requestId); 95 return; 96 } 97 // 3.填写element内容 98 // 设置element成员内容 99 OH_ArkUI_AccessibilityElementInfoSetElementId(element, nodes[i].id); 100 OH_ArkUI_AccessibilityElementInfoSetComponentType(element, nodes[i].type); 101 102 OH_LOG_Print(LOG_APP, LOG_INFO, LOG_PRINT_DOMAIN, LOG_PRINT_TEXT, "[requestId: %{public}d]DispatchTouchEventCB: send accessibility event", requestId); 103 // 4.eventType根据当前Action设置 104 // ... 105 SendAccessibilityAsyncEvent(eventInfo, elementInfo, eventType); 106 // 5.销毁eventInfo，elementInfo内存 107 OH_ArkUI_DestoryAccessibilityElementInfo(elementInfo); 108 OH_ArkUI_DestoryAccessibilityEventInfo(eventInfo); 109 // ... 110} 111void FillEvent(ArkUI_AccessibilityEventInfo *eventInfo, ArkUI_AccessibilityElementInfo *elementInfo, ArkUI_AccessibilityEventType eventType) 112{ 113 if (eventInfo == nullptr) { 114 OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_TEXT, "eventInfo is null"); 115 return; 116 } 117 if (elementInfo == nullptr) { 118 OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_TEXT, "elementInfo is null"); 119 return; 120 } 121 OH_ArkUI_AccessibilityEventSetEventType(eventInfo, eventType); 122 123 OH_ArkUI_AccessibilityEventSetElementInfo(eventInfo, elementInfo); 124 125} 126void SendAccessibilityAsyncEvent(ArkUI_AccessibilityEventInfo *eventInfo, ArkUI_AccessibilityElementInfo *elementInfo, ArkUI_AccessibilityEventType eventType) 127{ 128 // 1.填写event内容 129 FillEvent(eventInfo, elementInfo, ArkUI_AccessibilityEventType::ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_PAGE_STATE_UPDATE); 130 // 2.callback 131 auto callback = [](int32_t errorCode){ 132 OH_LOG_Print(LOG_APP, LOG_INFO, LOG_PRINT_DOMAIN, LOG_PRINT_TEXT, "result: %{public}d", errorCode); 133 } 134 // 3. 调用接口发送事件给OH侧 135 OH_ArkUI_SendAccessibilityAsyncEvent(provider_, eventInfo, callback) 136} 137``` 138 139 140 141```C 142int32_t ClearFocusedFocusAccessibilityNode() 143{ 144 // 找到当前获焦的组件，并清除焦点状态。 145 // ... 146 // 无障碍焦点状态 147 node.accessibilityFocused = false; 148 // 组件焦点状态 149 node.foucsed = false; 150 // ... 151} 152``` 153 154 155 156```C 157int32_t GetAccessibilityNodeCursorPosition(int64_t elementId, int32_t requestId, int32_t* index) 158{ 159 // 获取文本组件光标位置，并返回 160 // 查找对应组件节点 161 // ... 162 *index = node.cursorPosition; 163 // ... 164} 165``` 166 167 168 1693.使用XComponent句柄注册无障碍回调函数。 170 171```C 172void PluginRender::RegisterAccessibility(OH_NativeXComponent* nativeXComponent) 173{ 174 //... 175 //1.获取provider实例，定义”provider_“提供给函数返回 176 int32_t ret = OH_NativeXComponent_GetNativeAccessibilityProvider(nativeXComponent, &provider_); 177 if (provider_ == nullptr) { 178 return; 179 } 180 //2.注册回调函数，如下相关回调注册函数FindAccessibilityNodeInfosById等，需三方实现函数注册。 181 accessibilityProviderCallbacks_ = new ArkUI_AccessibilityProviderCallbacks(); 182 accessibilityProviderCallbacks_->findAccessibilityNodeInfosById = FindAccessibilityNodeInfosById; 183 accessibilityProviderCallbacks_->findAccessibilityNodeInfosByText = FindAccessibilityNodeInfosByText; 184 accessibilityProviderCallbacks_->findFocusedAccessibilityNode = FindFocusedAccessibilityNode; 185 accessibilityProviderCallbacks_->executeAccessibilityAction = ExecuteAccessibilityAction; 186 accessibilityProviderCallbacks_->clearFocusedFocusAccessibilityNode = ClearFocusedFocusAccessibilityNode; 187 accessibilityProviderCallbacks_->getAccessibilityNodeCursorPosition = GetAccessibilityNodeCursorPosition; 188 ret = OH_ArkUI_AccessibilityProviderRegisterCallback(provider_, accessibilityProviderCallbacks_); 189 if (ret != 0) { 190 return; 191 } 192} 193``` 194 195 196 1974.组件发生变化时，主动发送事件。参考事件定义[ArkUI_AccessibilityEventType](../reference/apis-arkui/arkui_native_interface_accessibility.md#arkui_accessibilityeventtype)说明。 198 199如果因为Touch事件导致页面变化，需要发送页面变化事件ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_PAGE_STATE_UPDATE以及获焦组件位置变化事件ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_FOCUS_NODE_UPDATE给无障碍子系统。 200 201```C 202// 定义一个函数DispatchTouchEventCB()，响应触摸事件时触发该回调 203void DispatchTouchEventCB(OH_NativeXComponent *component, void *window) 204{ 205 // ... 206 // 获取XComponent的id 207 char idStr[OH_XCOMPONENT_ID_LEN_MAX + 1] = { '\0' }; 208 uint64_t idSize = OH_XCOMPONENT_ID_LEN_MAX + 1; 209 if (OH_NativeXComponent_GetXComponentId(component, idStr, &idSize) != OH_NATIVEXCOMPONENT_RESULT_SUCCESS) { 210 OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "Callback", 211 "DispatchTouchEventCB: Unable to get XComponent id"); 212 return; 213 } 214 215 // 判断当前是否已注册无障碍provider 216 if (provider_ != nullptr) { 217 218 // 需判断当前Touch事件是否引起了页面变化和当前获焦组件的位置变化。若引起变化，则需要上报无障碍事件，通知无障碍服务以及辅助应用。 219 // ... 220 // 明确当前上报事件的组件节点为node 221 // 1.调用OH_ArkUI_CreateAccessibilityEventInfo创建ArkUI_AccessibilityEventInfo 222 ArkUI_AccessibilityEventInfo *eventInfo = OH_ArkUI_CreateAccessibilityEventInfo(); 223 if (eventInfo == nullptr) { 224 OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "Callback", 225 "DispatchTouchEventCB: Unable to create accessibility eventInfo"); 226 return; 227 } 228 // 2.调用OH_ArkUI_CreateAccessibilityElementInfo创建ArkUI_AccessibilityElementInfo 229 ArkUI_AccessibilityElementInfo *elementInfo = OH_ArkUI_CreateAccessibilityElementInfo(); 230 if (elementInfo == nullptr) { 231 OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "Callback", 232 "DispatchTouchEventCB: Unable to create accessibility elementInfo"); 233 return; 234 } 235 // 3.填写element内容 236 // 设置element成员内容 237 OH_ArkUI_AccessibilityElementInfoSetElementId(element, nodes[i].id); 238 OH_ArkUI_AccessibilityElementInfoSetComponentType(element, nodes[i].type); 239 // ... 240 241 OH_LOG_Print(LOG_APP, LOG_INFO, LOG_PRINT_DOMAIN, "Callback", 242 "DispatchTouchEventCB: send accessibility event"); 243 // 4.发送页面更新事件 244 SendAccessibilityAsyncEvent(eventInfo, elementInfo, ArkUI_AccessibilityEventType::ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_PAGE_STATE_UPDATE); 245 // 5.如当前处理引起了获焦组件的位置变化，发送获焦位置变化事件 246 SendAccessibilityAsyncEvent(eventInfo, elementInfo, ArkUI_AccessibilityEventType::ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_FOCUS_NODE_UPDATE); 247 // 6.销毁eventInfo，elementInfo内存 248 OH_ArkUI_DestoryAccessibilityElementInfo(elementInfo); 249 OH_ArkUI_DestoryAccessibilityEventInfo(eventInfo); 250 } 251 252 std::string id(idStr); 253 PluginRender *render = PluginRender::GetInstance(id); 254 if (render != nullptr) { 255 // 封装OnTouchEvent方法 256 render->OnTouchEvent(component, window); 257 } 258} 259 260void FillEvent(ArkUI_AccessibilityEventInfo *eventInfo, ArkUI_AccessibilityElementInfo *elementInfo, ArkUI_AccessibilityEventType eventType) 261{ 262 if (eventInfo == nullptr) { 263 OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_TEXT, "eventInfo is null"); 264 return; 265 } 266 if (elementInfo == nullptr) { 267 OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_TEXT, "elementInfo is null"); 268 return; 269 } 270 // 1.设置事件类型 271 OH_ArkUI_AccessibilityEventSetEventType(eventInfo, eventType); 272 // 2.设置发送事件的节点组件信息 273 OH_ArkUI_AccessibilityEventSetElementInfo(eventInfo, elementInfo); 274 275} 276void SendAccessibilityAsyncEvent(ArkUI_AccessibilityEventInfo *eventInfo, ArkUI_AccessibilityElementInfo *elementInfo, ArkUI_AccessibilityEventType eventType) 277{ 278 // 1.填写event内容 279 FillEvent(eventInfo, elementInfo, ArkUI_AccessibilityEventType::ARKUI_ACCESSIBILITY_NATIVE_EVENT_TYPE_PAGE_STATE_UPDATE); 280 // 2.设置创建callback函数，获取发送事件结果 281 auto callback = [](int32_t errorCode){ 282 OH_LOG_Print(LOG_APP, LOG_INFO, LOG_PRINT_DOMAIN, LOG_PRINT_TEXT, "result: %{public}d", errorCode); 283 } 284 // 3. 调用接口发送事件给无障碍子系统 285 OH_ArkUI_SendAccessibilityAsyncEvent(provider_, eventInfo, callback) 286} 287``` 288 2895.对接成功后，可开启无障碍功能。 290 291 292
