From fcee1d362dfdd270ed6f3e53646cb25108fa858f Mon Sep 17 00:00:00 2001 From: esterzhou Date: Wed, 21 Dec 2022 20:22:41 +0800 Subject: [PATCH] add and update docs (11703) Signed-off-by: esterzhou --- .../apis/js-apis-accessibility-GesturePath.md | 46 + .../js-apis-accessibility-GesturePoint.md | 47 + .../apis/js-apis-accessibility-config.md | 339 +++-- .../reference/apis/js-apis-accessibility.md | 792 +++++++---- ...plication-accessibilityExtensionAbility.md | 106 +- ...plication-accessibilityExtensionContext.md | 1159 +++++++++++++++++ .../errorcodes/errorcode-accessibility.md | 96 ++ 7 files changed, 2139 insertions(+), 446 deletions(-) create mode 100644 en/application-dev/reference/apis/js-apis-accessibility-GesturePath.md create mode 100644 en/application-dev/reference/apis/js-apis-accessibility-GesturePoint.md create mode 100644 en/application-dev/reference/apis/js-apis-inner-application-accessibilityExtensionContext.md create mode 100644 en/application-dev/reference/errorcodes/errorcode-accessibility.md diff --git a/en/application-dev/reference/apis/js-apis-accessibility-GesturePath.md b/en/application-dev/reference/apis/js-apis-accessibility-GesturePath.md new file mode 100644 index 0000000000..34d4df8dd9 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-accessibility-GesturePath.md @@ -0,0 +1,46 @@ +# @ohos.accessibility.GesturePath + + The **GesturePath** module provides APIs for creating gesture path information required for an accessibility application to inject gestures. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import GesturePath from '@ohos.accessibility.GesturePath'; +``` + +## GesturePath + +Defines a gesture path. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +### Attributes + +| Name | Type | Readable | Writable | Description | +| ------------ | ---------------------------------------- | ---- | ---- | ------ | +| points | Array<[GesturePoint](js-apis-accessibility-GesturePoint.md#gesturepoint)> | Yes | Yes | Gesture touch point. | +| durationTime | number | Yes | Yes | Total gesture duration, in milliseconds.| + +### constructor + +constructor(durationTime: number); + +Constructor used to create a **GesturePath** object. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| durationTime | number | Yes| Total gesture duration, in milliseconds.| + +**Example** + +```ts +let gesturePath = new GesturePath.GesturePath(20); +``` diff --git a/en/application-dev/reference/apis/js-apis-accessibility-GesturePoint.md b/en/application-dev/reference/apis/js-apis-accessibility-GesturePoint.md new file mode 100644 index 0000000000..5792c44cd9 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-accessibility-GesturePoint.md @@ -0,0 +1,47 @@ +# @ohos.accessibility.GesturePoint + + The **GesturePoint** module provides APIs for creating gesture touch point information required for an accessibility application to inject gestures. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import GesturePoint from '@ohos.accessibility.GesturePoint'; +``` + +## GesturePoint + +Defines a gesture touch point. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +### Attributes + +| Name | Type | Readable | Writable | Description | +| --------- | ------ | ---- | ---- | ------- | +| positionX | number | Yes | Yes | X coordinate of the touch point.| +| positionY | number | Yes | Yes | Y coordinate of the touch point.| + +### constructor + +constructor(positionX: number, positionY: number); + +Constructor used to create a **GesturePoint** object. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| positionX | number | Yes| X coordinate of the touch point.| +| positionY | number | Yes | Y coordinate of the touch point.| + +**Example** + +```ts +let gesturePoint = new GesturePoint.GesturePoint(1, 2); +``` diff --git a/en/application-dev/reference/apis/js-apis-accessibility-config.md b/en/application-dev/reference/apis/js-apis-accessibility-config.md index c33230f718..33b6f58627 100644 --- a/en/application-dev/reference/apis/js-apis-accessibility-config.md +++ b/en/application-dev/reference/apis/js-apis-accessibility-config.md @@ -1,17 +1,16 @@ -# System Accessibility Configuration +# @ohos.accessibility.config -The **config** module allows you to configure system accessibility features, including accessibility extension, high-contrast text, mouse buttons, and captions. +The System Accessibility Configuration module allows you to configure system accessibility features, including accessibility extension, high-contrast text, mouse buttons, and captions. > **NOTE** > -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. -> -> The APIs provided by this module are system APIs. +> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The APIs provided by this module are system APIs. ## Modules to Import -```typescript -import config from "@ohos.accessibility.config"; +```ts +import config from '@ohos.accessibility.config'; ``` ## Attributes @@ -22,20 +21,20 @@ import config from "@ohos.accessibility.config"; | -------- | -------- | -------- | -------- | -------- | | highContrastText | [Config](#config)\| Yes| Yes| Whether to enable high-contrast text.| | invertColor | [Config](#config)\| Yes| Yes| Whether to enable color inversion.| -| daltonizationColorFilter | [Config](#config)\<[DaltonizationColorFilter](#daltonizationcolorfilter)>| Yes| Yes| Daltonization filter. | +| daltonizationColorFilter | [Config](#config)<[DaltonizationColorFilter](#daltonizationcolorfilter)>| Yes| Yes| Configuration of the daltonization filter.| | contentTimeout | [Config](#config)\| Yes| Yes| Recommended duration for content display. The value ranges from 0 to 5000, in milliseconds.| -| animationOff | [Config](#config)\| Yes| Yes| Whether to enable animation.| +| animationOff | [Config](#config)\| Yes| Yes| Whether to disable animation.| | brightnessDiscount | [Config](#config)\| Yes| Yes| Brightness discount. The value ranges from 0 to 1.0.| | mouseKey | [Config](#config)\| Yes| Yes| Whether to enable the mouse button feature.| -| mouseAutoClick | [Config](#config)\| Yes| Yes| Interval for the automatic mouse clicks. The value ranges from 0 to 5000, in milliseconds.| +| mouseAutoClick | [Config](#config)\| Yes| Yes| Interval for automatic mouse clicks. The value ranges from 0 to 5000, in milliseconds.| | shortkey | [Config](#config)\| Yes| Yes| Whether to enable the accessibility extension shortcut key.| -| shortkeyTarget | [Config](#config)\| Yes| Yes| Target application for the accessibility extension shortcut key. The value format is bundleName/abilityName.| +| shortkeyTarget | [Config](#config)\| Yes| Yes| Target application for the accessibility extension shortcut key. The value format is 'bundleName/abilityName'.| | captions | [Config](#config)\| Yes| Yes| Whether to enable captions.| -| captionsStyle | [Config](#config)\<[accessibility.CaptionsStyle](./js-apis-accessibility.md#captionsstyle8)>| Yes| Yes| Captions style.| +| captionsStyle | [Config](#config)\<[accessibility.CaptionsStyle](js-apis-accessibility.md#captionsstyle8)>| Yes| Yes| Captions style.| ## enableAbility -enableAbility(name: string, capability: Array<[accessibility.Capability](./js-apis-accessibility.md#capability)>): Promise<void>; +enableAbility(name: string, capability: Array<accessibility.Capability>): Promise<void>; Enables an accessibility extension ability. This API uses a promise to return the result. @@ -45,29 +44,44 @@ Enables an accessibility extension ability. This API uses a promise to return th | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| name | string | Yes| Name of the accessibility extension ability. The format is bundleName/abilityName.| -| capability | Array<[accessibility.Capability](./js-apis-accessibility.md#capability)>) | Yes| Capability of the accessibility extension ability.| +| name | string | Yes| Name of the accessibility extension ability. The format is 'bundleName/abilityName'.| +| capability | Array<[accessibility.Capability](js-apis-accessibility.md#capability)> | Yes| Capability of the accessibility extension ability.| **Return value** | Type| Description| | -------- | -------- | -| Promise<void> | Promise used to return the execution result.| +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300001 | Invalid bundle name or ability name. | +| 9300002 | Target ability already enabled. | **Example** - ```typescript - config.enableAbility("com.ohos.example/axExtension", ['retrieve']) - .then(() => { - console.info('enable succeed'); - }).catch((error) => { - console.error('enable failed'); - }); - ``` +```ts +import accessibility from '@ohos.accessibility'; +let name = 'com.ohos.example/axExtension'; +let capability : accessibility.Capability[] = ['retrieve']; +try { + config.enableAbility(name, capability).then(() => { + console.info('enable ability succeed'); + }).catch((err) => { + console.error('failed to enable ability, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to enable ability, because ' + JSON.stringify(exception)); +}; +``` ## enableAbility -enableAbility(name: string, capability: Array<[accessibility.Capability](./js-apis-accessibility.md#capability)>, callback: AsyncCallback<void>): void; +enableAbility(name: string, capability: Array<accessibility.Capability>, callback: AsyncCallback<void>): void; Enables an accessibility extension ability. This API uses an asynchronous callback to return the result. @@ -77,21 +91,37 @@ Enables an accessibility extension ability. This API uses an asynchronous callba | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| name | string | Yes| Name of the accessibility extension ability. The format is bundleName/abilityName.| -| capability | Array<[accessibility.Capability](./js-apis-accessibility.md#capability)> | Yes| Capability of the accessibility extension ability.| -| callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| +| name | string | Yes| Name of the accessibility extension ability. The format is 'bundleName/abilityName'.| +| capability | Array<[accessibility.Capability](js-apis-accessibility.md#capability)> | Yes| Capability of the accessibility extension ability.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300001 | Invalid bundle name or ability name. | +| 9300002 | Target ability already enabled. | **Example** - ```typescript - config.enableAbility("com.ohos.example/axExtension", ['retrieve'], (err, data) => { - if (err) { - console.error('enable failed'); - return; - } - console.info('enable succeed'); - }) - ``` +```ts +import accessibility from '@ohos.accessibility'; +let name = 'com.ohos.example/axExtension'; +let capability : accessibility.Capability[] = ['retrieve']; +try { + config.enableAbility(name, capability, (err) => { + if (err) { + console.error('failed to enable ability, because ' + JSON.stringify(err)); + return; + } + console.info('enable ability succeed'); + }); +} catch (exception) { + console.error('failed to enable ability, because ' + JSON.stringify(exception)); +}; +``` ## disableAbility @@ -105,24 +135,36 @@ Disables an accessibility extension ability. This API uses a promise to return t | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| name | string | Yes| Name of the accessibility extension ability. The format is bundleName/abilityName.| +| name | string | Yes| Name of the accessibility extension ability. The format is 'bundleName/abilityName'.| **Return value** | Type| Description| | -------- | -------- | -| Promise<void> | Promise used to return the execution result.| +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300001 | Invalid bundle name or ability name. | **Example** - ```typescript - config.disableAbility("com.ohos.example/axExtension") - .then(() => { - console.info('disable succeed'); - }).catch((error) => { - console.error('disable failed'); - }); - ``` +```ts +let name = 'com.ohos.example/axExtension'; +try { + config.disableAbility(name).then(() => { + console.info('disable ability succeed'); + }).catch((err) => { + console.error('failed to disable ability, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to disable ability, because ' + JSON.stringify(exception)); +}; +``` ## disableAbility @@ -136,26 +178,39 @@ Disables an accessibility extension ability. This API uses an asynchronous callb | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| name | string | Yes| Name of the accessibility extension ability. The format is bundleName/abilityName.| -| callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| +| name | string | Yes| Name of the accessibility extension ability. The format is 'bundleName/abilityName'.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300001 | Invalid bundle name or ability name. | **Example** - ```typescript - config.disableAbility("com.ohos.example/axExtension", (err, data) => { - if (err) { - console.error('disable failed'); - return; - } - console.info('disable succeed'); - }) - ``` +```ts +let name = 'com.ohos.example/axExtension'; +try { + config.disableAbility(name, (err, data) => { + if (err) { + console.error('failed to enable ability, because ' + JSON.stringify(err)); + return; + } + console.info('disable succeed'); + }); +} catch (exception) { + console.error('failed to enable ability, because ' + JSON.stringify(exception)); +}; +``` -## on('enableAbilityListsStateChanged') +## on('enabledAccessibilityExtensionListChange') -on(type: 'enableAbilityListsStateChanged', callback: Callback<void>): void; +on(type: 'enabledAccessibilityExtensionListChange', callback: Callback<void>): void; -Adds a listener for changes in the list of enabled accessibility extension abilities. +Adds a listener for changes in the list of enabled accessibility extension abilities. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -163,22 +218,27 @@ Adds a listener for changes in the list of enabled accessibility extension abili | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes| Listening type. The value is fixed at **'enableAbilityListsStateChanged'**, indicating the changes in the list of enabled accessibility extension abilities. | +| type | string | Yes| Listening type. The value is fixed at **'enabledAccessibilityExtensionListChange'**, indicating listening for changes in the list of enabled accessibility extension abilities.| | callback | Callback<void> | Yes| Callback invoked when the list of enabled accessibility extension abilities changes.| **Example** - ```typescript - config.on('enableAbilityListsStateChanged',() => { - console.info('ax extension ability enable list changed'); - }); - ``` +```ts +try { + config.on('enabledAccessibilityExtensionListChange', () => { + console.info('subscribe enabled accessibility extension list change state success'); + }); +} catch (exception) { + console.error('failed to subscribe enabled accessibility extension list change state, because ' + + JSON.stringify(exception)); +}; +``` -## off('enableAbilityListsStateChanged') +## off('enabledAccessibilityExtensionListChange') -off(type: 'enableAbilityListsStateChanged', callback?: Callback<void>): void; +off(type: 'enabledAccessibilityExtensionListChange', callback?: Callback<void>): void; -Cancels the listener for changes in the list of enabled accessibility extension abilities. +Cancels the listener for changes in the list of enabled accessibility extension abilities. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -186,14 +246,21 @@ Cancels the listener for changes in the list of enabled accessibility extension | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | No| Listening type. The value is fixed at **'enableAbilityListsStateChanged'**, indicating the changes in the list of enabled accessibility extension abilities. | +| type | string | Yes| Listening type. The value is fixed at **'enabledAccessibilityExtensionListChange'**, indicating listening for changes in the list of enabled accessibility extension abilities.| | callback | Callback<void> | No| Callback invoked when the list of enabled accessibility extension abilities changes.| **Example** - ```typescript - config.off('enableAbilityListsStateChanged'); - ``` +```ts +try { + config.off('enabledAccessibilityExtensionListChange', () => { + console.info('Unsubscribe enabled accessibility extension list change state success'); + }); +} catch (exception) { + console.error('failed to Unsubscribe enabled accessibility extension list change state, because ' + + JSON.stringify(exception)); +}; +``` ## Config @@ -203,7 +270,7 @@ Implements configuration, acquisition, and listening for attributes. set(value: T): Promise<void>; -Sets this attribute. This API uses a promise to return the result. +Sets the attribute value. This API uses a promise to return the result. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -217,24 +284,28 @@ Sets this attribute. This API uses a promise to return the result. | Type| Description| | -------- | -------- | -| Promise<void> | Promise used to return the execution result.| +| Promise<void> | Promise that returns no value.| **Example** - ```typescript - config.highContrastText.set(true) - .then(() => { - console.info('highContrastText set succeed'); - }).catch((error) => { - console.error('highContrastText set failed'); - }); - ``` +```ts +let value = true; +try { + config.highContrastText.set(value).then(() => { + console.info('set highContrastText succeed'); + }).catch((err) => { + console.error('failed to set highContrastText, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to set config, because ' + JSON.stringify(exception)); +}; +``` ### set set(value: T, callback: AsyncCallback<void>): void; -Sets this attribute. This API uses an asynchronous callback to return the result. +Sets the attribute value. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -243,25 +314,30 @@ Sets this attribute. This API uses an asynchronous callback to return the result | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | value | T | Yes| Attribute value to set.| -| callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** - ```typescript - config.highContrastText.set(true, (err, data) => { - if (err) { - console.error('highContrastText set failed'); - return; - } - console.info('highContrastText set succeed'); - }) - ``` +```ts +let value = true; +try { + config.highContrastText.set(value, (err, data) => { + if (err) { + console.error('failed to set highContrastText, because ' + JSON.stringify(err)); + return; + } + console.info('set highContrastText succeed'); + }); +} catch (exception) { + console.error('failed to set config, because ' + JSON.stringify(exception)); +}; +``` ### get get(): Promise<T>; -Obtains the value of this attribute. This API uses a promise to return the result. +Obtains the attribute value. This API uses a promise to return the result. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -269,24 +345,25 @@ Obtains the value of this attribute. This API uses a promise to return the resul | Type| Description| | -------- | -------- | -| Promise<T> | Promise used to return the attribute value.| +| Promise<T> | Promise used to return the value obtained.| **Example** - ```typescript - config.highContrastText.get() - .then((value) => { - console.info('highContrastText get succeed'); - }).catch((error) => { - console.error('highContrastText get failed'); - }); - ``` +```ts +let value; +config.highContrastText.get().then((data) => { + value = data; + console.info('get highContrastText success'); +}).catch((err) => { + console.error('failed to get highContrastText, because ' + JSON.stringify(err)); +}); +``` ### get get(callback: AsyncCallback<T>): void; -Obtains the value of this attribute. This API uses an asynchronous callback to return the result. +Obtains the attribute value. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -294,25 +371,27 @@ Obtains the value of this attribute. This API uses an asynchronous callback to r | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<void> | Yes| Callback used to return the attribute value.| +| callback | AsyncCallback<T> | Yes| Callback used to return the attribute value.| **Example** - ```typescript - config.highContrastText.get((err, data) => { - if (err) { - console.error('highContrastText get failed'); - return; - } - console.info('highContrastText get succeed'); - }) - ``` +```ts +let value; +config.highContrastText.get((err, data) => { + if (err) { + console.error('failed to get highContrastText, because ' + JSON.stringify(err)); + return; + } + value = data; + console.info('get highContrastText success'); +}); +``` ### on on(callback: Callback<T>): void; -Adds a listener for attribute changes. +Adds a listener for attribute changes. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -324,17 +403,21 @@ Adds a listener for attribute changes. **Example** - ```typescript - config.highContrastText.on(() => { - console.info('highContrastText changed'); - }); - ``` +```ts +try { + config.highContrastText.on((data) => { + console.info('subscribe highContrastText success, result: ' + JSON.stringify(data)); + }); +} catch (exception) { + console.error('failed subscribe highContrastText, because ' + JSON.stringify(exception)); +} +``` ### off off(callback?: Callback<T>): void; -Cancels the listener for attribute changes. +Cancels the listener for attribute changes. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -342,13 +425,15 @@ Cancels the listener for attribute changes. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | Callback<T> | No| Callback invoked when the attribute changes.| +| callback | Callback<T> | No| Callback invoked when the list of enabled accessibility extension abilities changes.| **Example** - ```typescript - config.highContrastText.off(); - ``` +```ts +config.highContrastText.off((data) => { + console.info('Unsubscribe highContrastText success, result: ' + JSON.stringify(data)); +}); +``` ## DaltonizationColorFilter diff --git a/en/application-dev/reference/apis/js-apis-accessibility.md b/en/application-dev/reference/apis/js-apis-accessibility.md index 6d318b4ade..cf4443c60f 100644 --- a/en/application-dev/reference/apis/js-apis-accessibility.md +++ b/en/application-dev/reference/apis/js-apis-accessibility.md @@ -1,4 +1,4 @@ -# Accessibility +# @ohos.accessibility The **Accessibility** module implements the accessibility functions, including obtaining the accessibility application list, accessibility application enabled status, and captions configuration. @@ -8,7 +8,7 @@ The **Accessibility** module implements the accessibility functions, including o ## Modules to Import -```typescript +```ts import accessibility from '@ohos.accessibility'; ``` @@ -49,7 +49,7 @@ Provides information about an accessibility application. | Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| id | number | Yes| No| Ability ID.| +| id | string | Yes| No| Ability ID.| | name | string | Yes| No| Ability name.| | bundleName | string | Yes| No| Bundle name.| | targetBundleNames9+ | Array<string> | Yes| No| Name of the target bundle.| @@ -85,7 +85,7 @@ Describes the target action supported by an accessibility application. ## Capability -Enumerates the capabilities of an auxiliary application. +Enumerates the capabilities of an accessibility application. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -145,7 +145,7 @@ Describes the style of captions. ## CaptionsManager8+ -Implements configuration management for captions. +Implements configuration management for captions. Before calling any API of **CaptionsManager**, you must use the [accessibility.getCaptionsManager()](#accessibilitygetcaptionsmanager8) API to obtain a **CaptionsManager** instance. **System capability**: SystemCapability.BarrierFree.Accessibility.Hearing @@ -156,87 +156,113 @@ Implements configuration management for captions. | enabled | boolean | Yes| No| Whether to enable captions configuration.| | style | [CaptionsStyle](#captionsstyle8) | Yes| No| Style of captions.| -In 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. - ### on('enableChange') on(type: 'enableChange', callback: Callback<boolean>): void; -Enables listening for the enabled status changes of captions configuration. +Enables listening for the enabled status changes of captions configuration. This API uses an asynchronous callback to return the result. -- **Parameters** +**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 enabled status of captions configuration changes.| +| 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 enabled status of captions configuration changes.| -- **Example** +**Example** - ```typescript - captionsManager.on('enableChange',(data) => { - console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) - }) - ``` +```ts +let captionsManager = accessibility.getCaptionsManager(); +try { + captionsManager.on('enableChange', (data) => { + console.info('subscribe caption manager enable state change, result: ' + JSON.stringify(data)); + }); +} catch (exception) { + console.error('failed to subscribe caption manager enable state change, because ' + JSON.stringify(exception)); +} +``` ### on('styleChange') on(type: 'styleChange', callback: Callback<CaptionsStyle>): void; -Enables listening for captions style changes. +Enables listening for captions style changes. This API uses an asynchronous callback to return the result. -- **Parameters** +**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 style of captions changes.| +| 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 style of captions changes.| -- **Example** +**Example** + +```ts +let captionStyle; +let captionsManager = accessibility.getCaptionsManager(); +try { + captionsManager.on('styleChange', (data) => { + captionStyle = data; + console.info('subscribe caption manager style state change, result: ' + JSON.stringify(data)); + }); +} catch (exception) { + console.error('failed to subscribe caption manager style state change, because ' + JSON.stringify(exception)); +} +``` - ```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 the enabled status changes of captions configuration. +Disables listening for the enabled status changes of captions configuration. This API uses an asynchronous callback to return the result. -- **Parameters** +**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 enabled status of captions configuration changes.| +| 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 enabled status of captions configuration changes.| -- **Example** +**Example** - ```typescript - captionsManager.off('enableChange') - ``` +```ts +let captionsManager = accessibility.getCaptionsManager(); +try { + captionsManager.off('enableChange', (data) => { + console.info('Unsubscribe caption manager enable state change, result: ' + JSON.stringify(data)); + }); +} catch (exception) { + console.error('failed to Unsubscribe caption manager enable state change, because ' + JSON.stringify(exception)); +} +``` ### off('styleChange') off(type: 'styleChange', callback?: Callback<CaptionsStyle>): void; -Disables listening for captions style changes. +Disables listening for captions style changes. This API uses an asynchronous callback to return the result. -- **Parameters** +**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 style of captions changes.| +| 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 style of captions changes.| -- **Example** +**Example** - ```typescript - captionsManager.off('styleChange') - ``` +```ts +let captionStyle; +let captionsManager = accessibility.getCaptionsManager(); +try { + captionsManager.off('styleChange', (data) => { + captionStyle = data; + console.info('Unsubscribe caption manager style state change, result: ' + JSON.stringify(data)); + }); +} catch (exception) { + console.error('failed to Unsubscribe caption manager style state change, because ' + JSON.stringify(exception)); +} +``` ## EventInfo @@ -271,16 +297,20 @@ Implements a constructor. **System capability**: SystemCapability.BarrierFree.Accessibility.Core -- **Parameters** +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | jsonObject | string | Yes| JSON string required for creating an object.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| jsonObject | string | Yes| JSON string required for creating an object.| -- **Example** +**Example** - ```typescript - let eventInfo = new accessibility.EventInfo({"type":"click","bundleName":"com.example.MyApplication","triggerAction":"click"}) + ```ts + let eventInfo = new accessibility.EventInfo({ + 'type':'click', + 'bundleName':'com.example.MyApplication', + 'triggerAction':'click' + }); ``` ## EventType @@ -331,153 +361,319 @@ Enumerates window update types. | active | Window activity change.| | focus | Window focus change.| -## accessibility.getAbilityLists +## accessibility.getAbilityLists(deprecated) getAbilityLists(abilityType: AbilityType, stateType: AbilityState): Promise<Array<AccessibilityAbilityInfo>> Obtains the accessibility application list. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. +> You are advised to use[getAccessibilityExtensionList()](#accessibilitygetaccessibilityextensionlist9). + **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)); - }) - ``` +**Parameters** -## accessibility.getAbilityLists +| 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** + +```ts +let abilityType = 'spoken'; +let abilityState = 'enable'; +let abilityList: accessibility.AccessibilityInfo[]; +try { + accessibility.getAbilityLists(abilityType, abilityState).then((data) => { + for (let item of data) { + console.info(item.id); + console.info(item.name); + console.info(item.description); + console.info(item.bundleName); + extensionList.push(item); + } + console.info('get accessibility extension list success'); + }).catch((err) => { + console.error('failed to get accessibility extension list because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to get accessibility extension list because ' + JSON.stringify(exception)); +} +``` + +## accessibility.getAbilityLists(deprecated) 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. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. +> You are advised to use [getAccessibilityExtensionList()](#accessibilitygetaccessibilityextensionlist9-1). + **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); - } - }) - ``` +**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** + +```ts +let abilityType = 'spoken'; +let abilityState = 'enable'; +let abilityList: accessibility.AccessibilityInfo[]; +try { + accessibility.getAbilityLists(abilityType, abilityState, (err, data) => { + if (err) { + console.error('failed to get accessibility extension list because ' + JSON.stringify(err)); + return; + } + for (let item of data) { + console.info(item.id); + console.info(item.name); + console.info(item.description); + console.info(item.bundleName); + abilityList.push(item); + } + console.info('get accessibility extension list success'); + }).catch((err) => { + console.error('failed to get accessibility extension list because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to get accessibility extension list because ' + JSON.stringify(exception)); +} +``` + +## accessibility.getAccessibilityExtensionList9+ + +getAccessibilityExtensionList(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** + +```ts +let abilityType : accessibility.AbilityType = 'spoken'; +let abilityState : accessibility.AbilityState = 'enable'; +let extensionList: accessibility.AccessibilityAbilityInfo[] = []; +try { + accessibility.getAccessibilityExtensionList(abilityType, abilityState).then((data) => { + for (let item of data) { + console.info(item.id); + console.info(item.name); + console.info(item.description); + console.info(item.bundleName); + extensionList.push(item); + } + console.info('get accessibility extension list success'); + }).catch((err) => { + console.error('failed to get accessibility extension list because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to get accessibility extension list because ' + JSON.stringify(exception)); +} +``` + +## accessibility.getAccessibilityExtensionList9+ + +getAccessibilityExtensionList(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** + +```ts +let abilityType : accessibility.AbilityType = 'spoken'; +let abilityState : accessibility.AbilityState = 'enable'; +let extensionList: accessibility.AccessibilityAbilityInfo[] = []; +try { + accessibility.getAccessibilityExtensionList(abilityType, abilityState, (err, data) => { + if (err) { + console.error('failed to get accessibility extension list because ' + JSON.stringify(err)); + return; + } + for (let item of data) { + console.info(item.id); + console.info(item.name); + console.info(item.description); + console.info(item.bundleName); + extensionList.push(item); + } + console.info('get accessibility extension list success'); + }); +} catch (exception) { + console.error('failed to get accessibility extension list because ' + JSON.stringify(exception)); +} +``` ## accessibility.getCaptionsManager8+ getCaptionsManager(): CaptionsManager -Obtains the captions configuration. +Obtains a **CaptionsManager** instance. **System capability**: SystemCapability.BarrierFree.Accessibility.Hearing -- **Return value** +**Return value** - | Type| Description| - | -------- | -------- | - | [CaptionsManager](#captionsmanager8) | Captions configuration.| +| Type| Description| +| -------- | -------- | +| [CaptionsManager](#captionsmanager8) | Captions configuration.| -- **Example** +**Example** - ```typescript - captionsManager = accessibility.getCaptionsManager() - ``` +```ts +let captionsManager = accessibility.getCaptionsManager(); +``` -## accessibility.on('accessibilityStateChange' | 'touchGuideStateChange') +## accessibility.on('accessibilityStateChange') -on(type: 'accessibilityStateChange' | 'touchGuideStateChange', callback: Callback<boolean>): void +on(type: 'accessibilityStateChange', callback: Callback<boolean>): void -Enables listening for the enabled status changes of the accessibility application or touch guide mode. +Enables listening for the enabled status changes of the accessibility application. This API uses an asynchronous callback to return the result. -- **Parameters** +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | type | string | Yes| Type of the event to listen for.
- **'accessibilityStateChange'** means to listen for the enabled status changes of the accessibility application.
**System capability**: SystemCapability.BarrierFree.Accessibility.Core
- **'touchGuideStateChange'** means to listen for the enabled status changes of the touch guide mode.
**System capability**: SystemCapability.BarrierFree.Accessibility.Vision| - | callback | Callback\ | Yes| Callback invoked when the enabled status of captions configuration changes.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to listen for, which is set to **'accessibilityStateChange'** in this API.| +| callback | Callback<boolean> | Yes| Callback used to return the result.| -- **Example** +**Example** - ```typescript - accessibility.on('accessibilityStateChange',(data) => { - console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) - }) - ``` +```ts +try { + accessibility.on('accessibilityStateChange', (data) => { + console.info('subscribe accessibility state change, result: ' + JSON.stringify(data)); + }); +} catch (exception) { + console.error('failed to subscribe accessibility state change, because ' + JSON.stringify(exception)); +} +``` -## accessibility.off('accessibilityStateChange' | 'touchGuideStateChange') +## accessibility.on('touchGuideStateChange') -off(type: 'accessibilityStateChange ' | 'touchGuideStateChange', callback?: Callback<boolean>): void +on(type: 'touchGuideStateChange', callback: Callback<boolean>): void -Disables listening for the enabled status changes of the accessibility application or touch guide mode. +Enables listening for the enabled status changes of the touch guide mode. This API uses an asynchronous callback to return the result. -- **Parameters** +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | type | string | No| Type of the event to listen for.
- **'accessibilityStateChange'** means to listen for the enabled status changes of the accessibility application.
**System capability**: SystemCapability.BarrierFree.Accessibility.Core
- **'touchGuideStateChange'** means to listen for the enabled status changes of the touch guide mode.
**System capability**: SystemCapability.BarrierFree.Accessibility.Vision| - | callback | Callback<boolean> | No| Callback invoked when the enabled status changes.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to listen for, which is set to **'touchGuideStateChange'** in this API.| +| callback | Callback<boolean> | Yes| Callback used to return the result.| -- **Example** +**Example** - ```typescript - accessibility.off('accessibilityStateChange',(data) => { - console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data)) - }) - ``` +```ts +try { + accessibility.on('touchGuideStateChange', (data) => { + console.info('subscribe touch guide state change, result: ' + JSON.stringify(data)); + }); +} catch (exception) { + console.error('failed to subscribe touch guide state change, because ' + JSON.stringify(exception)); +} +``` + +## accessibility.off('accessibilityStateChange') + +off(type: 'accessibilityStateChange', callback?: Callback<boolean>): void + +Disables listening for the enabled status changes of the accessibility application. This API uses an asynchronous callback to return the result. + + + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | No| Type of the event to listen for, which is set to **'accessibilityStateChange'** in this API.| +| callback | Callback<boolean> | No| Callback used to return the result.| + +**Example** + +```ts +try { + accessibility.off('accessibilityStateChange', (data) => { + console.info('Unsubscribe accessibility state change, result: ' + JSON.stringify(data)); + }); +} catch (exception) { + console.error('failed to Unsubscribe accessibility state change, because ' + JSON.stringify(exception)); +} +``` + +## accessibility.off('touchGuideStateChange') + +off(type: 'touchGuideStateChange', callback?: Callback<boolean>): void + +Disables listening for the enabled status changes of the touch guide mode. This API uses an asynchronous callback to return the result. + + + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | No| Type of the event to listen for, which is set to **'touchGuideStateChange'** in this API.| +| callback | Callback<boolean> | No| Callback used to return the result.| + +**Example** + +```ts +try { + accessibility.off('touchGuideStateChange', (data) => { + console.info('Unsubscribe touch guide state change, result: ' + JSON.stringify(data)); + }); +} catch (exception) { + console.error('failed to Unsubscribe touch guide state change, because ' + JSON.stringify(exception)); +} +``` ## accessibility.isOpenAccessibility @@ -487,22 +683,21 @@ Checks whether accessibility is enabled. This API uses a promise to return the r **System capability**: SystemCapability.BarrierFree.Accessibility.Core -- **Return value** +**Return value** - | Type| Description| - | -------- | -------- | - | Promise<boolean> | Returns **true** if accessibility is enabled; returns **false** otherwise.| +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the result. Returns **true** if accessibility is enabled; returns **false** otherwise.| -- **Example** +**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)); - }) - ``` +```ts +accessibility.isOpenAccessibility().then((data) => { + console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) +}).catch((err) => { + console.error('failed to isOpenAccessibility because ' + JSON.stringify(err)); +}); +``` ## accessibility.isOpenAccessibility @@ -512,23 +707,23 @@ Checks whether accessibility is enabled. This API uses an asynchronous callback **System capability**: SystemCapability.BarrierFree.Accessibility.Core -- **Parameters** +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if accessibility is enabled; returns **false** otherwise.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if accessibility is enabled; returns **false** otherwise.| -- **Example** +**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)) - }) - ``` +```ts +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 @@ -538,22 +733,21 @@ Checks whether touch guide mode is enabled. This API uses a promise to return th **System capability**: SystemCapability.BarrierFree.Accessibility.Vision -- **Return value** +**Return value** - | Type| Description| - | -------- | -------- | - | Promise<boolean> | Returns **true** if touch guide mode is enabled; returns **false** otherwise.| +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the result. Returns **true** if touch guide mode is enabled; returns **false** otherwise.| -- **Example** +**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)); - }) - ``` +```ts +accessibility.isOpenTouchGuide().then((data) => { + console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) +}).catch((err) => { + console.error('failed to isOpenTouchGuide because ' + JSON.stringify(err)); +}); +``` ## accessibility.isOpenTouchGuide @@ -563,78 +757,172 @@ Checks whether touch guide mode is enabled. This API uses an asynchronous callba **System capability**: SystemCapability.BarrierFree.Accessibility.Vision -- **Parameters** +**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.| +| 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** +**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)) - }) - ``` +```ts +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 +## accessibility.sendEvent(deprecated) 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** +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. +> You are advised to use **[sendAccessibilityEvent()](#accessibilitysendaccessibilityevent9)**. - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | event | [EventInfo](#eventinfo) | Yes| Accessibility event.| +**System capability**: SystemCapability.BarrierFree.Accessibility.Core -- **Return value** +**Parameters** - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result. Returns data if the accessibility event is sent successfully; returns an error otherwise.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | [EventInfo](#eventinfo) | Yes| Accessibility event.| -- **Example** +**Return value** - ```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)); - }) - ``` +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +let eventInfo = new accessibility.EventInfo({ + 'type':'click', + 'bundleName':'com.example.MyApplication', + 'triggerAction':'click' +}); +accessibility.sendEvent(eventInfo).then(() => { + console.info('send event success'); +}).catch((err) => { + console.error('failed to sendEvent because ' + JSON.stringify(err)); +}); +``` -## accessibility.sendEvent +## accessibility.sendEvent(deprecated) sendEvent(event: EventInfo, callback: AsyncCallback<void>): void Sends an accessibility event. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. +> You are advised to use **[sendAccessibilityEvent()](#accessibilitysendaccessibilityevent9-1)**. + **System capability**: SystemCapability.BarrierFree.Accessibility.Core -- **Parameters** +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | [EventInfo](#eventinfo) | Yes| Accessibility event.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation fails, **error** that contains data is returned. | + +**Example** + +```ts +let eventInfo = new accessibility.EventInfo({ + 'type':'click', + 'bundleName':'com.example.MyApplication', + 'triggerAction':'click' +}); +accessibility.sendEvent(eventInfo, (err, data) => { + if (err) { + console.error('failed to sendEvent because ' + JSON.stringify(err)); + return; + } + console.info('sendEvent success'); +}); +``` - | 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.| +## accessibility.sendAccessibilityEvent9+ -- **Example** +sendAccessibilityEvent(event: EventInfo): Promise<void> - ```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)) - }) - ``` +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 that returns no value.| + +**Example** + +```ts +let eventInfo = new accessibility.EventInfo({ + 'type':'click', + 'bundleName':'com.example.MyApplication', + 'triggerAction':'click' +}); +try { + accessibility.sendAccessibilityEvent(eventInfo).then(() => { + console.info('send event success'); + }).catch((err) => { + console.error('failed to send event because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to send event because ' + JSON.stringify(exception)); +} +``` + +## accessibility.sendAccessibilityEvent9+ + +sendAccessibilityEvent(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. If the operation fails, **error** that contains data is returned. | + +**Example** + +```ts +let eventInfo = new accessibility.EventInfo({ + 'type':'click', + 'bundleName':'com.example.MyApplication', + 'triggerAction':'click' +}); +try { + accessibility.sendEvent(eventInfo, (err, data) => { + if (err) { + console.error('failed to send event because ' + JSON.stringify(err)); + return; + } + console.info('send event success'); + }); +} catch (exception) { + console.error('failed to send event because ' + JSON.stringify(exception)); +} +``` diff --git a/en/application-dev/reference/apis/js-apis-application-accessibilityExtensionAbility.md b/en/application-dev/reference/apis/js-apis-application-accessibilityExtensionAbility.md index a78f8cc320..a47e3e8908 100644 --- a/en/application-dev/reference/apis/js-apis-application-accessibilityExtensionAbility.md +++ b/en/application-dev/reference/apis/js-apis-application-accessibilityExtensionAbility.md @@ -1,12 +1,10 @@ -# Accessibility Extension Ability +# @ohos.application.AccessibilityExtensionAbility -The **AccessibilityExtensionAbility** module is based on the ExtensionAbility framework and provides the **AccessibilityExtensionAbility**. +The **AccessibilityExtensionAbility** module provides accessibility extension capabilities based on the ExtensionAbility framework. ->**NOTE** +> **NOTE** > ->The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. -> ->The APIs of this module can be used only in the stage model. +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -18,9 +16,9 @@ import AccessibilityExtensionAbility from '@ohos.application.AccessibilityExtens **System capability**: SystemCapability.BarrierFree.Accessibility.Core -| Name | Type | Readable | Writable | Description | +| Name | Type| Readable| Writable| Description | | --------- | -------- | ---- | ---- | ------------------------- | -| context | [AccessibilityExtensionContext](js-apis-accessibility-extension-context.md) | Yes | No | Context of the accessibility extension ability. | +| context | [AccessibilityExtensionContext](js-apis-inner-application-accessibilityExtensionContext.md) | Yes| No| Context of the accessibility extension ability.| ## AccessibilityEvent @@ -32,36 +30,10 @@ Defines an accessibility event. | Name | Type | Readable | Writable | Description | | --------- | ---------------------------------------- | ---- | ---- | ---------- | -| eventType | [EventType](js-apis-accessibility.md#eventtype) \| [WindowUpdateType](js-apis-accessibility.md#windowupdatetype) \| [TouchGuideType](#touchguidetype) \| [GestureType](#gesturetype) \| [PageUpdateType](#pageupdatetype) | Yes | No | Event type. | +| eventType | [accessibility.EventType](js-apis-accessibility.md#EventType) \| [accessibility.WindowUpdateType](js-apis-accessibility.md#WindowUpdateType) \| [TouchGuideType](#touchguidetype) \| [GestureType](#gesturetype) \| [PageUpdateType](#pageupdatetype) | Yes | No | Event type. | | target | AccessibilityElement | Yes | No | Target component where the event occurs.| | timeStamp | number | Yes | No | Timestamp of the event. | -## GesturePath - -Defines a gesture path. - -**System capability**: SystemCapability.BarrierFree.Accessibility.Core - -### Attributes - -| Name | Type | Readable | Writable | Description | -| ------------ | ---------------------------------------- | ---- | ---- | ------ | -| points | Array<[GesturePoint](gesturepoint)> | Yes | Yes | An array of gesture touch points. | -| durationTime | number | Yes | Yes | Total time consumed by the gesture.| - -## GesturePoint - -Defines a gesture touch point. - -**System capability**: SystemCapability.BarrierFree.Accessibility.Core - -### Attributes - -| Name | Type | Readable | Writable | Description | -| --------- | ------ | ---- | ---- | ------- | -| positionX | number | Yes | Yes | X-coordinate of the touch point.| -| positionY | number | Yes | Yes | Y-coordinate of the touch point.| - ## GestureType Enumerates gesture types. @@ -89,7 +61,7 @@ Enumerates gesture types. ## PageUpdateType -Enumerates the page refresh types. +Enumerates the page update types. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -106,27 +78,25 @@ Enumerates the touch guide event types. | Name | Description | | ---------- | ------------ | -| touchBegin | A touch starts in touch guide mode.| -| touchEnd | A touch ends in touch guide mode.| +| touchBegin | Start of touch in touch guide mode. | +| touchEnd | End of touch in touch guide mode. | ## AccessibilityExtensionAbility.onConnect onConnect(): void; -Called when the **AccessibilityExtensionAbility** is enabled and connected to the system service. In this API, you can initialize service logic. This API can be overridden as required. +Called when the **AccessibilityExtensionAbility** is enabled and connected to the system service. In this API, you can have the service logic initialized. This API can be overridden as required. **System capability**: SystemCapability.BarrierFree.Accessibility.Core -**Parameters** - -None - **Example** ```ts -onConnect(): void { - console.log("AxExtensionAbility onConnect"); -} +class MyAccessibilityExtensionAbility extends AccessibilityExtensionAbility { + onConnect() { + console.log('AxExtensionAbility onConnect'); + } +}; ``` ## AccessibilityExtensionAbility.onDisconnect @@ -137,16 +107,14 @@ Called when the **AccessibilityExtensionAbility** is disabled and disconnected f **System capability**: SystemCapability.BarrierFree.Accessibility.Core -**Parameters** - -None - **Example** ```ts -onDisconnect(): void { - console.log("AxExtensionAbility onDisconnect"); -} +class MyAccessibilityExtensionAbility extends AccessibilityExtensionAbility { + onDisconnect() { + console.log('AxExtensionAbility onDisconnect'); + } +}; ``` ## AccessibilityExtensionAbility.onAccessibilityEvent @@ -166,19 +134,21 @@ Called when an event that matches the specified bundle and event type occurs. In **Example** ```ts -onAccessibilityEvent(event: AccessibilityEvent): void { - console.log("AxExtensionAbility onAccessibilityEvent"); - if (event.eventType == 'click') { - console.log("AxExtensionAbility onAccessibilityEvent: click"); +class MyAccessibilityExtensionAbility extends AccessibilityExtensionAbility { + onAccessibilityEvent(event) { + console.log('AxExtensionAbility onAccessibilityEvent'); + if (event.eventType == 'click') { + console.log('AxExtensionAbility onAccessibilityEvent: click'); + } } -} +}; ``` ## AccessibilityExtensionAbility.onKeyEvent -onKeyEvent(keyEvent: inputEventClient.KeyEvent): boolean; +onKeyEvent(keyEvent: KeyEvent): boolean; -Called when a physical key is pressed. In this API, you can determine whether to intercept the key event based on the service. +Called when a physical key is pressed. In this API, you can determine whether to intercept an event based on the service. **System capability**: SystemCapability.BarrierFree.Accessibility.Core @@ -191,12 +161,14 @@ Called when a physical key is pressed. In this API, you can determine whether to **Example** ```ts -onKeyEvent(keyEvent: inputEventClient.KeyEvent): boolean { - console.log("AxExtensionAbility onKeyEvent"); - if (keyEvent.keyCode == 22) { - console.log("AxExtensionAbility onKeyEvent: intercept 22"); - return true; +class MyAccessibilityExtensionAbility extends AccessibilityExtensionAbility { + onKeyEvent(keyEvent) { + console.log('AxExtensionAbility onKeyEvent'); + if (keyEvent.keyCode == 22) { + console.log('AxExtensionAbility onKeyEvent: intercept 22'); + return true; + } + return false; } - return false; -} +}; ``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-accessibilityExtensionContext.md b/en/application-dev/reference/apis/js-apis-inner-application-accessibilityExtensionContext.md new file mode 100644 index 0000000000..ada115441c --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-accessibilityExtensionContext.md @@ -0,0 +1,1159 @@ +# AccessibilityExtensionContext + +The **AccessibilityExtensionContext** module, inherited from **ExtensionContext**, provides context for **Accessibility Extension** abilities. + +You can use the APIs of this module to configure the concerned information, obtain root information, and inject gestures. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> +> The APIs of this module can be used only in the stage model. + +## Usage + +Before using the **AccessibilityExtensionContext** module, you must define a child class that inherits from **AccessibilityExtensionAbility**. + +```ts +import AccessibilityExtensionAbility from '@ohos.application.AccessibilityExtensionAbility' +let axContext; +class MainAbility extends AccessibilityExtensionAbility { + onConnect(): void { + console.log('AxExtensionAbility onConnect'); + axContext = this.context; + } +} +``` + +## FocusDirection + +Enumerates the focus directions. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +| Name | Description | +| -------- | ------- | +| up | Search for the next focusable item above the current item in focus.| +| down | Search for the next focusable item below the current item in focus.| +| left | Search for the next focusable item on the left of the current item in focus.| +| right | Search for the next focusable item on the right of the current item in focus.| +| forward | Search for the next focusable item before the current item in focus.| +| backward | Search for the next focusable item after the current item in focus.| + +## FocusType + +Enumerates the focus types. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +| Name | Description | +| ------------- | ----------- | +| accessibility | Accessibility focus.| +| normal | Normal focus. | + +## Rect + +Defines a rectangle. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +| Name | Type | Readable | Writable | Description | +| ------ | ------ | ---- | ---- | --------- | +| left | number | Yes | No | Left boundary of the rectangle.| +| top | number | Yes | No | Top boundary of the rectangle.| +| width | number | Yes | No | Width of the rectangle. | +| height | number | Yes | No | Height of the rectangle. | + +## WindowType + +Enumerates the window types. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +| Name | Description | +| ----------- | --------- | +| application | Application window.| +| system | System window.| + +## AccessibilityExtensionContext.setTargetBundleName + +setTargetBundleName(targetNames: Array\): Promise\; + +Sets the concerned target bundle. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ------------------- | ---- | -------- | +| targetNames | Array<string> | Yes | Name of the target bundle.| + +**Return value** + +| Type | Description | +| ---------------------- | --------------------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +let targetNames = ['com.ohos.xyz']; +try { + axContext.setTargetBundleName(targetNames).then(() => { + console.info('set target bundle names success'); + }).catch((err) => { + console.error('failed to set target bundle names, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to set target bundle names, because ' + JSON.stringify(exception)); +}; +``` + +## AccessibilityExtensionContext.setTargetBundleName + +setTargetBundleName(targetNames: Array\, callback: AsyncCallback\): void; + +Sets the concerned target bundle. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ------------------- | ---- | -------- | +| targetNames | Array<string> | Yes | Name of the target bundle.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation fails, **error** that contains data is returned.| + +**Example** + +```ts +let targetNames = ['com.ohos.xyz']; +try { + axContext.setTargetBundleName(targetNames, (err, data) => { + if (err) { + console.error('failed to set target bundle names, because ' + JSON.stringify(err)); + return; + } + console.info('set target bundle names success'); + }); +} catch (exception) { + console.error('failed to set target bundle names, because ' + JSON.stringify(exception)); +}; +``` + +## AccessibilityExtensionContext.getFocusElement + +getFocusElement(isAccessibilityFocus?: boolean): Promise\; + +Obtains the focus element. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------------------- | ------- | ---- | ------------------- | +| isAccessibilityFocus | boolean | No | Whether the obtained focus element is an accessibility focus. The default value is **false**.| + +**Return value** + +| Type | Description | +| ----------------------------------- | ---------------------- | +| Promise<AccessibilityElement> | Promise used to return the current focus element.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300003 | Do not have accessibility right for this operation. | + +**Example** + +```ts +let focusElement; +try { + axContext.getFocusElement().then((data) => { + focusElement = data; + console.log('get focus element success'); + }).catch((err) => { + console.error('failed to get focus element, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to get focus element, because ' + JSON.stringify(exception)); +} +``` + +## AccessibilityExtensionContext.getFocusElement + +getFocusElement(callback: AsyncCallback\): void; + +Obtains the focus element. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<AccessibilityElement> | Yes | Callback used to return the current focus element.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300003 | Do not have accessibility right for this operation. | + +**Example** + +```ts +let focusElement; +try { + axContext.getFocusElement((err, data) => { + if (err) { + console.error('failed to get focus element, because ' + JSON.stringify(err)); + return; + } + focusElement = data; + console.info('get focus element success'); + }); +} catch (exception) { + console.error('failed to get focus element, because ' + JSON.stringify(exception)); +} +``` + +## AccessibilityExtensionContext.getFocusElement + +getFocusElement(isAccessibilityFocus: boolean, callback: AsyncCallback\): void; + +Obtains the focus element. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------------------- | ------- | ---- | ------------------- | +| isAccessibilityFocus | boolean | Yes | Whether the obtained focus element is an accessibility focus.| +| callback | AsyncCallback<AccessibilityElement> | Yes | Callback used to return the current focus element.| + +**Example** + +```ts +let focusElement; +let isAccessibilityFocus = true; +try { + axContext.getFocusElement(isAccessibilityFocus, (err, data) => { + if (err) { + console.error('failed to get focus element, because ' + JSON.stringify(err)); + return; + } + focusElement = data; + console.info('get focus element success'); +}); +} catch (exception) { + console.error('failed to get focus element, because ' + JSON.stringify(exception)); +} +``` +## AccessibilityExtensionContext.getWindowRootElement + +getWindowRootElement(windowId?: number): Promise\; + +Obtains the root element of a window. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------------------- | ------- | ---- | ------------------- | +| windowId | number | No | Window for which you want to obtain the root element. If this parameter is not specified, it indicates the current active window.| + +**Return value** + +| Type | Description | +| ----------------------------------- | ---------------------- | +| Promise<AccessibilityElement> | Promise used to return the root element.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300003 | Do not have accessibility right for this operation. | + +**Example** + +```ts +let rootElement; +try { + axContext.getWindowRootElement().then((data) => { + rootElement = data; + console.log('get root element of the window success'); + }).catch((err) => { + console.error('failed to get root element of the window, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to get root element of the window, ' + JSON.stringify(exception)); +} +``` + +## AccessibilityExtensionContext.getWindowRootElement + +getWindowRootElement(callback: AsyncCallback\): void; + +Obtains the root element of a window. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<AccessibilityElement> | Yes | Callback used to return the root element.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300003 | Do not have accessibility right for this operation. | + +**Example** + +```ts +let rootElement; +try { + axContext.getWindowRootElement((err, data) => { + if (err) { + console.error('failed to get root element of the window, because ' + JSON.stringify(err)); + return; + } + rootElement = data; + console.info('get root element of the window success'); +}); +} catch (exception) { + console.error('failed to get root element of the window, because ' + JSON.stringify(exception)); +} +``` + +## AccessibilityExtensionContext.getWindowRootElement + +getWindowRootElement(windowId: number, callback: AsyncCallback\): void; + +Obtains the root element of a window. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------------------- | ------- | ---- | ------------------- | +| windowId | number | Yes | Window for which you want to obtain the root element. If this parameter is not specified, it indicates the current active window.| +| callback | AsyncCallback<AccessibilityElement> | Yes | Callback used to return the root element.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300003 | Do not have accessibility right for this operation. | + +**Example** + +```ts +let rootElement; +let windowId = 10; +try { + axContext.getWindowRootElement(windowId, (err, data) => { + if (err) { + console.error('failed to get root element of the window, because ' + JSON.stringify(err)); + return; + } + rootElement = data; + console.info('get root element of the window success'); +}); +} catch (exception) { + console.error('failed to get root element of the window, because ' + JSON.stringify(exception)); +} +``` + +## AccessibilityExtensionContext.getWindows + +getWindows(displayId?: number): Promise\>; + +Obtains the list of windows on a display. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------------------- | ------- | ---- | ------------------- | +| displayId | number | No | ID of the display from which the window information is obtained. If this parameter is not specified, it indicates the default main display.| + +**Return value** + +| Type | Description | +| ----------------------------------- | ---------------------- | +| Promise<Array<AccessibilityElement>> | Promise used to return the window list.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300003 | Do not have accessibility right for this operation. | + +**Example** + +```ts +let windows; +try { + axContext.getWindows().then((data) => { + windows = data; + console.log('get windows success'); + }).catch((err) => { + console.error('failed to get windows, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to get windows, because ' + JSON.stringify(exception)); +} +``` + +## AccessibilityExtensionContext.getWindows + +getWindows(callback: AsyncCallback\>): void; + +Obtains the list of windows on a display. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<Array<AccessibilityElement>> | Yes | Callback used to return the window list.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300003 | Do not have accessibility right for this operation. | + +**Example** + +```ts +let windows; +try { + axContext.getWindows((err, data) => { + if (err) { + console.error('failed to get windows, because ' + JSON.stringify(err)); + return; + } + windows = data; + console.info('get windows success'); + }); +} catch (exception) { + console.error('failed to get windows, because ' + JSON.stringify(exception)); +} +``` + +## AccessibilityExtensionContext.getWindows + +getWindows(displayId: number, callback: AsyncCallback\>): void; + +Obtains the list of windows on a display. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------------------- | ------- | ---- | ------------------- | +| displayId | number | Yes | ID of the display from which the window information is obtained. If this parameter is not specified, it indicates the default main display.| +| callback | AsyncCallback<Array<AccessibilityElement>> | Yes | Callback used to return the window list.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300003 | Do not have accessibility right for this operation. | + +**Example** + +```ts +let windows; +let displayId = 10; +try { + axContext.getWindows(displayId, (err, data) => { + if (err) { + console.error('failed to get windows, because ' + JSON.stringify(err)); + return; + } + windows = data; + console.info('get windows success'); + }); +} catch (exception) { + console.error('failed to get windows, because ' + JSON.stringify(exception)); +} +``` + +## AccessibilityExtensionContext.injectGesture + +injectGesture(gesturePath: GesturePath): Promise\; + +Inject a gesture. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| gesturePath | [GesturePath](js-apis-accessibility-GesturePath.md#gesturepath) | Yes | Path of the gesture to inject. | + +**Return value** + +| Type | Description | +| ----------------------------------- | ---------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300003 | Do not have accessibility right for this operation. | + +**Example** + +```ts +import GesturePath from "@ohos.accessibility.GesturePath"; +import GesturePoint from '@ohos.accessibility.GesturePoint'; +let gesturePath = new GesturePath.GesturePath(100); +try { + for (let i = 0; i < 10; i++) { + let gesturePoint = new GesturePoint.GesturePoint(100, i * 200); + gesturePath.points.push(gesturePoint); + } + axContext.injectGesture(gesturePath).then(() => { + console.info('inject gesture success'); + }).catch((err) => { + console.error('failed to inject gesture, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('failed to inject gesture, because ' + JSON.stringify(exception)); +} +``` +## AccessibilityExtensionContext.injectGesture + +injectGesture(gesturePath: GesturePath, callback: AsyncCallback\): void + +Inject a gesture. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| gesturePath | [GesturePath](js-apis-accessibility-GesturePath.md#gesturepath) | Yes | Path of the gesture to inject. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300003 | Do not have accessibility right for this operation. | + +**Example** + +```ts +import GesturePath from "@ohos.accessibility.GesturePath"; +import GesturePoint from '@ohos.accessibility.GesturePoint'; +let gesturePath = new GesturePath.GesturePath(100); +try { + for (let i = 0; i < 10; i++) { + let gesturePoint = new GesturePoint.GesturePoint(100, i * 200); + gesturePath.points.push(gesturePoint); + } + axContext.injectGesture(gesturePath, (err, data) => { + if (err) { + console.error('failed to inject gesture, because ' + JSON.stringify(err)); + return; + } + console.info('inject gesture success'); + }); +} catch (exception) { + console.error('failed to inject gesture, because ' + JSON.stringify(exception)); +} +``` +## AccessibilityElement9+ + +Defines the accessibilityelement. Before calling APIs of **AccessibilityElement**, you must call [AccessibilityExtensionContext.getFocusElement()](#accessibilityextensioncontextgetfocuselement) or [AccessibilityExtensionContext.getWindowRootElement()](#accessibilityextensioncontextgetwindowrootelement) to obtain an **AccessibilityElement** instance. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +## attributeNames + +attributeNames\(): Promise\>; + +Obtains all attribute names of this element. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------------------------ | +| Promise<Array<T>> | Promise used to return all attribute names of the element.| + +**Example** + +```ts +let rootElement; +let attributeNames; +rootElement.attributeNames().then((data) => { + console.log('get attribute names success'); + attributeNames = data; +}).catch((err) => { + console.log('failed to get attribute names, because ' + JSON.stringify(err)); +}); +``` +## attributeNames + +attributeNames\(callback: AsyncCallback\>): void; + +Obtains all attribute names of this element. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| callback | AsyncCallback<Array<T>> | Yes | Callback used to return all attribute names of the element.| + +**Example** + +```ts +let rootElement; +let attributeNames; +rootElement.attributeNames((err, data) => { + if (err) { + console.error('failed to get attribute names, because ' + JSON.stringify(err)); + return; + } + attributeNames = data; + console.info('get attribute names success'); +}); +``` +## AccessibilityElement.attributeValue + +attributeValue\(attributeName: T): Promise\; + +Obtains the attribute value based on an attribute name. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| attributeName | T | Yes | Attribute name. | + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------------------------ | +| Promise<ElementAttributeValues[T]> | Promise used to return the attribute value.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300004 | This property does not exist. | + +**Example** + +```ts +let attributeName = 'name'; +let attributeValue; +let rootElement; +try { + rootElement.attributeValue(attributeName).then((data) => { + console.log('get attribute value by name success'); + attributeValue = data; + }).catch((err) => { + console.log('failed to get attribute value, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.log('failed to get attribute value, because ' + JSON.stringify(exception)); +} +``` +## AccessibilityElement.attributeValue + +attributeValue\(attributeName: T, + callback: AsyncCallback\): void; + +Obtains the attribute value based on an attribute name. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| attributeName | T | Yes | Attribute name. | +| callback | AsyncCallback<ElementAttributeValues[T]> | Yes | Callback used to return the attribute value.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300004 | This property does not exist. | + +**Example** + +```ts +let rootElement; +let attributeValue; +let attributeName = 'name'; +try { + rootElement.attributeValue(attributeName, (err, data) => { + if (err) { + console.error('failed to get attribute value, because ' + JSON.stringify(err)); + return; + } + attributeValue = data; + console.info('get attribute value success'); + }); +} catch (exception) { + console.log('failed to get attribute value, because ' + JSON.stringify(exception)); +} +``` +## actionNames + +actionNames(): Promise\>; + +Obtains the names of all actions supported by this element. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------------------------ | +| Promise<Array<string>> | Promise used to return the names of all actions supported by the element.| + +**Example** + +```ts +let rootElement; +let actionNames; +rootElement.actionNames().then((data) => { + console.log('get action names success'); + actionNames = data; +}).catch((err) => { + console.log('failed to get action names because ' + JSON.stringify(err)); +}); +``` +## actionNames + +actionNames(callback: AsyncCallback\>): void; + +Obtains the names of all actions supported by this element. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| callback | AsyncCallback<Array<string>> | Yes | Callback used to return the names of all actions supported by the element.| + +**Example** + +```ts +let rootElement; +let actionNames; +rootElement.actionNames((err, data) => { + if (err) { + console.error('failed to get action names, because ' + JSON.stringify(err)); + return; + } + actionNames = data; + console.info('get action names success'); +}); +``` +## performAction + +performAction(actionName: string, parameters?: object): Promise\; + +Performs an action based on the specified action name. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| actionName | string | Yes | Action name. | +| parameters | object | No | Parameter required for performing the target action. | + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------------------------ | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300005 | This action is not supported. | + +**Example** + +```ts +let rootElement; +try { + rootElement.performAction('action').then((data) => { + console.info('perform action success'); + }).catch((err) => { + console.log('failed to perform action, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.log('failed to perform action, because ' + JSON.stringify(exception)); +} +``` +## performAction + +performAction(actionName: string, callback: AsyncCallback\): void; + +Performs an action based on the specified action name. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| actionName | string | Yes | Attribute name. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300005 | This action is not supported. | + +**Example** + +```ts +let rootElement; +try { + rootElement.performAction('action', (err, data) => { + if (err) { + console.error('failed to perform action, because ' + JSON.stringify(err)); + return; + } + console.info('perform action success'); + }); +} catch (exception) { + console.log('failed to perform action, because ' + JSON.stringify(exception)); +} +``` +## performAction + +performAction(actionName: string, parameters: object, callback: AsyncCallback\): void; + +Performs an action based on the specified action name. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| actionName | string | Yes | Action name. | +| parameters | object | Yes | Parameter required for performing the target action. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Error codes** + +For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). + +| ID| Error Message| +| ------- | -------------------------------- | +| 9300005 | This action is not supported. | + +**Example** + +```ts +let rootElement; +let actionName = 'action'; +let parameters = { + 'setText': 'test text' +}; +try { + rootElement.performAction(actionName, parameters, (err, data) => { + if (err) { + console.error('failed to perform action, because ' + JSON.stringify(err)); + return; + } + console.info('perform action success'); + }); +} catch (exception) { + console.log('failed to perform action, because ' + JSON.stringify(exception)); +} +``` +## findElement('content') + +findElement(type: 'content', condition: string): Promise\>; + +Queries the element information of the **content** type. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | Yes | Information type. The value is fixed at **'content'**. | +| condition | string | Yes | Search criteria. | + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------------------------ | +| Promise<Array<AccessibilityElement>> | Promise used to return the result.| + +**Example** + +```ts +let rootElement; +let type = 'content'; +let condition = 'keyword'; +let elements; +try { + rootElement.findElement(type, condition).then((data) => { + elements = data; + console.log('find element success'); + }).catch((err) => { + console.log('failed to find element, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.log('failed to find element, because ' + JSON.stringify(exception)); +} +``` +## findElement('content') + +findElement(type: 'content', condition: string, callback: AsyncCallback\>): void; + +Queries the element information of the **content** type. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | Yes | Information type. The value is fixed at **'content'**. | +| condition | string | Yes | Search criteria. | +| callback | AsyncCallback<Array<AccessibilityElement>> | Yes | Callback used to return the result.| + +**Example** + +```ts +let rootElement; +let type = 'content'; +let condition = 'keyword'; +let elements; +try { + rootElement.findElement(type, condition, (err, data) => { + if (err) { + console.error('failed to find element, because ' + JSON.stringify(err)); + return; + } + elements = data; + console.info('find element success'); + }); +} catch (exception) { + console.log('failed to find element, because ' + JSON.stringify(exception)); +} +``` +## findElement('focusType') + +findElement(type: 'focusType', condition: FocusType): Promise\; + +Queries the element information of the **focusType** type. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | Yes | Information type. The value is fixed at **'focusType'**. | +| condition | [FocusType](#focustype) | Yes | Enumerates the focus types. | + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------------------------ | +| Promise<AccessibilityElement> | Promise used to return the result.| + +**Example** + +```ts +let rootElement; +let type = 'focusType'; +let condition = 'normal'; +let element; +try { + rootElement.findElement(type, condition).then((data) => { + element = data; + console.log('find element success'); + }).catch((err) => { + console.log('failed to find element, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.log('failed to find element, because ' + JSON.stringify(exception)); +} +``` +## findElement('focusType') + +findElement(type: 'focusType', condition: FocusType, callback: AsyncCallback\): void; + +Queries the element information of the **focusType** type. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | Yes | Information type. The value is fixed at **'focusType'**. | +| condition | [FocusType](#focustype) | Yes | Enumerates the focus types. | +| callback | AsyncCallback<AccessibilityElement> | Yes | Callback used to return the result.| + +**Example** + +```ts +let rootElement; +let type = 'focusType'; +let condition = 'normal'; +let element; +try { + rootElement.findElement(type, condition, (err, data) => { + if (err) { + console.error('failed to find element, because ' + JSON.stringify(err)); + return; + } + element = data; + console.info('find element success'); + }); +} catch (exception) { + console.log('failed to find element, because ' + JSON.stringify(exception)); +} +``` +## findElement('focusDirection') + +findElement(type: 'focusDirection', condition: FocusDirection): Promise\; + +Queries the element information of the **focusDirection** type. This API uses a promise to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | Yes | Information type. The value is fixed at **'focusDirection'**. | +| condition | [FocusDirection](#focusdirection) | Yes | Enumerates the focus directions. | + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------------------------ | +| Promise<AccessibilityElement> | Promise used to return the result.| + +**Example** + +```ts +let rootElement; +let type = 'focusDirection'; +let condition = 'up'; +let element; +try { + rootElement.findElement(type, condition).then((data) => { + element = data; + console.log('find element success'); + }).catch((err) => { + console.log('failed to find element, because ' + JSON.stringify(err)); + }); +} catch (exception) { + console.log('failed to find element, because ' + JSON.stringify(exception)); +} +``` +## findElement('focusDirection') + +findElement(type: 'focusDirection', condition: FocusDirection, callback: AsyncCallback\): void; + +Queries the element information of the **focusDirection** type. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BarrierFree.Accessibility.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | Yes | Information type. The value is fixed at **'focusDirection'**. | +| condition | [FocusDirection](#focusdirection) | Yes | Direction of the next focus element. | +| callback | AsyncCallback<AccessibilityElement> | Yes | Callback used to return the result.| + +**Example** + +```ts +let rootElement; +let type = 'focusDirection'; +let condition = 'up'; +let elements; +try { + rootElement.findElement(type, condition, (err, data) => { + if (err) { + console.error('failed to find element, because ' + JSON.stringify(err)); + return; + } + elements = data; + console.info('find element success'); + }); +} catch (exception) { + console.log('failed to find element, because ' + JSON.stringify(exception)); +} +``` diff --git a/en/application-dev/reference/errorcodes/errorcode-accessibility.md b/en/application-dev/reference/errorcodes/errorcode-accessibility.md new file mode 100644 index 0000000000..954c8464f3 --- /dev/null +++ b/en/application-dev/reference/errorcodes/errorcode-accessibility.md @@ -0,0 +1,96 @@ +# Accessibility Error Codes + +## 9300001 Invalid Bundle Name or Ability Name + +**Error Message** + +Invalid bundle name or ability name. + +**Description** + +This error code is reported when the entered bundle name or ability name is invalid. + +**Possible Causes** + + +1. The bundle name does not exist. +2. The bundle does not contain the target ability. + +**Solution** + +1. Verify the bundle name. +2. Check whether the ability name corresponding to the bundle name is correct. + +## 9300002 Target Ability Already Enabled + +**Error Message** + +Target ability already enabled. + +**Description** + +This error code is reported when the target ability is already enabled. + +**Possible Causes** + +The target ability is already enabled and cannot be enabled again. + +**Solution** + +1. Stop the target Ability. +2. Re-enable the target ability. + +## 9300003 No Accessibility Permission to Perform the Operation + +**Error Message** + +Do not have accessibility right for this operation. + +**Description** + +This error code is reported when an application performs an accessibility operation for which the related permission has not been granted. + +**Possible Causes** + +The permission for performing the accessibility operation is not granted when the accessibility application is enabled. + +**Solution** + +1. Request from the user the permission for performing the accessibility operation, stating the reason for the request. +2. Have the accessibility application re-enabled and the required accessibility operation enabled. + +## 9300004 Attribute Not Found + +**Error Message** + +This property does not exist. + +**Description** + +This error code is reported when the entered attribute of the accessibility element does not exist. + +**Possible Causes** + +The attribute does not exist in the accessibility element. + +**Solution** + +Make sure the accessibility element has the target attribute. + +## 9300005 Operation Not Supported + +**Error Message** + +This action is not supported. + +**Description** + +This error code is reported when the application performs an operation that is not supported by the accessibility element. + +**Possible Causes** + +The accessibility element does not support the target operation. + +**Solution** + +Make sure the operation is included in the list of operations supported by the accessibility element. -- GitLab