更新记录

1.0.0(2026-11-17)

-文字转语音TTS


平台兼容性

uni-app(4.0)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ × × √ - 5.0 15 √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × × × × × × ×

uni-app x(4.0)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - 5.0 15 √ -

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
√ × × ×

ly028-TTS

uni-app / uni-app x 三端系统文字转语音 UTS 插件:本地播报、队列打断/追加、朗读进度、长文本自动分段、合成到文件;Android 可选引擎,iOS 可配音频会话。支持 Android / iOS / HarmonyOS。

调用本机系统 TTS,不依赖第三方云端语音包;无需联网即可播报(鸿蒙为离线引擎,音色以设备已安装为准)。

点击下载体验
扫码体验
扫码体验


平台支持

工程类型 Android iOS HarmonyOS
uni-app App ✅ ✅ ✅
uni-app x App ✅ ✅ ✅
能力 Android iOS HarmonyOS
播报 / 停止 ✅ ✅ ✅
暂停 / 继续 ✅(记位后重播) ✅(系统原生) ✅(pause≈stop,resume 从当前句开头)
队列打断 / 追加 ✅ ✅ ✅
朗读进度 progress ✅(引擎支持时) ✅ ✅(句级)
长文本自动分段 ✅ ✅ ✅
发音人 / 语言列表 ✅ ✅ ✅(中/英离线)
合成到文件 ✅ ✅(iOS 13+) ✅
引擎列表 / 系统设置 ✅ ❌(501) ❌(501)
音频会话选项 ❌(501) ✅ ❌(501)
  • 环境:uni-app 建议 HBuilderX 3.7.2+;uni-app x 建议 4.0+(鸿蒙建议 4.31+)
  • 调试:UTS 原生插件必须进入 自定义调试基座 或 正式云打包包体;普通标准基座不含本插件原生代码
  • 三端:Android / iOS / HarmonyOS 真机测试通过

功能一览

功能 API 说明
播报 speak 语速 / 音调 / 音量 / 语言 / 发音人;返回 utteranceId
队列模式 queueMode flush 打断当前;add 排队追加
停止 / 暂停 / 继续 stop / pause / resume 控制播报生命周期
状态查询 getStatus / isSpeaking 空闲 / 播报中 / 已暂停、队列长度
朗读进度 onTtsEvent → progress 原文 UTF-16 下标 start / end,可做高亮
发音人 getVoices [{id, name, language, quality?}]
语言列表 getLanguages 语言标签数组
能力探测 checkSupport 当前端可用能力一览
预热 / 释放 initEngine / destroy 提前初始化或彻底释放引擎
合成文件 synthesizeToFile 写出本地音频并可用 InnerAudio 试听
Android 引擎 getEngines / engine / openTtsSettings 选引擎、打开系统 TTS 设置
iOS 音频会话 setAudioSessionOptions 压低他人音量 / 混播 / 静音键下仍出声
多语言文案 setLocale / getLocale 插件返回消息:zh-Hans / en
调试日志 setLogEnabled / isLogEnabled 开关

你想做什么

需求 建议用法
点一下读一段话 speak({ text, language: 'zh-CN' })
连点播报要「抢话」换成新内容 queueMode: 'flush'(默认)
连点播报要「排成队」一句接一句 queueMode: 'add'
字幕跟读高亮 监听 progress,用 start/end 截取原文
很长一篇文案 直接 speak 长文本即可,插件自动分段
只要音频文件、不马上播 synthesizeToFile
换人声 getVoices → 把 id 传给 speak.voiceId
Android 换引擎 / 下语音包 getEngines + openTtsSettings
iOS 播报时压低音乐 setAudioSessionOptions({ duckOthers: true })
后台继续播 iOS:宿主开启后台音频;ignoreSilentSwitch: true

快速开始

1. 安装

在 DCloud 插件市场 搜索 ly028-TTS,导入到项目 uni_modules 后:

  1. 在插件详情页 试用/购买 并绑定当前 AppID 工程
  2. manifest.json 配置 AppID
  3. 制作自定义调试基座 → 运行到自定义基座(真机)

一般无需额外危险权限;iOS 若需后台播报,请在 App 模块配置中开启后台音频。

