From 56341ddc35a0920f2c30761ccf0f4865af9293b5 Mon Sep 17 00:00:00 2001
From: zm2000 <18386612143@163.com>
Date: Mon, 28 Sep 2026 15:31:52 +0800
Subject: [PATCH] =?UTF-8?q?feat(packaging):=20=E8=B0=83=E6=95=B4=20speak()?=
=?UTF-8?q?=20=E8=AF=AD=E9=9F=B3=E9=99=8D=E7=BA=A7=E9=93=BE=E9=A1=BA?=
=?UTF-8?q?=E5=BA=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
将打包页语音播报降级链由「HTTP → 原生 TTS → Web Speech」
调整为「原生 TTS → HTTP → Web Speech」,并同步更新流程文档。
---
docs/packaging-voice-flow.md | 74 +++++++++++++++++++----------------
package-lock.json | 6 +--
package.json | 2 +-
src/pages/packaging/index.vue | 46 +++++++---------------
4 files changed, 59 insertions(+), 69 deletions(-)
diff --git a/docs/packaging-voice-flow.md b/docs/packaging-voice-flow.md
index 2c06e3b..aa53b44 100644
--- a/docs/packaging-voice-flow.md
+++ b/docs/packaging-voice-flow.md
@@ -9,14 +9,14 @@
打包业务存在 **两条互相独立的语音播报链路**,叠加生效:
-1. **页面主动播报链路** `speak()`:打包页在关键业务节点主动调用 `this.speak(文案)`,自带 HTTP 语音接口 / 原生 TTS / Web Speech 三级降级。
+1. **页面主动播报链路** `speak()`:打包页在关键业务节点主动调用 `this.speak(文案)`,自带原生 TTS / HTTP 语音接口 / Web Speech 三级降级,并有串行队列(`voicePlaying`/`voicePendingText`)避免连扫时音频互相打断。
2. **全局 toast 拦截播报链路**:`src/main.js` 在应用启动时接管了全局 `uni.showToast`,任何 toast 都会同步调用 `getVoice().play(title)`(`src/core/voice.js`)做一次语音播报。
```mermaid
flowchart LR
A[打包业务节点] --> B[this.speak 文案]
A --> C[uni.showToast 文案
silentVoice: true]
- B --> D[speak 链路
HTTP → 原生TTS → WebSpeech]
+ B --> D[speak 链路
原生TTS → HTTP → WebSpeech]
C --> E[main.js 全局拦截器]
E -- silentVoice 跳过 --> X[不再重复播报]
```
@@ -29,66 +29,73 @@ flowchart LR
定义于 `packaging/index.vue` 的 `methods.speak`(约 1185 行)。
-### 2.1 入口与文案截断
+### 2.1 入口:文本清洗 + 串行队列
```
speak(text)
- ├─ 空文本 → 直接 return
- └─ str.length > 12 → 截断为「前 12 字 + 等」
+ ├─ normalizeSpeakText:trim + 超 12 字截断为「前 12 字 + 等」
+ ├─ voicePlaying 为 true → 覆盖 voicePendingText(只保留最新一条待播)后直接 return
+ └─ 否则置 voicePlaying=true → playSpeakText(str)
```
- 截断规则:`str.slice(0, 12) + '等'`,防止长文案播报啰嗦。
- 当前所有业务文案均在 12 字以内(最长「绑定失败,请点击绑定重试」「已结束打包并下线全部成员」正好 12 字),暂不触发截断。
+- 串行队列:快速连扫时若正在播报,不打断当前音频,只保留最新一条待播文本(`voicePendingText`);当前一条播完由 `scheduleNextSpeak()` 取下一条,全部播完才把 `voicePlaying` 置回 false。
-### 2.2 平台分支
+### 2.2 降级链(平台分支)
```mermaid
flowchart TD
- S[speak text] --> P{编译平台}
- P -- APP-PLUS 安卓App --> H[speakViaHttp HTTP 语音接口]
- P -- H5 / Electron --> W[speakViaTtsOrWebSpeech]
- H -- 成功 --> END[播放完成]
- H -- 失败 --> W
- W --> T{ttsEngine 且 ttsReady}
- T -- 是 --> N[speakNativeTts 原生 TTS]
- T -- 否 --> WS[speakViaWebSpeech Web Speech]
+ S[playSpeakText str] --> T{APP-PLUS
ttsEngine 且 ttsReady}
+ T -- 是 --> N[speakNativeTts
原生 TTS]
+ T -- 否 --> H[speakViaHttp
HTTP 语音接口]
+ N --> E1[按语速估时 → scheduleNextSpeak]
+ H -- 成功 --> E2[scheduleNextSpeak]
+ H -- 失败 --> W[speakViaWebSpeech
Web Speech]
+ W --> E3[按语速估时 → scheduleNextSpeak]
```
### 2.3 各子方法职责
| 方法 | 职责 | 关键实现 |
| --- | --- | --- |
-| `speak(text)` | 播报总入口 | 文本清洗 + 12 字截断 + 平台分流 |
-| `speakViaHttp(msg)` | HTTP 语音接口(APP 首选) | GET `VOICE_API_URL + encodeURIComponent(msg)`,返回 `{audio}` 后用 `playVoiceAudio` 播放 |
+| `speak(text)` | 播报总入口 | 文本清洗 + 12 字截断 + 串行队列调度 |
+| `normalizeSpeakText(text)` | 文本清洗 | trim + >12 字截断为「前 12 字 + 等」 |
+| `playSpeakText(str)` | 队列执行单元 | 降级链:原生 TTS → HTTP → Web Speech |
+| `scheduleNextSpeak()` | 队列推进 | 取 `voicePendingText` 继续播,否则置 `voicePlaying=false` |
+| `estimateSpeakMs(str)` | 估时 | 每字约 300ms,500–4000ms 区间 |
+| `speakNativeTts(text)` | 原生 TTS(APP 首选) | `TextToSpeech.QUEUE_FLUSH=0` 清队列后播报 |
+| `speakViaHttp(msg)` | HTTP 语音接口(TTS 不可用时) | GET `VOICE_API_URL + encodeURIComponent(msg)`,返回 `{audio}` 后下载本地播放 |
+| `downloadVoiceAudio(src)` | 音频下载 | `uni.downloadFile` 下载到本地临时文件,失败回退远程地址 |
| `playVoiceAudio(src, onEnd)` | 音频播放 | `uni.createInnerAudioContext`,销毁旧实例再播,`onEnded`/`onError` 回调 |
-| `speakViaTtsOrWebSpeech(text)` | TTS 兜底 | 有引擎且就绪→原生 TTS;引擎未就绪→暂存到 `ttsPendingText`;无引擎→Web Speech |
-| `speakNativeTts(text)` | Android 原生 TTS | `TextToSpeech.QUEUE_FLUSH=0` 清队列后播报 |
-| `speakViaWebSpeech(text)` | Web Speech 降级 | `window.speechSynthesis`,`lang='zh-CN'` |
+| `speakViaWebSpeech(text)` | Web Speech(最终兜底) | `window.speechSynthesis`,`lang='zh-CN'` |
| `initNativeTts()` | 初始化原生 TTS | `plus.android.importClass('android.speech.tts.TextToSpeech')` + `OnInitListener` |
| `shutdownNativeTts()` | 释放 TTS | `stop()` + `shutdown()` + 清空字段 |
| `destroyVoiceAudio()` | 释放音频实例 | `stop()` + `destroy()` |
-### 2.4 HTTP 语音接口(解决平板缺中文语音包)
+### 2.4 原生 TTS(APP 首选)
+
+- 初始化:`initNativeTts()` 在 `mounted` 调用;`TextToSpeech(activity, OnInitListener)`。
+- 就绪条件:`onInit` 回调 `status===0` 且 `setLanguage(Locale.CHINA)` 返回值 `>= 0` 才置 `ttsReady=true`。
+- 播报:`speakNativeTts` 用 `TextToSpeech.QUEUE_FLUSH=0` 清队列后播报;无结束回调,播完后按 `estimateSpeakMs` 估时再推进队列。
+- 关键坑:**平板缺中文语音包时 `setLanguage` 返回 -2(不支持)→ `ttsReady=false`**,此时跳过原生 TTS,降级到 HTTP 接口发声。
+- 释放:`beforeUnmount` 调 `shutdownNativeTts()`。
+
+### 2.5 HTTP 语音接口(原生 TTS 不可用时的兜底)
- 常量(约 358 行):
- `VOICE_API_URL = 'http://tbdata.gztbyc.com/voice/'`
- `VOICE_API_PATH = 'http://tbdata.gztbyc.com'`
-- 请求:`uni.request`,GET `VOICE_API_URL + encodeURIComponent(msg)`,`timeout: 3000`,header `content-type: text/xml; charset=utf-8`。
+- 请求:`uni.request`,GET `VOICE_API_URL + encodeURIComponent(msg + '。。')`,`timeout: 3000`,header `content-type: text/xml; charset=utf-8`。
- 响应:`res.data.audio` 为音频相对路径,拼 `VOICE_API_PATH + audio` 得完整 src。
+- 下载:先 `downloadVoiceAudio` 下载到本地临时文件再播(避免内网/流式播放缓冲不足截断尾帧),失败回退直接播远程地址。
- 兜底:5 秒超时定时器,播放未结束也视为完成,避免一直等待。
-- 失败判定:请求 fail / 未返回 `audio` 字段 / 音频播放 error → `finish(false)` → 触发 TTS 降级。
-
-### 2.5 Android 原生 TTS(HTTP 失败后的兜底)
-
-- 初始化:`initNativeTts()` 在 `mounted` 调用;`TextToSpeech(activity, OnInitListener)`。
-- 就绪条件:`onInit` 回调 `status===0` 且 `setLanguage(Locale.CHINA)` 返回值 `>= 0` 才置 `ttsReady=true`。
-- 关键坑:**平板缺中文语音包时 `setLanguage` 返回 -2(不支持)→ `ttsReady=false`**,只能依赖 HTTP 接口发声;引擎未就绪期间只保留最后一条文案到 `ttsPendingText`,就绪后补播。
-- 释放:`beforeUnmount` 调 `shutdownNativeTts()`。
+- 失败判定:请求 fail / 未返回 `audio` 字段 / 音频播放 error → `finish(false)` → 触发 Web Speech 降级。
### 2.6 Web Speech(最终兜底)
- 仅 `typeof window !== 'undefined' && window.speechSynthesis` 可用。
-- Android App WebView 内 `window.speechSynthesis` 通常不可用 → 真机主要依赖 HTTP 接口 / 原生 TTS。
+- Android App WebView 内 `window.speechSynthesis` 通常不可用 → 真机主要依赖原生 TTS / HTTP 接口。
### 2.7 生命周期
@@ -115,7 +122,7 @@ flowchart TD
| --- | --- | --- |
| 触发方式 | 业务节点显式调用 | 任何 `uni.showToast` 自动触发 |
| 文案编码 | `encodeURIComponent(msg)` | 未编码 |
-| 降级链 | HTTP → 原生 TTS → Web Speech | 仅 HTTP,失败静默 |
+| 降级链 | 原生 TTS → HTTP → Web Speech | 仅 HTTP,失败静默 |
| 适用范围 | 仅打包页 | 全应用所有页面 |
---
@@ -205,6 +212,7 @@ flowchart TD
2. **平板缺中文语音包**:原生 TTS `setLanguage(Locale.CHINA)` 返回 -2,`ttsReady=false`,必须依赖 HTTP 语音接口 `tbdata.gztbyc.com` 才能发声(实测结论,见仓库记忆)。
3. **URL 编码不一致**:打包页 `speakViaHttp` 对文案做 `encodeURIComponent`,而 `core/voice.js` 的 `play()` 未编码,含中文/特殊字符文案在两链路下的请求 URL 不同,后端需同时兼容。
4. **长文本截断**:`speak()` 对 >12 字文案截断为「前 12 字 + 等」;当前所有文案均 ≤12 字,未触发。
-5. **HTTP 接口超时**:请求 timeout 3000ms + 播放 5s 兜底;接口不可达时自动降级 TTS/Web Speech,不影响业务流程。
+5. **HTTP 接口超时**:请求 timeout 3000ms + 播放 5s 兜底;接口不可达时自动降级 Web Speech,不影响业务流程。
6. **资源释放**:页面卸载时 `shutdownNativeTts()` + `destroyVoiceAudio()`,避免音频实例泄漏。
-7. **APP-PLUS 与 H5 差异**:Electron/H5 端跳过 HTTP 接口直接走 TTS/Web Speech(`#ifdef APP-PLUS` 条件编译)。
+7. **APP-PLUS 与 H5 差异**:原生 TTS 仅在 APP-PLUS 可用;Electron/H5 端无原生 TTS,实际生效链为「HTTP → Web Speech」。
+8. **串行队列**:`speak()` 内部用 `voicePlaying`/`voicePendingText` 串行播报,连扫时只保留最新一条待播,避免音频互相打断。
diff --git a/package-lock.json b/package-lock.json
index d9cc583..2e8e785 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "wms-worker-station",
- "version": "1.0.35",
+ "version": "1.0.40",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "wms-worker-station",
- "version": "1.0.35",
+ "version": "1.0.40",
"devDependencies": {
"@dcloudio/types": "^3.4.8",
"@dcloudio/uni-app": "3.0.0-5000720260410001",
@@ -8851,7 +8851,7 @@
},
"node_modules/qrcode-generator": {
"version": "2.0.4",
- "resolved": "https://registry.npmjs.org/qrcode-generator/-/qrcode-generator-2.0.4.tgz",
+ "resolved": "https://mirrors.cloud.tencent.com/npm/qrcode-generator/-/qrcode-generator-2.0.4.tgz",
"integrity": "sha512-mZSiP6RnbHl4xL2Ap5HfkjLnmxfKcPWpWe/c+5XxCuetEenqmNFf1FH/ftXPCtFG5/TDobjsjz6sSNL0Sr8Z9g==",
"dev": true,
"license": "MIT"
diff --git a/package.json b/package.json
index 79eed8e..2df61f0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "wms-worker-station",
- "version": "1.0.40",
+ "version": "1.0.41",
"description": "WMS仓库工作台(Android端 + 桌面端)",
"author": "tianbao",
"main": "electron/main.js",
diff --git a/src/pages/packaging/index.vue b/src/pages/packaging/index.vue
index 691eb9f..19be262 100644
--- a/src/pages/packaging/index.vue
+++ b/src/pages/packaging/index.vue
@@ -1503,28 +1503,32 @@ export default {
},
/**
* 播报单条文本(串行队列执行单元)
- * APP-PLUS:优先 HTTP 语音接口,失败兜底本地 TTS / Web Speech
- * 非 APP:直接走 TTS / Web Speech,按语速估时后取下一条
+ * 降级链:原生 TTS → HTTP 语音接口 → Web Speech
+ * 原生 TTS 仅在 APP-PLUS 且引擎就绪时可用;HTTP 失败后由 Web Speech 兜底
*/
playSpeakText(str) {
console.log('[语音播报] 开始播报:', str)
// #ifdef APP-PLUS
+ // 1) 原生 TTS 优先:引擎就绪则直接播报(无结束回调,按语速估时后取下一条)
+ if (this.ttsEngine && this.ttsReady) {
+ const ok = this.speakNativeTts(str)
+ if (ok) {
+ this.voiceNextTimer = setTimeout(() => this.scheduleNextSpeak(), this.estimateSpeakMs(str))
+ return
+ }
+ }
+ // #endif
+ // 2) HTTP 语音接口
this.speakViaHttp(str).then((ok) => {
console.log('[语音播报] HTTP 语音接口结果:', ok)
if (!ok) {
- this.speakViaTtsOrWebSpeech(str)
- // 原生 TTS / Web Speech 无结束回调,按语速估时后再取下一条
+ // 3) Web Speech 最终兜底(无结束回调,按语速估时后取下一条)
+ this.speakViaWebSpeech(str)
this.voiceNextTimer = setTimeout(() => this.scheduleNextSpeak(), this.estimateSpeakMs(str))
return
}
this.scheduleNextSpeak()
})
- return
- // #endif
- // #ifndef APP-PLUS
- this.speakViaTtsOrWebSpeech(str)
- this.voiceNextTimer = setTimeout(() => this.scheduleNextSpeak(), this.estimateSpeakMs(str))
- // #endif
},
scheduleNextSpeak() {
const next = this.voicePendingText
@@ -1682,28 +1686,6 @@ export default {
this.voiceAudioContext = null
}
},
- speakViaTtsOrWebSpeech(text) {
- const str = String(text)
- // #ifdef APP-PLUS
- console.log(
- '[语音播报] APP-PLUS 分支:',
- JSON.stringify({ hasEngine: !!this.ttsEngine, ttsReady: this.ttsReady, text: str })
- )
- if (this.ttsEngine) {
- if (this.ttsReady) {
- const ok = this.speakNativeTts(str)
- console.log('[语音播报] speakNativeTts 返回:', ok)
- } else {
- // 引擎未就绪:只保留最后一条待播文本
- this.ttsPendingText = str
- console.log('[语音播报] 引擎未就绪,暂存待播文本:', str)
- }
- return
- }
- console.log('[语音播报] 无 TTS 引擎,回退 Web Speech')
- // #endif
- this.speakViaWebSpeech(str)
- },
speakViaWebSpeech(text) {
console.log(
'[语音播报] Web Speech 分支:',