一、前言
- 在 HarmonyOS Next 中为应用添加语音朗读能力，主要依赖于系统提供的 TextToSpeech (TTS) 引擎。那么如何借助 HarmonyOS Next 的 textToSpeech API 实现语音朗读能力，让应用具备文本转语音的功能呢？
- 实现语音朗读功能，本质上是应用通过 TextToSpeech API 与系统 TTS 服务交互的过程。其核心流程如下：
二、语音朗读实现流程
① 配置权限与引入模块
- 在开始编码前，需要在项目的 module.json5 文件中声明必要的权限。根据应用场景，可能需要网络或设备位置权限。
{"module": {"requestPermissions": [{"name": "ohos.permission.INTERNET","reason": "用于在线语音服务"},{"name": "ohos.permission.APPROXIMATE_LOCATION","reason": "语音服务定位"}]}
}
import { textToSpeech } from '@kit.CoreSpeechKit'; // 引入CoreSpeechKit
import { BusinessError } from '@kit.BasicServicesKit';
② 创建与初始化 TTS 引擎
- 为了便于复用和管理，通常我们会将 TTS 功能封装成一个独立的管理类，例如 TextToSpeechManager，并采用单例模式确保全局唯一。在项目的 utils 文件夹下新建一个 TextToSpeechManager.ets 文件，用于封装语音朗读相关的功能：
import { textToSpeech } from '@kit.CoreSpeechKit';
import { BusinessError } from '@kit.BasicServicesKit';
export class TextToSpeechManager {private static instance: TextToSpeechManager;private constructor() {}public static getInstance():TextToSpeechManager {if (!TextToSpeechManager.instance) {TextToSpeechManager.instance = new TextToSpeechManager();}return TextToSpeechManager.instance;}// 创建TextSpeechEngine实例private ttsEngine : textToSpeech.TextToSpeechEngine | null = null;// 设置播报相关参数private extraParam : Record<string,Object> | null = null;// 实例化SpeakParams对象private speakParams : textToSpeech.SpeakParams | null = null;// SpeakListener对象,设置speak的回调信息private speakListener : textToSpeech.SpeakListener | null = null;createEngine() {// 设置创建引擎参数let extraParam : Record<string,Object> = {"style":'interaction-broadcast',"locate":'CN',"name":'EngineName'};let initParamsInfo : textToSpeech.CreateEngineParams = {language:'zh-CN', // 设置语言person:0, // 设置发音人online:1, // 是否使用在线引擎extraParams: extraParam};// 调用createEngine方法textToSpeech.createEngine(initParamsInfo, (err : BusinessError, textToSpeechEngine : textToSpeech.TextToSpeechEngine) => {if (!err) {console.info('Succeeded in creating engine');// 接收创建引擎的实例this.ttsEngine = textToSpeechEngine;} else {console.error(`Failed to create engine. Code:${err.code}, message:${err.message}.`);}});}}
③ 设置监听回调
- 为了感知语音合成的状态（如开始、结束、出错），需要设置监听回调：
// 得到TextToSpeechEngine实例对象后，实例化SpeakParams对象、SpeakListener对象，并传入待合成及播报的文本originalText，调用speak接口进行播报。initParam() {// 设置speak的回调信息this.speakListener = {// 开始播报回调onStart(requestId : string, response: textToSpeech.StartResponse) {console.info(`onStart, requestId：${JSON.stringify(requestId)} response: ${JSON.stringify(response)}`);},// 合成完成及播报完成回调onComplete(requestId : string, response: textToSpeech.CompleteResponse) {console.info(`onComplete, requestId：${JSON.stringify(requestId)} response: ${JSON.stringify(response)}`);},onStop(requestId : string, response: textToSpeech.StopResponse) {console.info(`onStop, requestId：${JSON.stringify(requestId)} response: ${JSON.stringify(response)}`);},onData(requestId : string, audio : ArrayBuffer, response : textToSpeech.SynthesisResponse) {console.info(`onData, requestId：${JSON.stringify(requestId)} response: ${JSON.stringify(response)}`);},onError(requestId : string, errorCode : number, errorMessage : string) {console.info(`onError, errorCode：${JSON.stringify(errorCode)} errorMessage: ${JSON.stringify(errorMessage)}`);},};// 设置回调this.ttsEngine?.setListener(this.speakListener);}
④ 执行语音朗读
- 准备好引擎和监听后，就可以调用 speak 方法进行朗读了。请注意，单次合成的文本长度通常有不超过 10000 个字符的限制：
// 调用播报方法: 可以通过修改speakParams主动设置播报策略speak(text:string) {if (!this.ttsEngine) {console.error('TTS Engine is not initialized');return;}if (!text || text.length > 10000) {console.error('Text is empty or too long');return;}// 设置播报相关参数this.extraParam = {"queueMode":0, "speed": 1, "volume": 0.1, "pitch":1, "languageContext":'zh-CN', "audioType":"pcm", "soundChannel":3,"playType":1};this.speakParams = { requestId:new Date().getTime().toString(), // requestId在同一实例内仅能用一次，请勿重复设置extraParams: this.extraParam };// 调用播报方法:可以通过修改speakParams主动设置播报策略this.ttsEngine?.speak(text, this.speakParams);}
⑤ 控制播放状态
// 停止调用播报方法: 当需要停止合成及播报时，可调用stop接口stop() {if (this.ttsEngine?.isBusy()) {this.ttsEngine?.stop();}}
三、实际应用步骤
- 首先要导入工具类，在需要使用语音朗读功能的页面中，首先导入封装好的工具类：
import { TextToSpeechManager } from "../utils/TextToSpeechManager"
- 初始化TTS引擎，在页面的生命周期方法中进行初始化操作，页面打开时需要创建 TextToSpeechEngine 实例以及实例化相关参数对象：
private textToSpeechManger = TextToSpeechManager.getInstance();aboutToAppear(): void {this.textToSpeechManger.createEngine();this.textToSpeechManger.initParam();}
- 接下来编写语音朗读的业务函数，当用户点击按钮时，直接将需要播报的文本传入到函数中即可实现语音朗读：
this.textToSpeechManger.speak(txt);
