• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# AccessibilityExtensionAbility Development
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
13This document is organized as follows:
14
15- [AccessibilityExtensionAbility Development](#accessibilityextensionability-development)
16  - [Creating an Accessibility Extension Service](#creating-an-accessibility-extension-service)
17    - [Creating a Project](#creating-a-project)
18    - [Creating an AccessibilityExtAbility File](#creating-an-accessibilityextability-file)
19  - [Processing an Accessibility Event](#processing-an-accessibility-event)
20  - [Declaring Capabilities of Accessibility Extension Services](#declaring-capabilities-of-accessibility-extension-services)
21  - [Enabling a Custom Accessibility Extension Service](#enabling-a-custom-accessibility-extension-service)
22
23## Creating an Accessibility Extension Service
24
25You can create an accessibility extension service by creating a project from scratch or adding the service to an existing project.
26
27### Creating a Project
28
29Perform the following steps in DevEco Studio:
301. From the upper left corner of DevEco Studio, choose **File** > **New** > **Create Project**.
312. By following the project creation wizard, click the **OpenHarmony** tab, select the **Empty Ability** template, and then click **Next**.
323. 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**.
33
34### Creating an AccessibilityExtAbility File
35
36To 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:
37
38```typescript
39import AccessibilityExtensionAbility from '@ohos.application.AccessibilityExtensionAbility';
40
41class AccessibilityExtAbility extends AccessibilityExtensionAbility {
42    onConnect() {
43        console.log('AccessibilityExtAbility onConnect');
44    }
45
46    onDisconnect() {
47        console.log('AccessibilityExtAbility onDisconnect');
48    }
49
50    onAccessibilityEvent(accessibilityEvent) {
51        console.log('AccessibilityExtAbility onAccessibilityEvent: ' + JSON.stringify(accessibilityEvent));
52    }
53}
54
55export default AccessibilityExtAbility;
56```
57
58The APIs defined in the file are as follows.
59
60| API| Description|
61| ---- | ---- |
62| onConnect(): void | Called when a connection with the extension service is set up.|
63| onDisconnect(): void | Called when the connection with the extension service is severed.|
64| onAccessibilityEvent(event: AccessibilityEvent): void | Called when an accessibility event occurs|
65
66## Processing an Accessibility Event
67
68You 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.
69
70```typescript
71onAccessibilityEvent(accessibilityEvent) {
72    console.log('AccessibilityExtAbility onAccessibilityEvent: ' + JSON.stringify(accessibilityEvent));
73    if (accessibilityEvent.eventType === 'pageStateUpdate') {
74        console.log('AccessibilityExtAbility onAccessibilityEvent: pageStateUpdate');
75        // TODO: Develop custom logic.
76    }
77}
78```
79For 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.
80
81You can also process physical key events in the accessibility extension service. For details, see [onKeyEvent](../reference/apis/js-apis-application-accessibilityExtensionAbility.md#accessibilityextensionabilityonkeyevent).
82
83## Declaring Capabilities of Accessibility Extension Services
84
85After 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.
86
87```json
88"extensionAbilities": [
89  {
90    "name": "AccessibilityExtAbility",
91    "srcEntry": "./ets/AccessibilityExtAbility/AccessibilityExtAbility.ts",
92    "label": "$string:MainAbility_label",
93    "description": "$string:MainAbility_desc",
94    "type": "accessibility",
95    "metadata": [
96      {
97        "name": "ohos.accessibleability",
98        "resource": "$profile:accessibility_config"
99      }
100    ]
101  }
102]
103```
104**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.
105```json
106{
107  "accessibilityCapabilities": [
108    "retrieve",
109    "gesture"
110  ]
111}
112```
113## Enabling a Custom Accessibility Extension Service
114
115To enable or disable an accessibility extension service, run the following command:
116- To enable the service: **accessibility enable -a AccessibilityExtAbility -b com.example.demo -c rg**
117- To disable the service: **accessibility disable -a AccessibilityExtAbility -b com.example.demo**
118
119In 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).
120
121If the service is enabled or disabled successfully, the message "enable ability successfully" or "disable ability successfully" is displayed.
122