更新记录

1.0.1（2026-08-26） 下载此版本

新增

• 语速控制：TtsSpeakerOptions.speechRate（倍率 0.5~2.0，默认 1.0）、setSpeechRate()、speechMessage 第二参数单次临时语速（TSpeechOptions.speechRate）
• 静音控制：TtsSpeakerOptions.alwaysPlay（true=静音也出声 / false=静音状态跳过播报），iOS / Android / 鸿蒙三端支持

修复

• iOS：播报无声问题 —— 播报前激活 AVAudioSession；ambient 类别在系统静音键下静音，alwaysPlay=true 切换 playback 类别强制出声
• iOS：speechMessage 声明为 async 导致闪退（UTS iOS 异步函数基于协程、仅 iOS 13+，且 AVFoundation 需主线程），改回同步方法
• Android：初始化回调在「语言数据丢失 / 不支持该语言」时 success 误报为 0，修正为 -1

重构

• 鸿蒙：从废弃 API @ohos.ai.textToSpeech 重写为 @kit.CoreSpeechKit（最低 API 12），语速经 extraParams.speed 传入，静音检测使用 @kit.AudioKit 的 getRingerMode

示例

• 示例页新增语速滑杆（0.5x~2.0x）与「静音也出声」开关

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

first

平台兼容性

uni-app(4.01)

uni-app x(4.01)

w-tts-speaker UTS 插件发布文档

功能简介

w-tts-speaker 是一个跨平台文本转语音（TTS）插件，支持在 uni-app 的 App 端（Android / iOS / 鸿蒙）将文本内容转换为语音播放。插件封装了系统原生 TTS 引擎：

• Android：基于 android.speech.tts.TextToSpeech 系统 API，最低支持 Android SDK 19
• iOS：基于 AVFoundation.AVSpeechSynthesizer，最低支持 iOS 12
• 鸿蒙（HarmonyOS）：基于 @kit.CoreSpeechKit（textToSpeech），最低支持 HarmonyOS NEXT（API 12+）

平台兼容性

API 参考

类型定义

// 语音播报结果
type TSpeakResult = {
    success: number    // 0 成功，非0 失败
    message: string    // 结果描述信息
}

// TTS 初始化参数（预留）
type TSpeakInitParams = {
    lang: string
    country: string
    speechRate?: number
}

// 回调函数类型
type TtsCallback = (res: TSpeakResult) => void

// 构造选项
type TtsSpeakerOptions = {
    callback?: TtsCallback | null   // 初始化完成回调
    language: "ZH" | "EN" | string  // 语言选择
    speechRate?: number             // 默认语速倍率，1.0=正常，建议 0.5~2.0，默认 1.0
    alwaysPlay?: boolean            // true=静音模式也出声；false=静音状态跳过播报。iOS 切换 playback/ambient，Android/鸿蒙检测静音状态。默认 false
}

// 单次播报选项
type TSpeechOptions = {
    speechRate?: number             // 临时语速倍率，覆盖默认值，仅本次生效
}

TtsSpeaker 类

构造函数

new TtsSpeaker(options: TtsSpeakerOptions)

创建 TTS 扬声器实例并初始化语音引擎。

参数说明：

回调结果（Android）：

回调结果（iOS）：

回调结果（鸿蒙）：

speechMessage(msg: string, options?: TSpeechOptions): Promise\<void>

将指定文本转换为语音并播放。

参数：

注意：

• Android 端使用 QUEUE_FLUSH 模式，调用后会清空待播放队列并立即播放新内容
• iOS 端调用前会自动激活 AVAudioSession；类别取决于 alwaysPlay：false（默认）为 ambient（跟随静音键、可与其它音频共存），true 为 playback（静音也出声）
• 鸿蒙端基于 @kit.CoreSpeechKit，通过 speak(text, speakParams) 播放，语速经 extraParams.speed 传入

setSpeechRate(rate: number): void

设置默认语速（倍率），1.0 为正常，建议 0.5~2.0，越界自动 clamp。设置后对后续播报生效。

• Android：调用 TextToSpeech.setSpeechRate()
• iOS：换算为 AVSpeechUtterance.rate（默认 0.5 × 倍率，clamp 到 [0, 1]）
• 鸿蒙：播报时经 SpeakParams.extraParams.speed 传入，setSpeechRate 更新默认值、下次播报生效

stopSpeech(): void

停止当前正在播放的语音。

• Android：调用 TextToSpeech.stop()
• iOS：调用 AVSpeechSynthesizer.stopSpeaking(at: .immediate)，立即停止
• 鸿蒙：调用引擎 stop()，立即停止

使用示例

基本用法

import { TtsSpeaker } from '@/uni_modules/w-tts-speaker';

// 创建 TTS 实例（中文）
const speaker = new TtsSpeaker({
    language: "ZH",
    callback: (res) => {
        if (res.success === 0) {
            console.log("TTS 初始化成功");
            // 初始化完成后播放文本
            speaker.speechMessage("你好，世界！");
        } else {
            console.error("TTS 初始化失败:", res.message);
        }
    }
});

// 停止播放
speaker.stopSpeech();

英文播报

const speaker = new TtsSpeaker({
    language: "EN",
    callback: (res) => {
        if (res.success === 0) {
            speaker.speechMessage("Hello, world!");
        }
    }
});

使用 async/await

const speaker = new TtsSpeaker({
    language: "ZH"
});

// speechMessage 返回 Promise，可以 await
await speaker.speechMessage("请注意，前方有障碍物。");
console.log("播报完成");

语速控制

// 方式一：初始化时设置默认语速（1.5 倍速）
const speaker = new TtsSpeaker({
    language: "ZH",
    speechRate: 1.5
});

// 方式二：运行时调整默认语速
speaker.setSpeechRate(2.0);

// 方式三：单次播报临时语速（仅本次生效，不改变默认值）
await speaker.speechMessage("这是一句慢速播报。", { speechRate: 0.5 });

权限配置

Android

插件无需额外声明运行时权限，系统 TTS 引擎由 Android 系统内置支持。但如果设备未安装 TTS 语音数据包，初始化时会回调 success: -1, message: "语言数据丢失"，需引导用户下载语音数据。

静音行为由 alwaysPlay 控制：false（默认）播报前检测设备状态，铃声静音/振动或媒体音量为零时跳过播报；true 强制播报。

如需在 AndroidManifest.xml 中添加权限，可在 utssdk/app-android/AndroidManifest.xml 中配置。

iOS

插件无需额外权限配置。播报音频会话类别由 alwaysPlay 控制：false（默认）使用 AVAudioSession.Category.ambient，可与背景音乐等其他音频共存，但跟随系统静音键（静音模式下无声）；true 使用 Category.playback，静音模式下也会出声（适合导航、提醒类播报）。

HarmonyOS

播报（@kit.CoreSpeechKit）与静音状态查询（@kit.AudioKit 的 getRingerMode）均无需额外权限。如需修改系统铃声模式，才需要申请 ohos.permission.MODIFY_AUDIO_SETTINGS。

静音行为由 alwaysPlay 控制：false（默认）播报前检测铃声模式，静音/振动模式下跳过播报；true 强制播报。

依赖信息

本插件无第三方依赖，仅使用系统原生 API：