语音（HarmonyVoice）使用指导
语音组件 - 鸿蒙端侧语音合成(TTS)与语音识别(ASR)。 鸿蒙独有组件，基于 HMS Core TTS + ASR API。
运行前提与搭建步骤
这些案例在包含该组件的鸿蒙 AI 伴侣或 HAP 中运行。Android 侧是供网页编辑器生成积木的声明，不能用安卓伴侣验证鸿蒙系统能力。
- 在设计器拖入
HarmonyVoice，保留名称HarmonyVoice1；拖入案例涉及的按钮、文本输入框以及一个标签标签1，按代码中的名称重命名。 - 根据下面的业务说明准备素材、JSON 或系统目标。案例中的按钮代表分步操作，先等初始化、加载或创建成功，再执行下一步。
- 接住完成事件与错误事件，将原始 JSON 或错误显示在标签。先确认原始结果，再编写业务处理。
识别需要麦克风授权与系统语音服务；PartialResult 是中间结果，RecognitionComplete 才是最终结果。朗读和识别是两条独立流程。
案例一：文字朗读
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when 按钮_朗读.Click() {
HarmonyVoice1.Speak(文本输入框1.Text)
}
when HarmonyVoice1.SpeakCompleted() {
标签1.Text = "朗读结束"
}
when HarmonyVoice1.Error(错误信息) {
标签1.Text = 错误信息
}
案例二：语音识别
when 按钮_识别.Click() {
HarmonyVoice1.StartListening()
}
when HarmonyVoice1.RecognitionComplete(结果文本) {
标签1.Text = 结果文本
}
when 按钮_停止.Click() {
HarmonyVoice1.StopListening()
}
参数与返回值速查
JSON 参数是文本，不能直接传字典；需要字典时可用 Web 客户端的 JSON 解码积木转换返回文本。完整默认值与类型见组件参考。
| 方法或事件 | 参数与用途 |
|---|---|
取消聆听（CancelListening） |
无参数。取消当前的语音识别，不返回任何结果。 |
获取音色列表（ListVoices） |
无参数。获取当前可用的语音合成发音人列表。 |
念读（文本）（Speak） |
文本：文本。使用语音合成朗读指定的文本内容。 |
开始聆听（StartListening） |
无参数。开始监听麦克风进行语音识别。 |
停止聆听（StopListening） |
无参数。停止语音识别监听并获取最终结果。 |
停止朗读（StopSpeaking） |
无参数。停止当前的语音朗读。 |
出错时（错误信息）（Error） |
错误信息：文本。发生错误时触发，返回错误信息。 |
聆听开始时（ListeningStarted） |
无参数。语音识别监听开始时触发。 |
产生部分结果时（文本）（PartialResult） |
文本：文本。语音识别过程中收到部分识别结果时触发。 |
识别完成时（结果文本）（RecognitionComplete） |
结果文本：文本。语音识别完成时触发，返回最终识别结果。 |
朗读完成时（SpeakCompleted） |
无参数。语音合成朗读完成时触发。 |
朗读开始时（SpeakStarted） |
无参数。语音合成开始朗读时触发。 |
朗读停止时（SpeakStopped） |
无参数。语音合成朗读被手动停止时触发。 |
收到音色列表时（音色列表JSON）（VoiceListReceived） |
音色列表JSON：文本。可用语音列表获取完成时触发，返回JSON格式的语音列表。 |
常见问题与验收
| 现象 | 检查与预期 |
|---|---|
| 安卓运行没有结果 | 切换到鸿蒙伴侣或 HAP；Android 的声明不会执行该鸿蒙系统能力。 |
| 方法已调用但界面没变化 | 生成 JSON 的方法只是构建数据；按业务流程交给渲染、启动或同步入口，不能将数据生成当成系统操作完成。 |
| 初始化、权限或设备失败 | 记录错误事件，确认系统服务、授权、目标应用或设备可用；只在成功事件后继续下一步。 |
| JSON 解析失败 | 使用上一组件的原始输出，检查引号和字段类型；空对象用于默认模板演示，不能代替真实目标信息。 |
| 两个案例验收 | 每个按钮单独操作一次，核对对应返回或事件；输入错误目标或取消操作时查看失败事件，不应显示成功提示。 |
扫码添加客服咨询
