xinli/纯前端TTS功能使用说明.md

# 纯前端 TTS 功能使用说明

## 📋 方案概述

基于浏览器 **Web Speech API** 实现的纯前端文字转语音功能，**无需后端服务**，适合局域网环境使用。

### ✅ 优势

1. **零后端依赖**：完全在浏览器中运行，不需要服务器支持
2. **即开即用**：直接打开 HTML 文件即可使用
3. **跨平台**：支持 Windows、Linux、Mac
4. **响应式设计**：适配桌面和移动设备
5. **功能完整**：支持音量、语速、音调调节

---

## 🎯 使用方式

### 方式一：独立工具（推荐用于测试）

直接打开 `局域网TTS工具.html` 文件：

1. 双击打开 `局域网TTS工具.html`
2. 在文本框中输入要朗读的文字
3. 调整音量、语速、音调参数
4. 点击"开始朗读"按钮

**特点**：
- 无需任何配置
- 适合快速测试和演示
- 可以放在局域网服务器上供多人使用

### 方式二：Vue 组件集成（用于项目）

在 Vue 项目中使用 `TtsPlayer` 组件：

```vue
<template>
  <div>
    <!-- 题目内容 -->
    <div class="question-content">{{ questionText }}</div>
    
    <!-- TTS 播放器 -->
    <TtsPlayer 
      :text="questionText" 
      lang="zh-CN"
      @start="onTtsStart"
      @end="onTtsEnd"
      @stop="onTtsStop"
    />
  </div>
</template>

<script>
import TtsPlayer from '@/components/Psychology/TtsPlayer.vue'

export default {
  components: {
    TtsPlayer
  },
  data() {
    return {
      questionText: '请根据您的实际情况，选择最符合的选项。'
    }
  },
  methods: {
    onTtsStart() {
      console.log('开始朗读')
    },
    onTtsEnd() {
      console.log('朗读完成')
    },
    onTtsStop() {
      console.log('停止朗读')
    }
  }
}
</script>
```

---

## 📦 文件说明

### 1. `局域网TTS工具.html`

**位置**：项目根目录  
**用途**：独立的 TTS 工具，可直接在浏览器中打开使用

**功能**：
- ✅ 文本输入和朗读
- ✅ 音量、语速、音调调节
- ✅ 预设文本快速填充
- ✅ 响应式设计，支持移动端

### 2. `xinli-ui/src/components/Psychology/TtsPlayer.vue`

**位置**：Vue 项目组件目录  
**用途**：可复用的 TTS 组件，集成到 Vue 项目中

**Props**：
- `text` (String): 要朗读的文本
- `lang` (String): 语言设置，默认 `zh-CN`

**Events**：
- `@start`: 开始朗读时触发
- `@end`: 朗读完成时触发
- `@stop`: 停止朗读时触发
- `@error`: 朗读出错时触发

---

## 🔧 在问卷答题页面中集成

### 步骤 1：导入组件

在 `xinli-ui/src/views/psychology/questionnaire/taking.vue` 中：

```vue
<script>
import TtsPlayer from '@/components/Psychology/TtsPlayer.vue'

export default {
  components: {
    TtsPlayer
  },
  // ...
}
</script>
```

### 步骤 2：添加 TTS 播放器

在题目显示区域添加 TTS 组件：

```vue
<template>
  <el-card shadow="never" class="question-card" v-if="currentItem">
    <div class="question-number">第 {{ currentIndex + 1 }} 题</div>
    <div class="question-content">{{ currentItem.itemContent }}</div>
    
    <!-- 添加 TTS 播放器 -->
    <div style="margin: 15px 0;">
      <TtsPlayer :text="currentItem.itemContent" />
    </div>
    
    <!-- 其他内容... -->
  </el-card>
</template>
```

### 步骤 3：可选 - 自动朗读

如果需要自动朗读题目，可以在切换题目时触发：

