1# AccessibilityExtensionContext (辅助功能扩展上下文)(系统接口) 2 3<!--Kit: Accessibility Kit--> 4<!--Subsystem: BarrierFree--> 5<!--Owner: @qiiiiiiian--> 6<!--Designer: @z7o--> 7<!--Tester: @A_qqq--> 8<!--Adviser: @w_Machine_cc--> 9 10AccessibilityExtensionContext是AccessibilityExtensionAbility上下文环境，继承自ExtensionContext。 11 12辅助功能扩展上下文模块提供辅助功能扩展的上下文环境的能力，包括允许配置辅助应用关注信息类型、查询节点信息、手势注入等。 13 14> **说明：** 15> 16> - 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 17> - 当前页面仅包含本模块的系统接口，其他公开接口请参[AccessibilityExtensionContext (辅助功能扩展上下文)](js-apis-inner-application-accessibilityExtensionContext.md)。 18 19## 使用说明 20 21在使用AccessibilityExtensionContext的功能前，需要通过AccessibilityExtensionAbility子类实例获取AccessibilityExtensionContex的实例。 22 23```ts 24import { AccessibilityExtensionAbility } from '@kit.AccessibilityKit'; 25 26class EntryAbility extends AccessibilityExtensionAbility { 27 onConnect(): void { 28 let axContext = this.context; 29 } 30} 31``` 32 33## Parameter<sup>20+</sup> 34 35无障碍节点元素执行特定操作时，为操作提供具体设置的参数值。 36详见[无障碍节点元素可执行的操作](./js-apis-accessibility-sys.md#accessibilityaction)。 37 38**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 39 40| 名称 | 类型 | 只读 |可选| 说明 | 41| ------------------- | ------ | ---- | ----|--------------------------------- | 42| setText | string | 否 |是 |设置组件文本时文本内容。 | 43| selectTextBegin | string | 否 | 是|选定组件内文本时的起始坐标，如：'2'。 | 44| selectTextEnd | string | 否 | 是|选定组件内文本时的结束坐标，如：'8'。 | 45| selectTextInForWard | bool | 否 | 是|选定组件内文本时是否向前选择，如：true。 | 46| offset | string | 否 | 是|设置光标的偏移量，如：'1'。 | 47| spanId | string | 否 |是 |对超链接文本进行点击操作时文本编号。 | 48| scrollType | string | 否 | 是|组件滚动类型，包括'fullScreen'（全屏）和'halfScreen'（半屏）。 | 49 50例如：选中文本输入框中index从0到7的字符时，executeAction(AccessibilityAction.SET_SELECTION, parameter)方法设置的参数如下: 51```ts 52let p : Parameter = { selectTextBegin: '0', selectTextEnd: '8', selectTextInForWard: true } 53``` 54 55## AccessibilityGrid<sup>20+</sup> 56 57辅助功能网格信息。 58详见[AccessibilityElement.currentItem](#accessibilityelement12)。 59 60**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 61 62| 名称 | 类型 | 只读 |可选| 说明 | 63| ------------------- | ------ | ---- | ----|--------------------------------- | 64| rowIndex | number | 否 |否 |网格行索引。 | 65| columnIndex | number | 否 | 否|网格列索引。 | 66 67 68## AccessibilitySpan<sup>20+</sup> 69 70辅助功能超链接文本信息。 71详见[AccessibilityElement.spans](#accessibilityelement12)。 72 73**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 74 75| 名称 | 类型 | 只读 |可选| 说明 | 76| ------------------- | ------ | ---- | ----|--------------------------------- | 77| spanId | number | 否 |否 |超链接文本编号。 | 78| spanText | string | 否 | 否|超链接文本的文本内容。 | 79| accessibilityText | string | 否 | 否|超链接文本的辅助功能文本。 | 80| accessibilityDescription | string | 否 | 否|超链接文本的辅助功能描述。 | 81| accessibilityLevel | string | 否 | 否|超链接文本的辅助功能级别。 | 82 83 84## startAbility<sup>12+</sup> 85 86startAbility(want: Want): Promise\<void>; 87 88提供拉起前台页面的能力。 89 90**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 91 92**参数：** 93 94| 参数名 | 类型 | 必填 | 说明 | 95| -------- | -------- | -------- | -------- | 96| want | [Want](../../reference/apis-ability-kit/js-apis-app-ability-want.md) | 是 | Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。 | 97 98**返回值：** 99 100| 类型 | 说明 | 101| ------------------- | ---------------- | 102| Promise<void> | 无返回结果的Promise对象。 | 103 104**错误码：** 105 106以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 107 108| 错误码ID | 错误信息 | 109| ------- | ---------------------------------------- | 110| 201 | Permission denied. Interface caller does not have permission. | 111| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 112 113**示例：** 114 115```ts 116import { BusinessError } from '@kit.BasicServicesKit'; 117 118let want: Want = { 119 bundleName: 'com.huawei.hmos.photos', 120 abilityName: 'com.huawei.hmos.photos.MainAbility' 121} 122 123axContext.startAbility(want).then(() => { 124 console.info(`startAbility Succeeded enable ability`); 125}).catch((err: BusinessError) => { 126 console.error(`startAbility failed to enable ability, Code is ${err.code}, message is ${err.message}`); 127}); 128``` 129 130## AccessibilityExtensionContext.getElements<sup>18+</sup> 131 132getElements(windowId: number, elementId?: number): Promise<Array<AccessibilityElement>>; 133 134提供批量查询节点的能力。 135 136**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| -------- | -------- | -------- | -------- | 142| windowId | number | 是 | 表示查询的窗口id。 | 143| elementId | number | 否 | 表示查询的节点id。传入此参数表示查询当前节点下的所有子节点列表，不传则查询窗口下所有节点。默认值为-1。 | 144 145**返回值：** 146| 类型 | 说明 | 147| ----------------------------------- | ---------------------- | 148| Promise<Array<AccessibilityElement>> | Promise对象，返回当前窗口或者当前节点下的所有子节点列表。 | 149 150**错误码：** 151 152以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 153 154| 错误码ID | 错误信息 | 155| ------- | ---------------------------------------- | 156| 202 | Permission verification failed. A non-system application calls a system API. | 157| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 158| 9300003 | No accessibility permission to perform the operation. | 159 160**示例：** 161 162```ts 163import { AccessibilityElement } from '@kit.AccessibilityKit'; 164import { BusinessError } from '@kit.BasicServicesKit'; 165 166let windowId: number = 10; 167let elementId: number = 10; 168 169axContext.getElements(windowId, elementId).then((data:AccessibilityElement[]) => { 170 console.log(`Succeeded in find element, ${JSON.stringify(data)}`); 171}).catch((err: BusinessError) => { 172 console.error(`failed to find element, Code is ${err.code}, message is ${err.message}`); 173}); 174``` 175 176## AccessibilityExtensionContext.getDefaultFocusedElementIds<sup>18+</sup> 177 178getDefaultFocusedElementIds(windowId: number): Promise<Array<number>>; 179 180提供查询应用自定义默认焦点的能力。 181 182**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| -------- | -------- | -------- | -------- | 188| windowId | number | 是 | 表示查询的窗口id。 | 189 190**返回值：** 191| 类型 | 说明 | 192| ----------------------------------- | ---------------------- | 193| Promise<Array<number>> | Promise对象，返回当前窗口下的自定义默认焦点列表。 | 194 195**错误码：** 196 197以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 198 199| 错误码ID | 错误信息 | 200| ------- | ---------------------------------------- | 201| 202 | Permission verification failed. A non-system application calls a system API. | 202| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 203| 9300003 | No accessibility permission to perform the operation. | 204 205**示例：** 206 207```ts 208import { AccessibilityElement } from '@kit.AccessibilityKit'; 209import { BusinessError } from '@kit.BasicServicesKit'; 210 211let windowId: number = 10; 212 213axContext.getDefaultFocusedElementIds(windowId).then((data: number[]) => { 214 console.log(`Succeeded in get default focus, ${JSON.stringify(data)}`); 215}).catch((err: BusinessError) => { 216 console.error(`failed to get default focus, Code is ${err.code}, message is ${err.message}`); 217}); 218``` 219 220## AccessibilityExtensionContext.holdRunningLockSync<sup>20+</sup> 221 222holdRunningLockSync(): void 223 224持有RunningLock锁，持锁后，屏幕不会自动灭屏。 225 226**需要权限**：ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 227 228**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 229 230**错误码：** 231 232以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 233 234| 错误码ID | 错误信息 | 235| ------- | ---------------------------------------- | 236| 201 | Permission verification failed. The application does not have the permission required to call the API. | 237| 202 | Permission verification failed. A non-system application calls a system API. | 238 239**示例：** 240 241```ts 242import { AccessibilityExtensionAbility } from '@kit.AccessibilityKit'; 243import { BusinessError } from '@kit.BasicServicesKit'; 244 245try { 246 axContext.holdRunningLockSync(); 247} catch (err) { 248 console.error(`Failed to hold RunningLock, Code is ${err.code}, message is ${err.message}`); 249} 250``` 251 252## AccessibilityExtensionContext.unholdRunningLockSync<sup>20+</sup> 253 254unholdRunningLockSync(): void 255 256释放RunningLock锁，恢复自动灭屏。 257 258**需要权限**：ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 259 260**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 261 262**错误码：** 263 264以以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 265 266| 错误码ID | 错误信息 | 267| ------- | ---------------------------------------- | 268| 201 | Permission verification failed. The application does not have the permission required to call the API. | 269| 202 | Permission verification failed. A non-system application calls a system API. | 270 271**示例：** 272 273```ts 274import { AccessibilityExtensionAbility } from '@kit.AccessibilityKit'; 275import { BusinessError } from '@kit.BasicServicesKit'; 276 277try { 278 axContext.unholdRunningLockSync(); 279} catch (err) { 280 console.error(`Failed to unhold RunningLock, code is ${err.code}, message is ${err.message}`); 281} 282``` 283 284## AccessibilityExtensionContext.on('preDisconnect')<sup>20+</sup> 285 286on(type: 'preDisconnect', callback: Callback<void>): void 287 288向无障碍服务注册回调函数，在无障碍服务关闭该无障碍扩展服务前会执行该回调函数。 289 290此注册函数需要与[notifyDisconnect](#accessibilityextensioncontextnotifydisconnect20)配合使用，如果不调用[notifyDisconnect](#accessibilityextensioncontextnotifydisconnect20)，则默认等待30秒后，无障碍扩展服务会自动关闭。 291 292**需要权限**：ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 293 294**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 295 296**参数：** 297 298| 参数名 | 类型 | 必填 | 说明 | 299| -------- | -------- | -------- | -------- | 300| type | string | 是 | 监听事件名，固定为‘preDisconnect’，即无障碍扩展服务即将关闭事件。 | 301| callback | Callback<void> | 是 |回调函数，在无障碍扩展服务即将关闭时回调。| 302 303**错误码：** 304 305以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 306 307| 错误码ID | 错误信息 | 308| ------- | ---------------------------------------- | 309| 201 | Permission verification failed. The application does not have the permission required to call the API. | 310| 202 | Permission verification failed. A non-system application calls a system API. | 311 312**示例：** 313 314```ts 315import { AccessibilityExtensionAbility } from '@kit.AccessibilityKit'; 316import { BusinessError } from '@kit.BasicServicesKit'; 317 318try { 319 axContext.on('preDisconnect', () => { 320 console.info(`To do something before accessibilityExtension disconnect.`); 321 }); 322} catch (err) { 323 console.error(`Failed to register, code is ${err.code}, message is ${err.message}`); 324} 325``` 326 327## AccessibilityExtensionContext.off('preDisconnect')<sup>20+</sup> 328 329off(type: 'preDisconnect', callback?: Callback<void>): void 330 331取消已经向无障碍服务注册的预关闭回调函数，无障碍服务关闭该扩展服务前不再执行该回调。 332 333**需要权限**：ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 334 335**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 336 337**参数：** 338 339| 参数名 | 类型 | 必填 | 说明 | 340| -------- | -------- | -------- | -------- | 341| type | string | 是 | 监听事件名，固定为‘preDisconnect’，即无障碍扩展服务即将关闭事件。 | 342| callback | Callback<void> | 否 |回调函数，取消指定无障碍扩展服务即将关闭时的回调。需与[on('preDisconnect')](#accessibilityextensioncontextonpredisconnect20)的callback一致。缺省时，表示注销所有已注册事件。| 343 344**错误码：** 345 346以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 347 348| 错误码ID | 错误信息 | 349| ------- | ---------------------------------------- | 350| 201 | Permission verification failed. The application does not have the permission required to call the API. | 351| 202 | Permission verification failed. A non-system application calls a system API. | 352 353**示例：** 354 355```ts 356import { AccessibilityExtensionAbility } from '@kit.AccessibilityKit'; 357import { BusinessError } from '@kit.BasicServicesKit'; 358 359try { 360 axContext.off('preDisconnect', () => { 361 console.info(`To do something before accessibilityExtension disconnect.`); 362 }); 363} catch (err) { 364 console.error(`Failed to unRegister, code is ${err.code}, message is ${err.message}`); 365} 366``` 367 368## AccessibilityExtensionContext.notifyDisconnect<sup>20+</sup> 369 370notifyDisconnect(): void 371 372通知无障碍服务可以关闭该无障碍扩展服务。 373 374此函数需要与注册预关闭接口[on('preDisconnect')](#accessibilityextensioncontextonpredisconnect20)配合使用，如果没有调用过注册预关闭函数，直接调用此函数不生效。 375 376**需要权限**：ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 377 378**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 379 380**错误码：** 381 382以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 383 384| 错误码ID | 错误信息 | 385| ------- | ---------------------------------------- | 386| 201 | Permission verification failed. The application does not have the permission required to call the API. | 387| 202 | Permission verification failed. A non-system application calls a system API. | 388 389**示例：** 390 391```ts 392import { AccessibilityExtensionAbility } from '@kit.AccessibilityKit'; 393import { BusinessError } from '@kit.BasicServicesKit'; 394 395try { 396 axContext.notifyDisconnect(); 397} catch (err) { 398 console.error(`Failed to notify accessibility, code is ${err.code}, message is ${err.message}`); 399} 400``` 401 402## getAccessibilityFocusedElement<sup>20+</sup> 403 404getAccessibilityFocusedElement(): Promise\<AccessibilityElement>; 405 406获取当前获得焦点的元素。 407 408**权限：** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 409 410**系统能力：** SystemCapability.BarrierFree.Accessibility.Core 411 412**返回值:** 413| 类型 | 描述 | 414| ----------------------------------- | ---------------------- | 415| Promise\<[AccessibilityElement](#accessibilityelement12)>| 异步返回函数结果.| 416 417**错误码:** 418以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 419 420| 错误码ID | 错误信息 | 421| ------- | ---------------------------------------- | 422| 201 | Permission verification failed.The application does not have the permission required to call the API. | 423| 202 | Permission verification failed. A non-system application calls a system API. | 424| 9300003 | No accessibility permission to perform the operation. | 425| 9300006 | The target application failed to connect to accessibility service. | 426 427**示例：** 428 429```ts 430import { AccessibilityElement } from '@kit.AccessibilityKit'; 431import { BusinessError } from '@kit.BasicServicesKit'; 432 433axContext.getAccessibilityFocusedElement().then((element: AccessibilityElement) => { 434 console.log(`Succeeded in get accessibility focused element, ${element.bundleName}`); 435}).catch((err: BusinessError) => { 436 console.error(`failed to get accessibility focused element, Code is ${err.code}, message is ${err.message}`); 437}); 438``` 439 440## getRootInActiveWindow<sup>20+</sup> 441 442getRootInActiveWindow(windowId ?: number): Promise\<[AccessibilityElement](#accessibilityelement12)>; 443 444获取活动窗口根元素。 445 446**权限：** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 447 448**系统能力：** SystemCapability.BarrierFree.Accessibility.Core 449 450**参数：** 451| 参数名 | 类型 | 必填 | 说明 | 452| -------- | -------- | -------- | -------- | 453| windowId | number | No | Window ID to be obtained.| 454 455**返回值:** 456| 类型 | 描述 | 457| ----------------------------------- | ---------------------- | 458| Promise\<[AccessibilityElement](#accessibilityelement12)>| Promise used to return the result.| 459 460**错误码:** 461以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 462| 错误码ID | 错误信息 | 463| ------- | ---------------------------------------- | 464| 201 | Permission verification failed.The application does not have the permission required to call the API. | 465| 202 | Permission verification failed. A non-system application calls a system API. | 466| 9300003 | No accessibility permission to perform the operation. | 467| 9300006 | The target application failed to connect to accessibility service. | 468 469**示例：** 470 471```ts 472import { AccessibilityElement } from '@kit.AccessibilityKit'; 473import { BusinessError } from '@kit.BasicServicesKit'; 474 475let windowId: number = 0; 476 477axContext.getRootInActiveWindow(windowId).then((element: AccessibilityElement) => { 478 console.log(`Succeeded in get root inactive window element, ${element.bundleName}`); 479}).catch((err: BusinessError) => { 480 console.error(`failed to get root inactive window element, Code is ${err.code}, message is ${err.message}`); 481}); 482``` 483 484## getAccessibilityWindowsSync<sup>20+</sup> 485 486getAccessibilityWindowsSync(displayId?: number): Array\<[AccessibilityElement](#accessibilityelement12)> 487 488获取窗口列表。 489 490**权限：** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 491 492**系统能力：** SystemCapability.BarrierFree.Accessibility.Core 493 494**参数：** 495| 参数名 | 类型 | 必填 | 说明 | 496| -------- | -------- | -------- | -------- | 497| displayId | number | No | 显示ID。如果未提供此参数，则表示默认displayId。 | 498 499**返回值：** 500 501| 类型 | 描述 | 502| ----------------------------------- | ---------------------- | 503| Array\<[AccessibilityElement](#accessibilityelement12)> | 窗口列表。| 504 505**错误码:** 506以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 507| 错误码ID | 错误信息 | 508| ------- | ---------------------------------------- | 509| 201 | Permission verification failed.The application does not have the permission required to call the API. | 510| 202 | Permission verification failed. A non-system application calls a system API. | 511| 9300003 | No accessibility permission to perform the operation. | 512 513**示例：** 514 515```ts 516import { AccessibilityElement } from '@kit.AccessibilityKit'; 517import { BusinessError } from '@kit.BasicServicesKit'; 518 519try { 520 let displayId: number = 0; 521 let windowList = context?.getAccessibilityWindowsSync(displayId); 522 if (windowList) { 523 for (let window of windowList) { 524 console.log(`getAccessibilityWindowsSync: windowId: ${window.windowId}`); 525 } 526 } 527} catch (err) { 528 console.log(`[FAILED] getAccessibilityWindowsSync: ${err.code} ${err.message}`) 529} 530``` 531 532## AccessibilityElement<sup>12+</sup> 533 534无障碍节点元素。在调用 **AccessibilityElement** 的 API 之前，应该调用 [AccessibilityExtensionContext.getAccessibilityFocusedElement()](#getaccessibilityfocusedelement20) 或 [AccessibilityExtensionContext.getRootInActiveWindow()](#getrootinactivewindow20) 来获取一个 **AccessibilityElement** 实例。 535 536**系统能力：** SystemCapability.BarrierFree.Accessibility.Core 537 538### 属性 539 540| 名称 | 类型 | 只读 | 可选 | 描述 | 541|----------------------|--------------------------------------------------------------------|------|------|-------------------| 542| accessibilityFocused<sup>20+</sup> | boolean | 否 | 是 | 表示元素是否因无障碍目的获得焦点。true表示已获得焦点，false表示未获得焦点。<br>默认值：false。| 543| bundleName<sup>20+</sup> | string | 否 | 是 | 包名。| 544| checkable<sup>20+</sup> | boolean | 否 | 是 | 元素是否可勾选。true表示可勾选，false表示不可勾选。<br>默认值：false。| 545| checked<sup>20+</sup> | boolean | 否 | 是 | 元素是否已勾选。true表示已勾选，false表示未勾选。<br>默认值：false。| 546| clickable<sup>20+</sup> | boolean | 否 | 是 | 元素是否可点击。true表示可点击，false表示不可点击。<br>默认值：false。| 547| componentId<sup>20+</sup> | number | 否 | 是 | 元素所属组件的ID。<br>默认值：-1。| 548| componentType<sup>20+</sup> | string | 否 | 是 | 元素所属组件的类型。| 549| contents<sup>20+</sup> | Array<string> | 否 | 是 | 元素显示内容。| 550| currentIndex<sup>20+</sup> | number | 否 | 是 | 当前项的索引。<br>默认值：0。| 551| description<sup>20+</sup> | string | 否 | 是 | 元素的描述信息。| 552| editable<sup>20+</sup> | boolean | 否 | 是 | 元素是否可编辑。true表示可编辑，false表示不可编辑。<br>默认值：false。| 553| endIndex<sup>20+</sup> | number | 否 | 是 | 屏幕上显示的最后一个列表项的索引。<br>默认值：0。| 554| error<sup>20+</sup> | string | 否 | 是 | 元素的错误状态。| 555| focusable<sup>20+</sup> | boolean | 否 | 是 | 元素是否可获得焦点。true表示可获得焦点，false表示不可获得焦点。<br/>默认值：false。| 556| hintText<sup>20+</sup> | string | 否 | 是 | 提示文本。| 557| inputType<sup>20+</sup> | number | 否 | 是 | 输入文本的类型。<br>默认值：0。| 558| inspectorKey<sup>20+</sup> | string | 否 | 是 | 检查器键。| 559| isActive<sup>20+</sup> | boolean | 否 | 是 | 元素是否处于活动状态。true表示活动状态，false表示非活动状态。<br>默认值：true。| 560| isEnable<sup>20+</sup> | boolean | 否 | 是 | 元素是否启用。true表示启用，false表示未启用。<br>默认值：false。| 561| isHint<sup>20+</sup> | boolean | 否 | 是 | 元素是否为提示信息。true表示元素是提示信息，false表示非提示信息。<br>默认值：false。| 562| isFocused<sup>20+</sup> | boolean | 否 | 是 | 表示元素是否已获得焦点。true表示已获得焦点，false表示未获得焦点。<br>默认值：false。| 563| isPassword<sup>20+</sup> | boolean | 否 | 是 | 元素是否为密码。true表示元素是密码，false表示不是密码。<br>默认值：false。| 564| isVisible<sup>20+</sup> | boolean | 否 | 是 | 元素是否可见。true表示元素可见，false表示元素不可见。<br>默认值：false。| 565| itemCount<sup>20+</sup> | number | 否 | 是 | 项目总数。<br>默认值：0。| 566| lastContent<sup>20+</sup> | string | 否 | 是 | 最后一项内容。| 567| layer<sup>20+</sup> | number | 否 | 是 | 元素的显示层级。| 568| longClickable<sup>20+</sup> | boolean | 否 | 是 | 元素是否可长按。true表示可长按，false表示不可长按。<br>默认值：false。| 569| pageId<sup>20+</sup> | number | 否 | 是 | 页面ID。<br>默认值：-1。| 570| pluralLineSupported<sup>20+</sup> | boolean | 否 | 是 | 表示元素是否支持多行文本。true表示支持，false表示不支持。<br>默认值：false。| 571| rect<sup>20+</sup> | [Rect](js-apis-inner-application-accessibilityExtensionContext.md#rect) | 否 | 是 | 元素的区域。| 572| resourceName<sup>20+</sup> | string | 否 | 是 | 元素的资源名称。| 573| screenRect<sup>20+</sup> | [Rect](js-apis-inner-application-accessibilityExtensionContext.md#rect) | 否 | 是 | 元素的显示区域。| 574| scrollable<sup>20+</sup> | boolean | 否 | 是 | 元素是否可滚动。true表示元素可滚动，false表示不可滚动。<br>默认值：false。| 575| selected<sup>20+</sup> | boolean | 否 | 是 | 元素是否已选中。true表示已选中，false表示未选中。<br>默认值：false。| 576| startIndex<sup>20+</sup> | number | 否 | 是 | 屏幕上第一个列表项的索引。<br>默认值：0。| 577| text<sup>20+</sup> | string | 否 | 是 | 元素的文本内容。| 578| textLengthLimit<sup>20+</sup> | number | 否 | 是 | 元素的最大文本长度。| 579| textMoveUnit<sup>20+</sup> | [accessibility.TextMoveUnit](js-apis-accessibility.md#textmoveunit)| 否 | 是 | 文本朗读时的移动单位。<br>默认值：0。| 580| triggerAction<sup>20+</sup> | [accessibility.Action](js-apis-accessibility.md#action) | 否 | 是 | 触发元素事件的操作。| 581| type<sup>20+</sup> | [WindowType](js-apis-inner-application-accessibilityExtensionContext.md#windowtype) | 否 | 是 | 元素的窗口类型。| 582| valueMax<sup>20+</sup> | number | 否 | 是 | 最大值。<br>默认值：0。| 583| valueMin<sup>20+</sup> | number | 否 | 是 | 最小值。<br>默认值：0。| 584| valueNow<sup>20+</sup> | number | 否 | 是 | 当前值。<br>默认值：0。| 585| windowId<sup>20+</sup> | number | 否 | 是 | 窗口ID。<br>默认值：-1。| 586| offset<sup>20+</sup> | number | 否 | 是 | 内容区域相对于可滚动组件（如List和Grid）顶部坐标的像素偏移量。<br>默认值：0。| 587| textType<sup>20+</sup> | string | 否 | 是 | 元素的无障碍文本类型，由组件的accessibilityTextHint属性配置。| 588| accessibilityText<sup>20+</sup> | string | 否 | 是 | 元素的无障碍文本信息。| 589| hotArea<sup>20+</sup> | [Rect](js-apis-inner-application-accessibilityExtensionContext.md#rect) | 否 | 是 | 元素的可触摸区域。| 590| customComponentType<sup>20+</sup> | string | 否 | 是 | 自定义组件类型。| 591| accessibilityNextFocusId<sup>20+</sup> | number | 否 | 是 | 下一个要获得焦点的组件的ID。<br>默认值：-1。| 592| accessibilityPreviousFocusId<sup>20+</sup> | number | 否 | 是 | 上一个要获得焦点的组件的ID。<br>默认值：-1。| 593| extraInfo<sup>20+</sup> | string | 否 | 是 | 元素的额外信息。值为JSON字符串。| 594| accessibilityScrollable<sup>20+</sup> | boolean | 否 | 是 | 元素是否因无障碍目的而可滚动。此属性优先级高于scrollable。<br>true表示元素可滚动，false表示元素不可滚动。<br>默认值：true。| 595| supportedActionNames<sup>20+</sup> | Array<string> | 否 | 是 | 支持的操作名称。| 596| accessibilityGroup<sup>20+</sup> | boolean | 否 | 是 | 元素是否为无障碍组。true表示元素是无障碍组，false表示元素不是无障碍组。<br>默认值：false。| 597| accessibilityLevel<sup>20+</sup> | string | 否 | 是 | 组件的无障碍级别。<br>'auto'：当前组件由无障碍分组服务和ArkUI进行综合判断组件是否可被辅助功能识别。<br>'yes'：当前组件可被辅助功能识别。<br>'no'：当前组件不可被辅助功能识别。<br>'no-hide-descendants'：当前组件及其所有子组件不可被辅助功能识别。| 598| navDestinationId<sup>20+</sup> | number | 否 | 是 | 组件的导航目标ID。| 599| currentItem<sup>20+</sup> | [AccessibilityGrid](#accessibilitygrid20) | 否 | 是 | 组件网格中的当前项。| 600| spans<sup>20+</sup> | [AccessibilitySpan](#accessibilityspan20)[] | 否 | 是 | 组件的跨度数组。| 601| accessibilityVisible<sup>20+</sup> | boolean | 否 | 是 | 组件是否无障碍可见。true表示可见，false表示不可见。| 602| mainWindowId<sup>20+</sup> | number | 否 | 是 | 组件的主窗口ID。| 603| clip<sup>20+</sup> | boolean | 否 | 是 | 组件是否需要裁剪。true表示需要裁剪，false表示不需要裁剪。| 604| parentId<sup>20+</sup> | number | 否 | 是 | 组件的父元素ID。| 605| childrenIds<sup>20+</sup> | Array\<number> | 否 | 是 | 组件的子元素ID列表。| 606 607**示例：** 608```ts 609import { AccessibilityElement } from '@kit.AccessibilityKit'; 610import { BusinessError } from '@kit.BasicServicesKit'; 611 612let windowId: number = 10; 613 614axContext.getRootInActiveWindow(windowId)..then((element: AccessibilityElement) => { 615 console.info("AccessibilityElement.checkable: " + element.checkable) 616 console.info("AccessibilityElement.checked: " + element.checked) 617 console.info("AccessibilityElement.clickable: " + element.clickable) 618 console.info("AccessibilityElement.componentId: " + element.componentId) 619 console.info("AccessibilityElement.componentType: " + element.componentType) 620 console.info("AccessibilityElement.contents: " + element.contents) 621 console.info("AccessibilityElement.currentIndex: " + element.currentIndex) 622 console.info("AccessibilityElement.description: " + element.description) 623 // .... 624}).catch((err) => { 625 console.log(`getRootInActiveWindow failed, code: ${err.code}, message: ${err.message}`); 626}) 627``` 628 629### enableScreenCurtain<sup>12+</sup> 630 631enableScreenCurtain(isEnable: boolean): void; 632 633提供开启/关闭幕帘屏的能力。 634 635**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 636 637**参数：** 638 639| 参数名 | 类型 | 必填 | 说明 | 640| ----------- | ---------------------------------------- | ---- | -------------- | 641| isEnable | boolean | 是 | true表示打开幕帘屏功能，false表示关闭幕帘屏功能。| 642 643**错误码：** 644 645以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 646 647| 错误码ID | 错误信息 | 648| ------- | ---------------------------------------- | 649| 202 | Permission verification failed. A non-system application calls a system API. | 650| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 651| 9300003 | No accessibility permission to perform the operation. | 652 653**示例：** 654 655```ts 656import { 657 AccessibilityElement, 658 AccessibilityEvent, 659 AccessibilityExtensionContext 660} from '@kit.AccessibilityKit'; 661import { BusinessError } from '@kit.BasicServicesKit'; 662 663export default class AccessibilityManager { 664 private static instance: AccessibilityManager; 665 context?: AccessibilityExtensionContext; 666 667 static getInstance(): AccessibilityManager { 668 if (!AccessibilityManager.instance) { 669 AccessibilityManager.instance = new AccessibilityManager(); 670 } 671 return AccessibilityManager.instance; 672 } 673 674 onStart(context: AccessibilityExtensionContext) { 675 this.context = context; 676 } 677 678 onStop() { 679 this.context = undefined; 680 } 681 682 onEvent(accessibilityEvent: AccessibilityEvent): void { 683 if (!this.context) { 684 console.error('context is not available!'); 685 return; 686 } 687 this.context.getWindowRootElement().then((rootElement: AccessibilityElement) => { 688 console.log(`Succeeded in get root element of the window, ${JSON.stringify(rootElement)}`); 689 rootElement.enableScreenCurtain(true); 690 console.log(`Succeeded in enableScreenCurtain`); 691 }).catch((err: BusinessError) => { 692 console.error(`failed to enableScreenCurtain, Code is ${err.code}, message is ${err.message}`); 693 }); 694 } 695} 696``` 697 698### findElement('elementId')<sup>12+</sup> 699 700findElement(type: 'elementId', condition: number): Promise\<AccessibilityElement>; 701 702根据elementId查询当前活动窗口下的节点元素，使用Promise异步回调。 703 704**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 705 706**参数：** 707 708| 参数名 | 类型 | 必填 | 说明 | 709| --------- | --------------------------------- | ---- | ---------------------------------------- | 710| type | string | 是 | 固定为'elementId', 表示根据elementId查询当前活动窗口下的节点元素。 | 711| condition | number | 是 | 表示要查询的节点元素的elementId。 | 712 713**返回值：** 714 715| 类型 | 说明 | 716| ----------------------------------- | -------------------------------- | 717| Promise<[AccessibilityElement](js-apis-inner-application-accessibilityExtensionContext.md#accessibilityelement9)> | Promise对象，返回满足指定查询条件的节点元素。 | 718 719**错误码：** 720 721以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 722 723| 错误码ID | 错误信息 | 724| ------- | ----------------------------- | 725| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 726 727**示例：** 728 729```ts 730import { BusinessError } from '@kit.BasicServicesKit'; 731 732//elementId为10 733let condition = 10; 734 735// rootElement是AccessibilityElement的实例 736rootElement.findElement('elementId', condition).then((data: AccessibilityElement) => { 737 console.log(`Succeeded in find element, ${JSON.stringify(data)}`); 738}).catch((err: BusinessError) => { 739 console.error(`failed to find element, Code is ${err.code}, message is ${err.message}`); 740}); 741``` 742 743### findElement('textType')<sup>12+</sup> 744 745findElement(type: 'textType', condition: string): Promise\<Array\<AccessibilityElement>>; 746 747根据节点配置的accessibilityTextHint无障碍文本类型查询所有节点元素，使用Promise异步回调。 748 749**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 750 751**参数：** 752 753| 参数名 | 类型 | 必填 | 说明 | 754| --------- | ------ | ---- | ----------------------------- | 755| type | string | 是 | 固定为'textType', 表示根据文本类型查找节点元素。 | 756| condition | string | 是 | 表示查找的条件。 | 757 758**返回值：** 759 760| 类型 | 说明 | 761| ---------------------------------------- | ----------------------------- | 762| Promise<Array<[AccessibilityElement](js-apis-inner-application-accessibilityExtensionContext.md#accessibilityelement9)>> | Promise对象，返回满足指定查询关键字的所有节点元素。 | 763 764**错误码：** 765 766以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 767 768| 错误码ID | 错误信息 | 769| ------- | ----------------------------- | 770| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 771 772**示例：** 773 774```ts 775import { BusinessError } from '@kit.BasicServicesKit'; 776 777// condition的内容需要与目标组件accessibilityTextHint属性的type字段值保持一致 778let condition = 'location'; 779 780// rootElement是AccessibilityElement的实例 781rootElement.findElement('textType', condition).then((data: AccessibilityElement[]) => { 782 console.log(`Succeeded in find element, ${JSON.stringify(data)}`); 783}).catch((err: BusinessError) => { 784 console.error(`failed to find element, Code is ${err.code}, message is ${err.message}`); 785}); 786``` 787 788### getCursorPosition<sup>12+</sup> 789 790getCursorPosition(): Promise\<number>; 791 792获取文本组件中光标位置，使用Promise异步回调。 793 794**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 795 796**返回值：** 797 798| 类型 | 说明 | 799| ------------------- | ---------------- | 800| Promise<number> | Promise对象，返回当前光标所处位置。 | 801 802**示例：** 803 804```ts 805import { BusinessError } from '@kit.BasicServicesKit'; 806 807// rootElement是AccessibilityElement的实例 808rootElement.getCursorPosition().then((data: number) => { 809 console.info(`Succeeded in getCursorPosition, ${data}`); 810}).catch((err: BusinessError) => { 811 console.error(`failed to getCursorPosition, Code is ${err.code}, message is ${err.message}`); 812}); 813``` 814 815### getCursorPosition<sup>12+</sup> 816 817getCursorPosition(callback: AsyncCallback\<number>): void; 818 819获取文本组件中光标位置，使用callback异步回调。 820 821**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 822 823**参数：** 824 825| 参数名 | 类型 | 必填 | 说明 | 826| ----------- | ---------------------------------------- | ---- | -------------- | 827| callback | AsyncCallback<number> | 是 | 回调函数，表示文本组件中光标位置。| 828 829**示例：** 830 831```ts 832import { BusinessError } from '@kit.BasicServicesKit'; 833 834// rootElement是AccessibilityElement的实例 835rootElement.getCursorPosition((err: BusinessError, data: number) => { 836 if (err && err.code) { 837 console.error(`failed to getCursorPosition, Code is ${err.code}, message is ${err.message}`); 838 return; 839 } 840 console.info(`Succeeded in getCursorPosition, ${data}`); 841}); 842``` 843 844 845### executeAction<sup>20+</sup> 846 847executeAction(action: AccessibilityAction, parameters?: Parameter): Promise\<void>; 848 849根据action指定的操作类型和parameters传入的参数，执行特定操作。使用Promise异步回调。 850 851**权限:** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 852 853**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 854 855**参数：** 856 857| 参数名 | 类型 | 必填 | 说明 | 858| ----------- | ---------------------------------------- | ---- |----------------------------------------------------------| 859| action | [AccessibilityAction](./js-apis-accessibility-sys.md#accessibilityaction)| 是 | 无障碍节点可执行的操作。 860| parameters | [Parameter](#parameter20) | 否 | 执行操作时设置的参数值，默认为空。 | 861 862**返回值：** 863 864| 类型 | 说明 | 865| ------------------- | ---------------- | 866| Promise<void> | 无返回结果的Promise对象。 | 867 868**错误码：** 869 870以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 871 872| 错误码ID | 错误信息 | 873| ------- | ---------------------------------------- | 874| 201 | Permission verification failed.The application does not have the permission required to call the API. | 875| 202 | Permission verification failed. A non-system application calls a system API. | 876| 9300005 | This action is not supported. | 877 878**示例：** 879```ts 880//无参数Action示例： 881import { BusinessError } from '@kit.BasicServicesKit'; 882import { AccessibilityAction, Parameter } from '@kit.AccessibilityKit'; 883 884// rootElement是AccessibilityElement的实例 885// Action描述中无明确要求的，均为无参数Action 886try { 887 rootElement.executeAction(AccessibilityAction.CLICK); 888 console.info(`Succeeded in perform action CLICK`); 889}catch (error){ 890 console.error(`failed to perform action CLICK, Code is ${error?.code}, message is ${error?.message}`); 891} 892``` 893 894 895 896```ts 897//有参数Action示例： 898import { BusinessError } from '@kit.BasicServicesKit'; 899import { AccessibilityAction, Parameter } from '@kit.AccessibilityKit'; 900 901try { 902 // selectTextBegin: 表示选择起始位置 903 // selectTextEnd: 表示选择结束位置 904 // selectTextInForWard: true表示为前光标，false表示为后光标 905 let p : Parameter = { selectTextBegin: '0', selectTextEnd: '8', selectTextInForWard: true } 906 // rootElement是AccessibilityElement的实例 907 // setSelection示例代码 908 rootElement.executeAction(AccessibilityAction.SET_SELECTION, p); 909 console.info(`Succeeded in perform action SET_SELECTION`); 910}catch (error){ 911 console.error(`failed to perform action SET_SELECTION, Code is ${error?.code}, message is ${error?.message}`); 912} 913``` 914 915```ts 916//有参数Action示例： 917import { BusinessError } from '@kit.BasicServicesKit'; 918import { AccessibilityAction, Parameter } from '@kit.AccessibilityKit'; 919 920try { 921 // offset: 表示光标的设置位置 922 let p : Parameter = { offset: '1' } 923 // rootElement是AccessibilityElement的实例 924 // setCursorPosition示例代码 925 rootElement.executeAction(AccessibilityAction.SET_CURSOR_POSITION, p); 926 console.info(`Succeeded in perform action SET_CURSOR_POSITION`); 927}catch (error){ 928 console.error(`failed to perform action SET_CURSOR_POSITION, Code is ${error?.code}, message is ${error?.message}`); 929} 930``` 931 932### getParent<sup>20+</sup> 933 934getParent(): Promise\<AccessibilityElement>; 935 936获取无障碍节点元素的父元素。 937 938**权限:** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 939 940**系统能力:** SystemCapability.BarrierFree.Accessibility.Core 941 942**返回值：** 943 944| 类型 | 描述 | 945| ---------------------------------------- | --------------------- | 946| Promise\<[AccessibilityElement](#accessibilityelement12)> | 父元素。| 947 948**错误码：** 949 950以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 951 952| 错误码ID | 错误信息 | 953| ------- | ---------------------------------------- | 954| 201 | Permission verification failed.The application does not have the permission required to call the API. | 955| 202 | Permission verification failed. A non-system application calls a system API. | 956 957**示例：** 958 959```ts 960import { AccessibilityElement } from '@kit.AccessibilityKit'; 961import { BusinessError } from '@kit.BasicServicesKit'; 962 963axContext.getAccessibilityFocusedElement().then((element: AccessibilityElement) => { 964 console.log(`element parent id: ${element.parentId}`); 965 element.getParent().then((parent: AccessibilityElement) => { 966 console.log(`parent element's parent id: ${parent.parentId}`); 967 }).catch((err) => { 968 console.log(`getParent failed, code: ${err.code}, message: ${err.message}`); 969 }) 970}).catch((err) => { 971 console.log(`getAccessibilityFocusedElement failed, code: ${err.code}, message: ${err.message}`); 972}) 973``` 974 975### getChildren<sup>20+</sup> 976 977getChildren(): Promise\<Array\<AccessibilityElement>>; 978 979获取元素的子元素列表。 980 981**权限:** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 982 983**系统能力:** SystemCapability.BarrierFree.Accessibility.Core 984 985**返回值：** 986 987| 类型 | 描述 | 988| ---------------------------------------- | --------------------- | 989| Promise\<Array\<[AccessibilityElement](#accessibilityelement12)>> | 子元素数组。| 990 991**错误码：** 992 993以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 994 995| 错误码ID | 错误信息 | 996| ------- | ---------------------------------------- | 997| 201 | Permission verification failed.The application does not have the permission required to call the API. | 998| 202 | Permission verification failed. A non-system application calls a system API. | 999 1000**示例：** 1001 1002```ts 1003import { AccessibilityElement } from '@kit.AccessibilityKit'; 1004import { BusinessError } from '@kit.BasicServicesKit'; 1005 1006axContext.getAccessibilityFocusedElement().then((element: AccessibilityElement) => { 1007 console.log(`element childrenIds: ${element.childrenIds}`); 1008 element.getChildren().then((children: AccessibilityElement[]) => { 1009 console.log(`children element's size: ${children.length}`); 1010 }).catch((err) => { 1011 console.log(`getChildren failed, code: ${err.code}, message: ${err.message}`); 1012 }) 1013}).catch((err) => { 1014 console.log(`getAccessibilityFocusedElement failed, code: ${err.code}, message: ${err.message}`); 1015}) 1016``` 1017 1018### getRoot<sup>20+</sup> 1019 1020getRoot(): Promise\<AccessibilityElement>; 1021 1022获取活动窗口中的根元素。 1023 1024**权限:** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 1025 1026**系统能力:** SystemCapability.BarrierFree.Accessibility.Core 1027 1028**返回值：** 1029 1030| 类型 | 描述 | 1031| ---------------------------------------- | --------------------- | 1032| Promise\<[AccessibilityElement](#accessibilityelement12)> | 根元素。| 1033 1034**错误码：** 1035 1036以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1037 1038| 错误码ID | 错误信息 | 1039| ------- | ---------------------------------------- | 1040| 201 | Permission verification failed.The application does not have the permission required to call the API. | 1041| 202 | Permission verification failed. A non-system application calls a system API. | 1042 1043**示例：** 1044 1045```ts 1046import { AccessibilityElement } from '@kit.AccessibilityKit'; 1047import { BusinessError } from '@kit.BasicServicesKit'; 1048 1049let windows: AccessibilityWindow[] = axContext.getAccessibilityWindowsSync() 1050for (let window of windows) { 1051 console.log(`window id: ${window.windowId}`); 1052 window.getRoot().then((root: AccessibilityElement) => { 1053 console.log(`root element's componentId: ${root.componentId}`); 1054 }).catch((err) => { 1055 console.log(`getRoot failed, code: ${err.code}, message: ${err.message}`); 1056 }) 1057} 1058``` 1059 1060### findElementByContent<sup>20+</sup> 1061 1062findElementByContent(condition: string): Promise\<Array\<AccessibilityElement>>; 1063 1064根据内容查找元素。 1065 1066**权限:** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 1067 1068**系统能力:** SystemCapability.BarrierFree.Accessibility.Core 1069 1070**参数：** 1071 1072| 名称 | 类型 | 必填 | 描述 | 1073| -------- | ---- | -------- | ------------------------------------------------------------ | 1074| condition | string | 是 | 内容。 | 1075 1076**返回值：** 1077 1078| 类型 | 描述 | 1079| ---------------------------------------- | --------------------- | 1080| Promise\<Array\<[AccessibilityElement](#accessibilityelement12)>> | 元素数组。| 1081 1082**错误码：** 1083 1084以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 1085 1086| 错误码ID | 错误信息 | 1087| ------- | ---------------------------------------- | 1088| 201 | Permission verification failed.The application does not have the permission required to call the API. | 1089| 202 | Permission verification failed. A non-system application calls a system API. | 1090| 9300006 | The target application failed to connect to accessibility service. | 1091 1092**示例：** 1093 1094```ts 1095// Page.ets 1096 build() { 1097 Text('Connect') 1098 .id('connect') 1099 .fontSize($r('app.float.page_text_font_size')) 1100 .fontWeight(FontWeight.Bold) 1101// ... 1102 1103// AccessibilityExtAbility.ets 1104import { AccessibilityElement } from '@kit.AccessibilityKit'; 1105import { BusinessError } from '@kit.BasicServicesKit'; 1106 1107let windowId: number = 10; 1108 1109axContext.getRootInActiveWindow(windowId)..then((root: AccessibilityElement) => { 1110 root.findElementByContent('connect').then((elements: AccessibilityElement[]) => { 1111 console.log("findElementByContent size=" + elements.length) 1112 }).catch((err) => { 1113 console.log(`findElementByContent failed, code: ${err.code}, message: ${err.message}`); 1114 }) 1115}).catch((err) => { 1116 console.log(`getRootInActiveWindow failed, code: ${err.code}, message: ${err.message}`); 1117}) 1118``` 1119 1120### findElementByFocusDirection<sup>20+</sup> 1121 1122findElementByFocusDirection(condition: FocusDirection): Promise\<AccessibilityElement>; 1123 1124根据焦点方向查找元素。 1125 1126**权限：** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 1127 1128**系统能力:** SystemCapability.BarrierFree.Accessibility.Core 1129 1130**参数：** 1131 1132| 名称 | 类型 | 必填 | 描述 | 1133| -------- | ---- | -------- | ------------------------------------------------------------ | 1134| condition | FocusDirection | 是 | 焦点方向。 | 1135 1136**返回值：** 1137 1138| 类型 | 描述 | 1139| ---------------------------------------- | --------------------- | 1140| Promise\<[AccessibilityElement](#accessibilityelement12)> | AccessibilityElement.| 1141 1142**错误码：** 1143 1144以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 1145 1146| 错误码ID | 错误信息 | 1147| ------- | ---------------------------------------- | 1148| 201 | Permission verification failed.The application does not have the permission required to call the API. | 1149| 202 | Permission verification failed. A non-system application calls a system API. | 1150| 9300006 | The target application failed to connect to accessibility service. | 1151 1152**示例：** 1153 1154```ts 1155// Page.ets 1156// Click TextInput and then it is the accessibility focus element, up direction element is Text#connect 1157 build() { 1158 Text('Connect') 1159 .id('connect') 1160 .fontSize($r('app.float.page_text_font_size')) 1161 .fontWeight(FontWeight.Bold) 1162 1163 TextInput({ placeholder: 'please input...' }) 1164 .id('text_input') 1165 .fontSize($r('app.float.page_text_font_size')) 1166// ... 1167 1168// AccessibilityExtAbility.ets 1169import { AccessibilityElement } from '@kit.AccessibilityKit'; 1170import { BusinessError } from '@kit.BasicServicesKit'; 1171 1172axContext.getAccessibilityFocusedElement().then((focus: AccessibilityElement) => { 1173 focus.findElementByFocusDirection('up').then((element: AccessibilityElement) => { 1174 console.log("findElementByFocusDirection UP componentId: " + element.componentId); 1175 }).catch((err) => { 1176 console.log(`findElementByFocusDirection UP failed, code: ${err.code}, message: ${err.message}`); 1177 }) 1178}).catch((err) => { 1179 console.log(`getAccessibilityFocusedElement failed, code: ${err.code}, message: ${err.message}`); 1180}) 1181``` 1182 1183### findElementsByAccessibilityHintText<sup>20+</sup> 1184 1185findElementsByAccessibilityHintText(condition: string): Promise\<Array\<AccessibilityElement>>; 1186 1187根据性提示文本查找元素。 1188 1189**权限：** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 1190 1191**系统能力:** SystemCapability.BarrierFree.Accessibility.Core 1192 1193**参数：** 1194 1195| 名称 | 类型 | 必填 | 描述 | 1196| -------- | ---- | -------- | ------------------------------------------------------------ | 1197| condition | string | 是 | 提示文本。 | 1198 1199**返回值：** 1200 1201| 类型 | 描述 | 1202| ---------------------------------------- | --------------------- | 1203| Promise\<Array\<[AccessibilityElement](#accessibilityelement12)>> | 元素数组。| 1204 1205**错误码：** 1206 1207以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 1208 1209| 错误码ID | 错误信息 | 1210| ------- | ---------------------------------------- | 1211| 201 | Permission verification failed.The application does not have the permission required to call the API. | 1212| 202 | Permission verification failed. A non-system application calls a system API. | 1213| 9300006 | The target application failed to connect to accessibility service. | 1214 1215**示例：** 1216 1217```ts 1218// Page.ets 1219 build() { 1220 Text('Connect') 1221 .id('connect') 1222 .fontSize($r('app.float.page_text_font_size')) 1223 .fontWeight(FontWeight.Bold) 1224 1225 TextInput({ placeholder: 'please input...' }) 1226 .id('text_input') 1227 .fontSize($r('app.float.page_text_font_size')) 1228 .accessibilityTextHint('location') 1229// ... 1230 1231// AccessibilityExtAbility.ets 1232import { AccessibilityElement } from '@kit.AccessibilityKit'; 1233import { BusinessError } from '@kit.BasicServicesKit'; 1234 1235let windowId: number = 10; 1236 1237axContext.getRootInActiveWindow(windowId).then((root: AccessibilityElement) => { 1238 root.findElementsByAccessibilityHintText('location').then((elements: AccessibilityElement[]) => { 1239 console.log("findElementsByAccessibilityHintText size=" + elements.length) 1240 }).catch((err) => { 1241 console.log(`findElementsByAccessibilityHintText failed, code: ${err.code}, message: ${err.message}`); 1242 }) 1243}).catch((err) => { 1244 console.log(`getRootInActiveWindow failed, code: ${err.code}, message: ${err.message}`); 1245}) 1246``` 1247 1248### findElementById<sup>20+</sup> 1249 1250findElementById(condition: number): Promise\<AccessibilityElement>; 1251 1252根据元素 ID 查找元素。 1253 1254**权限：** ohos.permission.ACCESSIBILITY_EXTENSION_ABILITY 1255 1256**系统能力:** SystemCapability.BarrierFree.Accessibility.Core 1257 1258**参数：** 1259 1260| 名称 | 类型 | 必填 | 描述 | 1261| -------- | ---- | -------- | ------------------------------------------------------------ | 1262| condition | number | 是 | 元素 ID。 | 1263 1264**返回值：** 1265 1266| 类型 | 描述 | 1267| ---------------------------------------- | --------------------- | 1268| Promise\<[AccessibilityElement](#accessibilityelement12)> | AccessibilityElement.| 1269 1270**错误码：** 1271 1272以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[无障碍子系统错误码](errorcode-accessibility.md)。 1273 1274| 错误码ID | 错误信息 | 1275| ------- | ---------------------------------------- | 1276| 201 | Permission verification failed.The application does not have the permission required to call the API.| 1277| 202 | Permission verification failed. A non-system application calls a system API. | 1278| 9300006 | The target application failed to connect to accessibility service. | 1279 1280**示例：** 1281 1282```ts 1283// Page.ets 1284// Click TextInput and then it is the accessibility focus element 1285 build() { 1286 Text('Connect') 1287 .id('connect') 1288 .fontSize($r('app.float.page_text_font_size')) 1289 .fontWeight(FontWeight.Bold) 1290 1291 TextInput({ placeholder: 'please input...' }) 1292 .id('text_input') 1293 .fontSize($r('app.float.page_text_font_size')) 1294// ... 1295 1296// AccessibilityExtAbility.ets 1297import { AccessibilityElement } from '@kit.AccessibilityKit'; 1298import { BusinessError } from '@kit.BasicServicesKit'; 1299 1300axContext.getAccessibilityFocusedElement().then((focus: AccessibilityElement) => { 1301 focus.findElementById(0).then((element: AccessibilityElement) => { 1302 console.log("findElementById componentId: " + element.componentId); 1303 }).catch((err) => { 1304 console.log(`findElementById failed, code: ${err.code}, message: ${err.message}`); 1305 }) 1306}).catch((err) => { 1307 console.log(`getAccessibilityFocusedElement failed, code: ${err.code}, message: ${err.message}`); 1308}) 1309``` 1310