HarmonyOS TTS（文本转语音）功能使用指南

本文介绍了如何在HarmonyOS应用中使用TTS（文本转语音）功能。主要内容包括：1）导入核心语音服务包并配置必要权限；2）实现TTS管理器类，包含引擎初始化、监听器设置和状态管理；3）核心功能实现如播放文本、停止播放、文本过滤等。文章提供了详细的代码示例，包括参数说明和使用方法，帮助开发者快速集成TTS功能到HarmonyOS应用中。通过TTS管理器类，开发者可以方便地控制语音播放状态，处理错

红目香薰

6872人浏览 · 2025-09-11 21:45:25

红目香薰 · 2025-09-11 21:45:25 发布

概述

TTS（Text-to-Speech）是HarmonyOS提供的重要语音服务能力，可以将文本内容转换为语音播放。本文基于实际项目经验，详细介绍如何在HarmonyOS应用中使用TTS功能。
在这里插入图片描述

核心依赖包

1. 主要导入包

import { textToSpeech } from '@kit.CoreSpeechKit'
import { BusinessError } from '@ohos.base'

包说明：

@kit.CoreSpeechKit：HarmonyOS核心语音服务包，提供TTS、语音识别等语音相关功能
@ohos.base：HarmonyOS基础类型定义包，提供错误处理等基础功能

2. 权限配置

在 module.json5 中需要申请相关权限：

{
  "requestPermissions": [
    {
      "name": "ohos.permission.MICROPHONE",
      "reason": "用于语音识别功能采集麦克风音频，进行语音转文字。",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "always"
      }
    },
    {
      "name": "ohos.permission.INTERNET",
      "reason": "用于联网获取或发送与语音能力相关的数据。",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "always"
      }
    }
  ]
}

TTS管理器类实现

1. 类结构定义

export class TTSManager {
  private tts: textToSpeech.TextToSpeechEngine | null = null
  private playing: boolean = false
  private paused: boolean = false
  private log: string = ''
  private onPlayingStateChange: (playing: boolean, paused: boolean) => void = () => {}
  private onLogChange: (log: string) => void = () => {}
  private userStopped: boolean = false
  private currentText: string = ''

  constructor(
    onPlayingStateChange?: (playing: boolean) => void,
    onLogChange?: (log: string) => void
  ) {
    if (onPlayingStateChange) {
      this.onPlayingStateChange = (playing, paused) => {
        onPlayingStateChange(playing)
      }
    }
    if (onLogChange) {
      this.onLogChange = onLogChange
    }
    this.initTTS()
  }
}

2. TTS引擎初始化

private initTTS(): void {
  const params: textToSpeech.CreateEngineParams = { 
    language: 'zh-CN',  // 设置语言为中文
    person: 0,          // 设置发音人（0为默认发音人）
    online: 1           // 设置为在线模式（1为在线，0为离线）
  }
  
  textToSpeech.createEngine(params, (err: BusinessError, engine: textToSpeech.TextToSpeechEngine) => {
    if (err || !engine) {
      this.updateLog(`创建TTS引擎失败: ${err?.message}`)
      return
    }
    this.tts = engine
    this.setListener()
  })
}

参数说明：

language：语音语言，支持 ‘zh-CN’（中文）、‘en-US’（英文）等
person：发音人选择，0为默认发音人
online：在线/离线模式，1为在线模式（需要网络），0为离线模式

3. 设置TTS监听器

private setListener(): void {
  if (!this.tts) return
  
  const listener: textToSpeech.SpeakListener = {
    onStart: (id, rsp) => {
      if (!this.paused) {
        this.userStopped = false
      }
      this.updatePlaying(true, false)
      this.updateLog('开始播报')
    },
    onComplete: (id, rsp) => {
      if (rsp && rsp.type === 1) {
        this.updateLog('播报完成')
      }
    },
    onStop: (id, rsp) => {
      // 停止事件处理
    },
    onData: (id, audio, rsp) => { 
      // 收到音频数据
    },
    onError: (id, code, msg) => {
      this.updateLog(`TTS错误(${code}): ${msg}`)
    }
  }
  this.tts.setListener(listener)
}

监听器事件说明：

onStart：开始播放时触发
onComplete：播放完成时触发
onStop：停止播放时触发
onData：接收到音频数据时触发
onError：发生错误时触发

核心功能实现

1. 播放文本

public speak(text: string): void {
  if (!this.tts) {
    this.updateLog('TTS未就绪')
    return
  }
  
  // 重置状态
  this.userStopped = false
  this.paused = false
  this.currentText = text
  
  // 过滤文本
  const filtered = this.filterText(text)
  const speakParams: textToSpeech.SpeakParams = { 
    requestId: 'tts_' + Date.now() 
  }
  
  try {
    this.tts.speak(filtered, speakParams)
  } catch (e) {
    this.updateLog(`播报失败: ${JSON.stringify(e)}`)
  }
}

