1# 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```typescript 12import accessibility from '@ohos.accessibility'; 13``` 14 15## AbilityState 16 17Enumerates the states of an accessibility application. 18 19**System capability**: SystemCapability.BarrierFree.Accessibility.Core 20 21| Name| Description| 22| -------- | -------- | 23| enable | The accessibility application is enabled.| 24| disable | The accessibility application is disabled.| 25| install | The accessibility application has been installed.| 26 27## AbilityType 28 29Enumerates the types of accessibility applications. 30 31**System capability**: SystemCapability.BarrierFree.Accessibility.Core 32 33| Name| Description| 34| -------- | -------- | 35| audible | The accessibility application provides audible feedback.| 36| generic | The accessibility application provides generic feedback.| 37| haptic | The accessibility application provides haptic feedback.| 38| spoken | The accessibility application provides spoken feedback.| 39| visual | The accessibility application provides visual feedback.| 40| all<sup>9+</sup> | All the preceding types.| 41 42## AccessibilityAbilityInfo 43 44Provides information about an accessibility application. 45 46**System capability**: SystemCapability.BarrierFree.Accessibility.Core 47 48### Attributes 49 50| Name| Type| Readable| Writable| Description| 51| -------- | -------- | -------- | -------- | -------- | 52| id | number | Yes| No| Ability ID.| 53| name | string | Yes| No| Ability name.| 54| bundleName | string | Yes| No| Bundle name.| 55| targetBundleNames<sup>9+</sup> | Array<string> | Yes| No| Name of the target bundle.| 56| abilityTypes | Array<[AbilityType](#abilitytype)> | Yes| No| Accessibility application type.| 57| capabilities | Array<[Capability](#capability)> | Yes| No| Capabilities list of the accessibility application.| 58| description | string | Yes| No| Description of the accessibility application.| 59| eventTypes | Array<[EventType](#eventtype)> | Yes| No| List of events that the accessibility application focuses on.| 60 61## Action 62 63Describes the target action supported by an accessibility application. 64 65**System capability**: SystemCapability.BarrierFree.Accessibility.Core 66 67| Name| Description| 68| -------- | -------- | 69| click | Clicking.| 70| longClick | Long pressing.| 71| scrollForward | Scrolling forward.| 72| scrollBackward | Scrolling backward.| 73| focus | Obtaining focus.| 74| clearFocus | Clearing focus.| 75| clearSelection | Clearing selection.| 76| accessibilityFocus | Obtaining the accessibility focus.| 77| clearAccessibilityFocus | Clearing the accessibility focus.| 78| cut | Cut.| 79| copy | Copy.| 80| paste | Paste.| 81| select | Select.| 82| setText | Setting the text.| 83| delete | Delete.| 84| setSelection | Setting the selection.| 85 86## Capability 87 88Enumerates the capabilities of an auxiliary application. 89 90**System capability**: SystemCapability.BarrierFree.Accessibility.Core 91 92| Name| Description| 93| -------- | -------- | 94| retrieve | Capability to retrieve the window content.| 95| touchGuide | Capability of touch guide mode.| 96| keyEventObserver | Capability to filter key events.| 97| zoom | Capability to control the display zoom level.| 98| gesture | Capability to perform gesture actions.| 99 100## CaptionsFontEdgeType<sup>8+</sup> 101 102Enumerates the font edge types of captions. 103 104**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 105 106| Name| Description| 107| -------- | -------- | 108| none | No effect.| 109| raised | Raised effect.| 110| depressed | Depressed effect.| 111| uniform | Uniform effect.| 112| dropShadow | Drop shadow effect.| 113 114## CaptionsFontFamily<sup>8+</sup> 115 116Enumerates the font families of captions. 117 118**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 119 120| Name| Description| 121| -------- | -------- | 122| default | Default font family.| 123| monospacedSerif | Monospaced Serif fonts, which use the same width for each character.| 124| serif | Serif fonts.| 125| monospacedSansSerif | Monospaced Sans Serif fonts, which use the same width for each character.| 126| sansSerif | Sans Serif fonts.| 127| casual | Casual fonts.| 128| cursive | Cursive fonts.| 129| smallCapitals | Small caps fonts.| 130 131## CaptionsStyle<sup>8+</sup> 132 133Describes the style of captions. 134 135**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 136 137| Name| Type| Readable| Writable| Description| 138| -------- | -------- | -------- | -------- | -------- | 139| fontFamily | [CaptionsFontFamily](#captionsfontfamily8) | Yes| No| Font family of captions.| 140| fontScale | number | Yes| No| Font scale of captions.| 141| fontColor | number \| string | Yes| No| Font color of captions.| 142| fontEdgeType | [CaptionsFontEdgeType](#captionsfontedgetype8) | Yes| No| Font edge type of captions.| 143| backgroundColor | number \| string | Yes| No| Background color of captions.| 144| windowColor | number \| string | Yes| No| Window color of captions.| 145 146## CaptionsManager<sup>8+</sup> 147 148Implements configuration management for captions. 149 150**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 151 152### Attributes 153 154| Name| Type| Readable| Writable| Description| 155| -------- | -------- | -------- | -------- | -------- | 156| enabled | boolean | Yes| No| Whether to enable captions configuration.| 157| style | [CaptionsStyle](#captionsstyle8) | Yes| No| Style of captions.| 158 159### Methods 160 161In the following API examples, you must first use the [accessibility.getCaptionsManager()](#accessibilitygetcaptionsmanager8) API to obtain a **captionsManager** instance, and then call the methods using the obtained instance. 162#### on('enableChange') 163 164on(type: 'enableChange', callback: Callback<boolean>): void; 165 166Enables listening for enabled status changes of captions configuration. 167 168- **Parameters** 169 170 | Name| Type| Mandatory| Description| 171 | -------- | -------- | -------- | -------- | 172 | type | string | Yes| Type of the event to listen for, which is set to **enableChange** in this API.| 173 | callback | Callback<boolean> | Yes| Callback invoked when the enabled status of captions configuration changes.| 174 175- **Example** 176 177 ```typescript 178 captionsManager.on('enableChange',(data) => { 179 console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) 180 }) 181 ``` 182 183#### on('styleChange') 184 185on(type: 'styleChange', callback: Callback<CaptionsStyle>): void; 186 187Enables listening for captions style changes. 188 189- **Parameters** 190 191 | Name| Type| Mandatory| Description| 192 | -------- | -------- | -------- | -------- | 193 | type | string | Yes| Type of the event to listen for, which is set to **styleChange** in this API.| 194 | callback | Callback<[CaptionsStyle](#captionsstyle8)> | Yes| Callback invoked when the style of captions changes.| 195 196- **Example** 197 198 ```typescript 199 captionsManager.on('styleChange',(data) => { 200 console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) 201 }) 202 ``` 203 204#### off('enableChange') 205 206off(type: 'enableChange', callback?: Callback<boolean>): void; 207 208Disables listening for enabled status changes of captions configuration. 209 210- **Parameters** 211 212 | Name| Type| Mandatory| Description| 213 | -------- | -------- | -------- | -------- | 214 | type | string | Yes| Type of the event to listen for, which is set to **enableChange** in this API.| 215 | callback | Callback<boolean> | No| Callback invoked when the enabled status of captions configuration changes.| 216 217- **Example** 218 219 ```typescript 220 captionsManager.off('enableChange') 221 ``` 222 223#### off('styleChange') 224 225off(type: 'styleChange', callback?: Callback<CaptionsStyle>): void; 226 227Disables listening for captions style changes. 228 229- **Parameters** 230 231 | Name| Type| Mandatory| Description| 232 | -------- | -------- | -------- | -------- | 233 | type | string | Yes| Type of the event to listen for, which is set to **styleChange** in this API.| 234 | callback | Callback<[CaptionsStyle](#captionsstyle8)> | No| Callback invoked when the style of captions changes.| 235 236- **Example** 237 238 ```typescript 239 captionsManager.off('styleChange') 240 ``` 241 242## EventInfo 243 244Describes a GUI change event. 245 246**System capability**: SystemCapability.BarrierFree.Accessibility.Core 247 248### Attributes 249 250| Name| Type| Readable| Writable| Description| 251| -------- | -------- | -------- | -------- | -------- | 252| type | [EventType](#eventtype) | Yes| Yes| Accessibility event type.| 253| windowUpdateType | [WindowUpdateType](#windowupdatetype) | Yes| Yes| Window update type.| 254| bundleName | string | Yes| Yes| Target application name.| 255| componentType | string | Yes| Yes| Type of the event source component, for example, button or chart.| 256| pageId | number | Yes| Yes| Page ID of the event source.| 257| description | string | Yes| Yes| Event description.| 258| triggerAction | [Action](#action) | Yes| Yes| Action that triggers the event.| 259| textMoveUnit | [TextMoveUnit](#textmoveunit) | Yes| Yes| Text movement unit.| 260| contents | Array<string> | Yes| Yes| Array of contents.| 261| lastContent | string | Yes| Yes| Latest content.| 262| beginIndex | number | Yes| Yes| Sequence number of the first item displayed on the page.| 263| currentIndex | number | Yes| Yes| Sequence number of the current item.| 264| endIndex | number | Yes| Yes| Sequence number of the last item displayed on the page.| 265| itemCount | number | Yes| Yes| Total number of items.| 266 267## EventType 268 269Enumerates accessibility event types. 270 271**System capability**: SystemCapability.BarrierFree.Accessibility.Core 272 273| Name| Description| 274| -------- | -------- | 275| click | Event of clicking a component.| 276| longClick | Event of long-pressing a component.| 277| select | Event of selecting a component.| 278| focus | Event indicating that the component obtains the focus.| 279| textUpdate | Event indicating that the component text has been updated.| 280| hoverEnter | Event indicating that the hover enters a component.| 281| hoverExit | Event indicating that the hover exits a component.| 282| scroll | Event of the scroll view.| 283| textSelectionUpdate | Event indicating that the selected text has been updated.| 284| accessibilityFocus | Event indicating that the accessibility focus has been obtained.| 285| accessibilityFocusClear | Event indicating that the accessibility focus has been cleared.| 286 287## TextMoveUnit 288 289Enumerates the movement units for traversing the node text. 290 291**System capability**: SystemCapability.BarrierFree.Accessibility.Core 292 293| Name| Description| 294| -------- | -------- | 295| char | The movement unit for traversing the node text is by character.| 296| word | The movement unit for traversing the node text is by word.| 297| line | The movement unit for traversing the node text is by line.| 298| page | The movement unit for traversing the node text is by page.| 299| paragraph | The movement unit for traversing the node text is by paragraph.| 300 301## WindowUpdateType 302 303Enumerates window update types. 304 305**System capability**: SystemCapability.BarrierFree.Accessibility.Core 306 307| Name| Description| 308| -------- | -------- | 309| add | Window adding.| 310| remove | Window deletion.| 311| title | Window title change.| 312| bounds | Window boundary change.| 313| layer | Window layer change.| 314| active | Window activity change.| 315| focus | Window focus change.| 316| accessibilityFocus | Window accessibility focus change.| 317| parent | Parent window change.| 318| children | Child window change.| 319| pip | Picture-in-picture (PIP) mode change.| 320 321## accessibility.getAbilityLists 322 323getAbilityLists(abilityType: AbilityType, stateType: AbilityState): Promise<Array<AccessibilityAbilityInfo>> 324 325Obtains the accessibility application list. This API uses a promise to return the result. 326 327**System capability**: SystemCapability.BarrierFree.Accessibility.Core 328 329- **Parameters** 330 331 | Name| Type| Mandatory| Description| 332 | -------- | -------- | -------- | -------- | 333 | abilityType | [AbilityType](#abilitytype) | Yes| Accessibility application type.| 334 | stateType | [AbilityState](#abilitystate) | Yes| Accessibility application status.| 335 336- **Return value** 337 338 | Type| Description| 339 | -------- | -------- | 340 | Promise<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | Promise used to return the accessibility application list.| 341 342- **Example** 343 344 ```typescript 345 accessibility.getAbilityLists("spoken", "enable") 346 .then((data) => { 347 console.info('success data:getAbilityList1 : ' + JSON.stringify(data)); 348 for (let item of data) { 349 console.info(item.id); 350 console.info(item.name); 351 console.info(item.description); 352 console.info(item.abilityTypes); 353 console.info(item.eventTypes); 354 console.info(item.capabilities); 355 console.info(item.packageName); 356 console.info(item.filterBundleNames); 357 console.info(item.bundleName); 358 } 359 }).catch((error) => { 360 console.error('failed to getAbilityList1 because ' + JSON.stringify(error)); 361 }) 362 ``` 363 364## accessibility.getAbilityLists 365 366getAbilityLists(abilityType: AbilityType, stateType: AbilityState,callback: AsyncCallback<Array<AccessibilityAbilityInfo>>): void 367 368Obtains the accessibility application list. This API uses an asynchronous callback to return the result. 369 370**System capability**: SystemCapability.BarrierFree.Accessibility.Core 371 372- **Parameters** 373 374 | Name| Type| Mandatory| Description| 375 | -------- | -------- | -------- | -------- | 376 | abilityType | [AbilityType](#abilitytype) | Yes| Accessibility application type.| 377 | stateType | [AbilityState](#abilitystate) | Yes| Accessibility application status.| 378 | callback | AsyncCallback<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | Yes| Callback used to return the accessibility application list.| 379 380- **Example** 381 382 ```typescript 383 accessibility.getAbilityLists("visual", "enable", (err, data) => { 384 if (err) { 385 console.error('failed to getAbilityList2 because ' + JSON.stringify(err)); 386 return; 387 } 388 console.info('success data:getAbilityList2 : ' + JSON.stringify(data)); 389 for (let item of data) { 390 console.info(item.id); 391 console.info(item.name); 392 console.info(item.description); 393 console.info(item.abilityTypes); 394 console.info(item.eventTypes); 395 console.info(item.capabilities); 396 console.info(item.packageName); 397 console.info(item.filterBundleNames); 398 console.info(item.bundleName); 399 } 400 }) 401 ``` 402 403## accessibility.getCaptionsManager<sup>8+</sup> 404 405getCaptionsManager(): CaptionsManager 406 407Obtains the captions configuration. 408 409**System capability**: SystemCapability.BarrierFree.Accessibility.Hearing 410 411- **Return value** 412 413 | Type| Description| 414 | -------- | -------- | 415 | [CaptionsManager](#captionsmanager8) | Captions configuration.| 416 417- **Example** 418 419 ```typescript 420 captionsManager = accessibility.getCaptionsManager() 421 ``` 422 423## accessibility.on('accessibilityStateChange' | 'touchGuideStateChange') 424 425on(type: 'accessibilityStateChange' | 'touchGuideStateChange', callback: Callback<boolean>): void 426 427Enables listening for the accessibility application or touch guide mode status changes. 428 429- **Parameters** 430 431 | Name| Type| Mandatory| Description| 432 | -------- | -------- | -------- | -------- | 433 | type | string | Yes| Type of the event to listen for.<br>- **'accessibilityStateChange'** means to listen for enabled status changes of the accessibility application.<br>**System capability**: SystemCapability.BarrierFree.Accessibility.Core<br>- **'touchGuideStateChange'** means to listen for enabled status changes of the touch guide mode.<br>**System capability**: SystemCapability.BarrierFree.Accessibility.Vision| 434 | callback | Callback<boolean> | Yes| Callback invoked when the enabled status of captions configuration changes.| 435 436- **Example** 437 438 ```typescript 439 accessibility.on('accessibilityStateChange',(data) => { 440 console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) 441 }) 442 ``` 443 444## accessibility.off('accessibilityStateChange' | 'touchGuideStateChange') 445 446off(type: 'accessibilityStateChange ' | 'touchGuideStateChange', callback?: Callback<boolean>): void 447 448Disables listening for the accessibility application or touch guide mode status changes. 449 450- **Parameters** 451 452 | Name| Type| Mandatory| Description| 453 | -------- | -------- | -------- | -------- | 454 | type | string | No| Type of the event to listen for.<br>- **'accessibilityStateChange'** means to listen for enabled status changes of the accessibility application.<br>**System capability**: SystemCapability.BarrierFree.Accessibility.Core<br>- **'touchGuideStateChange'** means to listen for enabled status changes of the touch guide mode.<br>**System capability**: SystemCapability.BarrierFree.Accessibility.Vision| 455 | callback | Callback<boolean> | No| Callback invoked when the enabled status changes.| 456 457- **Example** 458 459 ```typescript 460 accessibility.off('accessibilityStateChange',(data) => { 461 console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data)) 462 }) 463 ``` 464 465## accessibility.isOpenAccessibility 466 467isOpenAccessibility(): Promise<boolean> 468 469Checks whether accessibility is enabled. This API uses a promise to return the result. 470 471**System capability**: SystemCapability.BarrierFree.Accessibility.Core 472 473- **Return value** 474 475 | Type| Description| 476 | -------- | -------- | 477 | Promise<boolean> | Returns **true** if accessibility is enabled; returns **false** otherwise.| 478 479- **Example** 480 481 ```typescript 482 accessibility.isOpenAccessibility() 483 .then((data) => { 484 console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) 485 }).catch((error) => { 486 console.error('failed to isOpenAccessibility because ' + JSON.stringify(error)); 487 }) 488 ``` 489 490## accessibility.isOpenAccessibility 491 492isOpenAccessibility(callback: AsyncCallback<boolean>): void 493 494Checks whether accessibility is enabled. This API uses an asynchronous callback to return the result. 495 496**System capability**: SystemCapability.BarrierFree.Accessibility.Core 497 498- **Parameters** 499 500 | Name| Type| Mandatory| Description| 501 | -------- | -------- | -------- | -------- | 502 | callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if accessibility is enabled; returns **false** otherwise.| 503 504- **Example** 505 506 ```typescript 507 accessibility.isOpenAccessibility((err, data) => { 508 if (err) { 509 console.error('failed to isOpenAccessibility because ' + JSON.stringify(err)); 510 return; 511 } 512 console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) 513 }) 514 ``` 515 516## accessibility.isOpenTouchGuide 517 518isOpenTouchGuide(): Promise<boolean> 519 520Checks whether touch guide mode is enabled. This API uses a promise to return the result. 521 522**System capability**: SystemCapability.BarrierFree.Accessibility.Vision 523 524- **Return value** 525 526 | Type| Description| 527 | -------- | -------- | 528 | Promise<boolean> | Returns **true** if touch guide mode is enabled; returns **false** otherwise.| 529 530- **Example** 531 532 ```typescript 533 accessibility.isOpenTouchGuide() 534 .then((data) => { 535 console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) 536 }).catch((error) => { 537 console.error('failed to isOpenTouchGuide because ' + JSON.stringify(error)); 538 }) 539 ``` 540 541## accessibility.isOpenTouchGuide 542 543isOpenTouchGuide(callback: AsyncCallback<boolean>): void 544 545Checks whether touch guide mode is enabled. This API uses an asynchronous callback to return the result. 546 547**System capability**: SystemCapability.BarrierFree.Accessibility.Vision 548 549- **Parameters** 550 551 | Name| Type| Mandatory| Description| 552 | -------- | -------- | -------- | -------- | 553 | callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if touch guide mode is enabled; returns **false** otherwise.| 554 555- **Example** 556 557 ```typescript 558 accessibility.isOpenTouchGuide((err, data) => { 559 if (err) { 560 console.error('failed to isOpenTouchGuide because ' + JSON.stringify(err)); 561 return; 562 } 563 console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) 564 }) 565 ``` 566 567## accessibility.sendEvent 568 569sendEvent(event: EventInfo): Promise<void> 570 571Sends an accessibility event. This API uses a promise to return the result. 572 573**System capability**: SystemCapability.BarrierFree.Accessibility.Core 574 575- **Parameters** 576 577 | Name| Type| Mandatory| Description| 578 | -------- | -------- | -------- | -------- | 579 | event | [EventInfo](#eventinfo) | Yes| Accessibility event.| 580 581- **Return value** 582 583 | Type| Description| 584 | -------- | -------- | 585 | Promise<void> | Promise used to return the result. Returns data if the accessibility event is sent successfully; returns an error otherwise.| 586 587- **Example** 588 589 ```typescript 590 accessibility.sendEvent(this.eventInfo) 591 .then((data) => { 592 console.info('success data:sendEvent : ' + JSON.stringify(data)) 593 }).catch((error) => { 594 console.error('failed to sendEvent because ' + JSON.stringify(error)); 595 }) 596 ``` 597 598## accessibility.sendEvent 599 600sendEvent(event: EventInfo, callback: AsyncCallback<void>): void 601 602Sends an accessibility event. This API uses an asynchronous callback to return the result. 603 604**System capability**: SystemCapability.BarrierFree.Accessibility.Core 605 606- **Parameters** 607 608 | Name| Type| Mandatory| Description| 609 | -------- | -------- | -------- | -------- | 610 | event | [EventInfo](#eventinfo) | Yes| Accessibility event.| 611 | callback | AsyncCallback<void> | Yes| Callback used to return the result. Returns data if the accessibility event is sent successfully; returns an error otherwise.| 612 613- **Example** 614 615 ```typescript 616 accessibility.sendEvent(this.eventInfo,(err, data) => { 617 if (err) { 618 console.error('failed to sendEvent because ' + JSON.stringify(err)); 619 return; 620 } 621 console.info('success data:sendEvent : ' + JSON.stringify(data)) 622 }) 623 ``` 624