155 lines
6.4 KiB
Markdown
155 lines
6.4 KiB
Markdown
# 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份
|