daoqi/youle_app_android

Fork 0

Files

Joywayer c010c5eebd first commit

2026-02-16 18:18:11 +08:00

21 KiB

Raw Permalink Blame History

TSGame JSBridge 接口文档 - 系统功能与交互

版本: v1.9
更新时间: 2025年7月13日
文档类型: 接口规范文档 - 第二部分

文档说明

本文档是TSGame JSBridge接口规范文档的第二部分，专注于系统功能与交互相关接口，包括剪贴板操作、游戏状态管理、设备状态检测等功能。

适用平台: Android / HarmonyOS
接口范围: 剪贴板操作、游戏管理、设备状态检测

本文档包含的接口

接口名称	调用方向	主要功能	使用场景
`gameCopytext`	WebView→App	复制文本到剪贴板	文本复制分享功能
`gamepastetext`	WebView→App	获取剪贴板内容	文本粘贴读取功能
`getGameinstall`	WebView→App	检查游戏安装状态	本地游戏文件检测
`getphonestate`	WebView→App	获取电话通话状态	通话状态检测
`SwitchOverGameData`	WebView→App	启动指定游戏	游戏切换和启动
`backgameData`	WebView→App	返回数据到上级页面	页面数据回传

1. 文本复制接口 (gameCopytext)

接口概述

当WebView需要将文本内容复制到系统剪贴板时，通过此接口实现跨应用的文本复制功能，用户可以在其他应用中粘贴使用。

工作流程

sequenceDiagram
    participant User as 用户
    participant WebView as WebView
    participant App as App
    participant Clipboard as 系统剪贴板
    participant System as 系统
    
    User->>WebView: 触发复制操作
    WebView->>App: 调用gameCopytext接口
    App->>App: 接收要复制的文本
    App->>Clipboard: 写入文本到剪贴板
    Clipboard->>System: 更新系统剪贴板
    App->>WebView: 返回复制结果
    WebView->>User: 显示复制成功提示

参数规范

调用格式

WebViewJavascriptBridge.callHandler('gameCopytext', textContent, function(response) {
    console.log('文本复制结果:', response);
});

参数说明

参数	类型	必需	说明	示例值
textContent	string	✓	要复制的文本内容	"邀请码: ABC123"

接口调用示例

复制邀请码

function copyInviteCode(code) {
    const copyText = `邀请码: ${code}`;
    
    WebViewJavascriptBridge.callHandler('gameCopytext', copyText, function(response) {
        if (response === 'success') {
            showMessage('邀请码已复制到剪贴板');
        } else {
            showMessage('复制失败，请重试');
        }
    });
}

复制游戏链接

function copyGameLink(gameId) {
    const gameLink = `https://game.example.com/play/${gameId}`;
    
    WebViewJavascriptBridge.callHandler('gameCopytext', gameLink, function(response) {
        if (response === 'success') {
            showMessage('游戏链接已复制');
        } else {
            showMessage('复制失败');
        }
    });
}

HarmonyOS实现要点

接口名称: gameCopytext
调用方向: WebView → App
参数格式: 字符串类型的文本内容
权限要求: 无特殊权限要求
错误处理: 返回success/failure状态

2. 获取剪贴板内容接口 (gamepastetext)

接口概述

当WebView需要读取系统剪贴板中的文本内容时，通过此接口获取用户复制的文本数据，常用于邀请码输入等场景。

工作流程

sequenceDiagram
    participant User as 用户
    participant WebView as WebView
    participant App as App
    participant Clipboard as 系统剪贴板
    
    User->>WebView: 触发粘贴操作
    WebView->>App: 调用gamepastetext接口
    App->>Clipboard: 读取剪贴板内容
    Clipboard->>App: 返回文本内容
    App->>WebView: 回传文本内容
    WebView->>WebView: 处理粘贴的文本
    WebView->>User: 显示粘贴内容

参数规范

调用格式

WebViewJavascriptBridge.callHandler('gamepastetext', '', function(clipboardText) {
    console.log('剪贴板内容:', clipboardText);
});

参数说明

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

接口调用示例

