• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# AccessibilityExtensionAbility
2
3The **AccessibilityExtensionAbility** module provides accessibility extension capabilities based on the **ExtensionAbility** framework. You can develop your accessibility applications by applying the **AccessibilityExtensionAbility** template to enhance usability.
4
5> **Environment Requirements**
6>
7> IDE: DevEco Studio 3.0 Beta3 (3.0.0.900) or later
8>
9> SDK: API version 9 or later
10>
11> Model: stage
12
13## AccessibilityExtensionAbility Overview
14
15Accessibility is about giving equal access to everyone so that they can access and use information equally and conveniently under any circumstances. It helps narrow the digital divide between people of different classes, regions, ages, and health status in terms of information understanding, information exchange, and information utilization, so that they can participate in social life more conveniently and enjoy the benefits of technological advances.
16
17AccessibilityExtensionAbility is an accessibility extension service framework. It allows you to develop your own extension services and provides a standard mechanism for exchanging information between applications and extension services. You can make use of the provided capabilities and APIs to develop accessibility features for users with disabilities or physical limitations. For example, you can develop a screen reader for users with vision impairments.
18
19Below shows the AccessibilityExtensionAbility framework.
20
21![AccessibilityFramework](figures/AccessibilityFramework.png)
22
231. Accessibility application: extension service application developed based on the AccessibilityExtensionAbility framework, for example, a screen reader application.
242. Target application: application assisted by the accessibility application.
253. AccessibilityAbilityManagerService (AAMS): main service of the AccessibilityExtensionAbility framework, which is used to manage the lifecycle of accessibility applications and provide a bridge for information exchange between accessibility applications and target applications.
264. AccessibilityAbility (AAkit): ability that is used by the accessibility application to build an extension service ability operating environment and that provides interfaces for the accessibility application to query and operate the target application, including performing click/long press operations.
275. AccessibilitySystemAbilityClient (ASACkit): used by the target application to send accessibility events, such as content change events, to AAMS, and respond to the instructions (such as performing click/long press operations) sent by the accessibility application through AAMS.
28
29## Creating an Accessibility Extension Service
30
31You can create an accessibility extension service by creating a project from scratch or adding the service to an existing project. Only one accessibility extension service can be created for a project.
32
33### Creating a Project
34
35Perform the following steps in DevEco Studio:
361. From the upper left corner of DevEco Studio, choose **File** > **New** > **Create Project**.
372. By following the project creation wizard, click the **OpenHarmony** tab, select the **Empty Ability** template, and then click **Next**.
383. Set **Project type** to **Application**, **Compile API** (or **Compile SDK**, depending on the version used) to **9**, and **Model** to **Stage**, and then click **Finish**.
39
40### Creating an AccessibilityExtAbility File
41
42To add an accessibility extension service to a project, create the **AccessibilityExtAbility** folder in the **ets** folder of the project, create the **AccessibilityExtAbility.ts** file in the new folder, and add the following code to the new file:
43
44```typescript
45import AccessibilityExtensionAbility, { AccessibilityEvent } from '@ohos.application.AccessibilityExtensionAbility';
46
47class AccessibilityExtAbility extends AccessibilityExtensionAbility {
48    onConnect() {
49        console.info('AccessibilityExtAbility onConnect');
50    }
51
52    onDisconnect() {
53        console.info('AccessibilityExtAbility onDisconnect');
54    }
55
56    onAccessibilityEvent(accessibilityEvent: AccessibilityEvent) {
57        console.info('AccessibilityExtAbility onAccessibilityEvent: ' + JSON.stringify(accessibilityEvent));
58    }
59}
60
61export default AccessibilityExtAbility;
62```
63
64The APIs defined in the file are as follows.
65
66| API| Description|
67| ---- | ---- |
68| onConnect(): void | Called when a connection with the extension service is set up.|
69| onDisconnect(): void | Called when the connection with the extension service is severed.|
70| onAccessibilityEvent(event: AccessibilityEvent): void | Called when an accessibility event occurs|
71
72## Processing an Accessibility Event
73
74You can process the service logic for accessibility events in the **onAccessibilityEvent()** API. For details about the events, see [AccessibilityEvent](../reference/apis/js-apis-application-accessibilityExtensionAbility.md#accessibilityevent). The following code snippet uses the **pageStateUpdate** event as an example.
75
76```typescript
77onAccessibilityEvent(accessibilityEvent: AccessibilityEvent) {
78    console.info('AccessibilityExtAbility onAccessibilityEvent: ' + JSON.stringify(accessibilityEvent));
79    if (accessibilityEvent.eventType === 'pageStateUpdate') {
80        console.info('AccessibilityExtAbility onAccessibilityEvent: pageStateUpdate');
81        // TODO: Develop custom logic.
82    }
83}
84```
85For an accessibility event, you can use the APIs of the [AccessibilityExtensionContext](../reference/apis/js-apis-inner-application-accessibilityExtensionContext.md) module to configure the concerned information, obtain root information, and inject gestures.
86
87You can also process physical key events in the accessibility extension service. For details, see [onKeyEvent](../reference/apis/js-apis-application-accessibilityExtensionAbility.md#accessibilityextensionabilityonkeyevent).
88
89## Declaring Capabilities of Accessibility Extension Services
90
91After developing the custom logic for an accessibility extension service, you must add the configuration information of the service to the corresponding module-level **module.json5** file in the project directory. In the file, the **srcEntry** tag indicates the path to the accessibility extension service. Make sure the value of the **type** tag is fixed at **accessibility**. Otherwise, the connection to the service will fail.
92
93```json
94"extensionAbilities": [
95  {
96    "name": "AccessibilityExtAbility",
97    "srcEntry": "./ets/AccessibilityExtAbility/AccessibilityExtAbility.ts",
98    "label": "$string:MainAbility_label",
99    "description": "$string:MainAbility_desc",
100    "type": "accessibility",
101    "metadata": [
102      {
103        "name": "ohos.accessibleability",
104        "resource": "$profile:accessibility_config"
105      }
106    ]
107  }
108]
109```
110**accessibility_config** is the specific configuration of the accessibility extension service. You need to create the **accessibility_config.json** file in **resources/base/profile/** and declare the [capabilities](../reference/apis/js-apis-accessibility.md#capability) of the service in the file.
111```json
112{
113  "accessibilityCapabilities": [
114    "retrieve",
115    "gesture"
116  ]
117}
118```
119## Enabling or Disabling a Custom Accessibility Extension Service
120
121You can enable or disable a custom accessibility extension service through the command line interface or the device settings.
122
123**Method 1**: through the command line interface
124
125Run the **hdc shell** command, then the following system command:
126
127- To enable the service: **accessibility enable -a AccessibilityExtAbility -b com.example.demo -c rg**
128- To disable the service: **accessibility disable -a AccessibilityExtAbility -b com.example.demo**
129
130In the preceding commands, **AccessibilityExtAbility** indicates the name of the accessibility extension service, **com.example.demo** indicates the bundle name, and **rg** indicates the capabilities (**r** is short for retrieve and **g** gesture).
131
132If the service is enabled or disabled successfully, the message "enable ability successfully" or "disable ability successfully" is displayed.
133
134
135**Method 2**: through the device settings
136- From the device settings screen, access the list of installed extended services under accessibility.
137If an extended service is not installed, it is grayed out, and "No service" is displayed.
138- Select the target extended service, and toggle on or off the switch to enable or disable it.
139- If you opt to enable a service, a security reminder is displayed. Wait until the countdown ends and then select the check box indicating that you are aware of and willing to assume the listed risks.
140