495 lines
14 KiB
Markdown
495 lines
14 KiB
Markdown
# TSGame JSBridge 接口文档 - 用户认证与页面管理
|
||
|
||
**版本**: v1.9
|
||
**更新时间**: 2025年7月13日
|
||
**文档类型**: 接口规范文档 - 第一部分
|
||
|
||
## 文档说明
|
||
|
||
本文档是TSGame JSBridge接口规范文档的第一部分，专注于用户认证与页面管理相关功能，包括登录认证、页面跳转、语音控制等核心接口。
|
||
|
||
**适用平台**: Android / HarmonyOS
|
||
**接口范围**: 用户认证、页面管理、基础控制接口
|
||
|
||
### 本文档包含的接口
|
||
|
||
| 接口名称 | 调用方向 | 主要功能 | 使用场景 |
|
||
|----------|----------|----------|----------|
|
||
| `accreditlogin` | WebView→App | 授权登录 | 微信/QQ登录 |
|
||
| `cancellogin` | WebView→App | 取消登录 | 登录过程中取消操作 |
|
||
| `OpenurlTitleData` | WebView→App | 打开新WebView页面 | 页面跳转、外链访问 |
|
||
| `voicePlaying` | WebView→App | 语音播放开关控制 | 音效/语音开关设置 |
|
||
|
||
---
|
||
|
||
## 1. 授权登录接口 (accreditlogin)
|
||
|
||
### 接口概述
|
||
当用户在WebView中触发登录操作时，通过此接口调用App的授权登录功能，支持微信和QQ登录。App完成登录后会通过 `sharelogin` 接口将用户信息回传给WebView。
|
||
|
||
### 工作流程
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant WebView as WebView
|
||
participant App as App
|
||
participant WeChat as 微信/QQ
|
||
participant Server as 服务器
|
||
|
||
User->>WebView: 点击登录按钮
|
||
WebView->>App: 调用accreditlogin接口
|
||
App->>App: 检查登录类型参数
|
||
App->>WeChat: 启动授权登录
|
||
WeChat->>User: 显示授权页面
|
||
User->>WeChat: 确认授权
|
||
WeChat->>App: 返回授权码/用户信息
|
||
App->>Server: 发送登录请求
|
||
Server->>App: 返回登录结果
|
||
App->>WebView: 调用sharelogin回传用户信息
|
||
WebView->>WebView: 处理登录成功
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 调用格式
|
||
```javascript
|
||
WebViewJavascriptBridge.callHandler('accreditlogin', loginType, function(response) {
|
||
console.log('登录请求已发送');
|
||
});
|
||
```
|
||
|
||
#### 参数说明
|
||
| 参数 | 类型 | 必需 | 说明 | 取值 |
|
||
|------|------|------|------|------|
|
||
| loginType | string | ✓ | 登录类型 | "1"=微信登录, "2"=QQ登录 |
|
||
|
||
### 接口调用示例
|
||
|
||
#### 微信登录
|
||
```javascript
|
||
function loginWithWeChat() {
|
||
WebViewJavascriptBridge.callHandler('accreditlogin', '1', function(response) {
|
||
console.log('微信登录请求已发送');
|
||
// 等待sharelogin回调
|
||
});
|
||
}
|
||
|
||
// 注册登录成功回调
|
||
WebViewJavascriptBridge.registerHandler('sharelogin', function(userInfo) {
|
||
try {
|
||
const user = JSON.parse(userInfo);
|
||
console.log('登录成功:', user);
|
||
handleLoginSuccess(user);
|
||
} catch (e) {
|
||
console.error('登录信息解析失败:', e);
|
||
}
|
||
});
|
||
```
|
||
|
||
#### QQ登录
|
||
```javascript
|
||
function loginWithQQ() {
|
||
WebViewJavascriptBridge.callHandler('accreditlogin', '2', function(response) {
|
||
console.log('QQ登录请求已发送');
|
||
// 等待sharelogin回调
|
||
});
|
||
}
|
||
```
|
||
|
||
### HarmonyOS实现要点
|
||
- **接口名称**: `accreditlogin`
|
||
- **调用方向**: WebView → App
|
||
- **参数格式**: 字符串类型的登录类型（"1"=微信, "2"=QQ）
|
||
- **权限要求**: 需要微信/QQ SDK集成和相应权限
|
||
- **回调机制**: 通过sharelogin接口异步返回用户信息
|
||
- **错误处理**: 登录失败时应调用cancellogin或适当的错误处理
|
||
|
||
---
|
||
|
||
## 2. 取消登录接口 (cancellogin)
|
||
|
||
### 接口概述
|
||
当用户在登录过程中取消操作，或登录失败时，通过此接口通知App取消登录流程，清理相关状态和资源。
|
||
|
||
### 工作流程
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant WebView as WebView
|
||
participant App as App
|
||
participant AuthSDK as 授权SDK
|
||
|
||
User->>WebView: 取消登录或登录失败
|
||
WebView->>App: 调用cancellogin接口
|
||
App->>AuthSDK: 取消授权流程
|
||
App->>App: 清理登录状态
|
||
App->>App: 释放相关资源
|
||
App->>WebView: 返回取消确认
|
||
WebView->>WebView: 更新UI状态
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 调用格式
|
||
```javascript
|
||
WebViewJavascriptBridge.callHandler('cancellogin', '', function(response) {
|
||
console.log('登录已取消');
|
||
});
|
||
```
|
||
|
||
#### 参数说明
|
||
| 参数 | 类型 | 必需 | 说明 | 取值 |
|
||
|------|------|------|------|------|
|
||
| data | string | ✓ | 固定传入空字符串 | "" |
|
||
|
||
### 接口调用示例
|
||
|
||
#### 用户主动取消
|
||
```javascript
|
||
function cancelLogin() {
|
||
WebViewJavascriptBridge.callHandler('cancellogin', '', function(response) {
|
||
console.log('用户取消登录');
|
||
resetLoginUI();
|
||
});
|
||
}
|
||
|
||
function resetLoginUI() {
|
||
// 重置登录界面状态
|
||
document.getElementById('loginBtn').disabled = false;
|
||
document.getElementById('loginStatus').textContent = '请选择登录方式';
|
||
}
|
||
```
|
||
|
||
#### 登录超时处理
|
||
```javascript
|
||
function handleLoginTimeout() {
|
||
console.log('登录超时，自动取消');
|
||
|
||
WebViewJavascriptBridge.callHandler('cancellogin', '', function(response) {
|
||
showMessage('登录超时，请重试');
|
||
resetLoginUI();
|
||
});
|
||
}
|
||
```
|
||
|
||
### HarmonyOS实现要点
|
||
- **接口名称**: `cancellogin`
|
||
- **调用方向**: WebView → App
|
||
- **参数格式**: 空字符串
|
||
- **清理工作**: 取消第三方SDK授权流程，清理内存状态
|
||
- **UI响应**: 确保用户界面正确反馈取消状态
|
||
|
||
---
|
||
|
||
## 3. 打开新页面接口 (OpenurlTitleData)
|
||
|
||
### 接口概述
|
||
当WebView需要打开新的页面或外部链接时，通过此接口在App中打开新的WebView实例，支持自定义标题和数据传递。
|
||
|
||
### 工作流程
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant WebView as WebView
|
||
participant App as App
|
||
participant NewWebView as 新WebView
|
||
participant Server as 服务器
|
||
|
||
User->>WebView: 点击链接或按钮
|
||
WebView->>App: 调用OpenurlTitleData接口
|
||
App->>App: 解析URL和标题参数
|
||
App->>App: 创建新WebView实例
|
||
App->>NewWebView: 设置标题和初始参数
|
||
NewWebView->>Server: 加载目标URL
|
||
Server->>NewWebView: 返回页面内容
|
||
NewWebView->>User: 显示新页面
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 调用格式
|
||
```javascript
|
||
const pageData = {
|
||
url: "https://example.com/page",
|
||
title: "页面标题",
|
||
data: "传递的数据"
|
||
};
|
||
|
||
WebViewJavascriptBridge.callHandler('OpenurlTitleData', JSON.stringify(pageData), function(response) {
|
||
console.log('新页面已打开');
|
||
});
|
||
```
|
||
|
||
#### 参数说明
|
||
| 参数 | 类型 | 必需 | 说明 | 示例值 |
|
||
|------|------|------|------|--------|
|
||
| url | string | ✓ | 目标页面URL | "https://example.com/game" |
|
||
| title | string | ✓ | 页面标题 | "游戏详情" |
|
||
| data | string | ✗ | 传递给新页面的数据 | "gameId=123&mode=single" |
|
||
|
||
### 接口调用示例
|
||
|
||
#### 打开游戏详情页
|
||
```javascript
|
||
function openGameDetail(gameId) {
|
||
const pageData = {
|
||
url: `https://game.example.com/detail/${gameId}`,
|
||
title: "游戏详情",
|
||
data: `gameId=${gameId}&from=lobby`
|
||
};
|
||
|
||
WebViewJavascriptBridge.callHandler('OpenurlTitleData', JSON.stringify(pageData), function(response) {
|
||
console.log('游戏详情页已打开');
|
||
});
|
||
}
|
||
```
|
||
|
||
#### 打开帮助页面
|
||
```javascript
|
||
function openHelpPage() {
|
||
const pageData = {
|
||
url: "https://help.example.com/faq",
|
||
title: "帮助中心",
|
||
data: "source=app&version=1.0"
|
||
};
|
||
|
||
WebViewJavascriptBridge.callHandler('OpenurlTitleData', JSON.stringify(pageData), function(response) {
|
||
console.log('帮助页面已打开');
|
||
});
|
||
}
|
||
```
|
||
|
||
#### 带返回数据的页面
|
||
```javascript
|
||
function openSettingsPage() {
|
||
const pageData = {
|
||
url: "https://settings.example.com/profile",
|
||
title: "个人设置",
|
||
data: "userId=123&allowCallback=true"
|
||
};
|
||
|
||
WebViewJavascriptBridge.callHandler('OpenurlTitleData', JSON.stringify(pageData), function(response) {
|
||
console.log('设置页面已打开');
|
||
});
|
||
|
||
// 注册数据返回回调
|
||
WebViewJavascriptBridge.registerHandler('pageDataReturn', function(returnData) {
|
||
console.log('收到页面返回数据:', returnData);
|
||
handleSettingsUpdate(returnData);
|
||
});
|
||
}
|
||
```
|
||
|
||
### HarmonyOS实现要点
|
||
- **接口名称**: `OpenurlTitleData`
|
||
- **调用方向**: WebView → App
|
||
- **参数格式**: JSON字符串，包含url、title、data字段
|
||
- **WebView管理**: 创建新的WebView实例并管理生命周期
|
||
- **数据传递**: 支持向新页面传递初始化数据
|
||
- **标题设置**: 动态设置新页面的标题栏
|
||
|
||
---
|
||
|
||
## 4. 语音播放开关接口 (voicePlaying)
|
||
|
||
### 接口概述
|
||
控制App全局的语音播放开关状态，影响所有音频播放功能，包括音效、语音消息等。WebView可以查询和设置语音播放状态。
|
||
|
||
### 工作流程
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant WebView as WebView
|
||
participant App as App
|
||
participant AudioSystem as 音频系统
|
||
participant Settings as 设置存储
|
||
|
||
User->>WebView: 操作音效开关
|
||
WebView->>App: 调用voicePlaying接口
|
||
App->>App: 解析开关状态参数
|
||
|
||
alt 设置音效状态
|
||
App->>Settings: 保存音效设置
|
||
App->>AudioSystem: 更新全局音效状态
|
||
App->>WebView: 返回设置结果
|
||
else 查询音效状态
|
||
App->>Settings: 读取当前音效设置
|
||
App->>WebView: 返回当前状态
|
||
end
|
||
|
||
WebView->>WebView: 更新UI显示
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 调用格式
|
||
```javascript
|
||
// 设置音效开关
|
||
WebViewJavascriptBridge.callHandler('voicePlaying', '1', function(response) {
|
||
console.log('音效开关已设置:', response);
|
||
});
|
||
|
||
// 查询音效状态
|
||
WebViewJavascriptBridge.callHandler('voicePlaying', '', function(response) {
|
||
console.log('当前音效状态:', response);
|
||
});
|
||
```
|
||
|
||
#### 参数说明
|
||
| 参数 | 类型 | 必需 | 说明 | 取值 |
|
||
|------|------|------|------|------|
|
||
| state | string | ✓ | 音效开关状态或查询 | "1"=开启, "0"=关闭, ""=查询状态 |
|
||
|
||
#### 返回值说明
|
||
| 返回值 | 含义 |
|
||
|--------|------|
|
||
| "1" | 音效已开启 |
|
||
| "0" | 音效已关闭 |
|
||
|
||
### 接口调用示例
|
||
|
||
#### 音效开关控制器
|
||
```javascript
|
||
const VoiceController = {
|
||
currentState: null,
|
||
|
||
// 初始化时查询当前状态
|
||
init() {
|
||
this.getVoiceState((state) => {
|
||
this.currentState = state;
|
||
this.updateUI();
|
||
});
|
||
},
|
||
|
||
// 获取音效状态
|
||
getVoiceState(callback) {
|
||
WebViewJavascriptBridge.callHandler('voicePlaying', '', function(response) {
|
||
console.log('音效状态查询结果:', response);
|
||
if (callback) callback(response);
|
||
});
|
||
},
|
||
|
||
// 设置音效状态
|
||
setVoiceState(enabled, callback) {
|
||
const state = enabled ? '1' : '0';
|
||
|
||
WebViewJavascriptBridge.callHandler('voicePlaying', state, (response) => {
|
||
console.log('音效状态设置结果:', response);
|
||
this.currentState = response;
|
||
this.updateUI();
|
||
if (callback) callback(response);
|
||
});
|
||
},
|
||
|
||
// 切换音效状态
|
||
toggleVoice() {
|
||
const newState = this.currentState === '1' ? false : true;
|
||
this.setVoiceState(newState);
|
||
},
|
||
|
||
// 更新UI显示
|
||
updateUI() {
|
||
const switchElement = document.getElementById('voiceSwitch');
|
||
const statusElement = document.getElementById('voiceStatus');
|
||
|
||
if (switchElement) {
|
||
switchElement.checked = this.currentState === '1';
|
||
}
|
||
|
||
if (statusElement) {
|
||
statusElement.textContent = this.currentState === '1' ? '音效已开启' : '音效已关闭';
|
||
}
|
||
}
|
||
};
|
||
|
||
// 页面加载时初始化
|
||
document.addEventListener('DOMContentLoaded', function() {
|
||
VoiceController.init();
|
||
});
|
||
```
|
||
|
||
#### 音效开关UI组件
|
||
```javascript
|
||
function createVoiceSwitchUI() {
|
||
const container = document.createElement('div');
|
||
container.className = 'voice-switch-container';
|
||
container.innerHTML = `
|
||
<label class="voice-switch">
|
||
<input type="checkbox" id="voiceSwitch" onchange="handleVoiceSwitchChange(this)">
|
||
<span class="slider"></span>
|
||
</label>
|
||
<span id="voiceStatus">音效状态检测中...</span>
|
||
`;
|
||
|
||
return container;
|
||
}
|
||
|
||
function handleVoiceSwitchChange(checkbox) {
|
||
VoiceController.setVoiceState(checkbox.checked, (result) => {
|
||
if (result !== (checkbox.checked ? '1' : '0')) {
|
||
// 设置失败，恢复开关状态
|
||
checkbox.checked = result === '1';
|
||
showMessage('音效设置失败，请重试');
|
||
}
|
||
});
|
||
}
|
||
```
|
||
|
||
#### 游戏中的音效管理
|
||
```javascript
|
||
const GameAudioManager = {
|
||
// 播放音效前检查开关状态
|
||
playSound(audioUrl, callback) {
|
||
VoiceController.getVoiceState((state) => {
|
||
if (state === '1') {
|
||
// 音效开启，播放音频
|
||
this.executePlaySound(audioUrl, callback);
|
||
} else {
|
||
console.log('音效已关闭，跳过播放');
|
||
if (callback) callback('音效已关闭');
|
||
}
|
||
});
|
||
},
|
||
|
||
// 实际播放音效
|
||
executePlaySound(audioUrl, callback) {
|
||
// 调用音频播放接口
|
||
const audioData = {
|
||
audiourl: audioUrl,
|
||
type: "1",
|
||
user: "game_sound_" + Date.now()
|
||
};
|
||
|
||
WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData), function(response) {
|
||
console.log('音效播放请求已发送');
|
||
if (callback) callback(null);
|
||
});
|
||
}
|
||
};
|
||
```
|
||
|
||
### HarmonyOS实现要点
|
||
- **接口名称**: `voicePlaying`
|
||
- **调用方向**: WebView → App
|
||
- **参数格式**: 字符串类型的状态值（"1"/"0"）或空字符串查询
|
||
- **状态持久化**: 需要保存用户的音效偏好设置
|
||
- **全局影响**: 影响所有音频播放功能的开关状态
|
||
- **即时生效**: 状态改变应立即影响当前播放的音频
|
||
|
||
---
|
||
|
||
## 文档关联
|
||
|
||
本文档是TSGame JSBridge接口规范的第一部分，完整文档包括：
|
||
|
||
1. **用户认证与页面管理** (本文档) - 登录、页面跳转、语音控制
|
||
2. **系统功能与交互** - 剪贴板、游戏状态、设备检测
|
||
3. **位置与媒体服务** - GPS定位、音频播放
|
||
|
||
---
|
||
|
||
**文档维护**: TSGame开发团队
|
||
**最后更新**: 2025年7月13日
|
||
**版本**: v1.9
|
||
**联系方式**: 技术支持组
|