# 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需要将文本内容复制到系统剪贴板时，通过此接口实现跨应用的文本复制功能，用户可以在其他应用中粘贴使用。

### 工作流程
```mermaid
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: 显示复制成功提示
```

### 参数规范

#### 调用格式
```javascript
WebViewJavascriptBridge.callHandler('gameCopytext', textContent, function(response) {
    console.log('文本复制结果:', response);
});
```

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

### 接口调用示例

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

#### 复制游戏链接
```javascript
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需要读取系统剪贴板中的文本内容时，通过此接口获取用户复制的文本数据，常用于邀请码输入等场景。

### 工作流程
```mermaid
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: 显示粘贴内容
```

### 参数规范

#### 调用格式
```javascript
WebViewJavascriptBridge.callHandler('gamepastetext', '', function(clipboardText) {
    console.log('剪贴板内容:', clipboardText);
});
```

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

### 接口调用示例

#### 智能邀请码输入
```javascript
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('剪贴板为空');
        }
    });
}
```

#### 通用文本粘贴
```javascript
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)

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

### 工作流程
```mermaid
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显示
```

### 参数规范

#### 调用格式
```javascript
WebViewJavascriptBridge.callHandler('getGameinstall', gameId, function(isInstalled) {
    console.log('游戏安装状态:', isInstalled);
});
```

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

#### 返回值说明
| 返回值 | 含义 |
|--------|------|
| "true" | 游戏已安装 |
| "false" | 游戏未安装 |

### 接口调用示例

#### 游戏状态检查器
```javascript
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)

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

### 工作流程
```mermaid
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: 根据状态调整应用行为
```

### 参数规范

#### 调用格式
```javascript
WebViewJavascriptBridge.callHandler('getphonestate', '', function(phoneState) {
    console.log('电话状态:', phoneState);
});
```

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

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

### 接口调用示例

#### 通话状态监控器
```javascript
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)

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

### 工作流程
```mermaid
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: 返回启动结果
```

### 参数规范

#### 调用格式
```javascript
WebViewJavascriptBridge.callHandler('SwitchOverGameData', gameConfig, function(response) {
    console.log('游戏启动结果:', response);
});
```

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

### 接口调用示例

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

#### 带参数启动游戏
```javascript
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)

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

### 工作流程
```mermaid
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: 关闭子页面
```

### 参数规范

#### 调用格式
```javascript
const returnData = {
    type: "settings",
    data: {
        username: "新用户名",
        avatar: "avatar_url"
    }
};

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

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

### 接口调用示例

#### 设置页面数据返回
```javascript
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('设置已保存并返回');
        // 页面将被自动关闭
    });
}
```

#### 游戏选择结果返回
```javascript
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接口规范的第二部分，完整文档包括：

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

---

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