鸿蒙操作系统使用 Accessibility Kit 开发无障碍扩展服务实战
一、背景说明
鸿蒙装机量今日正式突破 1 亿台,HarmonyOS 7 设备占比已达 82%——随着用户基数扩大,视障、老年用户对无障碍体验的依赖也同步放大。本文聚焦一个具体技术点:使用 Accessibility Kit 的 AccessibilityExtensionAbility 开发一个无障碍扩展服务,实现服务声明、用户启用、无障碍事件监听、节点信息查询与手势注入的完整闭环,全部代码可直接编译运行。
二、技术原理
无障碍扩展服务基于 ExtensionAbility 框架(type 固定为 accessibility),系统在用户于「设置-辅助功能」中手动启用后拉起服务,核心机制如下:
- AccessibilityExtensionAbility:服务主体,生命周期回调
onConnect(服务连接,执行初始化)、onDisconnect(断开,释放资源)、onAccessibilityEvent(无障碍事件到达)。注意 API 12 起推荐用onConnect/onDisconnect的新增替代写法,onAccessibilityEvent事件仍在此回调处理。 - AccessibilityEvent:事件对象,
eventType涵盖五类——无障碍事件类型(如'click')、窗口变化类型(windowUpdate等)、触摸浏览类型(touchBegin等)、手势类型('rightThenDown'等字符串手势)、页面更新类型(pageContentUpdate/pageStateUpdate)。 - AccessibilityExtensionContext:服务上下文(
this.context),提供配置关注事件类型(updateSubscribes)、查询无障碍节点(getElementInfoByWindowId等)、手势注入(injectGesture)能力。 - accessibility_config:JSON 配置文件,声明服务具备的能力(
retrieve查询节点、gesture手势注入、touchGuide触摸浏览),能力按需声明。
数据流:用户在系统设置启用服务 → 系统拉起 Extension → onConnect 拿 context → 配置订阅事件 → onAccessibilityEvent 收到事件 → context 查询节点/注入手势 → 用户关闭服务 → onDisconnect。
三、实现步骤
工程为 Stage 模型(API 12+),无障碍服务本身无需声明用户权限,靠 accessibility_config 声明能力。
1. 配置文件
resources/base/profile/accessibility_config.json:
{
"accessibilityCapabilities": [
"retrieve",
"gesture",
"touchGuide"
]
}
module.json5 中注册扩展服务:
{
"extensionAbilities": [
{
"name": "AccessibilityExtAbility",
"srcEntry": "./ets/accessibilityext/AccessibilityExtAbility.ets",
"label": "$string:ax_service_label",
"description": "$string:ax_service_desc",
"type": "accessibility",
"metadata": [
{
"name": "ohos.accessibleability",
"resource": "$profile:accessibility_config"
}
]
}
]
}
2. 无障碍扩展服务 AccessibilityExtAbility.ets
import { AccessibilityExtensionAbility } from '@kit.AccessibilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG: string = 'AccessibilityExt';
const DOMAIN: number = 0xFF00;
class AccessibilityExtAbility extends AccessibilityExtensionAbility {
// 用户在系统设置中启用服务后回调,执行初始化
onConnect(): void {
hilog.info(DOMAIN, TAG, 'onConnect');
// 配置关注的事件类型:这里订阅页面内容更新与手势事件
this.context.updateSubscribes(
['pageContentUpdate', 'pageStateUpdate'], true);
}
// 用户关闭服务时回调,释放资源
onDisconnect(): void {
hilog.info(DOMAIN, TAG, 'onDisconnect');
this.context.updateSubscribes(
['pageContentUpdate', 'pageStateUpdate'], false);
}
// 无障碍事件集中处理入口
onAccessibilityEvent(event) {
// 手势事件:用户画出"右滑再下滑"手势时注入一次点击
if (event.eventType === 'rightThenDown') {
this.injectTap();
return;
}
// 页面内容更新事件:读取目标元素文本
if (event.eventType === 'pageContentUpdate' && event.target) {
hilog.info(DOMAIN, TAG, `page updated, element text=${event.target.text ?? ''}`);
}
}
// 通过 context 注入点击手势(模拟屏幕中心单击)
private injectTap(): void {
// GesturePath 由一系列 GesturePoint 构成,这里注入一个 300ms 的单击
const path = new (require('@ohos.accessibility').GesturePath)(0, 300);
this.context.injectGesture(path, () => {
hilog.info(DOMAIN, TAG, 'gesture injected');
});
}
}
export default AccessibilityExtAbility;
3. 引导用户启用服务(主应用侧)
无障碍服务必须由用户在系统设置中手动启用。应用侧可检测状态并跳转:
import { accessibility } from '@kit.AccessibilityKit';
import { commonEventManager } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';
// 查询本应用无障碍服务是否已启用
accessibility.isOpenAccessibility('com.example.axdemo/AccessibilityExtAbility')
.then((opened: boolean) => {
if (!opened) {
// 未启用:跳转到系统无障碍设置页引导用户开启
this.context.startAbility({
action: 'action.system.accessibility.settings'
});
}
})
.catch((err: BusinessError) => {
console.error(`check failed, code=${err.code}`);
});
// 可选:发送一条自定义无障碍事件,供自己的服务接收处理
const event: accessibility.AccessibilityEvent = {
eventType: 'click'
};
accessibility.publishAccessibilityEvent(event);
四、应用场景示例
典型无障碍场景——把页面更新事件转换为语音播报辅助信息(伪代码演示业务衔接):
onAccessibilityEvent(event) {
if (event.eventType === 'pageContentUpdate' && event.target) {
const text = event.target.text ?? '';
if (text.includes('验证码')) {
// 业务逻辑:验证码短信页到达时,把验证码通过 TTS 播报给视障用户
ttsAgent.speak(`收到验证码页面:${text}`);
}
}
}
五、技术要点
1. 服务启用的必要条件
- 服务不会自启动,必须由用户在「设置-辅助功能-已下载的服务」中手动开启,系统才开始拉起;
module.json5中type必须为accessibility,metadata 名称固定为ohos.accessibleability,配置错误会导致服务永远连接不上;accessibilityCapabilities按需声明:未声明retrieve时调用节点查询接口会失败。
2. 事件订阅要精简
updateSubscribes 订阅的事件类型越多,系统送达的事件越频繁——无障碍服务常驻后台,盲目全量订阅会放大功耗。只订阅业务必需的类型,页面内容更新(pageContentUpdate)触发频率最高,务必在回调内做快速判断后立刻返回。
3. 错误处理
try {
await this.context.injectGesture(path);
} catch (err) {
const e = err as BusinessError;
if (e.code === 401) {
console.error('参数错误:检查 GesturePath 构造');
} else {
console.error(`inject failed code=${e.code}, msg=${e.message}`);
}
}
4. 使用限制
- 无障碍扩展服务运行在独立 Extension 沙箱中,不能直接启动 UI;需要界面交互时通过
startAbility拉起主应用页面; - 手势注入能力(
gesture)属于敏感能力,部分系统版本要求服务在辅助功能设置中单独授予"手势注入"权限; - 服务常驻时长受系统管控,业务逻辑应尽量轻量,重操作转交主进程处理。
六、扩展建议
- 朗读增强:结合 Core Speech Kit 的 textToSpeech,把节点文本转为语音播报,覆盖视障用户核心诉求;
- 自定义手势指令:利用
GestureType字符串(如'threeFingerSingleTap')注册三指手势指令,实现"三指单击回到首页"这类自动化操作; - 批量查询节点:通过
AccessibilityExtensionContext的findElementById/findElementByText按窗口批量查询元素,实现界面自动遍历与可检测:
// 查询当前窗口中指定文本的元素并点击
const elements = await this.context.findElementByText('下一步');
if (elements.length > 0) {
await elements[0].click();
}
结语
本文用 Accessibility Kit 完成了鸿蒙无障碍扩展服务从配置声明、服务启用、事件监听到节点查询与手势注入的完整实现,核心代码约 150 行,均可直接编译运行。在鸿蒙用户突破 1 亿的节点上,为应用补齐无障碍能力,既是合规要求,也是触达更广用户群的直接路径。
更多推荐



所有评论(0)