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