diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index b1e826787f33151f1dd4eba2ff2078c35cbaab9d..e2e63510d2d33ffe895ae3c5320af8d6a7f18235 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -79,6 +79,7 @@ - [WebGL](js-apis-webgl.md) - [WebGL2](js-apis-webgl2.md) - [Screenshot](js-apis-screenshot.md) + - [Accessibility](js-apis-accessibility.md) - DFX - [HiAppEvent](js-apis-hiappevent.md) - [Performance Tracing](js-apis-hitracemeter.md) diff --git a/en/application-dev/reference/apis/js-apis-accessibility.md b/en/application-dev/reference/apis/js-apis-accessibility.md new file mode 100644 index 0000000000000000000000000000000000000000..c39e6e8f9437e64b3f05f59986ec08d35170eb71 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-accessibility.md @@ -0,0 +1,627 @@ +# Accessibility + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> 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. + +## Modules to Import + +```typescript +import accessibility from '@ohos.accessibility'; +``` + +## AbilityState + +Enumerates the states of an accessibility application. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +| Name| Description| +| -------- | -------- | +| enable | The accessibility application is enabled.| +| disable | The accessibility application is disabled.| +| install | The accessibility application has been installed.| + +## AbilityType + +Enumerates the types of accessibility applications. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +| Name| Description| +| -------- | -------- | +| audible | The accessibility application provides audible feedback.| +| generic | The accessibility application provides generic feedback.| +| haptic | The accessibility application provides haptic feedback.| +| spoken | The accessibility application provides spoken feedback.| +| visual | The accessibility application provides visual feedback.| + +## AccessibilityAbilityInfo + +Provides information about an accessibility application. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +### Attributes + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| id | number | Yes| No| Ability ID.| +| name | string | Yes| No| Ability name.| +| bundleName | string | Yes| No| Bundle name.| +| abilityTypes | Array<[AbilityType](#abilitytype)> | Yes| No| Accessibility application type.| +| capabilities | Array<[Capability](#capability)> | Yes| No| Capabilities list of the accessibility application.| +| description | string | Yes| No| Description of the accessibility application.| +| eventTypes | Array<[EventType](#eventtype)> | Yes| No| List of events that the accessibility application focuses on.| + +## Action + +Describes the target action supported by an accessibility application. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +| Name| Description| +| -------- | -------- | +| click | Clicking.| +| longClick | Long pressing.| +| scrollForward | Scrolling forward.| +| scrollBackward | Scrolling backward.| +| focus | Obtaining focus.| +| clearFocus | Clearing focus.| +| clearSelection | Clearing selection.| +| accessibilityFocus | Obtaining the accessibility focus.| +| clearAccessibilityFocus | Clearing the accessibility focus.| +| cut | Cut.| +| copy | Copy.| +| paste | Paste.| +| select | Select.| +| setText | Setting the text.| +| delete | Delete.| +| setSelection | Setting the selection.| + +## Capability + +Enumerates the capabilities of an auxiliary application. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +| Name| Description| +| -------- | -------- | +| retrieve | Capability to retrieve the window content.| +| touchGuide | Capability of touch guide mode.| +| keyEventObserver | Capability to filter key events.| +| zoom | Capability to control the display zoom level.| +| gesture | Capability to perform gesture actions.| + +## CaptionsFontEdgeType8+ + +Enumerates the caption font edge type. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Hearing + +| Name| Description| +| -------- | -------- | +| none | No effect.| +| raised | Raised effect.| +| depressed | Depressed effect.| +| uniform | Uniform effect.| +| dropShadow | Drop shadow effect.| + +## CaptionsFontFamily8+ + +Enumerates the caption font families. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Hearing + +| Name| Description| +| -------- | -------- | +| default | Default font family.| +| monospacedSerif | Monospaced Serif fonts, which use the same width for each character.| +| serif | Serif fonts.| +| monospacedSansSerif | Monospaced Sans Serif fonts, which use the same width for each character.| +| sansSerif | Sans Serif fonts.| +| casual | Casual fonts.| +| cursive | Cursive fonts.| +| smallCapitals | Small caps fonts.| + +## CaptionsStyle8+ + +Describes the caption style. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Hearing + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| fontFamily | [CaptionsFontFamily](#captionsfontfamily8) | Yes| No| Font family of the captions.| +| fontScale | number | Yes| No| Font scale of the captions.| +| fontColor | number \| string | Yes| No| Font color of the captions.| +| fontEdgeType | [CaptionsFontEdgeType](#captionsfontedgetype8) | Yes| No| Font edge type of the captions.| +| backgroundColor | number \| string | Yes| No| Background color of the captions.| +| windowColor | number \| string | Yes| No| Window color of the captions.| + +## CaptionsManager8+ + +Implements caption configuration management. + +### Attributes + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| enabled | boolean | Yes| No| Whether to enable caption configuration.| +| style | [CaptionsStyle](#captionsstyle8) | Yes| No| Caption style.| + +### Methods + +In the following API examples, you must first use the [accessibility.getCaptionsManager()](#accessibilitygetcaptionsmanager8) method to obtain a **captionsManager** instance, and then call the methods using the obtained instance. + +#### on('enableChange') + +on(type: 'enableChange', callback: Callback<boolean>): void; + +Enables listening for enable status changes of caption configuration. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Hearing + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to listen for, which is set to **enableChange** in this API.| + | callback | Callback<boolean> | Yes| Callback invoked when the enable status of caption configuration changes.| + +- Example + + ```typescript + captionsManager.on('enableChange',(data) => { + console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) + }) + ``` + +#### on('styleChange') + +on(type: 'styleChange', callback: Callback<CaptionsStyle>): void; + +Enables listening for caption style changes. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Hearing + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to listen for, which is set to **styleChange** in this API.| + | callback | Callback<[CaptionsStyle](#captionsstyle8)> | Yes| Callback invoked when the caption style changes.| + +- Example + + ```typescript + captionsManager.on('styleChange',(data) => { + console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) + }) + ``` + +#### off('enableChange') + +off(type: 'enableChange', callback?: Callback<boolean>): void; + +Disables listening for enable status changes of caption configuration. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Hearing + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to listen for, which is set to **enableChange** in this API.| + | callback | Callback<boolean> | No| Callback invoked when the enable status of caption configuration changes.| + +- Example + + ```typescript + captionsManager.off('enableChange') + ``` + +#### off('styleChange') + +off(type: 'styleChange', callback?: Callback<CaptionsStyle>): void; + +Disables listening for caption style changes.s is removed. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Hearing + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to listen for, which is set to **styleChange** in this API.| + | callback | Callback<[CaptionsStyle](#captionsstyle8)> | No| Callback invoked when the caption style changes.| + +- Example + + ```typescript + captionsManager.off('styleChange') + ``` + +## EventInfo + +Describes a GUI change event. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +### Attributes + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| type | [EventType](#eventtype) | Yes| Yes| Accessibility event type.| +| windowUpdateType | [WindowUpdateType](#windowupdatetype) | Yes| Yes| Window update type.| +| bundleName | string | Yes| Yes| Target application name.| +| componentType | string | Yes| Yes| Type of the event source component, for example, button or chart.| +| pageId | number | Yes| Yes| Page ID of the event source.| +| description | string | Yes| Yes| Event description.| +| triggerAction | [Action](#action) | Yes| Yes| Action that triggers the event.| +| textMoveUnit | [TextMoveUnit](#textmoveunit) | Yes| Yes| Text movement unit.| +| contents | Array<string> | Yes| Yes| Array of contents.| +| lastContent | string | Yes| Yes| Latest content.| +| beginIndex | number | Yes| Yes| Sequence number of the first item displayed on the page.| +| currentIndex | number | Yes| Yes| Sequence number of the current item.| +| endIndex | number | Yes| Yes| Sequence number of the last item displayed on the page.| +| itemCount | number | Yes| Yes| Total number of items.| + +## EventType + +Enumerates accessibility event types. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +| Name| Description| +| -------- | -------- | +| click | Event of clicking a component.| +| longClick | Event of long-pressing a component.| +| select | Event of selecting a component.| +| focus | Event indicating that the component obtains the focus.| +| textUpdate | Event indicating that the component text has been updated.| +| hoverEnter | Event indicating that the hover enters a component.| +| hoverExit | Event indicating that the hover exits a component.| +| scroll | Event of the scroll view.| +| textSelectionUpdate | Event indicating that the selected text has been updated.| +| accessibilityFocus | Event indicating that the accessibility focus has been obtained.| +| accessibilityFocusClear | Event indicating that the accessibility focus has been cleared.| + +## TextMoveUnit + +Enumerates the movement units for traversing the node text. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +| Name| Description| +| -------- | -------- | +| char | The movement unit for traversing the node text is by character.| +| word | The movement unit for traversing the node text is by word.| +| line | The movement unit for traversing the node text is by line.| +| page | The movement unit for traversing the node text is by page.| +| paragraph | The movement unit for traversing the node text is by paragraph.| + +## WindowUpdateType + +Enumerates window update types. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +| Name| Description| +| -------- | -------- | +| add | Window adding.| +| remove | Window deletion.| +| title | Window title change.| +| bounds | Window boundary change.| +| layer | Window layer change.| +| active | Window activity change.| +| focus | Window focus change.| +| accessibilityFocus | Window accessibility focus change.| +| parent | Parent window change.| +| children | Child window change.| +| pip | Picture-in-picture (PIP) mode change.| + +## accessibility.getAbilityLists + +getAbilityLists(abilityType: AbilityType, stateType: AbilityState): Promise<Array<AccessibilityAbilityInfo>> + +Obtains the accessibility application list. This API uses a promise to return the result. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | abilityType | [AbilityType](#abilitytype) | Yes| Accessibility application type.| + | stateType | [AbilityState](#abilitystate) | Yes| Accessibility application status.| + +- Return value + + | Type| Description| + | -------- | -------- | + | Promise<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | Promise used to return the accessibility application list.| + +- Example + + ```typescript + accessibility.getAbilityLists("spoken", "enable") + .then((data) => { + console.info('success data:getAbilityList1 : ' + JSON.stringify(data)); + for (let item of data) { + console.info(item.id); + console.info(item.name); + console.info(item.description); + console.info(item.abilityTypes); + console.info(item.eventTypes); + console.info(item.capabilities); + console.info(item.packageName); + console.info(item.filterBundleNames); + console.info(item.bundleName); + } + }).catch((error) => { + console.error('failed to getAbilityList1 because ' + JSON.stringify(error)); + }) + ``` + +## accessibility.getAbilityLists + +getAbilityLists(abilityType: AbilityType, stateType: AbilityState,callback: AsyncCallback<Array<AccessibilityAbilityInfo>>): void + +Obtains the accessibility application list. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | abilityType | [AbilityType](#abilitytype) | Yes| Accessibility application type.| + | stateType | [AbilityState](#abilitystate) | Yes| Accessibility application status.| + | callback | AsyncCallback<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | Yes| Callback used to return the accessibility application list.| + +- Example + + ```typescript + accessibility.getAbilityLists("visual", "enable", (err, data) => { + if (err) { + console.error('failed to getAbilityList2 because ' + JSON.stringify(err)); + return; + } + console.info('success data:getAbilityList2 : ' + JSON.stringify(data)); + for (let item of data) { + console.info(item.id); + console.info(item.name); + console.info(item.description); + console.info(item.abilityTypes); + console.info(item.eventTypes); + console.info(item.capabilities); + console.info(item.packageName); + console.info(item.filterBundleNames); + console.info(item.bundleName); + } + }) + ``` + +## accessibility.getCaptionsManager8+ + +getCaptionsManager(): CaptionsManager + +Obtains the accessibility caption configuration. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Hearing + +- Return value + + | Type| Description| + | -------- | -------- | + | [CaptionsManager](#captionsmanager8) | Accessibility caption configuration.| + +- Example + + ```typescript + captionsManager = accessibility.getCaptionsManager() + ``` + +## accessibility.on('accessibilityStateChange' | 'touchGuideStateChange') + +on(type: 'accessibilityStateChange' | 'touchGuideStateChange', callback: Callback<boolean>): void + +Enables listening for the accessibility application or touch guide mode status changes. + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to listen for.
- **accessibilityStateChange** means to listen for enable status changes of the accessibility application.
**System capability**: SystemCapability.Barrierfree.Accessibility.Core
- **touchGuideStateChange** means to listen for enable status changes of the touch guide mode.
**System capability**: SystemCapability.Barrierfree.Accessibility.Vision| + | callback | Callback<boolean> | Yes| Callback invoked when the enable status changes.| + +- Example + + ```typescript + accessibility.on('accessibilityStateChange',(data) => { + console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) + }) + ``` + +## accessibility.off('accessibilityStateChange' | 'touchGuideStateChange') + +off(type: 'accessibilityStateChange ' | 'touchGuideStateChange', callback?: Callback<boolean>): void + +Disables listening for the accessibility application or touch guide mode status changes. + + + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | No| Type of the event to listen for.
- **accessibilityStateChange** means to listen for enable status changes of the accessibility application.
**System capability**: SystemCapability.Barrierfree.Accessibility.Core
- **touchGuideStateChange** means to listen for enable status changes of the touch guide mode.
**System capability**: SystemCapability.Barrierfree.Accessibility.Vision| + | callback | Callback<boolean> | No| Callback invoked when the enable status changes.| + +- Example + + ```typescript + accessibility.off('accessibilityStateChange',(data) => { + console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data)) + }) + ``` + +## accessibility.isOpenAccessibility + +isOpenAccessibility(): Promise<boolean> + +Checks whether accessibility is enabled. This API uses a promise to return the result. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +- Return value + + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Returns **true** if accessibility is enabled; returns **false** otherwise.| + +- Example + + ```typescript + accessibility.isOpenAccessibility() + .then((data) => { + console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) + }).catch((error) => { + console.error('failed to isOpenAccessibility because ' + JSON.stringify(error)); + }) + ``` + +## accessibility.isOpenAccessibility + +isOpenAccessibility(callback: AsyncCallback<boolean>): void + +Checks whether accessibility is enabled. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +- Parameters + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if accessibility is enabled; returns **false** otherwise.| + +- Example + + ```typescript + accessibility.isOpenAccessibility((err, data) => { + if (err) { + console.error('failed to isOpenAccessibility because ' + JSON.stringify(err)); + return; + } + console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) + }) + ``` + +## accessibility.isOpenTouchGuide + +isOpenTouchGuide(): Promise<boolean> + +Checks whether touch guide mode is enabled. This API uses a promise to return the result. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +- Return value + + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Returns **true** if touch guide mode is enabled; returns **false** otherwise.| + +- Example + + ```typescript + accessibility.isOpenTouchGuide() + .then((data) => { + console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) + }).catch((error) => { + console.error('failed to isOpenTouchGuide because ' + JSON.stringify(error)); + }) + ``` + +## accessibility.isOpenTouchGuide + +isOpenTouchGuide(callback: AsyncCallback<boolean>): void + +Checks whether touch guide mode is enabled. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +- Parameters + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if touch guide mode is enabled; returns **false** otherwise.| + +- Example + + ```typescript + accessibility.isOpenTouchGuide((err, data) => { + if (err) { + console.error('failed to isOpenTouchGuide because ' + JSON.stringify(err)); + return; + } + console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) + }) + ``` + +## accessibility.sendEvent + +sendEvent(event: EventInfo): Promise<void> + +Sends an accessibility event. This API uses a promise to return the result. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | event | [EventInfo](#eventinfo) | Yes| Accessibility event.| + +- Return value + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result. Returns data if the accessibility event is sent successfully; returns an error otherwise.| + +- Example + + ```typescript + accessibility.sendEvent(this.eventInfo) + .then((data) => { + console.info('success data:sendEvent : ' + JSON.stringify(data)) + }).catch((error) => { + console.error('failed to sendEvent because ' + JSON.stringify(error)); + }) + ``` + +## accessibility.sendEvent + +sendEvent(event: EventInfo, callback: AsyncCallback<void>): void + +Sends an accessibility event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Barrierfree.Accessibility.Core + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | event | [EventInfo](#eventinfo) | Yes| Accessibility event.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result. Returns data if the accessibility event is sent successfully; returns an error otherwise.| + +- Example + + ```typescript + accessibility.sendEvent(this.eventInfo,(err, data) => { + if (err) { + console.error('failed to sendEvent because ' + JSON.stringify(err)); + return; + } + console.info('success data:sendEvent : ' + JSON.stringify(data)) + }) + ```