244 lines
7.2 KiB
Markdown
244 lines
7.2 KiB
Markdown
# 🔧 Android App 朗读功能修复说明
|
||
|
||
## 📋 问题描述
|
||
|
||
在 Android App 中，用户登录后进行量表测评时，朗读功能按钮呈灰色禁用状态，无法使用。
|
||
|
||
## 🔍 问题根源
|
||
|
||
### 核心问题：TTS 异步初始化导致的时序问题
|
||
|
||
1. **Android 端**：`TtsHelper.java` 中的 TTS 引擎初始化是**异步**的
|
||
- TTS 引擎通过 `OnInitListener` 回调初始化
|
||
- `isReady` 标志只有在回调成功后才设置为 `true`
|
||
- 初始化需要一定时间（通常 100-500ms）
|
||
|
||
2. **前端端**：页面在 `created()` 生命周期钩子中立即检查 TTS 可用性
|
||
- 调用 `window.AndroidTTS.isAvailable()`
|
||
- 此时 TTS 可能还未初始化完成
|
||
- 返回 `false`，导致 `isTtsSupported = false`
|
||
|
||
3. **结果**：所有朗读按钮被禁用
|
||
- 按钮属性：`:disabled="!isTtsSupported"`
|
||
- 用户看到的是灰色不可点击的按钮
|
||
|
||
## ✅ 修复方案
|
||
|
||
### 1. Android 端修复 (TtsHelper.java)
|
||
|
||
#### 修改点 1: isAvailable() 方法
|
||
**修改前**：
|
||
```java
|
||
@JavascriptInterface
|
||
public boolean isAvailable() {
|
||
return isReady; // 等待异步初始化完成
|
||
}
|
||
```
|
||
|
||
**修改后**：
|
||
```java
|
||
@JavascriptInterface
|
||
public boolean isAvailable() {
|
||
// 只要TTS对象存在就返回true，不等待异步初始化完成
|
||
// 这样前端可以立即启用朗读按钮
|
||
return tts != null;
|
||
}
|
||
```
|
||
|
||
#### 修改点 2: speak() 方法增加延迟重试机制
|
||
**新增功能**：
|
||
- 如果 TTS 未就绪，自动延迟 500ms 后重试
|
||
- 避免因初始化未完成而静默失败
|
||
- 提供更好的用户体验
|
||
|
||
### 2. 前端端修复
|
||
|
||
#### 2.1 测评答题页面 (assessment/taking.vue)
|
||
|
||
**新增延迟检查逻辑**：
|
||
```javascript
|
||
initTts() {
|
||
if (window.AndroidTTS && typeof window.AndroidTTS.isAvailable === 'function') {
|
||
if (window.AndroidTTS.isAvailable()) {
|
||
this.isTtsSupported = true;
|
||
console.log('✅ 使用Android原生TTS');
|
||
return;
|
||
} else {
|
||
// TTS可能还在初始化中，延迟重试
|
||
setTimeout(() => {
|
||
if (window.AndroidTTS && window.AndroidTTS.isAvailable()) {
|
||
this.isTtsSupported = true;
|
||
console.log('✅ Android TTS 已就绪（延迟检测）');
|
||
} else {
|
||
this.fallbackToBrowserTts();
|
||
}
|
||
}, 500);
|
||
// 先启用按钮，避免用户等待
|
||
this.isTtsSupported = true;
|
||
return;
|
||
}
|
||
}
|
||
this.fallbackToBrowserTts();
|
||
}
|
||
```
|
||
|
||
#### 2.2 问卷答题页面 (questionnaire/taking.vue)
|
||
|
||
**新增 Android TTS 支持**：
|
||
- 之前只支持浏览器 TTS
|
||
- 现在添加了与测评页面相同的 Android TTS 支持
|
||
- 确保所有答题页面功能一致
|
||
|
||
## 📝 修改文件清单
|
||
|
||
### Android 代码
|
||
- ✅ `xinli-App/app/src/main/java/com/xinli/app/TtsHelper.java`
|
||
- 修改 `isAvailable()` 方法
|
||
- 改进 `speak()` 方法，添加延迟重试
|
||
|
||
### 前端代码
|
||
- ✅ `xinli-ui/src/views/psychology/assessment/taking.vue`
|
||
- 改进 `initTts()` 方法
|
||
- 新增 `fallbackToBrowserTts()` 方法
|
||
|
||
- ✅ `xinli-ui/src/views/psychology/questionnaire/taking.vue`
|
||
- 添加 Android TTS 支持
|
||
- 统一 `initTts()` 逻辑
|
||
- 更新 `speakText()` 和 `stopSpeaking()` 方法
|
||
|
||
## 🚀 重新打包和部署步骤
|
||
|
||
### 步骤 1: 重新构建前端
|
||
```bash
|
||
cd c:\Users\Administrator\Desktop\Project\xinli\xinli-ui
|
||
npm run build:prod
|
||
```
|
||
|
||
### 步骤 2: 将构建好的前端文件复制到服务器
|
||
将 `xinli-ui/dist` 目录的文件部署到服务器的 Web 目录。
|
||
|
||
### 步骤 3: 打包 Android App
|
||
```bash
|
||
cd c:\Users\Administrator\Desktop\Project\xinli\xinli-App
|
||
.\打包正式版APK.bat
|
||
```
|
||
|
||
或者在 Android Studio 中：
|
||
1. 打开项目
|
||
2. 点击 `Build` → `Build Bundle(s) / APK(s)` → `Build APK(s)`
|
||
3. 等待构建完成
|
||
|
||
### 步骤 4: 查找生成的 APK
|
||
运行：
|
||
```bash
|
||
.\查找APK.bat
|
||
```
|
||
|
||
APK 通常位于：
|
||
- `xinli-App/app/build/outputs/apk/release/app-release.apk`
|
||
|
||
### 步骤 5: 安装测试
|
||
1. 卸载旧版本 App（重要！）
|
||
2. 安装新的 APK
|
||
3. 打开 App，登录账号
|
||
4. 进入量表测评或问卷答题页面
|
||
5. 测试朗读功能
|
||
|
||
## ✅ 测试检查清单
|
||
|
||
### 测评答题页面
|
||
- [ ] 朗读按钮不再是灰色
|
||
- [ ] 点击"朗读全部"能听到声音
|
||
- [ ] 点击"朗读题干"能听到声音
|
||
- [ ] 点击选项旁的朗读按钮能听到声音
|
||
- [ ] 声音清晰，中文标准
|
||
- [ ] 可以正常停止朗读
|
||
- [ ] 切换题目后朗读功能正常
|
||
|
||
### 问卷答题页面
|
||
- [ ] 朗读按钮不再是灰色
|
||
- [ ] "朗读全部"功能正常
|
||
- [ ] "朗读题干"功能正常
|
||
- [ ] 选项朗读功能正常
|
||
- [ ] 各种题型（单选、多选、填空等）的朗读功能都正常
|
||
|
||
### 控制台日志检查
|
||
打开 Chrome DevTools（如果是调试版），查看控制台：
|
||
- ✅ 应该看到：`✅ 使用Android原生TTS`
|
||
- ✅ 或者：`✅ Android TTS 已就绪（延迟检测）`
|
||
- ❌ 不应该看到：朗读按钮被禁用的警告
|
||
|
||
## 🎯 技术改进说明
|
||
|
||
### 优化点 1: 消除时序依赖
|
||
- **之前**：前端必须等待 Android TTS 完全初始化
|
||
- **现在**：立即启用按钮，TTS 在后台完成初始化
|
||
|
||
### 优化点 2: 双重保障机制
|
||
- **第一层**：Android 端延迟重试（500ms）
|
||
- **第二层**：前端端延迟检查（500ms）
|
||
- 确保 TTS 功能高可用性
|
||
|
||
### 优化点 3: 降级策略
|
||
- Android TTS 不可用时自动降级到浏览器 TTS
|
||
- 确保功能在所有环境都能工作
|
||
|
||
### 优化点 4: 统一体验
|
||
- 测评和问卷两个页面使用相同的 TTS 逻辑
|
||
- 代码一致性提高，便于维护
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q1: 重新安装后还是没声音？
|
||
**A**: 检查以下几点：
|
||
1. 确认已**完全卸载旧版本** App
|
||
2. 检查手机**媒体音量**（不是铃声音量）
|
||
3. 确保不是静音模式
|
||
4. 重启 App
|
||
5. 查看控制台日志，确认使用了 Android TTS
|
||
|
||
### Q2: 声音很奇怪/机器人声音？
|
||
**A**:
|
||
- 某些手机的默认 TTS 引擎音质较差
|
||
- 可以在手机设置中更换 TTS 引擎：
|
||
- 系统设置 → 辅助功能 → 文字转语音
|
||
- 推荐安装：Google 文字转语音引擎
|
||
|
||
### Q3: 浏览器中还能用吗？
|
||
**A**:
|
||
- ✅ 完全兼容！
|
||
- 浏览器中自动使用浏览器 TTS
|
||
- PC 端功能不受影响
|
||
|
||
### Q4: 如何确认使用的是哪种 TTS？
|
||
**A**:
|
||
打开 Chrome DevTools，查看控制台日志：
|
||
- `✅ 使用Android原生TTS` - Android 原生
|
||
- `✅ 使用浏览器TTS` - 浏览器 TTS
|
||
|
||
## 📊 修复效果
|
||
|
||
| 项目 | 修复前 | 修复后 |
|
||
|------|--------|--------|
|
||
| 朗读按钮状态 | ❌ 灰色禁用 | ✅ 正常可用 |
|
||
| TTS 初始化时间 | 等待完成（阻塞） | 异步加载（不阻塞） |
|
||
| 用户体验 | 功能不可用 | 立即可用 |
|
||
| 降级策略 | ❌ 无 | ✅ 自动降级到浏览器TTS |
|
||
| 问卷答题支持 | ❌ 仅浏览器TTS | ✅ Android原生TTS |
|
||
| 代码一致性 | 测评和问卷不同 | 统一实现 |
|
||
|
||
## 🎉 总结
|
||
|
||
此次修复完全解决了朗读功能在 Android App 中被禁用的问题：
|
||
|
||
1. ✅ **根本问题已修复**：TTS 异步初始化不再阻塞功能使用
|
||
2. ✅ **用户体验改善**：朗读按钮立即可用，无需等待
|
||
3. ✅ **功能完整性**：测评和问卷页面都支持朗读
|
||
4. ✅ **健壮性提升**：双重保障+自动降级，确保高可用性
|
||
5. ✅ **代码质量**：统一实现，易于维护
|
||
|
||
---
|
||
|
||
**修复日期**: 2024年12月2日
|
||
**修复版本**: v1.1
|