React Native 鸿蒙系统 TTS 实战:让表面开口
一条 120 字的播报,怎么在 RN 里切成段、排成队、送进系统离线引擎,再把状态、进度和日志画回一张光感表面?——这篇文章用一个跑在鸿蒙 PC 上的 React Native 0.84 三方库,把系统 TTS 这条链路拆开,也讲清楚三端语义不一致时怎么收口。
仓库地址:https://atomgit.com/oh-react-native/tts-spatial-glass-rn.git
版本地址:https://atomgit.com/oh-react-native/ohos_react_native/tree/0.84-main
三方库框架:https://atomgit.com/oh-react-native
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | <DevEco Studio 安装目录>(HarmonyOS SDK 26.0.0 / API 26) |
| 运行设备 | HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26 |
| React Native | 0.84.1 |
| React | 19.2.3(与 RN 0.84.1 内置 renderer 严格同版) |
| RNOH | @react-native-oh/react-native-harmony 0.84.3;OHPM @rnoh/react-native-openharmony 0.84.3 |
| 语言与构建 | TypeScript 5.9.3、Babel 7、Vitest 3.2.4、Node.js 24.12.0 / npm 11.12.1 |
| 鸿蒙 SDK | 编译/目标 26.0.0(API 26) |
| hvigor | DevEco Studio 自带(HVIGOR_JS 可覆盖) |
| spatial-glass-rn | 1.0.0(本仓库,npm 包 + RNOH HAR) |
| TTS 原生库 | @react-native-ohos/react-native-tts 4.3.1-beta.2(npm dist-tag rnoh0.84) |
| 示例应用 | Spatial Glass(example/harmony,bundle com.lqjmac.spatialglassrn) |
| 系统引擎 | 鸿蒙 Core Speech Kit textToSpeech(离线);Android TextToSpeech;iOS AVSpeechSynthesizer |
1. 给光感表面加上语音播报
这个库的第一版只解决"看":四张透明光斑叠出一张玻璃卡片,菜单贴着锚点翻转,浮层带着边缘收光。视觉上已经完整,但用起来还是静的——用户在仓储、订单、巡检这类场景里连续操作,盯着货架或单据,屏幕上的状态变化未必看得见。
把状态念出来,比再画一层 UI 更直接。问题是用什么念。
云端 TTS 是最容易想到的方案,但算三笔账就不划算:按字符计费、必须联网、文本要离开设备。扫码即播报、订单状态这类事件密集、随时可能发生在弱网仓库里的场景,稳定性和可用性比音色数量重要。系统自带的离线引擎正好反过来:随系统提供、免费、本地合成、文本不出设备。代价也明确:音色少、语言受设备限制、长文本要自己做分段和队列。
于是有了截图里这个页面:光感材质负责视觉呈现,系统 TTS 负责把状态念出来。
真机第一次跑通时,声音是出来的,但页面卡住了:播完了,状态还停在 播报中。查到最后是事件名对不上——上游 react-native-tts 发的是 tts-start / tts-finish,播放器订阅的是 start / finish。声音走的是原生,UI 等的是一个永远不会来的事件。
这个 bug 也暴露了后面的主要工作:TTS 的难点是把三个平台各自不同的语义,收成一套确定的 JS 状态机;speak() 本身只是入口。
具体拆成四件事:
- 长文怎么切(120 字、标点优先、切完还能显示真实进度);
- 段怎么排队(鸿蒙引擎忙时
speak()返回undefined,队列必须放在 JS 侧); - 事件怎么归一(
tts-*↔ 短名、旧事件过滤、每实例订阅); - 状态怎么画回表面(光感卡片承载状态、进度、语速和日志)。
2. 效果展示
先看效果。示例应用叫 Spatial Glass,在鸿蒙 PC 上是一个 2in1 窗口:

