1# @ohos.accessibility (Accessibility) 2 3The **Accessibility** module implements the accessibility functions, including obtaining the accessibility application list, accessibility application enabled status, and captions configuration. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import { accessibility } from '@kit.AccessibilityKit'; 13``` 14 15## AbilityState 16 17type AbilityState = 'enable' | 'disable' | 'install' 18 19Enumerates the states of an accessibility application. 20 21**System capability**: SystemCapability.BarrierFree.Accessibility.Core 22 23| Type | Description | 24| ------- | -------- | 25| 'enable' | The accessibility application is enabled.| 26| 'disable' | The accessibility application is disabled.| 27| 'install' | The accessibility application has been installed.| 28 29## AbilityType 30 31Enumerates the types of accessibility applications. 32 33**System capability**: SystemCapability.BarrierFree.Accessibility.Core 34 35| Name | Description | 36| ---------------- | --------- | 37| audible | The accessibility application provides audible feedback.| 38| generic | The accessibility application provides generic feedback.| 39| haptic | The accessibility application provides haptic feedback.| 40| spoken | The accessibility application provides spoken feedback.| 41| visual | The accessibility application provides visual feedback.| 42| all<sup>9+</sup> | All the preceding types.| 43 44## AccessibilityAbilityInfo 45 46Provides information about an accessibility application. 47 48**System capability**: SystemCapability.BarrierFree.Accessibility.Core 49 50### Attributes 51 52| Name | Type | Readable | Writable | Description | 53| ------------------------------ | ---------------------------------------- | ---- | ---- | ---------------- | 54| id | string | Yes | No | Ability ID.| 55| name | string | Yes | No | Ability name. | 56| bundleName | string | Yes | No | Bundle name. | 57| targetBundleNames<sup>9+</sup> | Array<string> | Yes | No | Name of the target bundle. | 58| abilityTypes | Array<[AbilityType](#abilitytype)> | Yes | No | Accessibility application type. | 59| capabilities | Array<[Capability](#capability)> | Yes | No | Capabilities list of the accessibility application. | 60| description | string | Yes | No | Description of the accessibility application. | 61| eventTypes | Array<[EventType](#eventtype)> | Yes | No | List of events that the accessibility application focuses on. | 62| needHide<sup>12+</sup> | boolean | Yes | No | Whether the auxiliary application is hidden in the list of installed extended services. The value **true** means the auxiliary application is hidden, and the value **false** means the opposite. | 63| label<sup>12+</sup> | string | Yes | No | Name of the application in the extended service list. | 64 65## Action 66 67type Action = 'accessibilityFocus' | 'clearAccessibilityFocus' | 'focus' | 'clearFocus' | 'clearSelection' | 68 'click' | 'longClick' | 'cut' | 'copy' | 'paste' | 'select' | 'setText' | 'delete' | 69 'scrollForward' | 'scrollBackward' | 'setSelection' | 'setCursorPosition' | 'home' | 70 'back' | 'recentTask' | 'notificationCenter' | 'controlCenter' | 'common' 71 72Target actions supported by the application. The target actions for which parameters need to be set have been specified in the description of the following table. 73 74**System capability**: SystemCapability.BarrierFree.Accessibility.Core 75 76| Type | Description | 77| ----------------------- |--------------------| 78| 'click' | Clicking. | 79| 'longClick' | Long pressing. | 80| 'scrollForward' | Scrolling forward.| 81| 'scrollBackward' | Scrolling backward.| 82| 'focus' | Obtaining the focus.| 83| 'clearFocus' | Clearing focus.| 84| 'clearSelection' | Clearing selection. Not supported yet.| 85| 'accessibilityFocus' | Obtaining the accessibility focus. | 86| 'clearAccessibilityFocus' | Clearing the accessibility focus. | 87| 'cut' | Cut. | 88| 'copy' | Copy. | 89| 'paste' | Paste. | 90| 'select' | Select. | 91| 'setCursorPosition' | Set text. You need to set the **setText** parameter.| 92| 'delete' | Delete. Not supported yet. | 93| 'setSelection' | Select. You need to set the **selectTextBegin**, **selectTextEnd** and **selectTextInForWard** parameters. | 94| 'common' | Common actions used in auto-focusing and auto-broadcasting. | 95| 'home' | Return to the home screen. | 96| 'back' | Return to the previous screen. | 97| 'recentTask' | Open a recent task. | 98| 'notificationCenter' | Open the notification bar. | 99| 'controlCenter' | Open the control center. | 100| 'setCursorPosition' | Set cursor location. You need to set the **offset** parameter. | 101 102## Capability 103 104type Capability = 'retrieve' | 'touchGuide' | 'keyEventObserver' | 'zoom' | 'gesture' 105 106Enumerates the capabilities of an accessibility application. 107 108**System capability**: SystemCapability.BarrierFree.Accessibility.Core 109 110| Type | Description | 111| ---------------- |-----------------------| 112| 'retrieve' | Capability to retrieve the window content. | 113| 'touchGuide' | Capability of touch guide mode. | 114| 'keyEventObserver' | Capability to filter key events. | 115| 'zoom' | Capability to control the display zoom level. Not supported currently.| 116| 'gesture' | Capability to perform gesture actions. | 117 118## CaptionsFontEdgeType<sup>8+</sup> 119 120type CaptionsFontEdgeType = 'none' | 'raised' | 'depressed' | 'uniform' | 'dropShadow' 121 122Enumerates the font edge types of captions. 123 124**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 125 126| Type | Description | 127| ---------- | ----- | 128| 'none' | No effect. | 129| 'raised' | Raised effect.| 130| 'depressed' | Depressed effect.| 131| 'uniform' | Uniform effect.| 132| 'dropShadow' | Drop shadow effect.| 133 134## CaptionsFontFamily<sup>8+</sup> 135 136type CaptionsFontFamily = 'default' | 'monospacedSerif' | 'serif' | 'monospacedSansSerif' | 137 'sansSerif' | 'casual' | 'cursive' | 'smallCapitals' 138 139Enumerates the font families of captions. 140 141**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 142 143| Name | Description | 144| ------------------- | ----------------- | 145| 'default' | Default font family. | 146| 'monospacedSerif' | Monospaced Serif fonts, which use the same width for each character. | 147| 'serif' | Serif fonts. | 148| 'monospacedSansSerif' | Monospaced Sans Serif fonts, which use the same width for each character.| 149| 'sansSerif' | Sans Serif fonts. | 150| 'casual' | Casual fonts. | 151| 'cursive' | Cursive fonts. | 152| 'smallCapitals' | Small caps fonts. | 153 154## CaptionsStyle<sup>8+</sup> 155 156Describes the style of captions. 157 158**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 159 160| Name | Type | Readable | Writable | Description | 161| --------------- | ---------------------------------------- | ---- | ---- | ----------- | 162| fontFamily | [CaptionsFontFamily](#captionsfontfamily8) | Yes | No | Font family of captions. | 163| fontScale | number | Yes | No | Font scale factor of captions, in percentage. The value ranges from 1 to 200.| 164| fontColor | number \| string | Yes | No | Font color of captions. For example, red corresponds to #FF0000. | 165| fontEdgeType | [CaptionsFontEdgeType](#captionsfontedgetype8) | Yes | No | Font edge type of captions. | 166| backgroundColor | number \| string | Yes | No | Background color of captions. For example, red corresponds to #FF0000. | 167| windowColor | number \| string | Yes | No | Window color of captions. For example, red corresponds to #FF0000. | 168 169## CaptionsManager<sup>8+</sup> 170 171Implements configuration management for captions. Before calling any API of **CaptionsManager**, you must use the [accessibility.getCaptionsManager()](#accessibilitygetcaptionsmanagerdeprecated) API to obtain a **CaptionsManager** instance. 172 173**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 174 175### Attributes 176 177| Name | Type | Readable | Writable | Description | 178| ------- | -------------------------------- | ---- | ---- | ----------- | 179| enabled | boolean | Yes | No | Whether to enable captions configuration.| 180| style | [CaptionsStyle](#captionsstyle8) | Yes | No | Style of captions. | 181 182For a boolean return value, **True** means that the feature is enabled, and **False** means the opposite. 183 184### on('enableChange')<sup>(deprecated)</sup> 185 186on(type: 'enableChange', callback: Callback<boolean>): void; 187 188Enables listening for the enabled status changes of captions configuration. This API uses an asynchronous callback to return the result. 189 190> **NOTE** 191> 192> This API is deprecated since API version 12. 193 194**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 195 196**Parameters** 197 198| Name | Type | Mandatory | Description | 199| -------- | ----------------------- | ---- | --------------------------------------- | 200| type | string | Yes | Listening type, which is set to **'enableChange'** in this API.| 201| callback | Callback<boolean> | Yes | Callback invoked when the enabled status of captions configuration changes. | 202 203**Error codes** 204 205For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 206 207| ID| Error Message| 208| ------- | -------------------------------- | 209| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 210 211**Example** 212 213```ts 214import { accessibility } from '@kit.AccessibilityKit'; 215 216let captionsManager = accessibility.getCaptionsManager(); 217captionsManager.on('enableChange', (data: boolean) => { 218 console.info(`subscribe caption manager enable state change, result: ${JSON.stringify(data)}`); 219}) 220``` 221 222### on('styleChange')<sup>(deprecated)</sup> 223 224on(type: 'styleChange', callback: Callback<CaptionsStyle>): void; 225 226Enables listening for captions style changes. This API uses an asynchronous callback to return the result. 227 228> **NOTE** 229> 230> This API is deprecated since API version 12. 231 232**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 233 234**Parameters** 235 236| Name | Type | Mandatory | Description | 237| -------- | ---------------------------------------- | ---- | ---------------------------------- | 238| type | string | Yes | Listening type, which is set to **'styleChange'** in this API.| 239| callback | Callback<[CaptionsStyle](#captionsstyle8)> | Yes | Callback invoked when the style of captions changes. | 240 241**Error codes** 242 243For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 244 245| ID| Error Message| 246| ------- | -------------------------------- | 247| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 248 249**Example** 250 251```ts 252import { accessibility } from '@kit.AccessibilityKit'; 253 254let captionsManager = accessibility.getCaptionsManager(); 255 256captionsManager.on('styleChange', (data: accessibility.CaptionsStyle) => { 257 console.info(`subscribe caption manager style state change, result: ${JSON.stringify(data)}`); 258}); 259``` 260 261### off('enableChange')<sup>(deprecated)</sup> 262 263off(type: 'enableChange', callback?: Callback<boolean>): void; 264 265Disables listening for the enabled status changes of captions configuration. This API uses an asynchronous callback to return the result. 266 267> **NOTE** 268> 269> This API is deprecated since API version 12. 270 271**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 272 273**Parameters** 274 275| Name | Type | Mandatory| Description | 276| -------- | ----------------------- | ---- | ------------------------------------------------------------ | 277| type | string | Yes | Listening type, which is set to **'enableChange'** in this API.| 278| callback | Callback<boolean> | No | Callback used for disable listening. The value must be the same as the value of **callback** in **on('enableChange')**. If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.| 279 280**Error codes** 281 282For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 283 284| ID| Error Message| 285| ------- | -------------------------------- | 286| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 287 288**Example** 289 290```ts 291import { accessibility } from '@kit.AccessibilityKit'; 292 293let captionsManager = accessibility.getCaptionsManager(); 294 295captionsManager.off('enableChange', (data: boolean) => { 296 console.info(`Unsubscribe caption manager enable state change, result: ${JSON.stringify(data)}`); 297}); 298``` 299 300### off('styleChange')<sup>(deprecated)</sup> 301 302off(type: 'styleChange', callback?: Callback<CaptionsStyle>): void; 303 304Disables listening for captions style changes. This API uses an asynchronous callback to return the result. 305 306> **NOTE** 307> 308> This API is deprecated since API version 12. 309 310**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 311 312**Parameters** 313 314| Name | Type | Mandatory| Description | 315| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 316| type | string | Yes | Listening type, which is set to **'styleChange'** in this API. | 317| callback | Callback<[CaptionsStyle](#captionsstyle8)> | No | Callback used for disable listening. The value must be the same as the value of **callback** in **on('styleChange')**. If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.| 318 319**Error codes** 320 321For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 322 323| ID| Error Message| 324| ------- | -------------------------------- | 325| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 326 327**Example** 328 329```ts 330import { accessibility } from '@kit.AccessibilityKit'; 331 332let captionsManager = accessibility.getCaptionsManager(); 333 334captionsManager.off('styleChange', (data: accessibility.CaptionsStyle) => { 335 console.info(`Unsubscribe caption manager style state change, result: ${JSON.stringify(data)}`); 336}); 337``` 338 339## EventInfo 340 341Describes a GUI change event. 342 343**System capability**: SystemCapability.BarrierFree.Accessibility.Core 344 345### Attributes 346 347| Name | Type | Mandatory | Description | 348| ---------------- | ------------------------------------- |-----|-----------------------| 349| type | [EventType](#eventtype) | Yes | Accessibility event type. | 350| windowUpdateType | [WindowUpdateType](#windowupdatetype) | No | Window update type. | 351| bundleName | string | Yes | Name of the target application. | 352| componentType | string | No | Type of the event source component, for example, button or chart. | 353| pageId | number | No | Page ID of the event source. | 354| description | string | No | Event description. | 355| triggerAction | [Action](#action) | Yes | Action that triggers the event. | 356| textMoveUnit | [TextMoveUnit](#textmoveunit) | No | Text move granularity. | 357| contents | Array<string> | No | Array of contents. | 358| lastContent | string | No | Latest content. | 359| beginIndex | number | No | Sequence number of the first item displayed on the page.| 360| currentIndex | number | No | Sequence number of the current item. | 361| endIndex | number | No | Sequence number of the last item displayed on the page.| 362| itemCount | number | No | Total number of records. | 363| elementId<sup>12+</sup> | number | No | Element ID of the component. | 364| textAnnouncedForAccessibility<sup>12+</sup> | string | No | Content for auto-broadcasting. | 365| customId<sup>12+</sup> | string | No | Component ID for auto-focusing. | 366 367### constructor 368 369constructor(jsonObject) 370 371Implements a constructor. 372 373**System capability**: SystemCapability.BarrierFree.Accessibility.Core 374 375**Parameters** 376 377| Name | Type | Mandatory | Description | 378| ---------- | ------ | ---- | -------------------- | 379| jsonObject | string | Yes | JSON string required for creating an object.| 380 381**Example** 382 383 ```ts 384 import { accessibility } from '@kit.AccessibilityKit'; 385 386 let eventInfo: accessibility.EventInfo = ({ 387 type: 'click', 388 bundleName: 'com.example.MyApplication', 389 triggerAction: 'click', 390 }); 391 ``` 392 393### constructor<sup>11+</sup> 394 395constructor(type: EventType, bundleName: string, triggerAction: Action) 396 397Implements a constructor. 398 399**System capability**: SystemCapability.BarrierFree.Accessibility.Core 400 401**Parameters** 402 403| Name | Type | Mandatory| Description | 404|------|-------------------|---|---------------| 405| type | [EventType](#eventtype) | Yes| Enumerates accessibility event types. | 406| bundleName | string | Yes| Target application name. | 407| triggerAction | [Action](#action) | Yes| Action that triggers the event.| 408 409**Example** 410 411 ```ts 412 import { accessibility } from '@kit.AccessibilityKit'; 413 414 let eventInfo = new accessibility.EventInfo('click', 'com.example.MyApplication', 'click'); 415 ``` 416 417## EventType 418 419type EventType = 'accessibilityFocus' | 'accessibilityFocusClear' | 420'click' | 'longClick' | 'focus' | 'select' | 'hoverEnter' | 'hoverExit' | 421'textUpdate' | 'textSelectionUpdate' | 'scroll' | 'requestFocusForAccessibility' | 422'announceForAccessibility' 423 424Enumerates accessibility event types. 425 426**System capability**: SystemCapability.BarrierFree.Accessibility.Core 427 428| Type | Description | 429| ----------------------- |------------------------| 430| 'accessibilityFocus' | Represents an event indicating that the accessibility focus is obtained. | 431| 'accessibilityFocusClear' | Represents an event indicating that the accessibility focus is cleared. | 432| 'click' | Event of clicking a component. | 433| 'longClick' | Represents an event indicating that the component is long pressed. | 434| 'select' | Event of selecting a component. | 435| 'hoverEnter' | Event indicating that the hover enters a component. | 436| 'hoverExit' | Event indicating that the hover exits a component. | 437| 'focus' | Event indicating that the component obtains the focus. Not supported currently. | 438| 'textUpdate' | Event indicating that the component text has been updated.| 439| 'textSelectionUpdate' | Event indicating that the selected text has been updated. Not supported currently.| 440| 'scroll' | Event of the scroll view. | 441| 'requestFocusForAccessibility' | Event of the auto-focusing.| 442| 'announceForAccessibility' | Event of the auto-broadcasting.| 443 444 445## TextMoveUnit 446 447type TextMoveUnit = 'char' | 'word' | 'line' | 'page' | 'paragraph' 448 449Enumerates the movement units for traversing the node text. 450 451**System capability**: SystemCapability.BarrierFree.Accessibility.Core 452 453| Type | Description | 454| --------- | --------------- | 455| 'char' | The movement unit for traversing the node text is by character.| 456| 'word' | The movement unit for traversing the node text is by word. | 457| 'line' | The movement unit for traversing the node text is by line. | 458| 'page' | The movement unit for traversing the node text is by page. | 459| 'paragraph' | The movement unit for traversing the node text is by paragraph.| 460 461## WindowUpdateType 462 463type WindowUpdateType = 'add' | 'remove' | 'bounds' | 'active' | 'focus' 464 465Enumerates window update types. 466 467**System capability**: SystemCapability.BarrierFree.Accessibility.Core 468 469| Type | Description | 470| ------ | ------------------ | 471| 'add' | Window adding. | 472| 'remove' | Window deletion. | 473| 'bounds' | Window boundary change. | 474| 'active' | Window activity change.| 475| 'focus' | Window focus change. | 476 477## accessibility.getAbilityLists<sup>(deprecated)</sup> 478 479getAbilityLists(abilityType: AbilityType, stateType: AbilityState): Promise<Array<AccessibilityAbilityInfo>> 480 481Obtains the accessibility application list. This API uses a promise to return the result. 482 483> **NOTE** 484> 485> This API is supported since API version 7 and deprecated since API version 9. 486> You are advised to use [accessibility.getAccessibilityExtensionList()](#accessibilitygetaccessibilityextensionlist9) instead. 487 488**System capability**: SystemCapability.BarrierFree.Accessibility.Core 489 490**Parameters** 491 492| Name | Type | Mandatory | Description | 493| ----------- | ----------------------------- | ---- | -------- | 494| abilityType | [AbilityType](#abilitytype) | Yes | Accessibility application type.| 495| stateType | [AbilityState](#abilitystate) | Yes | Accessibility application status.| 496 497**Return value** 498 499| Type | Description | 500| ---------------------------------------- | --------------------- | 501| Promise<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | Promise used to return the accessibility application list.| 502 503**Example** 504 505```ts 506import { accessibility } from '@kit.AccessibilityKit'; 507import { BusinessError } from '@kit.BasicServicesKit'; 508 509let abilityType: accessibility.AbilityType = 'spoken'; 510let abilityState: accessibility.AbilityState = 'enable'; 511 512accessibility.getAbilityLists(abilityType, abilityState).then((data: accessibility.AccessibilityAbilityInfo[]) => { 513 console.info(`Succeeded in get accessibility extension list, ${JSON.stringify(data)}`); 514}).catch((err: BusinessError) => { 515 console.error(`failed to get accessibility extension list because ${JSON.stringify(err)}`); 516}); 517``` 518 519## accessibility.getAbilityLists<sup>(deprecated)</sup> 520 521getAbilityLists(abilityType: AbilityType, stateType: AbilityState,callback: AsyncCallback<Array<AccessibilityAbilityInfo>>): void 522 523Obtains the accessibility application list. This API uses an asynchronous callback to return the result. 524 525> **NOTE** 526> 527> This API is supported since API version 7 and deprecated since API version 9. 528> You are advised to use [accessibility.getAccessibilityExtensionList()](#accessibilitygetaccessibilityextensionlist9-1) instead. 529 530**System capability**: SystemCapability.BarrierFree.Accessibility.Core 531 532**Parameters** 533 534| Name | Type | Mandatory | Description | 535| ----------- | ---------------------------------------- | ---- | ---------------- | 536| abilityType | [AbilityType](#abilitytype) | Yes | Accessibility application type. | 537| stateType | [AbilityState](#abilitystate) | Yes | Accessibility application status. | 538| callback | AsyncCallback<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | Yes | Callback used to return the accessibility application list.| 539 540**Example** 541 542```ts 543import { accessibility } from '@kit.AccessibilityKit'; 544import { BusinessError } from '@kit.BasicServicesKit'; 545 546let abilityType: accessibility.AbilityType = 'spoken'; 547let abilityState: accessibility.AbilityState = 'enable'; 548 549accessibility.getAbilityLists(abilityType, abilityState, (err: BusinessError, data: accessibility.AccessibilityAbilityInfo[]) => { 550 if (err) { 551 console.error(`failed to get accessibility extension list because ${JSON.stringify(err)}`); 552 return; 553 } 554 console.info(`Succeeded in get accessibility extension list, ${JSON.stringify(data)}`); 555}) 556``` 557 558## accessibility.getAccessibilityExtensionList<sup>9+</sup> 559 560getAccessibilityExtensionList(abilityType: AbilityType, stateType: AbilityState): Promise<Array<AccessibilityAbilityInfo>> 561 562Obtains the accessibility application list. This API uses a promise to return the result. 563 564**System capability**: SystemCapability.BarrierFree.Accessibility.Core 565 566**Parameters** 567 568| Name | Type | Mandatory | Description | 569| ----------- | ----------------------------- | ---- | -------- | 570| abilityType | [AbilityType](#abilitytype) | Yes | Accessibility application type.| 571| stateType | [AbilityState](#abilitystate) | Yes | Accessibility application status.| 572 573**Return value** 574 575| Type | Description | 576| ---------------------------------------- | --------------------- | 577| Promise<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | Promise used to return the accessibility application list.| 578 579**Error codes** 580 581For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 582 583| ID| Error Message| 584| ------- | -------------------------------- | 585| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 586 587**Example** 588 589```ts 590import { accessibility } from '@kit.AccessibilityKit'; 591import { BusinessError } from '@kit.BasicServicesKit'; 592 593let abilityType: accessibility.AbilityType = 'spoken'; 594let abilityState: accessibility.AbilityState = 'enable'; 595 596accessibility.getAccessibilityExtensionList(abilityType, abilityState).then((data: accessibility.AccessibilityAbilityInfo[]) => { 597 console.info(`Succeeded in get accessibility extension list, ${JSON.stringify(data)}`); 598}).catch((err: BusinessError) => { 599 console.error(`failed to get accessibility extension list, Code is ${err.code}, message is ${err.message}`); 600}); 601``` 602 603## accessibility.getAccessibilityExtensionList<sup>9+</sup> 604 605getAccessibilityExtensionList(abilityType: AbilityType, stateType: AbilityState, callback: AsyncCallback<Array<AccessibilityAbilityInfo>>): void 606 607Obtains the accessibility application list. This API uses an asynchronous callback to return the result. 608 609**System capability**: SystemCapability.BarrierFree.Accessibility.Core 610 611**Parameters** 612 613| Name | Type | Mandatory | Description | 614| ----------- | ---------------------------------------- | ---- | ---------------- | 615| abilityType | [AbilityType](#abilitytype) | Yes | Accessibility application type. | 616| stateType | [AbilityState](#abilitystate) | Yes | Accessibility application status. | 617| callback | AsyncCallback<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | Yes | Callback used to return the accessibility application list.| 618 619**Error codes** 620 621For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 622 623| ID| Error Message| 624| ------- | -------------------------------- | 625| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 626 627**Example** 628 629```ts 630import { accessibility } from '@kit.AccessibilityKit'; 631import { BusinessError } from '@kit.BasicServicesKit'; 632 633let abilityType: accessibility.AbilityType = 'spoken'; 634let abilityState: accessibility.AbilityState = 'enable'; 635 636accessibility.getAccessibilityExtensionList(abilityType, abilityState,(err: BusinessError, data: accessibility.AccessibilityAbilityInfo[]) => { 637 if (err) { 638 console.error(`failed to get accessibility extension list, Code is ${err.code}, message is ${err.message}`); 639 return; 640 } 641 console.info(`Succeeded in get accessibility extension list, ${JSON.stringify(data)}`); 642}); 643``` 644 645## accessibility.getAccessibilityExtensionListSync<sup>12+</sup> 646 647getAccessibilityExtensionListSync(abilityType: AbilityType, stateType: AbilityState): Array<AccessibilityAbilityInfo> 648 649Obtains the API for synchronizing the accessibility application list. 650 651**System capability**: SystemCapability.BarrierFree.Accessibility.Core 652 653**Parameters** 654 655| Name | Type | Mandatory | Description | 656| ----------- | ----------------------------- | ---- | -------- | 657| abilityType | [AbilityType](#abilitytype) | Yes | Accessibility application type.| 658| stateType | [AbilityState](#abilitystate) | Yes | Accessibility application status.| 659 660**Return value** 661 662| Type | Description | 663| ---------------------------------------- | --------------------- | 664| Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)> | Promise used to return the accessibility application list.| 665 666**Example** 667 668```ts 669import { accessibility } from '@kit.AccessibilityKit'; 670import { BusinessError } from '@kit.BasicServicesKit'; 671 672let abilityType: accessibility.AbilityType = 'all'; 673let abilityState: accessibility.AbilityState = 'install'; 674let data: accessibility.AccessibilityAbilityInfo[]; 675 676try { 677 data = accessibility.getAccessibilityExtensionListSync(abilityType, abilityState); 678 console.info(`Succeeded in get accessibility extension list, ${JSON.stringify(data)}`); 679} catch (error) { 680 let err = error as BusinessError; 681 console.error(`error code: ${err.code}`); 682} 683``` 684 685## accessibility.getCaptionsManager<sup>(deprecated)</sup> 686 687getCaptionsManager(): CaptionsManager 688 689Obtains a **CaptionsManager** instance. 690 691> **NOTE** 692> 693> This API is deprecated since API version 12. 694 695**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 696 697**Return value** 698 699| Type | Description | 700| ------------------------------------ | ---------- | 701| [CaptionsManager](#captionsmanager8) | Captions configuration.| 702 703**Example** 704 705```ts 706import { accessibility } from '@kit.AccessibilityKit'; 707 708let captionsManager = accessibility.getCaptionsManager(); 709``` 710 711## accessibility.on('accessibilityStateChange') 712 713on(type: 'accessibilityStateChange', callback: Callback<boolean>): void 714 715Enables listening for the enabled status changes of the accessibility application. This API uses an asynchronous callback to return the result. 716 717**System capability**: SystemCapability.BarrierFree.Accessibility.Core 718 719**Parameters** 720 721| Name | Type | Mandatory| Description | 722| -------- | ----------------------- | ---- | ------------------------------------------------------------ | 723| type | string | Yes | Listening type, which is set to **'accessibilityStateChange'** in this API.| 724| callback | Callback<boolean> | Yes | Callback used to return the result. The returned result indicates the global enabled status of the accessibility application.| 725 726**Error codes** 727 728For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 729 730| ID| Error Message| 731| ------- | -------------------------------- | 732| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 733 734**Example** 735 736```ts 737import { accessibility } from '@kit.AccessibilityKit'; 738 739accessibility.on('accessibilityStateChange', (data: boolean) => { 740 console.info(`subscribe accessibility state change, result: ${JSON.stringify(data)}`); 741}); 742``` 743 744## accessibility.on('touchGuideStateChange') 745 746on(type: 'touchGuideStateChange', callback: Callback<boolean>): void 747 748Enables listening for the enabled status changes of the touch guide mode. This API uses an asynchronous callback to return the result. 749 750**System capability**: SystemCapability.BarrierFree.Accessibility.Vision 751 752**Parameters** 753 754| Name | Type | Mandatory | Description | 755| -------- | ----------------------- | ---- | ---------------------------------------- | 756| type | string | Yes | Listening type, which is set to **'touchGuideStateChange'** in this API.| 757| callback | Callback<boolean> | Yes | Callback used to return the result. | 758 759**Error codes** 760 761For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 762 763| ID| Error Message| 764| ------- | -------------------------------- | 765| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 766 767**Example** 768 769```ts 770import { accessibility } from '@kit.AccessibilityKit'; 771 772accessibility.on('touchGuideStateChange', (data: boolean) => { 773 console.info(`subscribe touch guide state change, result: ${JSON.stringify(data)}`); 774}); 775``` 776 777## accessibility.off('accessibilityStateChange') 778 779off(type: 'accessibilityStateChange', callback?: Callback<boolean>): void 780 781Disables listening for the enabled status changes of the accessibility application. This API uses an asynchronous callback to return the result. 782 783**System capability**: SystemCapability.BarrierFree.Accessibility.Core 784 785**Parameters** 786 787| Name | Type | Mandatory| Description | 788| -------- | ----------------------- | ---- | ------------------------------------------------------------ | 789| type | string | Yes | Listening type, which is set to **'accessibilityStateChange'** in this API.| 790| callback | Callback<boolean> | No | Callback used for disable listening. The value must be the same as the value of **callback** in **accessibility.on('accessibilityStateChange')**. If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.| 791 792**Error codes** 793 794For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 795 796| ID| Error Message| 797| ------- | -------------------------------- | 798| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 799 800**Example** 801 802```ts 803import { accessibility } from '@kit.AccessibilityKit'; 804 805accessibility.off('accessibilityStateChange', (data: boolean) => { 806 console.info(`Unsubscribe accessibility state change, result: ${JSON.stringify(data)}`); 807}); 808``` 809 810## accessibility.off('touchGuideStateChange') 811 812off(type: 'touchGuideStateChange', callback?: Callback<boolean>): void 813 814Disables listening for the enabled status changes of the touch guide mode. This API uses an asynchronous callback to return the result. 815 816**System capability**: SystemCapability.BarrierFree.Accessibility.Core 817 818**Parameters** 819 820| Name | Type | Mandatory| Description | 821| -------- | ----------------------- | ---- | ------------------------------------------------------------ | 822| type | string | Yes | Listening type, which is set to **'touchGuideStateChange'** in this API.| 823| callback | Callback<boolean> | No | Callback used for disable listening. The value must be the same as the value of **callback** in **accessibility.on('touchGuideStateChange')**. If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.| 824 825**Error codes** 826 827For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 828 829| ID| Error Message| 830| ------- | -------------------------------- | 831| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 832 833**Example** 834 835```ts 836import { accessibility } from '@kit.AccessibilityKit'; 837 838accessibility.off('touchGuideStateChange', (data: boolean) => { 839 console.info(`Unsubscribe touch guide state change, result: ${JSON.stringify(data)}`); 840}); 841``` 842 843## accessibility.isOpenAccessibility<sup>(deprecated)</sup> 844 845isOpenAccessibility(): Promise<boolean> 846 847Checks whether accessibility is enabled. This API uses a promise to return the result. 848 849> **NOTE** 850> 851> This API is deprecated since API version 10. 852> 853> You are advised to use [accessibility.isOpenAccessibilitySync](#accessibilityisopenaccessibilitysync10) instead. 854 855**System capability**: SystemCapability.BarrierFree.Accessibility.Core 856 857**Return value** 858 859| Type | Description | 860| ---------------------- | ---------------------------------------- | 861| Promise<boolean> | Promise used to return the result. Returns **true** if accessibility is enabled; returns **false** otherwise.| 862 863**Example** 864 865```ts 866import { accessibility } from '@kit.AccessibilityKit'; 867import { BusinessError } from '@kit.BasicServicesKit'; 868 869accessibility.isOpenAccessibility().then((data: boolean) => { 870 console.info(`success data:isOpenAccessibility : ${JSON.stringify(data)}`) 871}).catch((err: BusinessError) => { 872 console.error(`failed to isOpenAccessibility, Code is ${err.code}, message is ${err.message}`); 873}); 874``` 875 876## accessibility.isOpenAccessibility<sup>(deprecated)</sup> 877 878isOpenAccessibility(callback: AsyncCallback<boolean>): void 879 880Checks whether accessibility is enabled. This API uses an asynchronous callback to return the result. 881 882> **NOTE** 883> 884> This API is deprecated since API version 10. 885> 886> You are advised to use [accessibility.isOpenAccessibilitySync](#accessibilityisopenaccessibilitysync10) instead. 887 888**System capability**: SystemCapability.BarrierFree.Accessibility.Core 889 890**Parameters** 891 892| Name | Type | Mandatory | Description | 893| -------- | ---------------------------- | ---- | ----------------------------------- | 894| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. Returns **true** if accessibility is enabled; returns **false** otherwise.| 895 896**Example** 897 898```ts 899import { accessibility } from '@kit.AccessibilityKit'; 900import { BusinessError } from '@kit.BasicServicesKit'; 901 902accessibility.isOpenAccessibility((err: BusinessError, data: boolean) => { 903 if (err) { 904 console.error(`failed to isOpenAccessibility, Code is ${err.code}, message is ${err.message}`); 905 return; 906 } 907 console.info(`success data:isOpenAccessibility : ${JSON.stringify(data)}`); 908}); 909``` 910 911## accessibility.isOpenAccessibilitySync<sup>10+</sup> 912 913isOpenAccessibilitySync(): boolean 914 915Checks whether accessibility is enabled. 916 917**Atomic service API**: This API can be used in atomic services since API version 11. 918 919**System capability**: SystemCapability.BarrierFree.Accessibility.Core 920 921**Return value** 922 923| Type | Description | 924| ----------- | ------------------------------------- | 925| boolean | Returns **true** if accessibility is enabled; returns **false** otherwise.| 926 927**Example** 928 929```ts 930import { accessibility } from '@kit.AccessibilityKit'; 931import { BusinessError } from '@kit.BasicServicesKit'; 932 933let status: boolean = accessibility.isOpenAccessibilitySync(); 934``` 935 936## accessibility.isOpenTouchGuide<sup>(deprecated)</sup> 937 938isOpenTouchGuide(): Promise<boolean> 939 940Checks whether touch guide mode is enabled. This API uses a promise to return the result. 941 942> **NOTE** 943> 944> This API is deprecated since API version 10. 945> 946> You are advised to use [accessibility.isOpenTouchGuideSync](#accessibilityisopentouchguidesync10) instead. 947 948**System capability**: SystemCapability.BarrierFree.Accessibility.Vision 949 950**Return value** 951 952| Type | Description | 953| ---------------------- | ---------------------------------------- | 954| Promise<boolean> | Promise used to return the result. Returns **true** if touch guide mode is enabled; returns **false** otherwise.| 955 956**Example** 957 958```ts 959import { accessibility } from '@kit.AccessibilityKit'; 960import { BusinessError } from '@kit.BasicServicesKit'; 961 962accessibility.isOpenTouchGuide().then((data: boolean) => { 963 console.info(`success data:isOpenTouchGuide : ${JSON.stringify(data)}`); 964}).catch((err: BusinessError) => { 965 console.error(`failed to isOpenTouchGuide, Code is ${err.code}, message is ${err.message}`); 966}); 967``` 968 969## accessibility.isOpenTouchGuide<sup>(deprecated)</sup> 970 971isOpenTouchGuide(callback: AsyncCallback<boolean>): void 972 973Checks whether touch guide mode is enabled. This API uses an asynchronous callback to return the result. 974 975> **NOTE** 976> 977> This API is deprecated since API version 10. 978> 979> You are advised to use [accessibility.isOpenTouchGuideSync](#accessibilityisopentouchguidesync10) instead. 980 981**System capability**: SystemCapability.BarrierFree.Accessibility.Vision 982 983**Parameters** 984 985| Name | Type | Mandatory | Description | 986| -------- | ---------------------------- | ---- | ------------------------------------- | 987| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. Returns **true** if touch guide mode is enabled; returns **false** otherwise.| 988 989**Example** 990 991```ts 992import { accessibility } from '@kit.AccessibilityKit'; 993import { BusinessError } from '@kit.BasicServicesKit'; 994 995accessibility.isOpenTouchGuide((err: BusinessError, data: boolean) => { 996 if (err) { 997 console.error(`failed to isOpenTouchGuide, Code is ${err.code}, message is ${err.message}`); 998 return; 999 } 1000 console.info(`success data:isOpenTouchGuide : ${JSON.stringify(data)}`); 1001}); 1002``` 1003 1004## accessibility.isOpenTouchGuideSync<sup>10+</sup> 1005 1006isOpenTouchGuideSync(): boolean 1007 1008Checks whether touch guide mode is enabled. 1009 1010**Atomic service API**: This API can be used in atomic services since API version 11. 1011 1012**System capability**: SystemCapability.BarrierFree.Accessibility.Vision 1013 1014**Return value** 1015 1016| Type | Description | 1017| ------- | ------------------------------------- | 1018| boolean | Returns **true** if accessibility is enabled; returns **false** otherwise.| 1019 1020**Example** 1021 1022```ts 1023import { accessibility } from '@kit.AccessibilityKit'; 1024 1025let status: boolean = accessibility.isOpenTouchGuideSync(); 1026``` 1027 1028## accessibility.sendEvent<sup>(deprecated)</sup> 1029 1030sendEvent(event: EventInfo): Promise<void> 1031 1032Sends an accessibility event. This API uses a promise to return the result. 1033 1034> **NOTE** 1035> 1036> This API is supported since API version 7 and deprecated since API version 9. 1037> You are advised to use [accessibility.sendAccessibilityEvent()](#accessibilitysendaccessibilityevent9) instead. 1038 1039**System capability**: SystemCapability.BarrierFree.Accessibility.Core 1040 1041**Parameters** 1042 1043| Name | Type | Mandatory | Description | 1044| ----- | ----------------------- | ---- | -------- | 1045| event | [EventInfo](#eventinfo) | Yes | Accessibility event.| 1046 1047**Return value** 1048 1049| Type | Description | 1050| ------------------- | ---------------- | 1051| Promise<void> | Promise that returns no value.| 1052 1053**Example** 1054 1055```ts 1056import { accessibility } from '@kit.AccessibilityKit'; 1057import { BusinessError } from '@kit.BasicServicesKit'; 1058 1059let eventInfo: accessibility.EventInfo = ({ 1060 type: 'click', 1061 bundleName: 'com.example.MyApplication', 1062 triggerAction: 'click', 1063}); 1064 1065accessibility.sendEvent(eventInfo).then(() => { 1066 console.info(`Succeeded in send event,eventInfo is ${eventInfo}`); 1067}).catch((err: BusinessError) => { 1068 console.error(`failed to sendEvent, Code is ${err.code}, message is ${err.message}`); 1069}); 1070``` 1071 1072## accessibility.sendEvent<sup>(deprecated)</sup> 1073 1074sendEvent(event: EventInfo, callback: AsyncCallback<void>): void 1075 1076Sends an accessibility event. This API uses an asynchronous callback to return the result. 1077 1078> **NOTE** 1079> 1080> This API is supported since API version 7 and deprecated since API version 9. 1081> You are advised to use [accessibility.sendAccessibilityEvent()](#accessibilitysendaccessibilityevent9-1) instead. 1082 1083**System capability**: SystemCapability.BarrierFree.Accessibility.Core 1084 1085**Parameters** 1086 1087| Name | Type | Mandatory | Description | 1088| -------- | ------------------------- | ---- | ---------------------------------------- | 1089| event | [EventInfo](#eventinfo) | Yes | Accessibility event. | 1090| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation fails, **err** that contains data is returned.| 1091 1092**Example** 1093 1094```ts 1095import { accessibility } from '@kit.AccessibilityKit'; 1096import { BusinessError } from '@kit.BasicServicesKit'; 1097 1098let eventInfo: accessibility.EventInfo = ({ 1099 type: 'click', 1100 bundleName: 'com.example.MyApplication', 1101 triggerAction: 'click', 1102}); 1103 1104accessibility.sendEvent(eventInfo, (err: BusinessError) => { 1105 if (err) { 1106 console.error(`failed to sendEvent, Code is ${err.code}, message is ${err.message}`); 1107 return; 1108 } 1109 console.info(`Succeeded in sendEvent, eventInfo is ${eventInfo}`); 1110}); 1111``` 1112 1113## accessibility.sendAccessibilityEvent<sup>9+</sup> 1114 1115sendAccessibilityEvent(event: EventInfo): Promise<void> 1116 1117Sends an accessibility event. This API uses a promise to return the result. 1118 1119**System capability**: SystemCapability.BarrierFree.Accessibility.Core 1120 1121**Parameters** 1122 1123| Name | Type | Mandatory | Description | 1124| ----- | ----------------------- | ---- | -------- | 1125| event | [EventInfo](#eventinfo) | Yes | Accessibility event.| 1126 1127**Return value** 1128 1129| Type | Description | 1130| ------------------- | ---------------- | 1131| Promise<void> | Promise that returns no value.| 1132 1133**Error codes** 1134 1135For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 1136 1137| ID| Error Message| 1138| ------- | -------------------------------- | 1139| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1140 1141**Example** 1142 1143```ts 1144import { accessibility } from '@kit.AccessibilityKit'; 1145import { BusinessError } from '@kit.BasicServicesKit'; 1146 1147let eventInfo: accessibility.EventInfo = ({ 1148 type: 'click', 1149 bundleName: 'com.example.MyApplication', 1150 triggerAction: 'click', 1151}); 1152 1153accessibility.sendAccessibilityEvent(eventInfo).then(() => { 1154 console.info(`Succeeded in send event,eventInfo is ${eventInfo}`); 1155}).catch((err: BusinessError) => { 1156 console.error(`failed to send event , Code is ${err.code}, message is ${err.message}`); 1157}); 1158``` 1159 1160## accessibility.sendAccessibilityEvent<sup>9+</sup> 1161 1162sendAccessibilityEvent(event: EventInfo, callback: AsyncCallback<void>): void 1163 1164Sends an accessibility event. This API uses an asynchronous callback to return the result. 1165 1166**System capability**: SystemCapability.BarrierFree.Accessibility.Core 1167 1168**Parameters** 1169 1170| Name | Type | Mandatory | Description | 1171| -------- | ------------------------- | ---- | ---------------------------------------- | 1172| event | [EventInfo](#eventinfo) | Yes | Accessibility event. | 1173| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation fails, **err** that contains data is returned.| 1174 1175**Error codes** 1176 1177For details about the error codes, see [Accessibility Error Codes](errorcode-accessibility.md). 1178 1179| ID| Error Message| 1180| ------- | -------------------------------- | 1181| 401 |Input parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1182 1183**Example** 1184 1185```ts 1186import { accessibility } from '@kit.AccessibilityKit'; 1187import { BusinessError } from '@kit.BasicServicesKit'; 1188 1189let eventInfo: accessibility.EventInfo = ({ 1190 type: 'click', 1191 bundleName: 'com.example.MyApplication', 1192 triggerAction: 'click', 1193}); 1194 1195accessibility.sendAccessibilityEvent(eventInfo, (err: BusinessError) => { 1196 if (err) { 1197 console.error(`failed to send event, Code is ${err.code}, message is ${err.message}`); 1198 return; 1199 } 1200 console.info(`Succeeded in send event, eventInfo is ${eventInfo}`); 1201}); 1202``` 1203 1204**Example of auto-focusing:** 1205 1206```ts 1207@Entry 1208@Component 1209struct Index { 1210 1211 build() { 1212 Column() { 1213 // Add the ID attribute to the component to be focused. The uniqueness of the ID is ensured by the user. 1214 Button ('Component to be focused').id ('click') 1215 } 1216 } 1217} 1218``` 1219```ts 1220import { accessibility } from '@kit.AccessibilityKit'; 1221import { BusinessError } from '@kit.BasicServicesKit'; 1222 1223let eventInfo: accessibility.EventInfo = ({ 1224 type: 'requestFocusForAccessibility', 1225 bundleName: 'com.example.MyApplication', 1226 triggerAction: 'common', 1227 customId: 'click' // ID of the component to be focused. 1228}); 1229 1230accessibility.sendAccessibilityEvent(eventInfo, (err: BusinessError) => { 1231 if (err) { 1232 console.error(`failed to send event, Code is ${err.code}, message is ${err.message}`); 1233 return; 1234 } 1235 console.info(`Succeeded in send event, eventInfo is ${eventInfo}`); 1236}); 1237``` 1238