更新记录

1.0.0（2026-06-16） 下载此版本

第一次上传

平台兼容性

uni-app

uni-app x(5.07)

apex-gu-cheng-tts 操作说明

跨平台 TTS（Text-to-Speech）语音合成 UTS 模块，支持 Android、iOS 和 HarmonyOS。

目录

1. 快速开始
2. API 参考
3. 类型定义
4. 错误码
5. 平台差异
6. 完整示例
7. 注意事项

快速开始

导入

import {
  ttsInit,
  ttsSpeak,
  ttsStop,
  ttsIsSpeaking,
} from '@/uni_modules/apex-gu-cheng-tts'

最小示例

// 1. 初始化
ttsInit({
  language: 'zh-CN',
  success: () => console.log('就绪'),
  fail: (err) => console.error('初始化失败', err.errMsg),
})

// 2. 朗读
ttsSpeak({
  text: '你好，世界',
  success: () => console.log('开始朗读'),
  fail: (err) => console.error('朗读失败', err.errMsg),
})

// 3. 停止
ttsStop({
  success: () => console.log('已停止'),
})

// 4. 查询状态
if (ttsIsSpeaking()) {
  console.log('正在朗读中...')
}

API 参考

ttsInit(options)

初始化 TTS 引擎。必须先调用此方法，后续的 ttsSpeak / ttsStop 才可用。

注意：重复调用 ttsInit 会自动销毁旧引擎再创建新的（Android / HarmonyOS 平台）。

ttsSpeak(options)

朗读指定文本。调用前需确保 TTS 已初始化成功。

注意：success 仅表示朗读请求已提交到引擎，不代表朗读已结束。朗读是否完成需通过轮询 ttsIsSpeaking() 判断。

ttsStop(options)

立即停止当前朗读。

ttsIsSpeaking()

同步查询当前是否正在朗读。

• 返回值：boolean
• true — 正在朗读中
• false — 空闲状态

ttsShutdown() (平台内部方法)

停止朗读并释放 TTS 引擎资源。Android / iOS / HarmonyOS 平台均有导出，可用于页面销毁时清理。

// 页面 onUnload 时清理
export function ttsShutdown(): void

类型定义

TTSInitResult

type TTSInitResult = {
  success: boolean   // 是否初始化成功
  message: string    // 描述信息
}

TTSSpeakResult

type TTSSpeakResult = {
  success: boolean   // 是否成功提交朗读请求
  message: string    // 描述信息
}

TTSStopResult

type TTSStopResult = {
  success: boolean   // 是否停止成功
  message: string    // 描述信息
}

TTSFail

interface TTSFail extends IUniError {
  errCode: TTSErrorCode  // 错误码
  errMsg: string         // 错误描述
}

错误码

平台差异

Android

• 底层使用系统 android.speech.tts.TextToSpeech API
• 语言解析支持 语言-地区 格式（如 zh-CN、en-US、ja-JP）
• ttsIsSpeaking() 直接调用 TextToSpeech.isSpeaking()，实时准确
• 需要 Activity 上下文，请确保在 uni-app 页面生命周期内初始化

iOS

• 底层使用 AVFoundation.AVSpeechSynthesizer
• 语速映射：接口 speed 范围 0.5~2.0，映射到 iOS 原生 rate 范围 0.0~1.0，公式：iosRate = speed × 0.5
• 音调使用 pitchMultiplier，范围与接口一致（0.5~2.0）
• 初始化是同步的，不会失败（除非内存不足）
• ttsIsSpeaking() 通过 synthesizer.isSpeaking 属性获取

HarmonyOS

• 底层使用 @kit.CoreSpeechKit 的 textToSpeech API
• 需要在线模式（online: 1），需设备联网
• 引擎创建是异步的（createEngine 返回 Promise）
• 支持完整的播报生命周期回调：onStart、onComplete、onStop、onError
• ttsIsSpeaking() 通过内部标志位维护，非原生查询

完整示例

以下示例来自 pages/index/index.uvue，展示了完整的 TTS 使用流程：

1. 页面初始化时启动 TTS

import { ref } from 'vue'
import { ttsInit, ttsSpeak, ttsStop, ttsIsSpeaking } from '@/uni_modules/apex-gu-cheng-tts'

const ttsReady = ref(false)
const speaking = ref(false)

ttsInit({
  rate: 1.0,
  pitch: 1.0,
  volume: 1.0,
  language: 'zh-CN',
  success: (res) => {
    ttsReady.value = true
    console.log('TTS初始化成功')
  },
  fail: (err) => {
    console.error('TTS初始化失败: ' + err.errMsg)
  },
})

2. 朗读文本（含轮询完成检测）

const textContent = ref('你好，欢迎使用TTS语音合成测试功能')
const curLang = ref('zh-CN')
const speed = ref(1.0)
const pitch = ref(1.0)
const volume = ref(1.0)

let pollTimer: number = 0

function handleSpeak(): void {
  const txt = textContent.value.trim()
  if (txt.length === 0) return

  ttsSpeak({
    text: txt,
    speed: speed.value,
    pitch: pitch.value,
    volume: volume.value,
    language: curLang.value,
    success: (res) => {
      speaking.value = true
    },
    fail: (err) => {
      console.error('朗读失败: ' + err.errMsg)
    },
    complete: () => {
      // 轮询检测朗读是否结束
      pollTimer = setInterval(() => {
        if (!ttsIsSpeaking()) {
          speaking.value = false
          console.log('朗读完成')
          clearInterval(pollTimer)
        }
      }, 300)

      // 30 秒超时保护
      setTimeout(() => {
        clearInterval(pollTimer)
      }, 30000)
    },
  })
}