使用示例：

// 创建TTS管理器实例
const ttsManager = new TTSManager(
  (playing) => { 
    console.log('播放状态:', playing) 
  },
  (log) => { 
    console.log('TTS日志:', log) 
  }
)

// 播放文本
ttsManager.speak('你好，欢迎使用HarmonyOS TTS功能！')

2. 停止播放

public stop(): void {
  try {
    this.userStopped = true
    this.paused = false
    this.updatePlaying(false, false)
    this.tts?.stop()
    this.updateLog('已停止播报')
  } catch (e) {
    this.updateLog(`停止失败: ${JSON.stringify(e)}`)
  }
}

使用示例：

// 停止当前播放
ttsManager.stop()

3. 文本过滤功能

private filterText(text: string): string {
  return text
    .replace(/[\u{1F600}-\u{1F64F}]/gu, '') // 移除表情符号
    .replace(/[\u{1F300}-\u{1F5FF}]/gu, '') // 移除符号和象形图
    .replace(/[\u{1F680}-\u{1F6FF}]/gu, '') // 移除交通和地图符号
    .replace(/[\u{2600}-\u{26FF}]/gu, '')   // 移除杂项符号
    .replace(/[\u{1F900}-\u{1F9FF}]/gu, '') // 移除补充符号
    .replace(/[:;=][)(\]>DPdpO0\-]+/g, '')  // 移除文本表情
    .replace(/[\s]+/g, ' ')                 // 合并多余空格
}

4. 状态管理

// 获取播放状态
public isPlaying(): boolean {
  return this.playing
}

// 获取暂停状态
public isPaused(): boolean {
  return this.paused
}

// 获取日志
public getLog(): string {
  return this.log
}

// 更新播放状态
private updatePlaying(playing: boolean, paused?: boolean): void {
  this.playing = playing
  if (paused !== undefined) {
    this.paused = paused
  }
  this.onPlayingStateChange(playing, this.paused)
}

// 更新日志
private updateLog(log: string): void {
  this.log = log
  this.onLogChange(log)
}

在UI组件中使用

1. 在页面中集成TTS

@Entry
@Component
struct Index {
  @State isSpeaking: boolean = false
  private ttsManager: TTSManager = new TTSManager(
    (playing) => { this.isSpeaking = playing },
    (log) => { this.addLog('TTS', log) }
  )

  // 朗读文本
  speakText() {
    if (!this.currentText.trim()) {
      this.addLog('朗读失败', '没有可朗读的内容')
      return
    }
    this.ttsManager.speak(this.currentText)
    this.addLog('开始朗读', `开始朗读文本，长度: ${this.currentText.length}字符`)
  }

  // 停止朗读
  stopSpeaking() {
    if (this.isSpeaking) {
      this.ttsManager.stop()
      this.addLog('停止朗读', '已停止朗读')
    }
  }

  aboutToDisappear() {
    this.ttsManager.shutdown()
  }
}

2. UI按钮控制

build() {
  Column() {
    // 播放/停止按钮
    Button(this.isSpeaking ? '停止朗读' : '朗读')
      .onClick(() => {
        if (this.isSpeaking) {
          this.stopSpeaking()
        } else {
          this.speakText()
        }
      })
      .backgroundColor(this.isSpeaking ? '#FF6B6B' : '#40E0D0')
      .fontColor(Color.White)
      .borderRadius(8)
      .width(80)
      .height(40)
  }
}

资源释放

关闭TTS引擎

public shutdown(): void {
  if (this.tts) {
    try {
      this.tts.shutdown()
    } catch (e) {
      console.error(`关闭TTS引擎失败: ${JSON.stringify(e)}`)
    }
    this.tts = null
  }
}

重要提醒： 在页面销毁时务必调用 shutdown() 方法释放TTS资源，避免内存泄漏。

完整使用示例

// 1. 创建TTS管理器
const ttsManager = new TTSManager(
  (playing) => {
    console.log('TTS播放状态:', playing)
  },
  (log) => {
    console.log('TTS日志:', log)
  }
)

// 2. 播放文本
ttsManager.speak('这是一段测试文本，用于验证TTS功能是否正常工作。')

// 3. 检查播放状态
if (ttsManager.isPlaying()) {
  console.log('正在播放中...')
}

// 4. 停止播放
ttsManager.stop()

// 5. 释放资源
ttsManager.shutdown()