更新记录

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）：基于 @ohos.ai.textToSpeech 系统 API

平台兼容性

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  // 语言选择
}

TtsSpeaker 类

构造函数

new TtsSpeaker(options: TtsSpeakerOptions)

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

参数说明：

回调结果（Android）：

回调结果（iOS）：

回调结果（鸿蒙）：

speechMessage(msg: string): Promise\<void>

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

参数：

注意：

• Android 端使用 QUEUE_FLUSH 模式，调用后会清空待播放队列并立即播放新内容
• iOS 端调用前会自动设置 AVAudioSession 为 ambient 类别（可与其它音频共存）
• 鸿蒙端使用 SPEAK_MODE_SYNC 模式，同步播放

stopSpeech(): void

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

• Android：调用 TextToSpeech.stop()
• iOS：调用 AVSpeechSynthesizer.stopSpeaking(at: .immediate)，立即停止
• 鸿蒙：调用 textToSpeech.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("播报完成");

权限配置

Android

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

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

iOS

插件无需额外权限配置。播报音频自动使用 AVAudioSession.Category.ambient 类别，可与背景音乐等其他音频共存。

依赖信息

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