更新记录

1.4.0（2026-10-13）

• 更新文档说明

1.3.9（2026-10-13）

• 优化安卓端、鸿蒙端、iOS 端，修复播报完成回调（finish）不触发或错配的问题
• 优化 Web 端，修复连续播报时误触发上一次完成回调的问题
• 优化四端语音参数，language 参数生效，重复调用时语速、音调、语言同样生效
• 优化四端异常处理，合成/播报失败不再静默
• 优化连续播报：安卓、Web、iOS 改为排队依次播报，不再互相打断
• 优化 iOS 端音频会话，播报结束后释放，不再长期占用并压低其他 App 音量
• 补齐安卓端 getAllSupportLanguage、Web 端支持语言查询与实例销毁、iOS 端实例销毁
• 移除安卓端、鸿蒙端无用权限，清理 Web 端无用文件

1.3.8（2026-03-10）

• 修复IOS端与其他插件同时使用出现音频权限抢占冲突的问题

平台兼容性

uni-app(4.66)

uni-app x(4.66)

其他

xwq-tts-speaker

将文本转成语音播报，支持自定义第三方 TTS 引擎（仅安卓）。

• 支持平台：App-Android、App-iOS、App-HarmonyOS、Web(H5)
• 当前版本：1.3.9 ｜ 更新日志见 changelog.md
• 环境要求：HBuilderX 4.45+，uni-app / uni-app x 4.66+

⚠️ 升级提示：1.2 版本起调整了安卓端的 API 调用方式，从旧版升级请参照下方示例改写。

一、平台支持

Web 端仅支持 Chrome、Safari、Edge 浏览器。

二、API 一览

图例：✅ 已实现 ⚠️ 语义差异 — 该端暂不支持

旧版安卓 API 已废弃：init、startSpeak、setSpeechRate（旧签名）等，1.2 版本后请使用上表的新 API。

三、参数说明

startSpeech(opt) 中 opt 的字段：

四、平台能力说明

HarmonyOS

• 引擎不提供 pause / resume 接口，因此 pauseSpeech 等同停止、continueSpeech 不产生播报行为
• 语种在创建引擎时确定，运行中切换 language 需先 destroyTTS() 再重新播报
• 单次播报文本上限 10000 字符
• 主动停止时不回调 finish / fail（与 Android、iOS 行为一致）

Android

• 支持指定第三方 TTS 引擎，enginesName 需为手机已安装引擎的包名（可用 getEngines() 获取），未安装会回调 fail
• pauseSpeech 语义为停止，continueSpeech 从头重播

iOS

• 语速有效范围 0.0 ~ 1.0（未传时使用系统默认速率 0.5），音高有效范围 0.5 ~ 2.0
• openSetting 打开的是本应用的设置页 —— iOS 不允许 App 跳转到系统「文字转语音」设置页

Web(H5)

• 依赖浏览器 speechSynthesis，仅 Chrome / Safari / Edge 支持
• 部分浏览器要求页面先有用户交互，才能开始播报；被策略拦截时会回调 fail

通用

• getAllSupportLanguage：iOS 与 Web 可返回真实语言列表；Android / HarmonyOS 的系统引擎未提供查询接口，返回空数组
• enginesName 指定的引擎必须已安装，否则会回调 fail
• 超长文本建议按句号或长度分段后分批播报

五、代码示例

示例一：完整用法

适用于 uni-app x 项目（Android / HarmonyOS / iOS 通用）。Web 端 API 完全一致，可直接复用。

<template>
    <view>
        <view class="area">
            <textarea @input="iptHandle"
                style="width: 100%;border: 1px solid #ccc;padding: 15px;background-color: #f2f2f2;margin-bottom: 15px;" />
            <button type="default" @click="start">文本转语音播报</button>
            <button type="default" @click="stop">停止播报</button>
            <button type="default" @click="getEnginesList">获取手机播报引擎</button>
            <button type="default" @click="openSysSetting">打开设置页面</button>
        </view>
        <view class="eng-list" style="padding: 15px;">
            <view class="title">
                <text style="font-weight: bold;font-size: 20px;">引擎列表：</text>
            </view>
            <view v-for="(i,k) in engineList" :key="k" class="item">
                {{ i }}
            </view>
        </view>
    </view>
</template>