智能邀请码输入

function smartPasteInviteCode() {
    WebViewJavascriptBridge.callHandler('gamepastetext', '', function(clipboardText) {
        if (clipboardText) {
            // 检查是否包含邀请码格式
            const inviteCodeMatch = clipboardText.match(/[A-Z0-9]{6,10}/);
            
            if (inviteCodeMatch) {
                const inviteCode = inviteCodeMatch[0];
                document.getElementById('inviteCodeInput').value = inviteCode;
                showMessage('已自动填入邀请码: ' + inviteCode);
            } else {
                showMessage('剪贴板中没有找到有效的邀请码');
            }
        } else {
            showMessage('剪贴板为空');
        }
    });
}

通用文本粘贴

function pasteTextToInput(inputId) {
    WebViewJavascriptBridge.callHandler('gamepastetext', '', function(clipboardText) {
        if (clipboardText) {
            const inputElement = document.getElementById(inputId);
            if (inputElement) {
                inputElement.value = clipboardText;
                inputElement.focus();
                showMessage('已粘贴文本');
            }
        } else {
            showMessage('剪贴板中没有文本内容');
        }
    });
}

HarmonyOS实现要点

接口名称: gamepastetext
调用方向: WebView → App
参数格式: 空字符串
权限要求: 可能需要剪贴板读取权限
返回数据: 直接返回剪贴板中的文本内容

3. 游戏安装状态检查接口 (getGameinstall)

接口概述

检查指定游戏是否已在设备上安装，用于判断是否需要下载游戏资源或显示不同的操作按钮。

工作流程

sequenceDiagram
    participant WebView as WebView
    participant App as App
    participant FileSystem as 文件系统
    participant GameFiles as 游戏文件
    
    WebView->>App: 调用getGameinstall接口
    App->>App: 解析游戏ID参数
    App->>FileSystem: 检查游戏安装路径
    FileSystem->>GameFiles: 验证游戏文件完整性
    GameFiles->>FileSystem: 返回文件状态
    FileSystem->>App: 返回安装状态
    App->>WebView: 回传安装结果
    WebView->>WebView: 更新UI显示

参数规范

调用格式

WebViewJavascriptBridge.callHandler('getGameinstall', gameId, function(isInstalled) {
    console.log('游戏安装状态:', isInstalled);
});

参数说明

参数	类型	必需	说明	示例值
gameId	string	✓	游戏标识符	"game_001", "poker", "landlord"

返回值说明

返回值	含义
"true"	游戏已安装
"false"	游戏未安装

接口调用示例

游戏状态检查器

const GameStatusChecker = {
    // 检查单个游戏状态
    checkGameStatus(gameId, callback) {
        WebViewJavascriptBridge.callHandler('getGameinstall', gameId, function(isInstalled) {
            const status = isInstalled === 'true';
            console.log(`游戏 ${gameId} 安装状态:`, status);
            
            if (callback) {
                callback(gameId, status);
            }
        });
    },
    
    // 批量检查游戏状态
    checkMultipleGames(gameIds, callback) {
        const results = {};
        let completed = 0;
        
        gameIds.forEach(gameId => {
            this.checkGameStatus(gameId, (id, isInstalled) => {
                results[id] = isInstalled;
                completed++;
                
                if (completed === gameIds.length) {
                    callback(results);
                }
            });
        });
    },
    
    // 更新游戏列表UI
    updateGameListUI(gameStatuses) {
        Object.keys(gameStatuses).forEach(gameId => {
            const gameElement = document.getElementById(`game_${gameId}`);
            const isInstalled = gameStatuses[gameId];
            
            if (gameElement) {
                const button = gameElement.querySelector('.game-action-btn');
                
                if (isInstalled) {
                    button.textContent = '开始游戏';
                    button.className = 'game-action-btn btn-play';
                    button.onclick = () => this.startGame(gameId);
                } else {
                    button.textContent = '下载游戏';
                    button.className = 'game-action-btn btn-download';
                    button.onclick = () => this.downloadGame(gameId);
                }
            }
        });
    },
    
    // 启动游戏
    startGame(gameId) {
        // 调用游戏启动接口
        WebViewJavascriptBridge.callHandler('SwitchOverGameData', gameId, function(response) {
            console.log(`游戏 ${gameId} 启动请求已发送`);
        });
    },
    
    // 下载游戏
    downloadGame(gameId) {
        showMessage(`开始下载游戏: ${gameId}`);
        // 实现游戏下载逻辑
    }
};