```vue
<script>
export default {
  watch: {
    currentItem(newItem) {
      if (newItem && this.autoRead) {
        // 延迟一下，确保组件已渲染
        this.$nextTick(() => {
          this.$refs.ttsPlayer?.speakText()
        })
      }
    }
  }
}
</script>
```

---

## 🌐 浏览器兼容性

### ✅ 完全支持

- **Chrome** 33+（推荐）
- **Edge** 14+
- **Safari** 7+
- **Opera** 20+

### ⚠️ 部分支持

- **Firefox**：需要手动启用 `media.webspeech.synth.enabled`

### ❌ 不支持

- **IE** 11 及以下版本

---

## 🎨 自定义配置

### 修改默认参数

在 `TtsPlayer.vue` 组件中：

```javascript
data() {
  return {
    volume: 1.0,  // 默认音量（0-1）
    rate: 1.0,    // 默认语速（0.5-2）
    pitch: 1.0,   // 默认音调（0.5-2）
  }
}
```

### 选择语音

```javascript
// 获取可用语音列表
const voices = this.synth.getVoices()
console.log(voices)

// 选择特定语音
const chineseVoice = voices.find(voice => 
  voice.name.includes('Chinese') || 
  voice.lang === 'zh-CN'
)
if (chineseVoice) {
  this.utterance.voice = chineseVoice
}
```

---

## 📝 使用示例

### 示例 1：基本使用

```vue
<TtsPlayer text="欢迎使用AI心理健康测评系统" />
```

### 示例 2：监听事件

```vue
<TtsPlayer 
  :text="questionText"
  @start="handleTtsStart"
  @end="handleTtsEnd"
/>
```

### 示例 3：动态文本

```vue
<TtsPlayer :text="currentQuestion.content" />
```

---

## ⚠️ 注意事项

1. **浏览器限制**：
   - 某些浏览器需要用户交互后才能播放语音
   - 建议在用户点击按钮后触发朗读

2. **语音质量**：
   - 不同浏览器的语音质量可能不同
   - Chrome 的中文语音质量通常较好

3. **网络环境**：
   - 完全离线可用，不需要网络连接
   - 适合局域网环境

4. **性能考虑**：
   - 长文本建议分段朗读
   - 避免同时播放多个语音

---

## 🐛 常见问题

### Q: 为什么没有声音？

**A**: 检查以下几点：
1. 浏览器是否支持 Web Speech API
2. 系统音量是否开启
3. 浏览器是否允许自动播放音频
4. 是否在用户交互后触发（某些浏览器要求）

### Q: 语音质量不好？

**A**: 
1. 使用 Chrome 浏览器（语音质量最好）
2. 调整语速和音调参数
3. 检查系统语音设置

### Q: 如何切换语音？

**A**: 
```javascript
const voices = speechSynthesis.getVoices()
const voice = voices.find(v => v.name.includes('Microsoft'))
utterance.voice = voice
```

---

## 📚 技术文档

### Web Speech API 参考

- [MDN - SpeechSynthesis](https://developer.mozilla.org/zh-CN/docs/Web/API/SpeechSynthesis)
- [MDN - SpeechSynthesisUtterance](https://developer.mozilla.org/zh-CN/docs/Web/API/SpeechSynthesisUtterance)

### API 参数说明

| 参数 | 类型 | 范围 | 说明 |
|------|------|------|------|
| `lang` | String | - | 语言代码，如 `zh-CN` |
| `volume` | Number | 0-1 | 音量大小 |
| `rate` | Number | 0.5-2 | 语速倍数 |
| `pitch` | Number | 0.5-2 | 音调高低 |
| `voice` | SpeechSynthesisVoice | - | 语音对象 |

---

## ✨ 功能特性

- ✅ 纯前端实现，无需后端
- ✅ 支持中文语音合成
- ✅ 可调节音量、语速、音调
- ✅ 响应式设计，支持移动端
- ✅ 预设文本快速填充
- ✅ 事件监听支持
- ✅ 错误处理机制

---

**创建时间**：2025-01-27  
**版本**：1.0.0  
**状态**：✅ 可用