3. 停止朗读

function handleStop(): void {
  ttsStop({
    success: () => {
      speaking.value = false
      console.log('已停止朗读')
    },
    fail: (err) => {
      console.error('停止失败: ' + err.errMsg)
    },
  })
}

4. 页面销毁时清理

// 在页面 onUnload 中调用
import { ttsShutdown } from '@/uni_modules/apex-gu-cheng-tts'

// 如果需要在页面销毁时释放引擎资源
// ttsShutdown()

注意事项

1. 初始化顺序：必须先调用 ttsInit 并等待 success 回调后，才能调用 ttsSpeak / ttsStop，否则会收到 9020004（未初始化）错误。

2. 朗读完成检测：ttsSpeak 的 success 回调仅表示请求已提交。判断朗读是否真正结束，需要通过轮询 ttsIsSpeaking() 实现，建议间隔 300ms，并设置超时保护（如 30 秒）。

3. 语言代码格式：使用 BCP-47 格式，常见值：	语言	代码
   中文（简体）	zh-CN
   英文（美国）	en-US
   日文	ja-JP

4. 参数范围：	参数	范围	默认值	说明
   语速 (speed/rate)	0.5 ~ 2.0	1.0	1.0 = 正常语速
   音调 (pitch)	0.5 ~ 2.0	1.0	1.0 = 正常音调
   音量 (volume)	0.0 ~ 1.0	1.0	0.0 = 静音，1.0 = 最大

5. HarmonyOS 平台需要网络连接（使用在线 TTS 服务），Android 和 iOS 使用本地引擎，可离线使用。

6. Android 平台重复调用 ttsInit 会自动关闭旧引擎；如果需要在页面切换时彻底释放资源，可调用 ttsShutdown()。

7. 线程安全：所有 TTS 操作应在主线程调用，UTS 模块内部未做线程调度。

8. 正常调用模板

   
   <template>
   <view class="page-container">
       <NavBar title="TTS测试" :showBack="true" />
   
       <scroll-view scroll-y class="scroll-content">
           <view class="content-wrapper">
               <!-- 状态指示 -->
               <view class="status-bar">
                   <view class="status-item">
                       <view class="status-dot" :class="ttsReady ? 'dot-green' : 'dot-red'" />
                       <text class="status-text">{{ ttsReady ? 'TTS已就绪' : 'TTS未就绪' }}</text>
                   </view>
                   <view class="status-item">
                       <view class="status-dot" :class="speaking ? 'dot-blue' : 'dot-gray'" />
                       <text class="status-text">{{ speaking ? '正在朗读' : '空闲' }}</text>
                   </view>
               </view>
   
               <!-- 文本输入 -->
               <view class="section">
                   <text class="section-label">朗读文本</text>
                   <textarea
                       v-model="textContent"
                       class="text-input"
                       placeholder="输入要朗读的文字..."
                       :maxlength="500"
                   />
               </view>
   
               <!-- 语言选择 -->
               <view class="section">
                   <text class="section-label">语言</text>
                   <view class="lang-group">
                       <view
                           v-for="lang in langList"
                           :key="lang.value"
                           class="lang-chip"
                           :class="curLang === lang.value ? 'lang-chip-active' : ''"
       @click="curLang = (lang.value as string)"
                       >
                           <text class="lang-chip-text">{{ lang.label }}</text>
                       </view>
                   </view>
               </view>
   
               <!-- 参数滑块 -->
               <view class="section">
                   <text class="section-label">语速: {{ speed.toFixed(1) }}</text>
                   <slider
                       class="param-slider"
                       :value="speed"
                       :min="0.5"
                       :max="2.0"
                       :step="0.1"
                       @change="onSpeedChange"
                   />
               </view>
   
               <view class="section">
                   <text class="section-label">音调: {{ pitch.toFixed(1) }}</text>
                   <slider
                       class="param-slider"
                       :value="pitch"
                       :min="0.5"
                       :max="2.0"
                       :step="0.1"
                       @change="onPitchChange"
                   />
               </view>
   
               <view class="section">
                   <text class="section-label">音量: {{ volume.toFixed(1) }}</text>
                   <slider
                       class="param-slider"
                       :value="volume"
                       :min="0.0"
                       :max="1.0"
                       :step="0.1"
                       @change=""
                   />
               </view>
   
               <!-- 操作按钮 -->
               <view class="btn-group">
                   <button class="btn-speak" :class="!ttsReady ? 'btn-disabled' : ''" :disabled="!ttsReady" @click="handleSpeak">
                       朗读
                   </button>
                   <button class="btn-stop" :class="!ttsReady ? 'btn-disabled' : ''" :disabled="!ttsReady" @click="handleStop">
                       停止
                   </button>
               </view>
   
               <!-- 快捷文本 -->
               <view class="section">
                   <text class="section-label">快捷文本</text>
                   <view class="quick-group">
                       <view
                           v-for="qt in quickTexts"
                           :key="qt"
                           class="quick-chip"
                           @click="textContent = qt"
                       >
                           <text class="quick-chip-text">{{ qt }}</text>
                       </view>
                   </view>
               </view>
   
               <!-- 日志 -->
               <view class="section">
                   <text class="section-label">运行日志</text>
                   <view class="log-box">
                       <text
                           v-for="(log, i) in logs"
                           :key="i"
                           class="log-line"
                       >{{ log }}</text>
                       <text v-if="logs.length === 0" class="log-empty">暂无日志</text>
                   </view>
               </view>
   
               <view class="bottom-space" />
           </view>
       </scroll-view>
   </view>
   </template>