// 页面加载时检查所有游戏状态
document.addEventListener('DOMContentLoaded', function() {
    const gameIds = ['poker', 'landlord', 'mahjong', 'chess'];
    
    GameStatusChecker.checkMultipleGames(gameIds, function(results) {
        GameStatusChecker.updateGameListUI(results);
    });
});

HarmonyOS实现要点

接口名称: getGameinstall
调用方向: WebView → App
参数格式: 字符串类型的游戏ID
文件检查: 验证游戏文件完整性和版本
返回格式: 字符串"true"或"false"

4. 电话状态检测接口 (getphonestate)

接口概述

获取设备当前的电话通话状态，用于在通话期间暂停游戏或调整音频设置，确保良好的用户体验。

工作流程

sequenceDiagram
    participant WebView as WebView
    participant App as App
    participant TelephonyService as 电话服务
    participant PhoneState as 通话状态
    
    WebView->>App: 调用getphonestate接口
    App->>TelephonyService: 查询电话状态
    TelephonyService->>PhoneState: 获取当前通话状态
    PhoneState->>TelephonyService: 返回状态信息
    TelephonyService->>App: 回传电话状态
    App->>WebView: 返回状态结果
    WebView->>WebView: 根据状态调整应用行为

参数规范

调用格式

WebViewJavascriptBridge.callHandler('getphonestate', '', function(phoneState) {
    console.log('电话状态:', phoneState);
});

参数说明

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

返回值说明

返回值	含义
"0"	空闲状态（无通话）
"1"	响铃状态（来电）
"2"	通话中状态

接口调用示例

通话状态监控器

const PhoneStateMonitor = {
    currentState: null,
    monitoringInterval: null,
    
    // 开始监控电话状态
    startMonitoring() {
        this.checkPhoneState();
        
        // 每2秒检查一次电话状态
        this.monitoringInterval = setInterval(() => {
            this.checkPhoneState();
        }, 2000);
    },
    
    // 停止监控
    stopMonitoring() {
        if (this.monitoringInterval) {
            clearInterval(this.monitoringInterval);
            this.monitoringInterval = null;
        }
    },
    
    // 检查电话状态
    checkPhoneState() {
        WebViewJavascriptBridge.callHandler('getphonestate', '', (phoneState) => {
            const newState = parseInt(phoneState);
            
            if (newState !== this.currentState) {
                this.handleStateChange(this.currentState, newState);
                this.currentState = newState;
            }
        });
    },
    
    // 处理状态变化
    handleStateChange(oldState, newState) {
        console.log(`电话状态变化: ${oldState} -> ${newState}`);
        
        switch (newState) {
            case 0: // 空闲状态
                this.onPhoneIdle();
                break;
            case 1: // 响铃状态
                this.onPhoneRinging();
                break;
            case 2: // 通话中
                this.onPhoneInCall();
                break;
        }
    },
    
    // 电话空闲时
    onPhoneIdle() {
        console.log('电话空闲，恢复游戏');
        this.resumeGame();
        this.restoreAudio();
    },
    
    // 电话响铃时
    onPhoneRinging() {
        console.log('电话响铃，暂停游戏');
        this.pauseGame();
        this.muteAudio();
    },
    
    // 通话中时
    onPhoneInCall() {
        console.log('通话中，保持游戏暂停');
        this.pauseGame();
        this.muteAudio();
    },
    
    // 暂停游戏
    pauseGame() {
        // 暂停游戏逻辑
        const gameContainer = document.getElementById('gameContainer');
        if (gameContainer) {
            gameContainer.style.display = 'none';
        }
        
        // 显示通话提示
        this.showCallNotification();
    },
    
    // 恢复游戏
    resumeGame() {
        // 恢复游戏逻辑
        const gameContainer = document.getElementById('gameContainer');
        if (gameContainer) {
            gameContainer.style.display = 'block';
        }
        
        // 隐藏通话提示
        this.hideCallNotification();
    },
    
    // 静音音频
    muteAudio() {
        // 设置音效为关闭
        WebViewJavascriptBridge.callHandler('voicePlaying', '0', function(response) {
            console.log('音效已静音');
        });
    },
    
    // 恢复音频
    restoreAudio() {
        // 恢复之前的音效设置
        WebViewJavascriptBridge.callHandler('voicePlaying', '1', function(response) {
            console.log('音效已恢复');
        });
    },
    
    // 显示通话提示
    showCallNotification() {
        let notification = document.getElementById('callNotification');
        if (!notification) {
            notification = document.createElement('div');
            notification.id = 'callNotification';
            notification.className = 'call-notification';
            notification.innerHTML = `
                <div class="notification-content">
                    <h3>通话中</h3>
                    <p>游戏已暂停，通话结束后将自动恢复</p>
                </div>
            `;
            document.body.appendChild(notification);
        }
        notification.style.display = 'block';
    },
    
    // 隐藏通话提示
    hideCallNotification() {
        const notification = document.getElementById('callNotification');
        if (notification) {
            notification.style.display = 'none';
        }
    }
};