2. 最小示例

import {
  speak,
  stop,
  pause,
  resume,
  onTtsEvent,
  offTtsEvent,
  setLocale,
  setLogEnabled
} from '@/uni_modules/ly028-TTS'

setLocale('zh-Hans') // 可选:插件提示文案语言
setLogEnabled(true)  // 可选:调试日志

onTtsEvent((e) => {
  // e.type: start / progress / paused / resumed / done / error
  if (e.type === 'progress') {
    // 用 e.start / e.end 高亮原文片段
    console.log('朗读区间', e.start, e.end)
    return
  }
  console.log(e.type, e.utteranceId, e.msg)
})

speak(
  {
    text: '你好,欢迎使用 ly028 文字转语音。',
    language: 'zh-CN',
    rate: 1.0,
    pitch: 1.0,
    volume: 1.0,
    queueMode: 'flush' // 打断当前;改成 'add' 则追加排队
  },
  (ret) => {
    if (ret.code !== 0) {
      uni.showToast({ title: ret.msg, icon: 'none' })
      return
    }
    const data = JSON.parse(ret.data || '{}')
    // data.utteranceId — 与事件里的 utteranceId 对应
    console.log('utteranceId', data.utteranceId)
  }
)

// 页面卸载时:
// offTtsEvent()

3. 打断 vs 追加(务必读懂)

queueMode 效果 适用
flush(默认) 打断当前:立刻停掉正在说的,清空队列,换成这段新话 导航播报、点击即读最新内容
add 排队追加:不打断,说完当前这段再接下一段 多条消息依次播报

连点「播报」就能体会:flush 会抢话,add 会排成队。

// 追加一句,不打断当前
speak({ text: '第二句', queueMode: 'add' })

4. 合成到文件并试听

import { synthesizeToFile } from '@/uni_modules/ly028-TTS'

synthesizeToFile(
  '把这段话合成文件。',
  { language: 'zh-CN', rate: 1.0 },
  (ret) => {
    if (ret.code !== 0) return
    const { path } = JSON.parse(ret.data || '{}')
    const audio = uni.createInnerAudioContext()
    audio.src = path.indexOf('://') > 0 ? path : 'file://' + path
    audio.play()
  }
)

API

方法 说明 返回
speak(options, callback?) 播报 回调 TtsResult;成功 data 含 utteranceId 等
stop(callback?) 停止并清空队列 TtsResult
pause(callback?) 暂停 TtsResult
resume(callback?) 继续 TtsResult
getStatus(callback) 当前状态 data: {status, utteranceId, queueSize}
isSpeaking(callback) 是否正在播报(暂停中为 false) boolean
getVoices(callback) 发音人列表 data JSON 数组
getLanguages(callback) 语言标签列表 data JSON 数组
checkSupport(callback) 能力探测 code 恒 0;见 data.features
initEngine(options?, callback?) 预热引擎;Android 可传 { engine } TtsResult
destroy(callback?) 停止并释放引擎(下次自动重建) TtsResult
synthesizeToFile(text, options?, callback) 合成到缓存目录文件 data: {path, utteranceId, ...}
getEngines(callback) 仅 Android 引擎列表 其他端 501
openTtsSettings(callback?) 仅 Android 打开系统 TTS 设置 其他端 501
setAudioSessionOptions(options, callback?) 仅 iOS 音频会话 其他端 501
onTtsEvent(callback) / offTtsEvent() 监听 / 取消生命周期事件 —
setLocale(locale) / getLocale() 插件消息语言 —
setLogEnabled(bool) / isLogEnabled() 调试日志 —

回调结果统一为信封:

{ "code": 0, "msg": "ok", "data": "{ ... }", "subCode": 400 }
字段 说明
code 0 成功,1 失败
subCode 失败细分码,见下文(成功时可无)
msg 提示文案(随 setLocale)
data 成功时多为 JSON 字符串,请再 JSON.parse

speak 参数

字段 类型 默认 说明
text string 必填 要播报的文本
rate number 1.0 语速 0.5 ~ 2.0
pitch number 1.0 音调 0.5 ~ 2.0
volume number 1.0 音量 0 ~ 1
language string 平台默认 如 zh-CN / en-US
voiceId string — 来自 getVoices;未命中则回退 language,成功时 voiceFallback=true
queueMode string flush flush 打断 / add 追加
utteranceId string 自动生成 自定义 id,事件与回调会带回
engine string 系统默认 仅 Android,来自 getEngines 的 name

