更新记录

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

初次提交

平台兼容性

uni-app x(4.75)

其他

laoqianjunzi-tts

laoqianjunzi-tts 是一个面向 uni-app x 的 UTS 语音播报插件，提供统一的文字转语音能力，覆盖 Android、iOS、Harmony、Web 四个平台。

插件特点：

• 使用统一 API 发起播报、暂停、恢复、停止和资源释放。
• 可以读取当前运行时能力、可用语言列表和平台侧语音引擎信息。
• 提供示例页面，便于直接验证不同平台的播报行为。
• 所有能力均围绕当前插件接口设计，不要求额外兼容层接入。

示例页面位置：uni_modules/laoqianjunzi-tts/pages/index.uvue

适用环境

基于当前插件配置，推荐环境如下：

支持平台

注意：

• 受限 表示提供了同名方法，但行为不等同于真正的原生断点暂停恢复。
• 返回结果会受到系统语音包、设备语言资源、浏览器能力和厂商 ROM 的影响。

安装与引入

将插件放入项目 uni_modules 目录后，直接从插件根路径引入：

import {
  ttsDescribeRuntime,
  ttsDispose,
  ttsListEngines,
  ttsListLocales,
  ttsOpenSettings,
  ttsPause,
  ttsResume,
  ttsSpeak,
  ttsStop
} from '@/uni_modules/laoqianjunzi-tts'

import type {
  LqjTtsEvent,
  LqjTtsOptions,
  LqjTtsRuntime
} from '@/uni_modules/laoqianjunzi-tts'

建议在页面卸载时主动释放资源：

onUnload(() => {
  ttsDispose()
})

快速开始

下面是最常用的播报示例：

import { ttsDispose, ttsSpeak } from '@/uni_modules/laoqianjunzi-tts'
import type { LqjTtsEvent, LqjTtsOptions } from '@/uni_modules/laoqianjunzi-tts'

function buildRequest(): LqjTtsOptions {
  return {
    text: '你好，这是一段来自 laoqianjunzi-tts 的示例播报。',
    pitch: 1,
    rate: 1,
    locale: 'zh-CN',
    androidEngine: null,
    onReady: (payload: LqjTtsEvent) => {
      console.log('ready', payload.category, payload.detail)
    },
    onError: (payload: LqjTtsEvent) => {
      console.log('error', payload.category, payload.detail)
    },
    onComplete: () => {
      console.log('playback complete')
    }
  }
}

function playSpeech(): void {
  ttsSpeak(buildRequest())
}

onUnload(() => {
  ttsDispose()
})

API 总览

类型说明

LqjTtsEvent

type LqjTtsEvent = {
  category: string
  detail: string
}

字段说明：

• category：事件类别，例如 ready、error。
• detail：当前平台返回的可读描述，用于日志输出或调试提示。

LqjTtsOptions

type LqjTtsOptions = {
  text: string
  pitch: number | null
  rate: number | null
  locale: string | null
  androidEngine: string | null
  onReady: ((payload: LqjTtsEvent) => void) | null
  onError: ((payload: LqjTtsEvent) => void) | null
  onComplete: (() => void) | null
}

字段说明：

LqjTtsRuntime

type LqjTtsRuntime = {
  platformName: string
  engineName: string
  supportsPause: boolean
  supportsEngineSelection: boolean
  supportsSettingsJump: boolean
}

典型用途：

• 根据 supportsPause 控制页面是否展示“暂停/恢复”按钮。
• 根据 supportsEngineSelection 决定是否提供 Android 引擎输入框。
• 根据 supportsSettingsJump 决定是否展示“打开系统设置”入口。

详细 API 说明

ttsSpeak(request: LqjTtsOptions)

发起一次新的语音播报。

调用建议：

• text 为空时，会进入 onError 回调。
• locale 为空时，各平台会使用默认中文环境，默认值为 zh-CN 或等价区域设置。
• 如果当前平台支持的语言资源不足，也会进入 onError。
• 这是同步调用入口，不返回 Promise，状态结果通过回调获取。

关于 onReady：

• onReady 表示“当前任务已经进入可播报阶段”或“实际开始播报”。
• 不同平台触发时机不同，不能把它当作唯一的一次性成功回调。
• Android 和 Harmony 在首次初始化引擎时，可能先反馈“引擎已就绪”，随后再反馈“任务已开始”。

关于 onComplete：

• 仅在文本自然播报完成时触发。
• ttsStop()、受限平台上的 ttsPause()、页面销毁后的释放，不保证触发 onComplete。

ttsPause()

请求暂停当前播报。

平台差异：

• iOS、Web：支持实际暂停。
• Android：内部使用停止当前播报的方式处理，不能视为精确断点暂停。
• Harmony：内部同样不是严格断点暂停。

如果页面需要展示暂停按钮，建议先结合 ttsDescribeRuntime().supportsPause 判断。

ttsResume()

恢复当前播报。

