harmony 鸿蒙AccessibilityExtensionAbility

2023-06-24
浏览 (365)

AccessibilityExtensionAbility

The 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.

Environment Requirements

IDE: DevEco Studio 3.0 Beta3 (3.0.0.900) or later

SDK: API version 9 or later

Model: stage

AccessibilityExtensionAbility Overview

Accessibility 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.

AccessibilityExtensionAbility 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.

Below shows the AccessibilityExtensionAbility framework.

AccessibilityFramework

Accessibility application: extension service application developed based on the AccessibilityExtensionAbility framework, for example, a screen reader application.
Target application: application assisted by the accessibility application.
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.
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.
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.

Creating an Accessibility Extension Service

You 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.

Creating a Project

Perform the following steps in DevEco Studio: 1. From the upper left corner of DevEco Studio, choose File > New > Create Project. 2. By following the project creation wizard, click the OpenHarmony tab, select the Empty Ability template, and then click Next. 3. 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.

Creating an AccessibilityExtAbility File

To 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:

import AccessibilityExtensionAbility, { AccessibilityEvent } from '@ohos.application.AccessibilityExtensionAbility';

class AccessibilityExtAbility extends AccessibilityExtensionAbility {
    onConnect() {
        console.info('AccessibilityExtAbility onConnect');
    }

    onDisconnect() {
        console.info('AccessibilityExtAbility onDisconnect');
    }

    onAccessibilityEvent(accessibilityEvent: AccessibilityEvent) {
        console.info('AccessibilityExtAbility onAccessibilityEvent: ' + JSON.stringify(accessibilityEvent));
    }
}

export default AccessibilityExtAbility;

The APIs defined in the file are as follows.

API	Description
onConnect(): void	Called when a connection with the extension service is set up.
onDisconnect(): void	Called when the connection with the extension service is severed.
onAccessibilityEvent(event: AccessibilityEvent): void	Called when an accessibility event occurs

Processing an Accessibility Event

You can process the service logic for accessibility events in the onAccessibilityEvent() API. For details about the events, see AccessibilityEvent. The following code snippet uses the pageStateUpdate event as an example.

onAccessibilityEvent(accessibilityEvent: AccessibilityEvent) {
    console.info('AccessibilityExtAbility onAccessibilityEvent: ' + JSON.stringify(accessibilityEvent));
    if (accessibilityEvent.eventType === 'pageStateUpdate') {
        console.info('AccessibilityExtAbility onAccessibilityEvent: pageStateUpdate');
        // TODO: Develop custom logic.
    }
}

For an accessibility event, you can use the APIs of the AccessibilityExtensionContext module to configure the concerned information, obtain root information, and inject gestures.

You can also process physical key events in the accessibility extension service. For details, see onKeyEvent.

Declaring Capabilities of Accessibility Extension Services

After 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.

"extensionAbilities": [
  {
    "name": "AccessibilityExtAbility",
    "srcEntry": "./ets/AccessibilityExtAbility/AccessibilityExtAbility.ts",
    "label": "$string:MainAbility_label",
    "description": "$string:MainAbility_desc",
    "type": "accessibility",
    "metadata": [
      {
        "name": "ohos.accessibleability",
        "resource": "$profile:accessibility_config"
      }
    ]
  }
]

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 of the service in the file.

{
  "accessibilityCapabilities": [
    "retrieve",
    "gesture"
  ]
}

Enabling or Disabling a Custom Accessibility Extension Service

You can enable or disable a custom accessibility extension service through the command line interface or the device settings.

Method 1: through the command line interface

Run the hdc shell command, then the following system command:

To enable the service: accessibility enable -a AccessibilityExtAbility -b com.example.demo -c rg
To disable the service: accessibility disable -a AccessibilityExtAbility -b com.example.demo

In 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).

If the service is enabled or disabled successfully, the message “enable ability successfully” or “disable ability successfully” is displayed.

Method 2: through the device settings - From the device settings screen, access the list of installed extended services under accessibility. If an extended service is not installed, it is grayed out, and “No service” is displayed. - Select the target extended service, and toggle on or off the switch to enable or disable it. - 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.