一条 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 Native0.84.1
React19.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)
hvigorDevEco Studio 自带(HVIGOR_JS 可覆盖)
spatial-glass-rn1.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 / RNOHCore Speech Kit textToSpeech仅离线支持(库内自建 AudioPlayer)固定 zh-CN、默认聆小珊(13 号)引擎忙时 speak() 返回 undefined,播放器重试
Androidandroid.speech.tts.TextToSpeech取决于系统引擎不支持(桥层返回 false)voices() / engines()需要设备安装可用的 TTS 引擎
iOSAVSpeechSynthesizer系统语音支持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-* 映射过来:

事件处理
startstatus = 'speaking',记录 START
progress记录 DATA(鸿蒙只带 utteranceId,不带 location/length)
finishspoken += 1,提交下一段;队列空则 idle
cancel清理活跃分段,提交下一段
errorstatus = 'error',清空队列,保留 lastError
pausestatus = 'paused'
resumestatus = '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() 返回的主要字段:

字段类型说明
availableboolean当前二进制是否链接了 TTS 原生模块
canPauseboolean当前平台是否支持真正的暂停/继续(鸿蒙、iOS 为 true)
status'idle' | 'speaking' | 'paused' | 'error'播放状态
currentText / queueLengthstring | null / number当前分段与等待队列长度
spoken / totalnumber当前批次的进度
lastErrorstring | null最近一次错误
rate / pitchnumber语速(0.5–2)与音调(0–2)
logSystemTtsLogEntry[]最近 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 播放器管理队列、进度和暂停/停止,光感材质负责把状态显示出来。

Logo

开源鸿蒙跨平台开发社区汇聚开发者与厂商,共建“一次开发,多端部署”的开源生态,致力于降低跨端开发门槛,推动万物智联创新。

更多推荐