first commit
This commit is contained in:
494
guides/JavaScript调用原生接口文档/TSGame_JSBridge_用户认证与页面管理.md
Normal file
494
guides/JavaScript调用原生接口文档/TSGame_JSBridge_用户认证与页面管理.md
Normal file
@@ -0,0 +1,494 @@
|
||||
# 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
|
||||
**联系方式**: 技术支持组
|
||||
Reference in New Issue
Block a user