# 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  
**联系方式**: 技术支持组