一、背景说明

鸿蒙装机量今日正式突破 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)属于敏感能力,部分系统版本要求服务在辅助功能设置中单独授予"手势注入"权限;
  • 服务常驻时长受系统管控,业务逻辑应尽量轻量,重操作转交主进程处理。
六、扩展建议
  1. 朗读增强:结合 Core Speech Kit 的 textToSpeech,把节点文本转为语音播报,覆盖视障用户核心诉求;
  2. 自定义手势指令:利用 GestureType 字符串(如 'threeFingerSingleTap')注册三指手势指令,实现"三指单击回到首页"这类自动化操作;
  3. 批量查询节点:通过 AccessibilityExtensionContext 的 findElementById/findElementByText 按窗口批量查询元素,实现界面自动遍历与可检测:
// 查询当前窗口中指定文本的元素并点击
const elements = await this.context.findElementByText('下一步');
if (elements.length > 0) {
  await elements[0].click();
}
结语

本文用 Accessibility Kit 完成了鸿蒙无障碍扩展服务从配置声明、服务启用、事件监听到节点查询与手势注入的完整实现,核心代码约 150 行,均可直接编译运行。在鸿蒙用户突破 1 亿的节点上,为应用补齐无障碍能力,既是合规要求,也是触达更广用户群的直接路径。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