englishread-admin/UniApp微信小程序TTS接口调用说明.md

UniApp微信小程序TTS接口调用说明

本文档详细介绍如何在UniApp微信小程序中调用后端的文字转语音(TTS)接口。

📁 文件说明

1. uniapp-tts-example.vue

完整的TTS功能页面组件，包含：

• 文本输入界面
• 音色选择功能
• 语速和音量调节
• 音频格式选择
• 音频播放功能
• 完整的错误处理

2. uniapp-tts-config.js

TTS功能的配置文件，包含：

• API接口配置
• 参数验证工具
• 错误处理配置
• 通用工具函数

🚀 快速开始

1. 文件集成

将以下文件复制到你的UniApp项目中：

your-project/
├── pages/
│   └── tts/
│       └── index.vue          # 复制 uniapp-tts-example.vue 内容
├── utils/
│   └── tts-config.js          # 复制 uniapp-tts-config.js 内容
└── pages.json                 # 添加页面路由配置

2. 页面路由配置

在 pages.json 中添加TTS页面路由：

{
  "pages": [
    {
      "path": "pages/tts/index",
      "style": {
        "navigationBarTitleText": "文字转语音",
        "navigationBarBackgroundColor": "#007aff",
        "navigationBarTextStyle": "white"
      }
    }
  ]
}

3. 配置API地址

修改 uniapp-tts-config.js 中的API地址：

export const API_CONFIG = {
  // 开发环境API地址
  DEV_BASE_URL: 'http://localhost:8080',  // 修改为你的开发环境地址
  
  // 生产环境API地址
  PROD_BASE_URL: 'https://your-domain.com',  // 修改为你的生产环境地址
};

🔧 功能特性

1. 音色管理

• 自动加载后端音色列表
• 支持音色选择和切换
• 音色信息缓存

2. 参数控制

• 语速调节：支持-2到6的语速范围
• 音量控制：支持-10到10的音量范围
• 格式选择：支持WAV、MP3、PCM格式

3. 音频处理

• 二进制音频数据处理
• 本地音频文件创建
• 音频播放控制
• 文件大小显示

4. 用户体验

• 实时状态反馈
• 转换进度提示
• 错误信息展示
• 响应式界面设计

📋 接口说明

1. 获取音色列表

接口地址： GET /appletApi/tts/list

响应格式：

{
  "success": true,
  "result": [
    {
      "id": 0,
      "name": "云小宁",
      "description": "甜美女声"
    }
  ]
}

2. 文字转语音

接口地址： GET /appletApi/tts/textToVoice

请求参数：

参数名	类型	必填	说明
text	String	是	要转换的文本内容
speed	Float	否	语速，范围[-2,6]，默认0
voiceType	Integer	否	音色ID，默认0
volume	Float	否	音量，范围[-10,10]，默认0
codec	String	否	音频格式，默认wav
userId	String	否	用户ID，用于日志记录

响应格式： 二进制音频数据

💡 使用示例

1. 基础调用

import { API_CONFIG, UTILS } from '@/utils/tts-config.js';

// 调用TTS接口
async function callTTS() {
  try {
    const response = await uni.request({
      url: UTILS.buildApiUrl(API_CONFIG.ENDPOINTS.TEXT_TO_VOICE),
      method: 'GET',
      data: {
        text: '你好，世界！',
        speed: 0,
        voiceType: 0,
        volume: 0,
        codec: 'wav',
        userId: 'user123'
      },
      responseType: 'arraybuffer'
    });
    
    if (response.statusCode === 200) {
      // 处理音频数据
      console.log('TTS调用成功');
    }
  } catch (error) {
    console.error('TTS调用失败:', error);
  }
}

2. 参数验证

import { UTILS } from '@/utils/tts-config.js';

// 验证文本
const textValidation = UTILS.validateText('要转换的文本');
if (!textValidation.valid) {
  console.error(textValidation.message);
  return;
}