<script setup>
    import { startSpeech, stopSpeech, getEngines, openSetting } from "@/uni_modules/xwq-tts-speaker";
    import { Option, Info } from "@/uni_modules/xwq-tts-speaker/utssdk/interface.uts";

    const iptVal = ref("");
    const engineList = ref([] as string[]);

    const iptHandle = (e : UniInputEvent) => {
        iptVal.value = e.detail.value;
    };

    // 开始播报
    const start = () => {
        startSpeech({
            content: iptVal.value,       // 播报内容
            enginesName: null,           // 第三方引擎名，传 null 用系统默认（仅安卓生效）
            pitch: 1,                    // 音调，默认 1，越小越偏男声
            speechRate: 1,               // 语速，默认 1
            language: 'zh-CN',           // 语言，默认 zh-CN
            success: (val : Info) => {
                console.log('初始化成功', val);
            },
            fail: (val : Info) => {
                console.log('播报失败', val);
            },
            finish: () => {
                console.log('播报结束');
            }
        } as Option);
    };

    // 停止播报
    const stop = () => {
        stopSpeech();
    };

    // 获取引擎列表
    const getEnginesList = () => {
        engineList.value = getEngines();
    };

    // 打开系统设置
    const openSysSetting = () => {
        openSetting();
    };
</script>

注：Option / Info 来自插件的内部类型定义，仅用于类型标注；uni-app（非 x）项目无需引入。

示例二：uni-app（非 x）项目

<template>
    <view>
        <textarea @input="iptHandle"
            style="width: 100%;border: 1px solid #ccc;padding: 15px;background-color: #f2f2f2;margin-bottom: 15px;" />
        <button type="default" @click="start">文本转语音播报</button>
        <button type="default" @click="stop">停止播报</button>
    </view>
</template>

<script setup>
    import { startSpeech, stopSpeech } from "@/uni_modules/xwq-tts-speaker";

    const iptVal = ref("");

    const iptHandle = (e) => {
        iptVal.value = e.detail.value;
    };

    const start = () => {
        startSpeech({
            content: iptVal.value,
            enginesName: null,
            pitch: 1,
            finish: () => {
                console.log('播报结束');
            }
        });
    };

    const stop = () => {
        stopSpeech();
    };
</script>

示例三：iOS 参数用法

import { startSpeech } from '@/uni_modules/xwq-tts-speaker';

startSpeech({
    content: '我家住在一个遥远的地方，美丽又安静！',
    speechRate: 0.5,   // iOS 语速范围 0.0 ~ 1.0
    pitch: 0.9,        // iOS 音高范围 0.5 ~ 2.0
    language: 'zh-CN',
    finish: () => {
        console.log('播报结束');
    }
});

六、常见问题

Q：调用后没有声音？ 先看是否收到 fail 回调；Android 可点「打开设置页面」检查系统 TTS 引擎是否可用，enginesName 指定的第三方引擎必须已安装。

Q：finish 没有触发？ 确认播报内容非空且未超长（鸿蒙上限 10000 字符）；若刚调用过 stopSpeech()，属于主动停止，按设计不会回调 finish。

Q：想用第三方 TTS 引擎？ 仅 Android 支持：先调用 getEngines() 拿到引擎名，再把名字传给 enginesName。

Q：continueSpeech() 没有续播？ HarmonyOS 引擎没有 resume 接口，Android 端该方法是「从头重播」，只有 iOS 与 Web 是真正的续播。

其他插件预览

• （兼容安卓、IOS）UTS 车牌识别插件
• (兼容IOS、安卓、鸿蒙)二维码、条码识别，mlkit扫码插件 毫秒级识别效率，支持多码识别，连续扫
• TTS（安卓、ios、鸿蒙、web）将文字转成语音播报
• （兼容安卓、IOS端）离线语音识别插件、支持离线语音
• （UNIAPPX原生播放器）仿抖音视频刷刷刷 刷视频 自动滑动视频，短剧刷视频必备神器
• (安卓、IOS) PDF预览插件
• (兼容安卓、鸿蒙端、iOS)onnx 大模型实时语音识别 wav音频文件转文本
• （兼容安卓、鸿蒙）录音插件，支持pcm实时回调，wav转换，后台录音
• （nvue）app端仿抖音短视频 丝滑切换视频效果，无限数据加载
• 兼容安卓、IOS端支持全局消息弹窗插件
• (支持安卓和IOS端)原生UTS组件svg插件
• （兼容IOS和安卓Web三端）SVGA 动画组件 支持自定义文本、图片，图层隐藏功能
• 系统权限验证、获取、跳转
• （兼容安卓、IOS、鸿蒙）二维码 qrcode 自定义logo图片 颜色可自定义
• 仿抖音短视频微信小程序 丝滑切换视频效果，无限数据加载不卡顿，咨询进IM交流群