页面标题是「让表面开口。」,副标题写着「用系统自带的离线语音引擎朗读,再让光感材质承载状态、进度和操作。没有云端请求,也没有额外的语音包。」下面就是 SpatialVoiceConsole:
- 卡片头部:
SYSTEM TTS / OFFLINE、系统语音合成、离线引擎 · 无需联网 · 免费,右上角状态点写着播报中; - 预览区:
0 / 2 段 · 队列 1,正文是当前正在播的长文; - 三个脚本 chip:
仓储播报、订单状态、长文分段,截图里选中的是「长文分段」; - 操作行:
重新朗读(播报中时主按钮会换文案)、暂停、停止; - 语速档位:
0.75x / 1x / 1.25x / 1.5x,截图里是 1x; - 事件日志(最新在上):
DATA 合成中、START #9e3d9e3a-…、QUEUE 打断并排队 2 段。
这三条日志对应一次播报的完整流程:QUEUE 是 JS 队列收下两段文本,START 是引擎开始念第一段,DATA 是引擎回传的进度事件。等第一段结束,finish 会把 spoken 推到 1,队列里的第二段接着提交;两段都完成后,状态回到 待命,进度变成 2 / 2。
几个截图里看不到、但真机上验证过的行为:
- 播报中点
暂停,状态变成已暂停,暂停按钮变继续;再点继续,当前这条能念到FINISH,不是从头重播; - 播报中点
停止,队列清空、引擎停止、状态回待命; - 长文播报时,
停止最多等当前这一段,而不是等整篇合成完; - 设备日志里能看到
HiAI_OfflineTtsService的onTtsStart/onTtsComplete,以及person: 13、language: zh_CN、online: 1——离线系统引擎,不是云端接口。
卡片的材质来自同系列的 SpatialSurface:光学底片、四张光斑、镜面高光、颗粒层、上下两道边。控制台没有另起一套视觉,只是把状态点、进度、按钮和日志放进这张表面里。语音由系统引擎提供,光感表面负责显示状态;状态点的颜色取自 SPATIAL_THEME。
也要提前说清楚能力边界:鸿蒙当前只有 zh-CN 离线音色,voices() 返回的条目 id/name 是空的,不要做音色选择器;Android 的桥不支持真正的暂停,控制台会直接禁用暂停按钮;音色、语言、离线包最终以设备为准。
3. 系统语音从哪来:三种引擎、一套队列
先看链路。业务侧只面对一个 speak(),下面从 JS 队列一直走到系统引擎:
业务 JS
│ tts.speak(text)
▼
SystemTtsPlayer ← 分段、队列、重试、状态机
│ bridge.speak(chunk)
▼
react-native-tts ← Android / iOS 原生实现
│ (鸿蒙 bundle 按 harmony.alias 重定向)
▼
@react-native-ohos/react-native-tts
│ TurboModule: TTSNativeModule
▼
RNTTSTurboModule(ArkTS)
│
▼
Core Speech Kit textToSpeech.createEngine / speak
│ playType = 0(音频流)
▼
AudioPlayer(AudioRenderer) ← 暂停/继续/停止、缓冲排序
不用云端,逐项对比:
| 维度 | 云端 TTS | 系统级 TTS(本库) |
|---|---|---|
| 费用 | 按字符/调用量计费,或按并发扩容 | 免费,随系统提供 |
| 网络 | 必须联网,弱网抖动直接影响播报 | 离线,本地合成,无请求往返 |
| 延迟 | 一次请求几百毫秒起,且不可控 | 由设备性能决定,稳定可预期 |
| 隐私 | 文本离开设备 | 文本不离开设备 |
| 音色 | 丰富、可定制 | 系统内置音色,选择少 |
| 包体积 | 取决于缓存策略 | 不打包语音模型,零额外体积 |
代价是能力受设备约束,所以播放器必须把三个平台的差异封装掉:
| 平台 | 系统引擎 | 离线 | 暂停/继续 | 音色选择 | 备注 |
|---|---|---|---|---|---|
| HarmonyOS / RNOH | Core Speech Kit textToSpeech | 仅离线 | 支持(库内自建 AudioPlayer) | 固定 zh-CN、默认聆小珊(13 号) | 引擎忙时 speak() 返回 undefined,播放器重试 |
| Android | android.speech.tts.TextToSpeech | 取决于系统引擎 | 不支持(桥层返回 false) | voices() / engines() | 需要设备安装可用的 TTS 引擎 |
| iOS | AVSpeechSynthesizer | 系统语音 | 支持 | voices() | 静音开关行为可配置 |
鸿蒙侧还有三条硬约束,直接决定了 API 的形态:
- 只有离线模式:
CreateEngineParams.online当前只能为1,所以不要给"在线/离线"留开关; - 只有中文离线音色:
language: 'zh-CN',默认person: 13(聆小珊);voices()的 id/name 为空,不要做音色选择器; - 单引擎、单条播报:同设备所有应用合计最多 3 个引擎实例;RN 桥在引擎忙时直接返回
undefined,队列必须放在 JS 侧。
为什么队列必须放在 JS 侧
三个平台对"连续 speak"的语义并不一致:
- 鸿蒙:引擎忙时
speak()返回undefined,这一次请求直接被丢弃; - Android:原生队列可以接受,
QUEUE_ADD/QUEUE_FLUSH自己有一套规则; - iOS:原生队列也能接受,但 flush 的行为又和 Android 不完全一样。
如果直接把 speak() 透传给业务,鸿蒙上连续点两次,第二次会静默丢失;Android 上又会被原生队列缓存,用户点"停止"时清不干净。播放器因此在 JS 侧维护唯一队列:
speak()先按 120 字分段;- 默认
interrupt: true:清空旧队列、停掉当前播报,再排新段; pump()一次只提交一段,收到finish再提交下一段;- 停止时清空队列,最多等当前一段的合成时间。
这样"已播 / 总段数"、打断、停止、追加都变成确定行为,三个平台共享同一套交互语义。
事件状态机
播放器只处理七个短事件名,桥负责把上游的 tts-* 映射过来:
| 事件 | 处理 |
|---|---|
start | status = 'speaking',记录 START |
progress | 记录 DATA(鸿蒙只带 utteranceId,不带 location/length) |
finish | spoken += 1,提交下一段;队列空则 idle |
cancel | 清理活跃分段,提交下一段 |
error | status = 'error',清空队列,保留 lastError |
pause | status = 'paused' |
resume | status = 'speaking' |
事件按 utteranceId 匹配活跃分段;不匹配的旧事件(例如打断后上一条的 finish)会被忽略。没有这个过滤,快速连点两次会出现"第二段还没开始,第一段的 finish 就把进度推了一格"的错位。
4. 工程怎么搭:一个 npm 包、一个只做 autolinking 的 HAR、一个第三方 TTS 包
先看整体结构。这个库由四层组成:npm 库 + 只做 autolinking 的 HAR + 示例宿主 + 第三方 TTS 原生包,每层解决不同的问题:
spatial-glass-rn/ # npm 库根目录(package.json,v1.0.0)
├─ src/ # 纯 TS/TSX
│ ├─ SpatialSurface.tsx # 四张光斑 + 颗粒 + 边缘收光
│ ├─ SpatialOverlay.tsx # Modal、定位、入场/退场、返回键
│ ├─ SpatialMenu.tsx # 菜单内容与无障碍语义
│ ├─ SpatialPopover.tsx # 任意内容浮层
│ ├─ SpatialVoiceConsole.tsx # 系统 TTS 控制台(光感材质)
│ ├─ tts/
│ │ ├─ bridge.ts # react-native-tts → 小接口
│ │ ├─ player.ts # 分段队列、重试、事件状态机
│ │ ├─ useSystemTts.ts # React hook
│ │ ├─ text.ts # 分段、语速/音调夹取、时间格式
│ │ └─ types.ts # 对外类型
│ ├─ geometry.ts / theme.ts / measureSpatialAnchor.ts / useReducedMotion.ts
│ ├─ assets/ # halo.png / grain.png
│ └─ index.ts
├─ lib/ # Babel CJS/ESM + tsc 声明(构建产物)
├─ harmony/
│ ├─ rn_spatial_glass.har # npm 分发的 HAR
│ └─ rn_spatial_glass/
│ ├─ Index.ets # export SpatialGlassPackage
│ ├─ oh-package.json5 # @rnoh/spatial-glass-rn
│ └─ src/main/ets/SpatialGlassPackage.ets
├─ example/
│ ├─ App.tsx # 光感菜单 + 语音播报示例
│ └─ harmony/ # ★ DevEco 打开这个目录运行
│ └─ entry/ # HAP + EntryAbility + RNApp
├─ docs/
│ ├─ material-path.md # 材质路径
│ ├─ system-tts.md # 系统 TTS 设计、平台差异、鸿蒙接入
│ ├─ package-check.md # npm 包校验
│ └─ verification.md # 构建与验证记录
├─ __tests__/ # Vitest(geometry / theme / tts-text / tts-player)
├─ scripts/ # build-harmony.sh / verify-package.cjs / clean.mjs
├─ artifacts/ # npm 压缩包与构建日志(不进包)
├─ babel.config.cjs
├─ tsconfig.json / tsconfig.types.json / tsconfig.example.json
├─ index.d.ts / react-native.config.js
└─ README*.md / VALIDATION.md

