youle_app_android/guides/JavaScript调用原生接口文档/TSGame_JSBridge_用户认证与页面管理.md

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。

工作流程

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: 处理登录成功

参数规范

调用格式

WebViewJavascriptBridge.callHandler('accreditlogin', loginType, function(response) {
    console.log('登录请求已发送');
});

参数说明

参数	类型	必需	说明	取值
loginType	string	✓	登录类型	"1"=微信登录, "2"=QQ登录

接口调用示例

微信登录

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登录

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取消登录流程，清理相关状态和资源。

工作流程

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状态

参数规范

调用格式

WebViewJavascriptBridge.callHandler('cancellogin', '', function(response) {
    console.log('登录已取消');
});

参数说明

参数	类型	必需	说明	取值
data	string	✓	固定传入空字符串	""

接口调用示例

用户主动取消

function cancelLogin() {
    WebViewJavascriptBridge.callHandler('cancellogin', '', function(response) {
        console.log('用户取消登录');
        resetLoginUI();
    });
}

function resetLoginUI() {
    // 重置登录界面状态
    document.getElementById('loginBtn').disabled = false;
    document.getElementById('loginStatus').textContent = '请选择登录方式';
}

登录超时处理

function handleLoginTimeout() {
    console.log('登录超时，自动取消');
    
    WebViewJavascriptBridge.callHandler('cancellogin', '', function(response) {
        showMessage('登录超时，请重试');
        resetLoginUI();
    });
}

HarmonyOS实现要点

• 接口名称: cancellogin
• 调用方向: WebView → App
• 参数格式: 空字符串
• 清理工作: 取消第三方SDK授权流程，清理内存状态
• UI响应: 确保用户界面正确反馈取消状态

---

3. 打开新页面接口 (OpenurlTitleData)

接口概述

当WebView需要打开新的页面或外部链接时，通过此接口在App中打开新的WebView实例，支持自定义标题和数据传递。

工作流程

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: 显示新页面

参数规范

调用格式

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"

接口调用示例

打开游戏详情页

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('游戏详情页已打开');
    });
}

打开帮助页面

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('帮助页面已打开');
    });
}

带返回数据的页面

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可以查询和设置语音播放状态。

工作流程

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显示

参数规范

调用格式

// 设置音效开关
WebViewJavascriptBridge.callHandler('voicePlaying', '1', function(response) {
    console.log('音效开关已设置:', response);
});

// 查询音效状态
WebViewJavascriptBridge.callHandler('voicePlaying', '', function(response) {
    console.log('当前音效状态:', response);
});

参数说明

参数	类型	必需	说明	取值
state	string	✓	音效开关状态或查询	"1"=开启, "0"=关闭, ""=查询状态

返回值说明

返回值	含义
"1"	音效已开启
"0"	音效已关闭

接口调用示例

音效开关控制器

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组件

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('音效设置失败，请重试');
        }
    });
}

游戏中的音效管理

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