更新记录

1.0.0（2026-07-03）

新版本发布，暂时只支持android，ios后续会更新上

平台兼容性

uni-app(4.0)

yzj-tts

yzj-tts 是一个面向 uni-app 的原生 TTS UTS 插件，Android 基于系统 TextToSpeech，iOS 基于系统 AVSpeechSynthesizer。插件提供初始化、文本播报、队列追加、音调/语速/音量设置、状态查询和事件监听能力，适用于扫码结果播报、表单提示、设备状态提醒等语音播报场景。

功能特性

• 文本转语音播报
• 支持 flush 替换播报、add 队列追加播报
• 支持语言、音调、语速、音量设置
• 支持停止播放、查询状态
• 支持监听 init、start、done、stop、error 事件

支持平台

非 App 平台调用时会返回 9031002。

快速开始

import {
  initTts,
  onTtsEvent,
  offTtsEvent,
  speakTts,
  stopTts,
  releaseTts
} from '@/uni_modules/yzj-tts'

let ttsListenerId: number | null = null

export async function startTtsDemo() {
  if (ttsListenerId == null) {
    ttsListenerId = onTtsEvent((event) => {
      console.log('[tts:event]', event)
      if (event.type === 'done') {
        console.log('[tts:done]', event)
      }
    })
  }

  await initTts({
    language: 'zh-CN',
    pitch: 1,
    speechRate: 1,
    volume: 1
  })

  await speakTts({
    text: '第一段播报',
    queueMode: 'flush'
  })

  await speakTts({
    text: '这是追加到后面的第二段播报',
    queueMode: 'add'
  })
}

export async function stopTtsDemo() {
  await stopTts()
}

export function destroyTtsDemo() {
  if (ttsListenerId != null) {
    offTtsEvent(ttsListenerId)
    ttsListenerId = null
  }
  releaseTts()
}

API

initTts

初始化 TTS 引擎。

initTts(options?: {
  language?: string
  pitch?: number
  speechRate?: number
  volume?: number
}): Promise<{
  ok: boolean
  errCode: number | null
  errMsg: string | null
  initialized: boolean
  language: string | null
  pitch: number
  speechRate: number
  volume: number
  enginePackage: string | null
  timestamp: number
}>

language 常用值说明：

language 补充说明：

• 不传或传空字符串时，Android 使用系统默认语言，iOS 优先使用当前系统语言
• Android 端依赖系统 TTS 引擎和语音包是否支持该语言；如果当前引擎不支持，会返回 9031006
• iOS 端会优先匹配你传入的语言；如果没有完全匹配的 voice，会继续尝试基础语言或系统可用 voice
• 建议优先使用标准写法，如 zh-CN、en-US，不要传随意字符串

speakTts

提交一段文本进行播报。

speakTts(options: {
  text: string
  utteranceId?: string
  queueMode?: 'flush' | 'add'
  language?: string
  pitch?: number
  speechRate?: number
  volume?: number
  onStart?: (event) => void
  onDone?: (event) => void
  onStop?: (event) => void
  onError?: (event) => void
}): Promise<{
  ok: boolean
  errCode: number | null
  errMsg: string | null
  accepted: boolean
  utteranceId: string
  queueMode: 'flush' | 'add'
  text: string
  timestamp: number
}>

• text: 要播报的文本，不能为空
• utteranceId: 本次播报任务 ID，不传时自动生成
• queueMode: 'flush': 打断当前播报并立即播放新文本
• queueMode: 'add': 追加到当前播报队列尾部
• language、pitch、speechRate、volume: 仅对本次播报生效，含义和范围同 initTts
• onStart、onDone、onStop、onError: 当前播报任务的生命周期回调

speakTts 中的 language 为“本次播报覆盖值”：

• 传了 language：仅当前这次播报按该语言执行
• 不传 language：沿用上一次 initTts() 或前一次成功播报后的当前语言设置

stopTts

停止当前播报。

stopTts(): Promise<{
  ok: boolean
  errCode: number | null
  errMsg: string | null
  stopped: boolean
  timestamp: number
}>

getTtsState

获取当前状态。

getTtsState(): {
  initialized: boolean
  speaking: boolean
  language: string | null
  pitch: number
  speechRate: number
  volume: number
  enginePackage: string | null
  lastUtteranceId: string | null
}

onTtsEvent

注册插件级事件监听。

onTtsEvent(listener: (event: {
  type: 'init' | 'start' | 'done' | 'stop' | 'error'
  utteranceId: string | null
  errCode: number | null
  errMsg: string | null
  timestamp: number
}) => void): number

返回监听器 ID，用于后续移除。

offTtsEvent

取消事件监听。

offTtsEvent(listenerId?: number): void

• 传 listenerId: 移除指定监听器
• 不传参数: 清空全部监听器

releaseTts

释放 TTS 引擎和监听器。

releaseTts(): void

释放后如果还要继续使用，需要重新调用 initTts()。

事件说明

推荐调用顺序

1. 调用 initTts() 初始化
2. 调用 onTtsEvent() 注册事件监听
3. 调用 speakTts() 开始播报
4. 需要中断时调用 stopTts()
5. 页面销毁或不再使用时调用 offTtsEvent() / releaseTts()

错误码

注意事项

• Android 依赖系统自带或用户已安装的 TTS 引擎
• queueMode: 'add' 是追加到后续队列，不是修改当前已经提交的那段文本
• 当前版本不提供暂停 / 继续能力，如需中断请使用 stopTts()
• 插件采用单例管理模式，不适合同一时刻维护多套独立 TTS 会话
• 建议在页面卸载时调用 offTtsEvent() 或 releaseTts() 清理监听和资源