// 页面加载时开始监控
document.addEventListener('DOMContentLoaded', function() {
    PhoneStateMonitor.startMonitoring();
});

// 页面卸载时停止监控
window.addEventListener('beforeunload', function() {
    PhoneStateMonitor.stopMonitoring();
});

HarmonyOS实现要点

接口名称: getphonestate
调用方向: WebView → App
参数格式: 空字符串
权限要求: 需要READ_PHONE_STATE权限
状态值: 返回0/1/2表示不同的通话状态

5. 游戏启动接口 (SwitchOverGameData)

接口概述

启动指定的游戏应用或切换到其他游戏模块，支持传递启动参数和配置信息。

工作流程

sequenceDiagram
    participant User as 用户
    participant WebView as WebView
    participant App as App
    participant GameEngine as 游戏引擎
    participant GameModule as 游戏模块
    
    User->>WebView: 选择游戏
    WebView->>App: 调用SwitchOverGameData接口
    App->>App: 解析游戏ID和参数
    App->>GameEngine: 初始化游戏引擎
    GameEngine->>GameModule: 加载指定游戏模块
    GameModule->>GameEngine: 返回加载状态
    GameEngine->>App: 游戏启动完成
    App->>WebView: 返回启动结果

参数规范

调用格式

WebViewJavascriptBridge.callHandler('SwitchOverGameData', gameConfig, function(response) {
    console.log('游戏启动结果:', response);
});

参数说明

参数	类型	必需	说明	示例值
gameConfig	string	✓	游戏配置信息	"poker" 或 JSON配置字符串

接口调用示例

启动扑克游戏

function startPokerGame() {
    WebViewJavascriptBridge.callHandler('SwitchOverGameData', 'poker', function(response) {
        if (response === 'success') {
            console.log('扑克游戏启动成功');
        } else {
            showMessage('游戏启动失败，请重试');
        }
    });
}

带参数启动游戏

function startGameWithParams(gameId, gameMode, playerCount) {
    const gameConfig = JSON.stringify({
        gameId: gameId,
        mode: gameMode,
        players: playerCount,
        timestamp: Date.now()
    });
    
    WebViewJavascriptBridge.callHandler('SwitchOverGameData', gameConfig, function(response) {
        console.log('游戏启动配置已发送');
    });
}

HarmonyOS实现要点

接口名称: SwitchOverGameData
调用方向: WebView → App
参数格式: 游戏ID字符串或JSON配置
游戏管理: 需要游戏模块加载和切换机制
错误处理: 处理游戏启动失败的情况

6. 页面数据返回接口 (backgameData)

接口概述

当子页面需要向上级页面传递数据时，通过此接口实现页面间的数据回传，常用于设置页面、选择页面等场景。

