更新记录

1.0.0（2026-01-27）

• feat: 提供语音合成（TTS）核心 API（Android/iOS）
• feat: 新增 playground 验证页（uniappx-speech-playground/pages/index/index.uvue）
• docs: 完善使用文档与发布/实现说明

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-speech

uni-app / uni-app x App 端语音合成（TTS）插件（Android / iOS）。

平台

• Android / iOS：支持（App 端）
• Harmony / Web / 小程序：不支持

说明：

• 本插件为 TTS（语音合成），不需要麦克风/语音识别权限
• Android onBoundary 仅在 API 26+ 触发（系统限制）

安装

• 插件市场安装后，会在项目根目录生成 uni_modules/hans-speech/
• 或将 hans-speech 文件夹复制到你的项目 uni_modules/ 下

引入

import {
  speak,
  stop,
  pause,
  resume,
  getAvailableVoicesAsync,
  isSpeakingAsync,
  maxSpeechInputLength,
  getMaxSpeechInputLength,
  setLogEnabled,
  isLogEnabled,
} from '@/uni_modules/hans-speech'

快速开始

speak('你好', {
  language: 'zh-CN',
  rate: 1.0,
  pitch: 1.0,
  onStart: () => console.log('start'),
  onDone: () => console.log('done'),
  onStopped: () => console.log('stopped'),
  onBoundary: (e) => console.log(e.charIndex, e.charLength),
  onError: (e) => console.error(e.message),
})

停止/暂停/恢复/状态：

await stop()
const speaking = await isSpeakingAsync()

// iOS only
await pause()
await resume()

语音列表与选择发音人

const voices = await getAvailableVoicesAsync()
const v = voices.length > 0 ? voices[0] : null

speak('Hello', {
  voice: v?.identifier ?? '',
})

Voice 字段：

• identifier: string（用于 SpeechOptions.voice）
• name: string
• language: string（例如 zh-CN / en-US）
• quality: string（通常为 Default / Enhanced，平台返回值可能略有差异）

speak(text, options)

SpeechOptions：

• language?: string：语言/地区（例如 zh-CN / en-US），不传则使用系统默认语言
• rate?: number：语速，建议范围 0.1 ~ 2.0（不传则使用系统默认）
• pitch?: number：语调，建议范围 0.5 ~ 2.0（不传则使用系统默认）
• voice?: string：发音人 identifier（来自 getAvailableVoicesAsync()）
• useApplicationAudioSession?: boolean：仅 iOS 13+，不传则使用系统默认
• 回调：onStart / onBoundary / onDone / onStopped / onError

说明：

• 多次调用 speak() 会追加到队列；需要“打断并重播”请先 await stop() 再 speak()
• speak() 的错误通过 options.onError(error) 回调返回（error.message 中会包含错误码信息，例如 HansSpeechError(9010002): ...）

文本长度限制

• maxSpeechInputLength: number：Android 为系统限制；iOS 为 Number.MAX_VALUE
• getMaxSpeechInputLength(): number：获取当前限制值（用于兼容少量场景下导入常量失败的问题）

平台差异

• pause()/resume()：仅 iOS 支持；Android/Harmony 会抛出 9010001
• onBoundary：Android 仅 API 26+ 触发；iOS 正常触发

日志

插件内部默认会打印关键行为与事件，可按需关闭：

setLogEnabled(false)
const enabled = isLogEnabled()

错误码

统一错误码段：90xxxxx

• 9010001：not supported（Harmony / Android pause/resume）
• 9010002：input too long（Android）
• 9010003：invalid voice（iOS）
• 9010004：get voices failed
• 9010005：unknown

提示：

• pause()/resume()/stop()/getAvailableVoicesAsync() 通过 Promise reject 返回错误对象（通常包含 errCode/errMsg/errSubject）
• speak() 的错误通过 options.onError(error) 回调返回