@capacitor/screen-reader

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/screen-reader 是 capacitor 生态系统中的插件，用于检测屏幕阅读器状态并提供简单的文本转语音功能，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台，本文档主要说明在 OpenHarmony 系统中的使用。

该插件可检测当前系统屏幕阅读器是否启用，并提供文本朗读功能，帮助开发者为视力障碍用户提供更好的无障碍体验，常用于无障碍访问场景。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/screen-reader

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/screen-reader

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
    "pkg": "@capacitor/screen-reader",
    "classpath": "ScreenReader"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(ScreenReader)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  ScreenReader
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中 src/main/cpp/ScreenReader 目录下的 ScreenReader.h、ScreenReader.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/ScreenReader 目录下。

将源码中 src/main/ets/components/ScreenReader 目录下的 ScreenReader.ets 文件引入到 capacitor 模块中 src/main/ets/components/ScreenReader 目录下。

4. 添加 ArkTS 配置

在 capacitor 模块的 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

"buildOption": {
  // ...
  "arkOptions": {
    "runtimeOnly": [
      // ...
      "./src/main/ets/components/ScreenReader/ScreenReader.ets"
      // ...
    ]
  }
}

卸载

# 卸载 screen-reader 插件
hionic plugin remove @capacitor/screen-reader

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

不涉及特殊权限。

使用示例

示例 1：检测屏幕阅读器是否启用

import { ScreenReader } from '@capacitor/screen-reader';

// 检测屏幕阅读器是否启用
const checkScreenReaderEnabled = async () => {
  try {
    const { value } = await ScreenReader.isEnabled();
    console.log('屏幕阅读器已启用？' + value);
    return value;
  } catch (error) {
    console.error('检测屏幕阅读器状态失败：', error);
  }
};

示例 2：使用文本朗读功能

import { ScreenReader } from '@capacitor/screen-reader';

// 朗读指定文本
const sayHello = async () => {
  try {
    await ScreenReader.speak({ 
      value: '这是一段测试文本！' 
    });
    console.log('文本朗读已执行');
  } catch (error) {
    console.error('文本朗读失败：', error);
  }
};

// 使用特定语言朗读
const speakInLanguage = async () => {
  try {
    await ScreenReader.speak({ 
      value: 'Hello World!',
      language: 'en-US'
    });
    console.log('英文朗读已执行');
  } catch (error) {
    console.error('文本朗读失败：', error);
  }
};

示例 3：监听屏幕阅读器状态变化

import { ScreenReader } from '@capacitor/screen-reader';

let listenerHandle = null;

// 添加屏幕阅读器状态变化监听器
const addScreenStateListener = async () => {
  try {
    listenerHandle = await ScreenReader.addListener('stateChange', ({ value }) => {
      console.log(`屏幕阅读器状态现在是 ${value ? '开启' : '关闭'}`);
    });
    console.log('屏幕阅读器状态监听器已添加');
  } catch (error) {
    console.error('添加监听器失败：', error);
  }
};

// 移除所有监听器
const removeAllListeners = async () => {
  try {
    await ScreenReader.removeAllListeners();
    console.log('所有监听器已移除');
  } catch (error) {
    console.error('移除监听器失败：', error);
  }
};

使用说明

ScreenReader 是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效。

接口方法

| 方法名 | 调用方式 | 入参类型 | 功能描述 | |----------------------|----------------------------------------------------|--------------------------------|---------------------------| | isEnabled() | ScreenReader.isEnabled() | 无入参 | 检测当前是否激活了屏幕阅读器，API 18 后支持 | | speak() | ScreenReader.speak(options) | SpeakOptions | 文本转语音功能 | | removeAllListeners() | ScreenReader.removeAllListeners() | 无入参 | 移除附加到此插件的所有监听器，API 18 后支持 |

事件监听

插件支持 标准事件监听 / 移除监听 能力

| 事件名称 | 事件标识 | 回调参数 | 触发时机 | |-----------|-------------|---------------------------------------------|---------------------| | 屏幕阅读器状态变化 | stateChange | StateChangeListener | 当屏幕阅读器状态改变时，立即触发该事件 |

数据结构

SpeakOptions

调用 speak 方法时的入参对象

| 参数 | 类型 | 描述 | 必填 | |------------|----------|-----------------------------------------------|----| | value | string | 要朗读的文本 | 是 | | language | string | 朗读文本的语言，OpenHarmony 仅支持中文（'zh-CN'）和英文（'en-US'） | 否 |

StateChangeListener

addListener 方法中 stateChange 事件的回调函数类型

| 参数 | 类型 | 描述 | |---------|------------------------------------------|-----------| | state | ScreenReaderState | 屏幕阅读器状态对象 |

ScreenReaderState

屏幕阅读器状态对象

| 参数 | 类型 | 描述 | |---------|-----------|-----------------| | value | boolean | 屏幕阅读器当前是否处于活动状态 |

常见问题

Q: isEnabled 方法始终返回 false？

• 原因：设备未开启屏幕阅读器服务或者 API 版本不支持。
• 解决方案：在 OpenHarmony 系统设置内开启屏幕阅读器。

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- ScreenReader   # 插件核心 C++ 实现
|                             |---- ScreenReader.cpp
|                             |---- ScreenReader.h
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- ScreenReader   # ArkTS 组件实现
|                                   |---- ScreenReader.ets
|     |---- README.md                # 说明文档
|     |---- package.json             # npm 配置文件
|     |---- plugin.xml               # capacitor 插件配置
|     |---- LICENSE                  # 许可证文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。