工作流程

sequenceDiagram
    participant ChildPage as 子页面
    participant App as App
    participant ParentPage as 父页面
    participant DataHandler as 数据处理器
    
    ChildPage->>App: 调用backgameData接口
    App->>App: 接收返回数据
    App->>DataHandler: 解析数据格式
    DataHandler->>App: 验证数据完整性
    App->>ParentPage: 传递数据到父页面
    ParentPage->>ParentPage: 处理返回数据
    App->>ChildPage: 关闭子页面

参数规范

调用格式

const returnData = {
    type: "settings",
    data: {
        username: "新用户名",
        avatar: "avatar_url"
    }
};

WebViewJavascriptBridge.callHandler('backgameData', JSON.stringify(returnData), function(response) {
    console.log('数据返回成功');
});

参数说明

参数	类型	必需	说明	示例值
returnData	string	✓	JSON格式的返回数据	JSON字符串

接口调用示例

设置页面数据返回

function saveSettingsAndReturn() {
    const settingsData = {
        type: "userSettings",
        data: {
            username: document.getElementById('username').value,
            avatar: document.getElementById('avatar').src,
            theme: document.querySelector('input[name="theme"]:checked').value,
            notifications: document.getElementById('notifications').checked
        },
        timestamp: Date.now()
    };
    
    WebViewJavascriptBridge.callHandler('backgameData', JSON.stringify(settingsData), function(response) {
        console.log('设置已保存并返回');
        // 页面将被自动关闭
    });
}

游戏选择结果返回

function selectGameAndReturn(gameId, gameMode) {
    const selectionData = {
        type: "gameSelection",
        data: {
            selectedGame: gameId,
            gameMode: gameMode,
            difficulty: document.getElementById('difficulty').value
        }
    };
    
    WebViewJavascriptBridge.callHandler('backgameData', JSON.stringify(selectionData), function(response) {
        console.log('游戏选择已确认');
    });
}

HarmonyOS实现要点

接口名称: backgameData
调用方向: WebView → App
参数格式: JSON字符串格式的数据
页面管理: 数据传递后通常会关闭当前页面
数据验证: 需要验证返回数据的格式和完整性

文档关联

本文档是TSGame JSBridge接口规范的第二部分，完整文档包括：

用户认证与页面管理 - 登录、页面跳转、语音控制
系统功能与交互 (本文档) - 剪贴板、游戏状态、设备检测
位置与媒体服务 - GPS定位、音频播放

文档维护: TSGame开发团队
最后更新: 2025年7月13日
版本: v1.9
联系方式: 技术支持组

21 KiB Raw Permalink Blame History Unescape Escape

TSGame JSBridge 接口文档 - 系统功能与交互

文档说明

本文档包含的接口

1. 文本复制接口 (gameCopytext)

接口概述

工作流程

参数规范

调用格式

参数说明

接口调用示例

复制邀请码

复制游戏链接

HarmonyOS实现要点

2. 获取剪贴板内容接口 (gamepastetext)

接口概述

工作流程

参数规范

调用格式

参数说明

接口调用示例

智能邀请码输入

通用文本粘贴

HarmonyOS实现要点

3. 游戏安装状态检查接口 (getGameinstall)

接口概述

工作流程

参数规范

调用格式

参数说明

返回值说明

接口调用示例

游戏状态检查器

HarmonyOS实现要点

4. 电话状态检测接口 (getphonestate)

接口概述

工作流程

参数规范

调用格式

参数说明

返回值说明

接口调用示例

通话状态监控器

HarmonyOS实现要点

5. 游戏启动接口 (SwitchOverGameData)

接口概述

工作流程

参数规范

调用格式

参数说明

接口调用示例

启动扑克游戏

带参数启动游戏

HarmonyOS实现要点

6. 页面数据返回接口 (backgameData)

接口概述

工作流程

参数规范

调用格式

参数说明

接口调用示例

设置页面数据返回

游戏选择结果返回

HarmonyOS实现要点

文档关联

21 KiB

Raw Permalink Blame History