平台差异：

• iOS、Web：恢复暂停中的语音任务。
• Android：会基于上一次文本重新触发播报，不保证从暂停位置继续。
• Harmony：会重新基于最近一次请求继续执行，不保证从原断点续播。

ttsStop()

立即停止当前播报。

适用场景：

• 用户主动打断当前播报。
• 页面切换前停止声音输出。
• 发起新任务前先清理旧任务。

ttsListEngines()

获取平台侧的引擎列表或语音配置摘要。

返回规则：

• Android：返回系统 TTS 引擎名称列表，可用于 androidEngine 字段。
• iOS：返回空数组，因为当前实现不提供引擎切换。
• Harmony：返回语音配置描述字符串，例如 zh-CN | gender=... | style=... | desc=...。
• Web：返回浏览器可用 voice 名称列表。

注意：

• Android 在语音引擎尚未初始化时，可能返回空数组。若要读取更准确的引擎列表，建议至少先调用一次 ttsSpeak()。
• Harmony 返回的是“语音档案摘要”，不是 Android 意义上的引擎包名。

ttsListLocales()

获取当前平台可用的语言列表。

返回规则：

• Android：返回系统可用语言标签。
• iOS：返回 AVSpeechSynthesisVoice 提供的语言代码列表。
• Harmony：返回当前可查询到的语言列表；若语音目录尚未刷新，可能先返回默认或最近一次请求语言。
• Web：返回浏览器 voice 对应的语言标签。

建议：

• 将返回值直接作为 locale 候选项供用户选择。
• 不要假设不同设备返回顺序一致。

ttsDispose()

释放插件占用的内部资源。

推荐时机：

• 页面 onUnload。
• 长时间不再使用播报能力时。
• 测试页面反复切换时，避免遗留上一次引擎状态。

ttsOpenSettings()

尝试打开系统语音相关设置页面。

平台差异：

• Android：优先打开 TTS 设置页，失败时回退到系统设置页。
• iOS：尝试跳转到系统设置相关页面。
• Harmony、Web：当前实现不提供实际设置页跳转，仅输出日志说明。

注意：

• 该方法返回 void，不通过返回值指示是否成功跳转。
• 页面层最好先读取 supportsSettingsJump 再决定是否展示入口。

ttsDescribeRuntime()

获取当前运行平台的能力快照。

示例：

import { ttsDescribeRuntime } from '@/uni_modules/laoqianjunzi-tts'
import type { LqjTtsRuntime } from '@/uni_modules/laoqianjunzi-tts'

const runtimeInfo = ttsDescribeRuntime() as LqjTtsRuntime
console.log(runtimeInfo.platformName)
console.log(runtimeInfo.engineName)
console.log(runtimeInfo.supportsPause)

适合用于：

• 页面初始化时渲染平台能力卡片。
• 针对不同平台隐藏不适用的功能按钮。
• 调试时确认当前接入的是哪一套底层实现。

参数范围与默认值

pitch 与 rate 在不同平台会自动收敛到各自可接受范围，不需要业务层自行裁剪，但建议仍然传入合理值。

推荐值：

• 中文常规播报：rate = 1、pitch = 1
• 稍慢说明型播报：rate = 0.75 ~ 0.9
• 英文播报：先配合 locale = 'en-US'，再根据实际发音调整 rate 与 pitch

推荐接入流程

1. 页面初始化时调用 ttsDescribeRuntime()，先判断当前平台支持情况。
2. 根据平台能力决定是否展示暂停、设置跳转、引擎选择等控件。
3. 发起播报时使用 ttsSpeak()，通过 onReady、onError、onComplete 记录状态。
4. 需要时调用 ttsListLocales()、ttsListEngines() 填充候选项。
5. 页面销毁时调用 ttsDispose()，避免保留底层语音资源。

注意事项

• 插件面向 uni-app x 使用，不建议按普通 uni-app 页面模式接入。
• locale 建议统一使用带连字符的语言标签格式，例如 zh-CN、en-US。
• androidEngine 只在 Android 生效，其他平台会忽略该字段。
• ttsPause() 与 ttsResume() 是否可用，应以 ttsDescribeRuntime() 返回值为准，不要只根据方法是否存在来判断。
• ttsListEngines()、ttsListLocales() 的返回值依赖用户设备，不应在业务中写死数量、排序或具体内容。
• 如果要做完整交互验证，可以直接运行示例页 uni_modules/laoqianjunzi-tts/pages/index.uvue。

示例页面说明

插件内置页面示例包含以下内容：

• 运行时能力读取
• 文本、语言、语速、音调配置
• Android 引擎名称输入
• 引擎列表与语言列表读取
• 播报日志实时输出

示例页路径：uni_modules/laoqianjunzi-tts/pages/index.uvue

如果你需要在业务页面中快速落地，建议先运行示例页确认目标设备上的语言包与播报行为，再复制相关调用方式到正式页面。