# TSGame JSBridge 接口文档 - 总览

**版本**: v1.9  
**更新时间**: 2025年7月13日  
**文档类型**: 接口规范文档总览

## 文档说明

本文档集详细描述TSGame游戏中WebView JavaScript调用App原生功能的所有JSBridge接口规范。为了便于阅读和维护，文档按功能模块拆分为4个部分。

**适用平台**: Android / HarmonyOS  
**总接口数量**: 18个核心接口

## 文档结构

### 📁 文档分册

| 文档名称 | 接口数量 | 主要功能 | 文件名 |
|----------|----------|----------|---------|
| **用户认证与页面管理** | 4个 | 登录认证、页面跳转、语音控制 | `TSGame_JSBridge_用户认证与页面管理.md` |
| **系统功能与交互** | 4个 | 剪贴板操作、游戏管理、设备检测 | `TSGame_JSBridge_系统功能与交互.md` |
| **位置与媒体服务** | 5个 | GPS定位、音频播放 | `TSGame_JSBridge_位置与媒体服务.md` |
| **高级功能与扩展** | 5个 | 录音控制、震动反馈、社交分享 | `TSGame_JSBridge_高级功能与扩展.md` |

## 完整接口清单

### 🔐 用户认证与页面管理
| 接口名称 | 功能描述 | 调用方向 | 使用场景 |
|----------|----------|----------|----------|
| `accreditlogin` | 授权登录 | WebView→App | 微信/QQ登录 |
| `cancellogin` | 取消登录 | WebView→App | 登录过程中取消操作 |
| `OpenurlTitleData` | 打开新WebView页面 | WebView→App | 页面跳转、外链访问 |
| `voicePlaying` | 语音播放开关控制 | WebView→App | 音效/语音开关设置 |

### 🔧 系统功能与交互
| 接口名称 | 功能描述 | 调用方向 | 使用场景 |
|----------|----------|----------|----------|
| `gameCopytext` | 复制文本到剪贴板 | WebView→App | 文本复制分享功能 |
| `gamepastetext` | 获取剪贴板内容 | WebView→App | 文本粘贴读取功能 |
| `getGameinstall` | 检查游戏安装状态 | WebView→App | 本地游戏文件检测 |
| `getphonestate` | 获取电话通话状态 | WebView→App | 通话状态检测 |
| `SwitchOverGameData` | 启动指定游戏 | WebView→App | 游戏切换和启动 |
| `backgameData` | 返回数据到上级页面 | WebView→App | 页面数据回传 |

### 🌍 位置与媒体服务
| 接口名称 | 功能描述 | 调用方向 | 使用场景 |
|----------|----------|----------|----------|
| `startlocation` | 开始位置定位 | WebView→App | GPS定位服务 |
| `getlocationinfo` | 获取当前位置信息 | WebView→App | 位置信息查询 |
| `stopVoice` | 停止语音播放 | WebView→App | 音频控制 |
| `playAudio` | 播放音频文件 | WebView→App | 音频播放 |
| `mediaTypeAudio` | 音频播放控制 | WebView→App | 音频媒体播放 |

### 🚀 高级功能与扩展
| 接口名称 | 功能描述 | 调用方向 | 使用场景 |
|----------|----------|----------|----------|
| `prepareaudio` | 录音准备 | WebView→App | 语音录制准备 |
| `vibrator` | 单次震动 | WebView→App | 触觉反馈 |
| `repeatvibrator` | 重复震动 | WebView→App | 持续触觉反馈 |
| `canclevibrator` | 取消震动 | WebView→App | 停止震动反馈 |
| `friendsSharetypeUrlToptitleDescript` | 社交分享 | WebView→App | 微信/抖音分享 |

## 接口依赖关系

### 🔗 接口调用链
```mermaid
graph TD
    A[WebView页面] --> B[用户认证]
    B --> C[accreditlogin 授权登录]
    B --> D[cancellogin 取消登录]
    
    A --> E[页面管理]
    E --> F[OpenurlTitleData 页面跳转]
    E --> G[backgameData 数据返回]
    
    A --> H[系统交互]
    H --> I[gameCopytext 复制文本]
    H --> J[gamepastetext 粘贴文本]
    H --> K[getGameinstall 游戏检测]
    H --> L[SwitchOverGameData 游戏启动]
    
    A --> M[设备状态]
    M --> N[getphonestate 电话状态]
    M --> O[voicePlaying 音效开关]
    
    A --> P[位置服务]
    P --> Q[startlocation 开始定位]
    Q --> R[getlocationinfo 获取位置]
    
    A --> S[媒体播放]
    S --> T[mediaTypeAudio 音频播放]
    O --> T
```

### ⚙️ 核心依赖
- **定位服务**: `getlocationinfo` 需要先调用 `startlocation`
- **音频播放**: `mediaTypeAudio` 受 `voicePlaying` 开关控制
- **登录流程**: `cancellogin` 用于取消 `accreditlogin` 流程
- **页面数据**: `backgameData` 配合 `OpenurlTitleData` 实现数据回传

## 开发指南

### 📋 快速上手
1. **选择相关文档**: 根据需要实现的功能选择对应的文档分册
2. **查看接口概述**: 了解接口的基本功能和使用场景
3. **参考工作流程**: 通过Mermaid流程图理解接口交互过程
4. **使用代码示例**: 参考完整的代码示例进行开发
5. **注意实现要点**: 查看HarmonyOS实现要点确保正确实现

### 🔧 开发最佳实践
- **错误处理**: 每个接口都应包含完善的错误处理机制
- **权限检查**: 使用涉及设备功能的接口前检查相应权限
- **状态管理**: 合理管理接口调用状态，避免重复调用
- **用户体验**: 在接口调用过程中提供适当的用户反馈

### 📱 HarmonyOS适配要点
- **权限声明**: 在module.json5中声明所需权限
- **SDK集成**: 集成必要的第三方SDK（如高德地图）
- **API适配**: 使用HarmonyOS对应的系统API
- **测试验证**: 在HarmonyOS设备上充分测试接口功能

## 版本信息

### 📈 版本历史
| 版本 | 更新时间 | 主要变更 | 文档结构 |
|------|----------|----------|----------|
| v1.0-v1.7 | 2024-01 ~ 2024-11 | 逐步新增基础接口 | 单一文档 |
| v1.8 | 2024-12 | 新增详细接口说明 | 单一文档 |
| v1.9 | 2025-07 | 新增位置和音频接口，拆分文档 | 多文档结构 |

### 🔄 向后兼容性
- ✅ 新版本保持对旧版本的完全兼容
- ✅ 不会删除或修改现有接口参数
- ✅ 新增参数使用可选方式，不影响现有实现
- ✅ 文档拆分不影响接口规范内容

## 技术支持

### 📞 联系方式
- **文档维护**: TSGame开发团队
- **技术支持**: 技术支持组
- **更新通知**: 关注版本更新日志

### 🐛 问题反馈
如发现文档问题或接口实现疑问，请及时反馈：
1. **接口功能问题**: 描述具体使用场景和遇到的问题
2. **文档内容问题**: 指出具体位置和建议修改内容
3. **HarmonyOS适配问题**: 提供设备信息和错误日志

---

**最后更新**: 2025年7月13日  
**当前版本**: v1.9  
**总文档行数**: 约5300行 → 1800行×3份