// 验证语速
const speedValidation = UTILS.validateSpeed(1);
if (!speedValidation.valid) {
  console.error(speedValidation.message);
  return;
}

3. 音频播放

// 创建音频上下文
const audioContext = wx.createInnerAudioContext();
audioContext.src = audioFilePath;

// 监听播放事件
audioContext.onPlay(() => {
  console.log('开始播放');
});

audioContext.onEnded(() => {
  console.log('播放结束');
});

audioContext.onError((error) => {
  console.error('播放失败:', error);
});

// 开始播放
audioContext.play();

⚠️ 注意事项

1. 权限配置

在 manifest.json 中配置必要的权限：

{
  "mp-weixin": {
    "permission": {
      "scope.writePhotosAlbum": {
        "desc": "保存音频文件到相册"
      }
    }
  }
}

2. 网络配置

在微信小程序后台配置服务器域名，将你的API域名添加到request合法域名中。

3. 文件大小限制

• 微信小程序本地文件存储有限制
• 建议音频文件不超过10MB
• 长文本建议分段处理

4. 错误处理

// 统一错误处理
function handleError(error, context = '') {
  console.error(`${context}错误:`, error);
  
  let message = '操作失败，请重试';
  
  if (error.errMsg) {
    if (error.errMsg.includes('network')) {
      message = '网络连接失败，请检查网络';
    } else if (error.errMsg.includes('timeout')) {
      message = '请求超时，请重试';
    }
  }
  
  uni.showToast({
    title: message,
    icon: 'error'
  });
}

🔍 调试技巧

1. 开启调试日志

// 在开发环境开启详细日志
if (process.env.NODE_ENV === 'development') {
  console.log('TTS请求参数:', params);
  console.log('TTS响应数据:', response);
}

2. 网络请求监控

// 监控请求状态
uni.onNetworkStatusChange((res) => {
  console.log('网络状态:', res.isConnected ? '已连接' : '已断开');
  console.log('网络类型:', res.networkType);
});

3. 性能监控

// 监控转换耗时
const startTime = Date.now();
// ... TTS调用 ...
const endTime = Date.now();
console.log(`TTS转换耗时: ${(endTime - startTime) / 1000}秒`);

📈 性能优化

1. 音色列表缓存

// 缓存音色列表，避免重复请求
const VOICE_CACHE_KEY = 'tts_voice_list';
const CACHE_EXPIRE_TIME = 24 * 60 * 60 * 1000; // 24小时

function getCachedVoiceList() {
  const cached = uni.getStorageSync(VOICE_CACHE_KEY);
  if (cached && (Date.now() - cached.timestamp) < CACHE_EXPIRE_TIME) {
    return cached.data;
  }
  return null;
}

2. 音频文件管理

// 清理过期的音频文件
function cleanupAudioFiles() {
  const fileManager = wx.getFileSystemManager();
  // 实现文件清理逻辑
}

3. 请求防抖

// 防止重复请求
let isConverting = false;

async function convertToVoice() {
  if (isConverting) {
    console.log('正在转换中，请稍候...');
    return;
  }
  
  isConverting = true;
  try {
    // TTS转换逻辑
  } finally {
    isConverting = false;
  }
}

🤝 技术支持

如果在使用过程中遇到问题，请检查：

1. 网络连接：确保设备网络正常
2. API地址：确认API地址配置正确
3. 参数格式：检查请求参数是否符合要求
4. 权限设置：确认小程序权限配置正确
5. 后端服务：确认后端TTS服务正常运行

📝 更新日志

v1.0.0 (2025-01-XX)

• 初始版本发布
• 支持基础TTS功能
• 完整的参数控制
• 音频播放功能
• 错误处理机制

---

注意： 本示例基于JeecgBoot 3.8.1框架开发，使用腾讯云TTS服务。在实际使用时，请根据你的具体环境进行相应调整。