• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# AccessibilityExtensionAbility开发指南
2
3AccessibilityExtensionAbility基于ExtensionAbility框架，提供无障碍扩展服务，开发者可以基于AccessibilityExtensionAbility模板开发自己的辅助功能应用，协助用户完成一些快捷的交互过程。
4
5> **环境要求**
6>
7> IDE: DevEco Studio 3.0 Beta3 (3.0.0.900)及以后版本
8>
9> SDK: API Version 9 及以后版本
10>
11> Model: Stage
12
13本文档将从以下场景来介绍AccessibilityExtensionAbility的基本开发：
14
15- [如何创建一个无障碍扩展服务](#如何创建一个无障碍扩展服务)
16- [如何处理一个无障碍事件](#如何处理一个无障碍事件)
17- [如何声明无障碍扩展服务具备的能力](#如何声明无障碍扩展服务具备的能力)
18- [如何开启自定义的无障碍扩展服务](#如何开启自定义的无障碍扩展服务)
19- [相关示例](#相关示例)
20
21## 如何创建一个无障碍扩展服务
22
23开发者在创建一个无障碍扩展服务时，如工程满足环境要求，开发者可自主选择是否跳过创建工程步骤，在已有工程中新增无障碍扩展服务。
24
25### 创建工程
26
27如需新增独立的无障碍扩展服务应用，可按以下步骤进行。在DevEco Studio中新建一个工程，具体步骤如下：
281. 在DevEco Studio的左上角标签栏，选择`File -> New -> Create Project`新建一个工程；
292. 根据工程创建向导，选择`OpenHarmony`标签页，选择`Empty Ability`模板，点击Next，进入项目详细配置页；
303. 选择项目类型为Application，Compile API（高版本为Compile SDK）为9，Model为`Stage`，然后点击Finish完成工程创建。
31
32### 新建AccessibilityExtAbility文件
33
34在已创建工程的ets文件夹下创建AccessibilityExtAbility文件夹，在该文件夹下创建AccessibilityExtAbility.ts文件，在新增的文件中加入以下代码：
35
36```typescript
37import AccessibilityExtensionAbility from '@ohos.application.AccessibilityExtensionAbility';
38
39class AccessibilityExtAbility extends AccessibilityExtensionAbility {
40    onConnect() {
41        console.info('AccessibilityExtAbility onConnect');
42    }
43
44    onDisconnect() {
45        console.info('AccessibilityExtAbility onDisconnect');
46    }
47
48    onAccessibilityEvent(accessibilityEvent) {
49        console.info('AccessibilityExtAbility onAccessibilityEvent: ' + JSON.stringify(accessibilityEvent));
50    }
51}
52
53export default AccessibilityExtAbility;
54```
55
56其中，主要定义了以下接口：
57
58| 接口 | 描述 |
59| ---- | ---- |
60| onConnect(): void | 当扩展服务连接时回调 |
61| onDisconnect(): void | 当扩展服务断开时回调 |
62| onAccessibilityEvent(event: AccessibilityEvent): void | 当无障碍事件发生时回调 |
63
64## 如何处理一个无障碍事件
65
66相关无障碍事件可以在`onAccessibilityEvent()`方法中进行业务逻辑处理，具体事件可参考[AccessibilityEvent](../reference/apis/js-apis-application-accessibilityExtensionAbility.md#accessibilityevent)。此处以事件`pageStateUpdate`为例：
67
68```typescript
69onAccessibilityEvent(accessibilityEvent) {
70    console.info('AccessibilityExtAbility onAccessibilityEvent: ' + JSON.stringify(accessibilityEvent));
71    if (accessibilityEvent.eventType === 'pageStateUpdate') {
72        console.info('AccessibilityExtAbility onAccessibilityEvent: pageStateUpdate');
73        // TODO: 自定义相关逻辑开发
74    }
75}
76```
77在相应的无障碍事件中，可以使用[辅助功能扩展上下文（AccessibilityExtensionContext）](../reference/apis/js-apis-inner-application-accessibilityExtensionContext.md)提供的接口进行扩展开发，包括允许配置辅助应用关注信息类型、查询节点信息、手势注入等。
78
79此外，还可在无障碍扩展服务中对物理按键事件进行处理，具体可参考[onKeyEvent](../reference/apis/js-apis-application-accessibilityExtensionAbility.md#accessibilityextensionabilityonkeyevent)。
80
81## 如何声明无障碍扩展服务具备的能力
82
83在完成自定义无障碍扩展服务的逻辑开发后，还需要在工程中Module对应的module.json5文件中加入新增扩展服务的配置信息，其中`srcEntry`标签为`extensionAbility`对应的路径。需要注意的一点是配置信息中的type标签要按照与无障碍子系统的约定进行配置，固定为`accessibility`，否则将无法正常连接。
84
85```json
86"extensionAbilities": [
87  {
88    "name": "AccessibilityExtAbility",
89    "srcEntry": "./ets/AccessibilityExtAbility/AccessibilityExtAbility.ts",
90    "label": "$string:MainAbility_label",
91    "description": "$string:MainAbility_desc",
92    "type": "accessibility",
93    "metadata": [
94      {
95        "name": "ohos.accessibleability",
96        "resource": "$profile:accessibility_config"
97      }
98    ]
99  }
100]
101```
102另外，配置信息中的`accessibility_config`为无障碍扩展服务的具体配置，需要在`resources/base/profile/`下新建`accessibility_config.json`文件，在该文件中声明此无障碍扩展服务具备的[能力类型](../reference/apis/js-apis-accessibility.md#capability):
103```json
104{
105  "accessibilityCapabilities": [
106    "retrieve",
107    "gesture"
108  ]
109}
110```
111## 如何开启自定义的无障碍扩展服务
112
113目前设置中尚未开放无障碍扩展服务开启关闭功能，需要使用命令行进行开启关闭。
114- 开启命令：`accessibility enable -a AccessibilityExtAbility -b com.example.demo -c rg`
115- 关闭命令：`accessibility disable -a AccessibilityExtAbility -b com.example.demo`
116
117其中，`AccessibilityExtAbility`为自定义的无障碍扩展服务名，`com.example.demo`为bundleName，`rg`为无障碍扩展服务具体的类型（其中，r为`retrieve`的首字母，其余同理）。
118
119若开启或关闭成功，则会打印`enable ability successfully`或`disable ability successfully`。
120
121## 相关示例
122
123针对AccessibilityExtensionAbility开发，有以下相关示例可供参考：
124
125[AccessibilityExtAbility的创建和使用（ArkTS）（API 9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/SystemFeature/ApplicationModels/AccessibilityExtAbility)
126
127