四层的分工要拎清,不然很容易在 DevEco 里打开错地方:
src/是纯 JS/TS,光感材质、菜单、浮层、TTS 播放器都在这里;harmony/rn_spatial_glass.har是 RNOH autolinking 用的 HAR,但里面的SpatialGlassPackage不提供任何 TurboModule——光感 UI 全部由 RN 的核心视图合成;example/harmony/才是带entry的示例宿主,DevEco 打开它才能跑;- 系统 TTS 的原生能力由宿主链接的
rn_tts.har提供(来自@react-native-ohos/react-native-tts)。
package.json 同时声明 npm 入口、TTS 原生依赖和 RNOH autolinking 元数据(节选):
{
"name": "spatial-glass-rn",
"version": "1.0.0",
"source": "./src/index.ts",
"main": "./lib/commonjs/index.js",
"module": "./lib/module/index.js",
"types": "index.d.ts",
"react-native": "./src/index.ts",
"dependencies": {
"@react-native-ohos/react-native-tts": "4.3.1-beta.2"
},
"harmony": {
"alias": "spatial-glass-rn",
"autolinking": {
"ohPackageName": "@rnoh/spatial-glass-rn",
"etsPackageClassName": "SpatialGlassPackage"
}
}
}
react-native 条件让 Metro 直接读 src/index.ts,Babel 负责转译;不使用 Metro 源码的工程落到 main / module 的 lib/。harmony.autolinking 告诉 RNOH 这个包对应的 ohpm 包名和 ETS 类名。
HAR 里的 SpatialGlassPackage 只提供一个空的 TurboModule 工厂,注释写得很清楚:
// harmony/rn_spatial_glass/src/main/ets/SpatialGlassPackage.ets
export class SpatialGlassPackage extends RNOHPackage {
override getAnyThreadTurboModuleFactoryByNameMap(): Map<
string,
(ctx: AnyThreadTurboModuleContext) => AnyThreadTurboModule | null
> {
return new Map<string, (ctx: AnyThreadTurboModuleContext) => AnyThreadTurboModule | null>();
}
}
保留这个只做身份登记的包,是为了让库能被 RNOH 发现、版本化、被 DevEco 检查,而不是在 autolinking 时被当成"没有鸿蒙实现"的包跳过。TTS 的原生能力则由第三方包提供,符合 RNOH 三方库模型:能力各自打包,宿主负责链接。
示例宿主的 TTS 接线有四步。entry/oh-package.json5 增加 HAR:
{
"dependencies": {
"@rnoh/spatial-glass-rn": "file:../../../harmony/rn_spatial_glass",
"@react-native-ohos/react-native-tts": "file:../../../node_modules/@react-native-ohos/react-native-tts/harmony/rn_tts.har"
}
}
CMake 把 rnoh_tts 链上:
add_subdirectory(
"${OH_MODULE_DIR}/@react-native-ohos/react-native-tts/src/main/cpp"
./rn_tts)
target_link_libraries(rnoh_app PUBLIC rnoh rnoh_tts)
C++ 侧注册 TtsPackage:
#include "TtsPackage.h"
std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
return {std::make_shared<TtsPackage>(ctx)};
}
ArkTS 侧把 SpatialGlassPackage 和 RNTTSPackage 一起交给 RNApp:
import { RNTTSPackage } from '@react-native-ohos/react-native-tts/ts';
export function createRNPackages(ctx: RNPackageContext): RNOHPackage[] {
return [new SpatialGlassPackage(ctx), new RNTTSPackage(ctx)];
}
Metro 打包时,react-native-tts 会按 harmony.alias 重定向到鸿蒙包,日志里能看到:
[INFO] Redirected imports to 1 harmony-specific third-party package(s):
[INFO] • react-native-tts → @react-native-ohos/react-native-tts
所以业务代码始终 import 原库名,不需要改路径。这也是这个库能在 Android / iOS / 鸿蒙三端共用同一份 TS 的原因。
5. 把代码讲透
5.1 分段:120 字、标点优先
鸿蒙引擎一次只合成一条 utterance。长文整段丢进去,会有两个问题:停止 要等很久,进度也不可见。分段函数就是从这里来的:
export const TTS_CHUNK_LENGTH = 120;
export function chunkText(text: string, maxLength = TTS_CHUNK_LENGTH): string[] {
const normalized = text.replace(/\r\n?/g, '\n');
const clean = normalized.trim();
if (!clean) {
return [];
}
const limit = Math.max(8, Math.floor(maxLength));
if (clean.length <= limit) {
return [clean];
}
const chunks: string[] = [];
let cursor = 0;
while (cursor < clean.length) {
const hardEnd = Math.min(cursor + limit, clean.length);
let end = hardEnd;
if (hardEnd < clean.length) {
// 在窗口后半段回看,优先断在标点上
const floor = cursor + Math.max(1, Math.floor(limit * 0.55));
for (let probe = hardEnd; probe > floor; probe -= 1) {
const previous = clean[probe - 1];
if (previous && SOFT_BREAKS.has(previous)) {
end = probe;
break;
}
}
}
const piece = clean.slice(cursor, end).trim();
if (piece) {
chunks.push(piece);
}
cursor = end;
// 跳过切口后的空白,避免下一段以空格开头
while (cursor < clean.length) {
const next = clean[cursor];
if (next !== ' ' && next !== '\t' && next !== '\n') {
break;
}
cursor += 1;
}
}
return chunks;
}
三个细节:
第一,软换行集合包含中英文标点和空白。 。!?;…:,、—、换行、空格、制表符都算"可以停"的位置。标点本身保留在段尾,不丢字。
第二,只在窗口后半段回看。 floor = cursor + limit * 0.55,如果为了找一个逗号把段落切得太短,进度会碎成一堆 20 字的段,反而不好听。后半段回看是"尽量断得自然,但不牺牲段长"的折中。
第三,找不到标点就硬切。 没有标点的长串(比如一长串编号)仍然要切,否则引擎会一直合成;硬切是最后手段,不是默认行为。
为什么是 120 字?它是"一段念完十几到几十秒"和"停止最多等一段"之间的折中。段太短,队列和事件开销变大;段太长,用户按停止时要等更久。这个值可以通过参数覆盖,但默认值是按播报场景调的。
5.2 队列:一次只提交一条
SystemTtsPlayer 是整条链路的核心。它不依赖 React,可以被单测直接驱动;useSystemTts 只是把它的快照和日志转成 React state。
speak() 先处理"打断还是追加":
const chunks = chunkText(text);
if (chunks.length === 0) {
return false;
}
const interrupt = options.interrupt !== false;
if (interrupt) {
await this.halt();
this.spoken = 0;
this.total = chunks.length;
} else if (!this.active && this.queue.length === 0 && this.spoken >= this.total) {
// 上一批已经播完,追加的新一批从 0 开始计数
this.spoken = 0;
this.total = chunks.length;
} else {
this.total += chunks.length;
}
this.queue.push(...chunks.map((chunk) => ({ text: chunk })));
this.log('speak', `${interrupt ? '打断并排队' : '追加'} ${chunks.length} 段`);
this.pump();
return true;
默认 interrupt: true 是有意的:语音 UI 应该以最新一次操作为准。用户在菜单里连点两项,第二项应该立刻覆盖第一项,而不是排队等第一项念完。
pump() 只在没有活跃分段时提交下一条:
const next = this.queue.shift();
if (!next) {
this.status = 'idle';
this.notify();
return;
}
this.active = next;
this.status = 'speaking';
this.notify();
this.attempt(next, 0);
attempt() 处理鸿蒙特有的"speak() 返回空":
let utteranceId: string | number | undefined;
try {
utteranceId = this.bridge.speak(item.text);
} catch (error) {
this.failCurrent(describeError(error));
return;
}
if (utteranceId === undefined || utteranceId === null) {
// 引擎可能还在 createEngine,或上一条还没结束
if (attempt >= MAX_SPEAK_ATTEMPTS) {
this.failCurrent('TTS 引擎未就绪:speak() 连续返回空值');
return;
}
this.retryTimer = setTimeout(() => {
this.retryTimer = null;
this.attempt(item, attempt + 1);
}, RETRY_DELAY_MS);
return;
}
item.utteranceId = utteranceId;
this.notify();
RETRY_DELAY_MS = 120、MAX_SPEAK_ATTEMPTS = 20:最多重试 20 次,合计约 2.4 秒。这个窗口足够覆盖引擎初始化,又不会让用户觉得"按了没反应"。超过就进入 error,把错误暴露到 UI,而不是无限等下去。
收到 finish 时,播放器只做三件事:推进 spoken、清空 active、调 pump() 提交下一段。total 保持不变,所以进度是真实的 1 / 2、2 / 2,不是根据时间猜的动画。
5.3 桥:懒加载、事件名归一化、每实例订阅
react-native-tts 不能在库入口静态 import。它在模块加载阶段会构造 NativeEventEmitter,如果宿主没有链接原生模块,import 本身就会抛错——一个 UI 库不能因为宿主没装 TTS 就连页面都加载不了。
桥的做法是延迟到真正需要时才 require:
let cached: NativeTts | null | undefined;
function loadNativeTts(): NativeTts | null {
if (cached !== undefined) {
return cached;
}
if (!nativeModulePresent()) {
cached = null;
return null;
}
try {
// 字符串字面量仍可被 Metro 静态解析;
// 鸿蒙 bundle 会按 harmony.alias 把它重定向到 ohos 包
const mod = require('react-native-tts') as { default?: NativeTts } | NativeTts;
cached = (mod as { default?: NativeTts }).default ?? (mod as NativeTts);
} catch {
cached = null;
}
return cached;
}
nativeModulePresent() 先查 TurboModuleRegistry.get('TTSNativeModule'),再退回 NativeModules.TextToSpeech。两个都拿不到,createNativeTtsBridge() 返回 null,hook 的 available 为 false,控制台显示 引擎未链接,speak() 返回 false。这样库在任何宿主里都能 import 和渲染,拿不到原生模块时降级。
事件名的归一化也在桥里:
export function toNativeTtsEventName(type: string): string {
return `tts-${type}`;
}
播放器内部用 start / finish / cancel / error / progress / pause / resume 这套短名字,桥把它们翻译成上游的 tts-start 等。这样播放器、控制台和文档共享一套词汇,平台差异都收在桥这一层。
订阅用 DeviceEventEmitter,而不是 tts.addEventListener:
subscribe: (type, handler) => {
const subscription = DeviceEventEmitter.addListener(
toNativeTtsEventName(type),
(event: SystemTtsEvent) => {
if (event && typeof event === 'object') {
handler(event);
}
},
);
return () => subscription.remove();
},
原因是鸿蒙包装层的 removeEventListener 按事件类型删除最后一个监听器。同一个进程里如果挂了两个控制台,卸载其中一个会把另一个的监听也删掉。直接订阅 RCTDeviceEventEmitter 可以让每个 hook 实例独立 remove(),互不影响。
canPause 也在桥里按平台决定:
const canPause = platform === 'harmony' || platform === 'ios';
Android 的 TextToSpeech 没有真正的暂停/继续,桥层把 canPause 置为 false,播放器直接返回 false;鸿蒙和 iOS 才把 true 暴露给 UI。
5.4 控制台:把状态画回表面
SpatialVoiceConsole 是纯展示组件:外面创建 useSystemTts(),把 controller 传进来;它只负责把 snapshot 映射成文字、颜色和按钮状态。
状态映射只有五种:
function getStatusMeta(tts: SystemTtsController): { label: string; color: string } {
if (!tts.available) {
return { label: '引擎未链接', color: '#FF8FA3' };
}
switch (tts.status) {
case 'speaking':
return { label: '播报中', color: '#62E8FF' };
case 'paused':
return { label: '已暂停', color: '#FFD4A8' };
case 'error':
return { label: '合成失败', color: '#FF8FA3' };
default:
return { label: '待命', color: 'rgba(226, 236, 255, 0.64)' };
}
}
预览区把进度和队列拼成一行:
<Text style={styles.previewMeta}>
{tts.total > 0 ? `${tts.spoken} / ${tts.total} 段` : '待朗读'}
{tts.queueLength > 0 ? ` · 队列 ${tts.queueLength}` : ''}
{tts.rate !== 1 ? ` · ${tts.rate.toFixed(2)}x` : ''}
</Text>
截图里的 0 / 2 段 · 队列 1 就是这一行:当前这批共 2 段,已播 0 段,队列里还有 1 段。它显示的是播放器的真实状态。
按钮的文案跟着状态走:
{tts.status === 'speaking' ? '重新朗读' : '朗读'}
...
{tts.status === 'paused' ? '继续' : '暂停'}
暂停按钮的 disabled 条件是 !tts.canPause || tts.status === 'idle',所以 Android 上它是灰的,鸿蒙上播报中可用。这是平台差异在 UI 上的唯一投影,不需要业务自己判断平台。
日志只显示最近 3 条,倒序排列;类型映射成短标签:
const EVENT_LABELS: Record<SystemTtsLogEntry['type'], string> = {
start: 'START',
finish: 'FINISH',
cancel: 'CANCEL',
error: 'ERROR',
progress: 'DATA',
pause: 'PAUSE',
resume: 'RESUME',
speak: 'QUEUE',
stop: 'STOP',
info: 'INFO',
};
整个控制台放在 SpatialSurface 里,使用 intensity={0.95},状态点、边框和 chip 的颜色都从 SPATIAL_THEME 读取。它没有另建一套设计系统:光感表面本身就用来承载状态,TTS 只是换了一种状态。
5.5 交付:autolinking HAR、第三方 TTS 包与 npm 包
构建分三条线:
npm run verify # 库 + 示例 typecheck、33 个 Vitest、Babel 双格式、声明
npm run build:har # 构建 harmony/rn_spatial_glass.har
npm run build:example # Metro bundle + ohpm install + assembleHap
build:har 产出的 HAR 只有约 2.9 KB,因为 SpatialGlassPackage 不提供任何 TurboModule;它的价值是让这个包拥有 RNOH 三方库的标准身份,能被 autolinking 发现、版本化、被 DevEco 检查。TTS 原生代码不在里面,由宿主链接 rn_tts.har——这也是为什么示例工程的 TTS 接线有四步,而不是一行 npm install 就完事。
verify:package 先 npm pack,再解包逐项校验,不直接检查工作区:
lib/commonjs/index.js、lib/module/index.js、lib/typescript/index.d.ts;lib/typescript/tts/index.d.ts、src/tts/index.ts;harmony/rn_spatial_glass.har内的Index.d.ets、oh-package.json5、ets/modules.abc;- 拒绝
node_modules、build、.hvigor、oh_modules、签名材料。
当前包的结果是 138 个文件、137,592 字节(解包后 628,279 字节),包内容与 HAR 全部通过。示例 HAP 约 38 MB,包含 RNOH 原生库和 resources/rawfile/bundle.harmony.js。
6. 我踩过的坑(每一条都有真实报错或真机现象)
这一节是坑清单,以下每一条都来自这次开发的报错、真机现象和排查记录。
坑一:事件名对不上,播完了 UI 还停在"播报中"。 第一次真机跑,声音正常出来,日志也走完了,但状态一直是 播报中。查到最后是上游发 tts-start / tts-finish,播放器订阅的是 start / finish:
react-native-tts → tts-start / tts-finish / tts-cancel / tts-progress
SystemTtsPlayer → start / finish / cancel / progress
声音走原生,UI 等的是一个永远不会来的事件。修复是桥里的 toNativeTtsEventName(),把短名翻译成 tts-*;tts-text.test.ts 锁死了这个映射,避免以后再改回去。跨库事件名要当作契约维护。
坑二:静态 import react-native-tts,宿主没链接时整个库都起不来。 react-native-tts 在模块加载阶段会构造 NativeEventEmitter;如果宿主没有链接 TTS 原生模块,import 本身就会抛错。一个 UI 库不能因为宿主没装 TTS 就连页面都加载不了。
修复是把 import 改成运行时 require,并先用 TurboModuleRegistry / NativeModules 探测模块是否存在;拿不到就返回 null,available = false,控制台显示 引擎未链接。这样库在没有 TTS 的宿主里仍然可用,只是语音功能降级。
坑三:鸿蒙引擎忙时 speak() 返回 undefined,请求会静默丢失。 鸿蒙的 TextToSpeechManager.speak() 在两种情况下返回空:createEngine() 还没 resolve,或者上一条还没结束。如果直接把这个返回值当"成功",用户连续点两次,第二次就没了。
播放器的处理是每 120ms 重试一次,最多 20 次;仍然拿不到 id 才进入 error,提示 TTS 引擎未就绪:speak() 连续返回空值。这段重试是鸿蒙接入的必需路径。
坑四:Android 没有真正的暂停。 react-native-tts 的 Android 实现没有可用的暂停/继续,桥层按平台把 canPause 置为 false;但很多 UI 还是会画一个可点的暂停按钮,点了没反应。控制台据此禁用按钮并把它置灰;resume() 也只在桥支持时才可能成功。平台没有的能力,UI 上不要给可点的按钮。
坑五:两个控制台会互相删监听。 鸿蒙包装层的 removeEventListener 按事件类型删除最后一个监听器。同一个进程里挂两个控制台,卸载其中一个时会把另一个的监听也删掉,表现为"另一个控制台突然收不到 finish,永远停在播报中"。
修复是不走 tts.addEventListener,而是直接订阅 DeviceEventEmitter,每个 hook 自己 remove()。这个问题只有多实例场景才会出现,单控制台的 demo 永远测不出来。
坑六:macOS 大小写不敏感,assert.h 被 RNOH 的 Assert.h 顶掉了。 在 Mac 上构建 RNOH 原生工程,报的是铺天盖地的:
error: use of undeclared identifier 'assert'
RNOH 把 src/main/cpp/RNOH 加进了 include path,而那个目录里有一个 Assert.h。macOS 的 APFS 默认大小写不敏感,#include <assert.h> 会先命中 Assert.h;那个头文件不定义标准的 assert 宏,所以每个包含 <cassert> 的编译单元都炸了。
修复是在 example/harmony/entry/src/main/cpp/compat/ 放一个真正的 assert.h,再在 CMakeLists.txt 里把它插到 RNOH 的 include 目录前面:
include_directories(BEFORE "${CMAKE_CURRENT_SOURCE_DIR}/compat")
这个坑只在大小写不敏感的文件系统上出现,Linux CI 上反而看不到;如果 RNOH 哪天把 Assert.h 改名,这个 shim 就可以删掉。
7. 现在怎么用:从一次 speak 到语音控制台
这个工程现在是一个标准 React Native 三方库(包名 spatial-glass-rn,版本 1.0.0)。安装:
npm install spatial-glass-rn
react / react-native 只作为 peer 依赖,不捆绑。鸿蒙宿主还需要接入 @react-native-ohos/react-native-tts 的 rn_tts.har(example/harmony 是完整示例);Android / iOS 宿主按 RN 常规方式 autolink react-native-tts。
最小用法:
import React from 'react';
import { Text, View } from 'react-native';
import {
SpatialVoiceConsole,
useSystemTts,
type SpatialVoiceScript,
} from 'spatial-glass-rn';
const SCRIPTS: SpatialVoiceScript[] = [
{
id: 'warehouse',
label: '仓储播报',
text: '3 号库位,B 区,共 12 件,其中 2 件临期。请优先复核临期商品。',
},
{
id: 'long',
label: '长文分段',
text: '一段超过 120 字的长文本,会被播放器按标点切成多段,再逐段交给系统引擎。',
},
];
export function VoicePanel() {
const tts = useSystemTts();
return (
<View>
<Text>{tts.available ? '系统 TTS 已链接' : '当前宿主没有系统 TTS'}</Text>
<SpatialVoiceConsole tts={tts} scripts={SCRIPTS} />
</View>
);
}
不需要控制台时,也可以直接调 hook:
const tts = useSystemTts();
await tts.speak('3 号库位,B 区,共 12 件。', { interrupt: true });
tts.setRate(1.25);
await tts.pause();
await tts.resume();
await tts.stop();
useSystemTts() 返回的主要字段:
| 字段 | 类型 | 说明 |
|---|---|---|
available | boolean | 当前二进制是否链接了 TTS 原生模块 |
canPause | boolean | 当前平台是否支持真正的暂停/继续(鸿蒙、iOS 为 true) |
status | 'idle' | 'speaking' | 'paused' | 'error' | 播放状态 |
currentText / queueLength | string | null / number | 当前分段与等待队列长度 |
spoken / total | number | 当前批次的进度 |
lastError | string | null | 最近一次错误 |
rate / pitch | number | 语速(0.5–2)与音调(0–2) |
log | SystemTtsLogEntry[] | 最近 40 条事件 |
speak(text, options?) | Promise<boolean> | 入队并开始播报;默认打断当前队列 |
stop() / pause() / resume() | Promise<...> | 停止、暂停、继续 |
setRate() / setPitch() | void | 自动夹取到引擎范围 |
clearLog() | void | 清空事件日志 |
底层还导出了纯函数与类,方便测试或自定义 UI:
| API | 说明 |
|---|---|
chunkText(text, maxLength?) | 按标点分段,纯函数 |
normalizeRate() / normalizePitch() | 夹取到 Core Speech Kit 范围 |
formatClock(timestamp) | HH:MM:SS,不依赖 Intl |
SystemTtsPlayer | 不依赖 React 的队列播放器 |
createNativeTtsBridge() | 把 react-native-tts 适配成小接口;模块缺失返回 null |
toNativeTtsEventName() | start → tts-start |
构建与验证:
npm install
npm run verify # 库 + 示例 typecheck、33 个 Vitest、Babel 双格式、声明
npm run build:har # 构建 RNOH HAR
npm run build:example # 构建示例 HAP(需要 DevEco 的 hvigor/ohpm)
npm run verify:package # 校验 npm tarball 与 HAR 内容
当前版本的验证结果:
| 项目 | 状态 |
|---|---|
npm run verify | 通过:库与示例 typecheck 0 错误;33 个 Vitest(geometry 10、theme 3、tts-text 11、tts-player 9);Babel 产出 17 个模块;声明生成成功 |
npm run verify:package | 通过:138 个文件、137,592 字节(解包 628,279 字节);HAR 内容与入口校验通过 |
npm run build:har | 通过:rn_spatial_glass.har 约 2.9 KB(只含 SpatialGlassPackage,无 TurboModule) |
npm run build:example | 通过:unsigned HAP 约 38 MB;Metro 日志显示 react-native-tts → @react-native-ohos/react-native-tts |
| 真机(单条) | HUAWEI MateBook Pro S,HarmonyOS 7.0.0.111 / API 26;播报中 → 待命,1 / 1 段,日志 QUEUE → START → DATA → FINISH |
| 真机(暂停/继续) | 播报中点暂停变 已暂停,按钮变 继续;继续后念到 FINISH |
| 真机(长文) | 选「长文分段」后朗读,显示 0 / 2 段 · 队列 1;停止清空队列并回 待命 |
| 真机(引擎) | 设备日志出现 HiAI_OfflineTtsService 的 onTtsStart / onTtsComplete,person: 13、language: zh_CN、online: 1 |
能力边界也写清楚:
- 系统 TTS 不是云端 TTS:没有在线音色、没有 SSML 级控制、没有发音词典;音色、语言、离线包以设备为准;
- 鸿蒙只有
zh-CN离线音色:voices()的 id/name 为空,不要做音色选择器;多语言内容需要降级或提示; - Android 不支持暂停:
canPause为false,控制台会禁用暂停按钮; - 队列在 JS 侧:120 字一段,默认打断,最多 20 次
speak()重试;极长文本的分段和重试会增加总耗时; - HAR 不提供 TurboModule 是设计:光感 UI 不需要原生模块,HAR 只负责 autolinking 身份;TTS 原生能力由
rn_tts.har提供,宿主必须显式链接; - 不做音频焦点/ducking:与其他媒体同时播放时的混音、压低、恢复由宿主或系统决定;本库只负责播放器语义(暂停/继续/停止),
AudioPlayer由 TTS 原生包提供; - 单实例建议:虽然桥支持多实例订阅,但同一页面建议只挂一个
useSystemTts(),避免多个队列同时抢引擎。
更完整的说明在仓库的文档里:
- 光感组件、系统 TTS API、平台差异、安装与发布形态;
- 队列设计、
speak()空值重试、事件状态机、鸿蒙接入与 hilog 排查; - 光感材质的分层与设计边界;
- npm 包校验、构建记录与真机验证;
example/App.tsx:本文截图对应的示例页面。
同系列的光感实现共享同一套视觉语言,但语音这一层是 RN 侧新增的:系统引擎负责合成和播放,JS 播放器管理队列、进度和暂停/停止,光感材质负责把状态显示出来。
更多推荐

所有评论(0)