{"_id":"@capacitor-ohos/screen-reader","_rev":"2-dbf89a55e62ad276b64da8c725643dd9","name":"@capacitor-ohos/screen-reader","dist-tags":{"latest":"8.0.2"},"versions":{"8.0.1":{"name":"@capacitor-ohos/screen-reader","version":"8.0.1","keywords":["capacitor","plugin","native"],"author":{"url":"Group","name":"Huawei Device Co., Ltd and iSoftStone Information Technology"},"license":"MIT","_id":"@capacitor-ohos/screen-reader@8.0.1","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-screen-reader/issues"},"dist":{"shasum":"b5c2dfbfec39a906de253ccb9760ff258fa84f7d","tarball":"https://registry.npmjs.org/@capacitor-ohos/screen-reader/-/screen-reader-8.0.1.tgz","fileCount":10,"integrity":"sha512-iS9BZw7lWZPDgnq8Zn/qdVgz0AHgHmfe62PdtGMTEAfVZkymVVcVjXXUtJgBSQzCourwIlba16Vcxf0PXWRvhg==","signatures":[{"sig":"MEYCIQCceVrc8cTcL9EM1GPkSWhmrtm/FJWZ7s0RLPlOuzc91AIhAIMjUVKbdGct8YIeNC862KhmTMdvdDkMbEPdHZ1drsj2","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45710},"gitHead":"75cc7a86e896ad1c7a30513c5a7dcf7f8c31504f","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"capacitor":{"id":"@capacitor/screen-reader","platforms":["openharmony"]},"repository":{"url":"gitcode:CPF-Ionic/capacitor-screen-reader","type":"git"},"_npmVersion":"10.5.1","description":"The Screen Reader API provides simple text-to-speech capabilities for visual.","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/screen-reader_8.0.1_1777544204772_0.3650318646774813","host":"s3://npm-registry-packages-npm-production"}},"8.0.2":{"name":"@capacitor-ohos/screen-reader","version":"8.0.2","description":"The Screen Reader API provides simple text-to-speech capabilities for visual.","capacitor":{"id":"@capacitor/screen-reader","platforms":["openharmony"]},"repository":{"type":"git","url":"gitcode:CPF-Ionic/capacitor-screen-reader"},"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-screen-reader/issues"},"keywords":["capacitor","plugin","native"],"author":{"name":"Huawei Device Co., Ltd and iSoftStone Information Technology","url":"Group"},"license":"MIT","_id":"@capacitor-ohos/screen-reader@8.0.2","gitHead":"1b91970ea95103f1dffb3b23c9dffad0535f631f","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-5kkRYiswUliT7qvWOgomzOFZ9MPFowQaRV2aygqhOzxr0FH6sD/1ZjJku3tWm/oT6SCa5l8UngXjqxxkeBE+6Q==","shasum":"d3110f15bf5f201d7df029781ad3bb7b44b998cb","tarball":"https://registry.npmjs.org/@capacitor-ohos/screen-reader/-/screen-reader-8.0.2.tgz","fileCount":10,"unpackedSize":46885,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDcwPHl8Qm/zx30G8qsIh/EYgolyjKWN4iCtYZcE5E6bAIhAK/BEaId1vLVTEzZDJbS+JjmBcyeaP+PWNqjCRe2vdSv"}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/screen-reader_8.0.2_1784794124014_0.21688042944212338"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-30T10:16:44.703Z","modified":"2026-07-23T08:08:44.310Z","8.0.1":"2026-04-30T10:16:44.919Z","8.0.2":"2026-07-23T08:08:44.151Z"},"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-screen-reader/issues"},"author":{"name":"Huawei Device Co., Ltd and iSoftStone Information Technology","url":"Group"},"license":"MIT","keywords":["capacitor","plugin","native"],"repository":{"type":"git","url":"gitcode:CPF-Ionic/capacitor-screen-reader"},"description":"The Screen Reader API provides simple text-to-speech capabilities for visual.","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"readme":"# <center>@capacitor/screen-reader</center>\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [@capacitor/screen-reader@8.0.0](https://www.npmjs.com/package/@capacitor/screen-reader) 开发。\r\n\r\n## 简介\r\n\r\n`@capacitor/screen-reader` 是 capacitor 生态系统中的插件，用于检测屏幕阅读器状态并提供简单的文本转语音功能，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台，本文档主要说明在 OpenHarmony 系统中的使用。\r\n\r\n该插件可检测当前系统屏幕阅读器是否启用，并提供文本朗读功能，帮助开发者为视力障碍用户提供更好的无障碍体验，常用于无障碍访问场景。\r\n\r\n## 支持平台\r\n\r\n- **OpenHarmony**：5.0+\r\n\r\n## 下载安装\r\n\r\n通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。\r\n\r\n### 命令行安装（推荐）\r\n\r\n安装hionic CLI：\r\n\r\n```bash\r\nnpm install -g hionic\r\n```\r\n\r\n以下两种方式中**任选其一**即可，无需重复操作：\r\n\r\nnpm安装：\r\n\r\n```bash\r\n# 安装插件\r\nnpm install @capacitor/screen-reader\r\n\r\n# 同步插件\r\nhionic sync openharmony\r\n```\r\n\r\nhionic CLI安装：\r\n\r\n```bash\r\nhionic plugin add @capacitor/screen-reader\r\n```\r\n\r\n### 手动引入安装\r\n\r\n根据插件源码中 `plugin.xml` 配置在项目中引入插件：\r\n\r\n#### 1. 添加插件配置\r\n\r\n根据 `plugin.xml` 的 `config-json` 项，通过 `target` 字段找到 `entry` 模块中 `capacitor.plugins.json` 文件，并根据 `param` 标签添加配置如下：\r\n\r\n```json\r\n{\r\n    \"pkg\": \"@capacitor/screen-reader\",\r\n    \"classpath\": \"ScreenReader\"\r\n}\r\n```\r\n\r\n#### 2. 修改 CMake 配置\r\n\r\n根据 `plugin.xml` 的 `CMakeLists` 项，通过 `modules-name` 字段找到模块 capacitor，路径为 `target` 字段的 `CMakeLists.txt` 文件，并根据 `param` 标签添加 `add_subdirectory` 和 `target_link_libraries` 如下：\r\n\r\n```cmake\r\n#START_ADD_SUBDIRECTORY\r\n// ...\r\nadd_subdirectory(ScreenReader)\r\n// ...\r\n#END_ADD_SUBDIRECTORY\r\n\r\n// ...\r\n\r\ntarget_link_libraries(capacitor PUBLIC\r\n  \"-Wl,--whole-archive\"\r\n  // ...\r\n  ScreenReader\r\n  // ...\r\n  \"-Wl,--no-whole-archive\"\r\n)\r\n```\r\n\r\n#### 3. 复制源码文件\r\n\r\n根据 `plugin.xml` 的 `source-file` 项，根据 `src` 字段找到需要复制的文件，并根据 `modules-name` 字段和 `target-dir` 字段找到文件复制的具体模块和目录：\r\n\r\n将源码中 src/main/cpp/ScreenReader 目录下的 ScreenReader.h、ScreenReader.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/ScreenReader 目录下。\r\n\r\n将源码中 src/main/ets/components/ScreenReader 目录下的 ScreenReader.ets 文件引入到 capacitor 模块中 src/main/ets/components/ScreenReader 目录下。\r\n\r\n#### 4. 添加 ArkTS 配置\r\n\r\n在 capacitor 模块的 `build-profile.json5` 文件中，`buildOption/arkOptions/runtimeOnly/sources` 配置项数组中加入步骤 3 中拷贝的 ets 文件路径：\r\n\r\n```json\r\n\"buildOption\": {\r\n  // ...\r\n  \"arkOptions\": {\r\n    \"runtimeOnly\": [\r\n      // ...\r\n      \"./src/main/ets/components/ScreenReader/ScreenReader.ets\"\r\n      // ...\r\n    ]\r\n  }\r\n}\r\n```\r\n\r\n## 卸载\r\n\r\n```bash\r\n# 卸载 screen-reader 插件\r\nhionic plugin remove @capacitor/screen-reader\r\n```\r\n\r\n## 约束与限制\r\n\r\n### 兼容性\r\n\r\n在以下版本中已测试通过：\r\n\r\n1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;\r\n\r\n### 权限要求\r\n\r\n不涉及特殊权限。\r\n\r\n## 使用示例\r\n\r\n### 示例 1：检测屏幕阅读器是否启用\r\n\r\n```javascript\r\nimport { ScreenReader } from '@capacitor/screen-reader';\r\n\r\n// 检测屏幕阅读器是否启用\r\nconst checkScreenReaderEnabled = async () => {\r\n  try {\r\n    const { value } = await ScreenReader.isEnabled();\r\n    console.log('屏幕阅读器已启用？' + value);\r\n    return value;\r\n  } catch (error) {\r\n    console.error('检测屏幕阅读器状态失败：', error);\r\n  }\r\n};\r\n```\r\n\r\n### 示例 2：使用文本朗读功能\r\n\r\n```javascript\r\nimport { ScreenReader } from '@capacitor/screen-reader';\r\n\r\n// 朗读指定文本\r\nconst sayHello = async () => {\r\n  try {\r\n    await ScreenReader.speak({ \r\n      value: '这是一段测试文本！' \r\n    });\r\n    console.log('文本朗读已执行');\r\n  } catch (error) {\r\n    console.error('文本朗读失败：', error);\r\n  }\r\n};\r\n\r\n// 使用特定语言朗读\r\nconst speakInLanguage = async () => {\r\n  try {\r\n    await ScreenReader.speak({ \r\n      value: 'Hello World!',\r\n      language: 'en-US'\r\n    });\r\n    console.log('英文朗读已执行');\r\n  } catch (error) {\r\n    console.error('文本朗读失败：', error);\r\n  }\r\n};\r\n```\r\n\r\n### 示例 3：监听屏幕阅读器状态变化\r\n\r\n```javascript\r\nimport { ScreenReader } from '@capacitor/screen-reader';\r\n\r\nlet listenerHandle = null;\r\n\r\n// 添加屏幕阅读器状态变化监听器\r\nconst addScreenStateListener = async () => {\r\n  try {\r\n    listenerHandle = await ScreenReader.addListener('stateChange', ({ value }) => {\r\n      console.log(`屏幕阅读器状态现在是 ${value ? '开启' : '关闭'}`);\r\n    });\r\n    console.log('屏幕阅读器状态监听器已添加');\r\n  } catch (error) {\r\n    console.error('添加监听器失败：', error);\r\n  }\r\n};\r\n\r\n// 移除所有监听器\r\nconst removeAllListeners = async () => {\r\n  try {\r\n    await ScreenReader.removeAllListeners();\r\n    console.log('所有监听器已移除');\r\n  } catch (error) {\r\n    console.error('移除监听器失败：', error);\r\n  }\r\n};\r\n```\r\n\r\n## 使用说明\r\n\r\n`ScreenReader` 是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效。\r\n\r\n### 接口方法\r\n\r\n| 方法名 | 调用方式 | 入参类型 | 返回类型 | 功能描述 |\r\n|----------------------|----------------------------------------------------|--------------------------------|--------------------------|---------------------------|\r\n| isEnabled()          |  ScreenReader.isEnabled()                          |  无入参                           | Promise&lt;[ScreenReaderState](#screenreaderstate)&gt; |  检测当前是否激活了屏幕阅读器，API 18 后支持  |\r\n| speak(options)           |  ScreenReader.speak(options)                  |  [SpeakOptions](#speakoptions) | Promise&lt;void&gt;  |  文本转语音功能                  |\r\n| addListener(eventName, listener) | ScreenReader.addListener(eventName, listener) | eventName: 'stateChange', listener: [StateChangeListener](#statechangelistener) | Promise&lt;[PluginListenerHandle](#pluginlistenerhandle)&gt; | 添加屏幕阅读器状态变化监听器，API 18 后支持 |\r\n| removeAllListeners() |  ScreenReader.removeAllListeners()                 |  无入参                           | Promise&lt;void&gt;  | 移除附加到此插件的所有监听器，API 18 后支持   |\r\n\r\n### 数据结构\r\n\r\n#### SpeakOptions\r\n\r\n调用 `speak` 方法时的入参对象\r\n\r\n| 参数\t        | 类型       | \t描述                                           | 必填 |\r\n|------------|----------|-----------------------------------------------|----|\r\n| `value`    | \tstring\t | 要朗读的文本                                        | 是  |\r\n| `language` | `string` | 朗读文本的语言，OpenHarmony 仅支持中文（`'zh-CN'`）和英文（`'en-US'`） | 否  |\r\n\r\n#### StateChangeListener\r\n\r\n`addListener` 方法中 `stateChange` 事件的回调函数类型\r\n\r\n| 参数      | 类型                                       |  描述       |\r\n|---------|------------------------------------------|-----------|\r\n| `state` |  [ScreenReaderState](#screenreaderstate) | 屏幕阅读器状态对象 |\r\n\r\n#### PluginListenerHandle\r\n\r\n监听器句柄对象，用于管理监听器生命周期\r\n\r\n| 参数      | 类型        |  描述             |\r\n|---------|-----------|-----------------|\r\n| `remove` | `() => Promise<void>` | 移除监听器的方法 |\r\n\r\n\r\n#### StateChangeListener\r\n\r\n`addListener` 方法中 `stateChange` 事件的回调函数类型\r\n\r\n| 参数\t     | 类型                                       | \t描述       |\r\n|---------|------------------------------------------|-----------|\r\n| `state` | \t[ScreenReaderState](#screenreaderstate) | 屏幕阅读器状态对象 |\r\n\r\n#### ScreenReaderState\r\n\r\n屏幕阅读器状态对象\r\n\r\n| 参数\t     | 类型        | \t描述             |\r\n|---------|-----------|-----------------|\r\n| `value` | \tboolean\t | 屏幕阅读器当前是否处于活动状态 |\r\n\r\n## 常见问题\r\n\r\n**Q: `isEnabled` 方法始终返回 false？**\r\n\r\n* **原因**：设备未开启屏幕阅读器服务或者 API 版本不支持。\r\n* **解决方案**：在 OpenHarmony 系统设置内开启屏幕阅读器。\r\n\r\n## 目录结构\r\n\r\n```\r\n|---- 项目根目录\r\n|     |---- src\r\n|           |---- main\r\n|                 |---- cpp\r\n|                       |---- ScreenReader   # 插件核心 C++ 实现\r\n|                             |---- ScreenReader.cpp\r\n|                             |---- ScreenReader.h\r\n|                             |---- CMakeLists.txt\r\n|                 |---- ets\r\n|                       |---- components\r\n|                             |---- ScreenReader   # ArkTS 组件实现\r\n|                                   |---- ScreenReader.ets\r\n|     |---- README.md                # 说明文档\r\n|     |---- package.json             # npm 配置文件\r\n|     |---- plugin.xml               # capacitor 插件配置\r\n|     |---- LICENSE                  # 许可证文件\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Ionic/capacitor-screen-reader/issues)，当然，也非常欢迎发 [PR](https://gitcode.com/CPF-Ionic/capacitor-screen-reader/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **MIT License** 开源，详见 [LICENSE](./LICENSE) 文件。\r\n","readmeFilename":"README.md"}