成功时 data 常见字段:

字段 说明
utteranceId 本句标识,与事件对应
chunks 分段数量(长文本)
voiceFallback 指定发音人未命中、已回退语言时为 true

synthesizeToFile 参数

第二个参数 options:

字段 说明
rate / pitch / volume / language / voiceId 同 speak
fileName 仅文件名;写入应用缓存目录 ly028-tts/
平台 默认格式 说明
Android 由引擎决定(常见 WAV) 文本过长可能返回 422
iOS 13+ .caf;也可 .wav / .aif / .aiff iOS 12 返回 501
HarmonyOS .wav(16k/16bit PCM);也可 .pcm 其他扩展名 422

成功 data 常见字段:path、utteranceId、size 等。


事件 onTtsEvent

type 说明
start 开始播报某一句
progress 朗读进度;start/end 为原文 UTF-16 下标
paused / resumed 暂停 / 继续
done 结束(含被 stop 打断时,可能带 msg)
error 失败;可看 errorCode / msg

事件字段:type、utteranceId、msg、start、end、errorCode。

页面离开时请调用 offTtsEvent(),避免重复监听。


暂停 / 继续 / 进度(三端差异)

Android iOS HarmonyOS
暂停 停止并记住最近朗读位置 系统原生暂停 等同停止
继续 从记住的位置重新播 系统原生继续 从当前句开头再播
进度 字词级(引擎提供时) 字词级 句级(按分段)

错误码 subCode

subCode 含义 常见场景
400 参数错误 空文本、非法 queueMode
404 未找到 Android 指定引擎未安装、无 TTS 设置页
409 状态冲突 未播报时 pause、未暂停时 resume、合成被 stop 打断
422 无法处理 文本超长、语言不支持、输出扩展名不支持
500 内部错误 引擎初始化失败、音频会话失败
501 平台不支持 如 iOS 调 getEngines、Android 调 setAudioSessionOptions

使用须知

项 说明
系统引擎 发音人、音质、是否支持某语言取决于设备已安装的 TTS 引擎/音色包
长文本 可直接传入长文,插件自动分段;进度下标已换算回原文
权限 Android 无需危险权限;声明了 TTS 相关查询。iOS 后台播报需宿主开启后台音频
隐私 播报与合成在设备端完成,插件不上传文本
鸿蒙音色 离线中文 / 英文;voiceId 形如 zh-CN-13、en-US-8
鸿蒙长度 单次文本建议 ≤ 10000 字;过长分段处理

常见问题

Q:标准基座里调用没反应?
A:必须使用自定义调试基座或云打包正式包。

Q:flush 和 add 到底怎么选?
A:要「永远播最新一句」用 flush;要「多句排队播完」用 add。连点播报最容易听出差别。

Q:没有 progress 高亮?
A:Android 部分引擎不回调字词进度;鸿蒙为句级。可先 checkSupport 看能力,或换引擎(Android openTtsSettings)。

Q:iOS 静音键没声音?
A:调用 setAudioSessionOptions({ ignoreSilentSwitch: true })(默认即为 true)。

Q:iOS 进后台就停?
A:在宿主 App 开启后台音频(UIBackgroundModes 含 audio),并保持播报会话选项正确。

Q:鸿蒙 pause 后继续像重播?
A:属平台能力限制:pause≈stop,resume 从当前句开头再播。

Q:换了 voiceId 还是默认声?
A:查看回调 voiceFallback;未命中时会回退 language。请用 getVoices 返回的真实 id。


更新日志

详见同目录 changelog.md。当前版本 1.1.1。


点击下载体验
扫码体验
扫码体验

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android:无危险权限,Manifest 声明 TTS_SERVICE <queries>;iOS:AVAudioSession 播放(后台播报需宿主开启 UIBackgroundModes audio);HarmonyOS:@kit.CoreSpeechKit textToSpeech 离线引擎

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据,仅调用系统 TTS 引擎本地播报

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。