更新记录
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 后:
- 在插件详情页 试用/购买 并绑定当前 AppID 工程
manifest.json配置 AppID- 制作自定义调试基座 → 运行到自定义基座(真机)
一般无需额外危险权限;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。
点击下载体验
扫码体验

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 933
赞赏 0
下载 12768972
赞赏 1959
赞赏
京公网安备:11010802035340号