first commit
This commit is contained in:
833
guides/JavaScript调用原生接口文档/TSGame_JSBridge_位置与媒体服务.md
Normal file
833
guides/JavaScript调用原生接口文档/TSGame_JSBridge_位置与媒体服务.md
Normal file
@@ -0,0 +1,833 @@
|
||||
# TSGame JSBridge 接口文档 - 位置与媒体服务
|
||||
|
||||
**版本**: v1.9
|
||||
**更新时间**: 2025年7月13日
|
||||
**文档类型**: 接口规范文档 - 第三部分
|
||||
|
||||
## 文档说明
|
||||
|
||||
本文档是TSGame JSBridge接口规范文档的第三部分，专注于位置服务与媒体播放相关接口，包括GPS定位、音频播放控制等功能。
|
||||
|
||||
**适用平台**: Android / HarmonyOS
|
||||
**接口范围**: GPS定位服务、音频媒体播放
|
||||
|
||||
### 本文档包含的接口
|
||||
|
||||
| 接口名称 | 调用方向 | 主要功能 | 使用场景 |
|
||||
|----------|----------|----------|----------|
|
||||
| `startlocation` | WebView→App | 开始位置定位 | GPS定位服务 |
|
||||
| `getlocationinfo` | WebView→App | 获取当前位置信息 | 位置信息查询 |
|
||||
| `mediaTypeAudio` | WebView→App | 音频播放控制 | 音频媒体播放 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 开始定位接口 (startlocation)
|
||||
|
||||
### 接口概述
|
||||
当WebView需要开始GPS定位服务时，通过此接口启动位置定位功能。支持连续定位和单次定位两种模式，定位结果会通过`getlocationinfo`接口异步返回或自动回调到WebView。
|
||||
|
||||
### 工作流程
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant WebView as WebView
|
||||
participant App as App
|
||||
participant LocationClient as 位置服务
|
||||
participant AMapSDK as 高德地图SDK
|
||||
participant GPS as GPS/网络定位
|
||||
|
||||
User->>WebView: 触发定位需求
|
||||
WebView->>App: 调用startlocation接口
|
||||
App->>App: 解析定位类型参数
|
||||
App->>LocationClient: 初始化AMapLocationClient
|
||||
LocationClient->>AMapSDK: 配置定位选项
|
||||
AMapSDK->>GPS: 启动定位服务
|
||||
|
||||
alt 连续定位模式
|
||||
GPS->>AMapSDK: 持续返回位置信息
|
||||
AMapSDK->>LocationClient: 定位回调(每3秒)
|
||||
LocationClient->>App: onLocationChanged事件
|
||||
App->>WebView: 调用getlocationinfo传递位置
|
||||
else 单次定位模式
|
||||
GPS->>AMapSDK: 返回最高精度位置
|
||||
AMapSDK->>LocationClient: 单次定位回调
|
||||
LocationClient->>App: onLocationChanged事件
|
||||
App->>App: 保存位置信息供后续查询
|
||||
end
|
||||
```
|
||||
|
||||
### 参数规范
|
||||
|
||||
#### 调用格式
|
||||
```javascript
|
||||
WebViewJavascriptBridge.callHandler('startlocation', locationType, function(response) {
|
||||
console.log('定位服务已启动');
|
||||
});
|
||||
```
|
||||
|
||||
#### 参数说明
|
||||
| 参数 | 类型 | 必需 | 说明 | 取值 |
|
||||
|------|------|------|------|------|
|
||||
| locationType | string | ✓ | 定位类型 | "1"=连续定位, "2"或其他=单次定位 |
|
||||
|
||||
#### 定位类型说明
|
||||
| 类型值 | 定位模式 | 说明 | 适用场景 |
|
||||
|--------|----------|------|----------|
|
||||
| "1" | 连续定位 | 每3秒更新一次位置信息 | 导航、实时跟踪 |
|
||||
| "2" | 单次定位 | 获取一次最高精度位置 | 位置标记、签到 |
|
||||
| 其他值 | 单次定位 | 默认为单次定位模式 | 通用位置获取 |
|
||||
|
||||
### 接口调用示例
|
||||
|
||||
#### 启动连续定位
|
||||
```javascript
|
||||
// 启动连续定位，适用于导航场景
|
||||
function startContinuousLocation() {
|
||||
WebViewJavascriptBridge.callHandler('startlocation', '1', function(response) {
|
||||
console.log('连续定位已启动，每3秒更新一次位置');
|
||||
|
||||
// 连续定位会自动调用getlocationinfo回调
|
||||
// 需要注册位置更新处理函数
|
||||
window.onLocationUpdate = function(locationData) {
|
||||
updateUserPosition(locationData);
|
||||
};
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
#### 启动单次定位
|
||||
```javascript
|
||||
// 启动单次定位，适用于签到场景
|
||||
function startOnceLocation() {
|
||||
WebViewJavascriptBridge.callHandler('startlocation', '2', function(response) {
|
||||
console.log('单次定位已启动，正在获取最精确位置');
|
||||
|
||||
// 等待3秒后查询位置信息
|
||||
setTimeout(() => {
|
||||
getLocationInfo();
|
||||
}, 3000);
|
||||
});
|
||||
}
|
||||
|
||||
// 获取定位结果
|
||||
function getLocationInfo() {
|
||||
WebViewJavascriptBridge.callHandler('getlocationinfo', '', function(locationJson) {
|
||||
if (locationJson) {
|
||||
const location = JSON.parse(locationJson);
|
||||
console.log('定位成功:', location);
|
||||
showLocationOnMap(location);
|
||||
} else {
|
||||
console.log('定位失败或未完成');
|
||||
}
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
#### 智能定位管理器
|
||||
```javascript
|
||||
// 定位管理器
|
||||
const LocationManager = {
|
||||
isLocating: false,
|
||||
locationType: 'once', // 'once' 或 'continuous'
|
||||
locationTimer: null,
|
||||
|
||||
// 开始定位
|
||||
startLocation(type = 'once') {
|
||||
if (this.isLocating) {
|
||||
console.log('定位服务已在运行中');
|
||||
return;
|
||||
}
|
||||
|
||||
this.locationType = type;
|
||||
this.isLocating = true;
|
||||
|
||||
const typeParam = type === 'continuous' ? '1' : '2';
|
||||
|
||||
WebViewJavascriptBridge.callHandler('startlocation', typeParam, (response) => {
|
||||
console.log(`${type}定位已启动`);
|
||||
|
||||
if (type === 'continuous') {
|
||||
this.startLocationMonitoring();
|
||||
} else {
|
||||
this.checkLocationResult();
|
||||
}
|
||||
});
|
||||
},
|
||||
|
||||
// 停止定位
|
||||
stopLocation() {
|
||||
this.isLocating = false;
|
||||
|
||||
if (this.locationTimer) {
|
||||
clearInterval(this.locationTimer);
|
||||
this.locationTimer = null;
|
||||
}
|
||||
|
||||
console.log('定位服务已停止');
|
||||
},
|
||||
|
||||
// 监控连续定位
|
||||
startLocationMonitoring() {
|
||||
// 每4秒检查一次位置更新（略大于定位间隔3秒）
|
||||
this.locationTimer = setInterval(() => {
|
||||
this.getCurrentLocation((location) => {
|
||||
if (location) {
|
||||
this.onLocationUpdate(location);
|
||||
}
|
||||
});
|
||||
}, 4000);
|
||||
},
|
||||
|
||||
// 检查单次定位结果
|
||||
checkLocationResult() {
|
||||
// 等待3秒让定位完成
|
||||
setTimeout(() => {
|
||||
this.getCurrentLocation((location) => {
|
||||
this.isLocating = false;
|
||||
|
||||
if (location) {
|
||||
this.onLocationReceived(location);
|
||||
} else {
|
||||
this.onLocationError('定位失败');
|
||||
}
|
||||
});
|
||||
}, 3000);
|
||||
},
|
||||
|
||||
// 获取当前位置
|
||||
getCurrentLocation(callback) {
|
||||
WebViewJavascriptBridge.callHandler('getlocationinfo', '', (locationJson) => {
|
||||
if (locationJson) {
|
||||
try {
|
||||
const location = JSON.parse(locationJson);
|
||||
callback(location);
|
||||
} catch (e) {
|
||||
console.error('位置数据解析失败:', e);
|
||||
callback(null);
|
||||
}
|
||||
} else {
|
||||
callback(null);
|
||||
}
|
||||
});
|
||||
},
|
||||
|
||||
// 位置更新回调（连续定位）
|
||||
onLocationUpdate(location) {
|
||||
console.log('位置更新:', location);
|
||||
// 更新地图显示
|
||||
updateMapPosition(location);
|
||||
// 触发位置变化事件
|
||||
this.triggerLocationChange(location);
|
||||
},
|
||||
|
||||
// 位置获取回调（单次定位）
|
||||
onLocationReceived(location) {
|
||||
console.log('定位完成:', location);
|
||||
// 显示位置信息
|
||||
showLocationDetails(location);
|
||||
// 执行签到等操作
|
||||
performLocationBasedAction(location);
|
||||
},
|
||||
|
||||
// 定位错误处理
|
||||
onLocationError(error) {
|
||||
console.error('定位错误:', error);
|
||||
showMessage('定位失败，请检查位置权限和网络连接');
|
||||
},
|
||||
|
||||
// 触发位置变化事件
|
||||
triggerLocationChange(location) {
|
||||
const event = new CustomEvent('locationChanged', {
|
||||
detail: location
|
||||
});
|
||||
window.dispatchEvent(event);
|
||||
}
|
||||
};
|
||||
|
||||
// 使用示例
|
||||
LocationManager.startLocation('continuous'); // 启动连续定位
|
||||
// LocationManager.startLocation('once'); // 启动单次定位
|
||||
|
||||
// 监听位置变化
|
||||
window.addEventListener('locationChanged', function(event) {
|
||||
const location = event.detail;
|
||||
console.log('位置已更新:', location.address);
|
||||
});
|
||||
```
|
||||
|
||||
### HarmonyOS实现要点
|
||||
- **接口名称**: `startlocation`
|
||||
- **调用方向**: WebView → App
|
||||
- **参数格式**: 字符串类型的定位类型（"1"=连续定位, "2"=单次定位）
|
||||
- **权限要求**: 需要精确位置权限和网络权限
|
||||
- **SDK依赖**: 使用高德地图SDK (AMapLocationClient)
|
||||
- **定位模式**: 高精度定位模式 (Hight_Accuracy)
|
||||
- **连续定位**: 3秒间隔的连续位置更新
|
||||
- **单次定位**: 3秒内最高精度的一次定位
|
||||
- **回调机制**: 通过AMapLocationListener.onLocationChanged接收位置更新
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取位置信息接口 (getlocationinfo)
|
||||
|
||||
### 接口概述
|
||||
当WebView需要获取当前设备的位置信息时，通过此接口查询最近一次定位的结果。必须先调用`startlocation`接口启动定位服务，才能获取到有效的位置数据。
|
||||
|
||||
### 工作流程
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant WebView as WebView
|
||||
participant App as App
|
||||
participant LocationCache as 位置缓存
|
||||
participant LocationData as 位置数据对象
|
||||
|
||||
WebView->>App: 调用getlocationinfo接口
|
||||
App->>LocationCache: 检查缓存的位置信息
|
||||
|
||||
alt 有位置数据
|
||||
LocationCache->>LocationData: 获取MaplocationInfo对象
|
||||
LocationData->>LocationData: 序列化为JSON
|
||||
LocationData->>App: 返回JSON字符串
|
||||
App->>WebView: 回调返回位置JSON
|
||||
else 无位置数据
|
||||
LocationCache->>App: 返回null
|
||||
App->>WebView: 回调返回null
|
||||
end
|
||||
|
||||
WebView->>WebView: 解析位置JSON数据
|
||||
WebView->>WebView: 处理位置信息
|
||||
```
|
||||
|
||||
### 参数规范
|
||||
|
||||
#### 调用格式
|
||||
```javascript
|
||||
WebViewJavascriptBridge.callHandler('getlocationinfo', '', function(locationJson) {
|
||||
if (locationJson) {
|
||||
const location = JSON.parse(locationJson);
|
||||
console.log('当前位置:', location);
|
||||
} else {
|
||||
console.log('暂无位置信息');
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### 参数说明
|
||||
| 参数 | 类型 | 必需 | 说明 | 取值 |
|
||||
|------|------|------|------|------|
|
||||
| data | string | ✓ | 固定传入空字符串 | "" |
|
||||
|
||||
#### 返回数据结构
|
||||
| 字段 | 类型 | 说明 | 示例值 |
|
||||
|------|------|------|-------|
|
||||
| latitude | number | 纬度 | 39.908692 |
|
||||
| longitude | number | 经度 | 116.397477 |
|
||||
| address | string | 详细地址 | "北京市东城区正义路2号" |
|
||||
| country | string | 国家 | "中国" |
|
||||
| province | string | 省份 | "北京市" |
|
||||
| city | string | 城市 | "北京市" |
|
||||
| district | string | 城区 | "东城区" |
|
||||
| street | string | 街道 | "正义路" |
|
||||
| cityCode | string | 城市编码 | "010" |
|
||||
|
||||
### 接口调用示例
|
||||
|
||||
#### 基础位置获取
|
||||
```javascript
|
||||
// 获取当前位置信息
|
||||
function getCurrentLocation() {
|
||||
WebViewJavascriptBridge.callHandler('getlocationinfo', '', function(locationJson) {
|
||||
if (locationJson) {
|
||||
try {
|
||||
const location = JSON.parse(locationJson);
|
||||
displayLocationInfo(location);
|
||||
} catch (e) {
|
||||
console.error('位置数据解析失败:', e);
|
||||
}
|
||||
} else {
|
||||
console.log('位置信息不可用，请先启动定位服务');
|
||||
startLocationFirst();
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// 显示位置信息
|
||||
function displayLocationInfo(location) {
|
||||
console.log('=== 当前位置信息 ===');
|
||||
console.log('纬度:', location.latitude);
|
||||
console.log('经度:', location.longitude);
|
||||
console.log('地址:', location.address);
|
||||
console.log('城市:', location.city);
|
||||
console.log('区县:', location.district);
|
||||
|
||||
// 更新页面显示
|
||||
updateLocationDisplay(location);
|
||||
}
|
||||
|
||||
// 提示启动定位
|
||||
function startLocationFirst() {
|
||||
if (confirm('需要先启动定位服务，是否立即启动？')) {
|
||||
WebViewJavascriptBridge.callHandler('startlocation', '2', function(response) {
|
||||
console.log('定位服务已启动，3秒后重新获取位置');
|
||||
setTimeout(getCurrentLocation, 3000);
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 完整的位置服务流程
|
||||
```javascript
|
||||
// 位置服务管理器
|
||||
const LocationService = {
|
||||
// 获取位置信息（带自动定位）
|
||||
getLocationWithAutoStart(callback) {
|
||||
// 先尝试获取已有的位置信息
|
||||
WebViewJavascriptBridge.callHandler('getlocationinfo', '', (locationJson) => {
|
||||
if (locationJson) {
|
||||
// 已有位置信息，直接返回
|
||||
try {
|
||||
const location = JSON.parse(locationJson);
|
||||
callback(null, location);
|
||||
} catch (e) {
|
||||
callback('位置数据解析失败', null);
|
||||
}
|
||||
} else {
|
||||
// 没有位置信息，启动定位
|
||||
this.startLocationAndGet(callback);
|
||||
}
|
||||
});
|
||||
},
|
||||
|
||||
// 启动定位并获取结果
|
||||
startLocationAndGet(callback) {
|
||||
console.log('正在启动定位服务...');
|
||||
|
||||
WebViewJavascriptBridge.callHandler('startlocation', '2', (response) => {
|
||||
console.log('定位服务已启动，等待定位完成...');
|
||||
|
||||
// 等待定位完成
|
||||
this.waitForLocation(callback, 0);
|
||||
});
|
||||
},
|
||||
|
||||
// 等待定位完成
|
||||
waitForLocation(callback, attempts) {
|
||||
if (attempts >= 10) {
|
||||
callback('定位超时', null);
|
||||
return;
|
||||
}
|
||||
|
||||
setTimeout(() => {
|
||||
WebViewJavascriptBridge.callHandler('getlocationinfo', '', (locationJson) => {
|
||||
if (locationJson) {
|
||||
try {
|
||||
const location = JSON.parse(locationJson);
|
||||
callback(null, location);
|
||||
} catch (e) {
|
||||
callback('位置数据解析失败', null);
|
||||
}
|
||||
} else {
|
||||
// 继续等待
|
||||
this.waitForLocation(callback, attempts + 1);
|
||||
}
|
||||
});
|
||||
}, 1000); // 每秒检查一次
|
||||
},
|
||||
|
||||
// 验证位置数据完整性
|
||||
validateLocation(location) {
|
||||
const required = ['latitude', 'longitude'];
|
||||
const missing = required.filter(field => !location[field]);
|
||||
|
||||
return {
|
||||
isValid: missing.length === 0,
|
||||
missing: missing,
|
||||
hasAddress: !!location.address
|
||||
};
|
||||
},
|
||||
|
||||
// 格式化位置显示
|
||||
formatLocationDisplay(location) {
|
||||
const validation = this.validateLocation(location);
|
||||
|
||||
if (!validation.isValid) {
|
||||
return '位置信息不完整';
|
||||
}
|
||||
|
||||
// 构建显示文本
|
||||
let display = `${location.latitude.toFixed(6)}, ${location.longitude.toFixed(6)}`;
|
||||
|
||||
if (validation.hasAddress) {
|
||||
display += `\n${location.address}`;
|
||||
}
|
||||
|
||||
return display;
|
||||
}
|
||||
};
|
||||
|
||||
// 使用示例
|
||||
LocationService.getLocationWithAutoStart((error, location) => {
|
||||
if (error) {
|
||||
console.error('获取位置失败:', error);
|
||||
showMessage('定位失败: ' + error);
|
||||
} else {
|
||||
console.log('位置获取成功:', location);
|
||||
|
||||
const validation = LocationService.validateLocation(location);
|
||||
if (validation.isValid) {
|
||||
const displayText = LocationService.formatLocationDisplay(location);
|
||||
showLocationInfo(displayText);
|
||||
} else {
|
||||
console.warn('位置数据不完整:', validation.missing);
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### HarmonyOS实现要点
|
||||
- **接口名称**: `getlocationinfo`
|
||||
- **调用方向**: WebView → App
|
||||
- **参数格式**: 空字符串
|
||||
- **返回数据**: JSON字符串格式的位置信息对象
|
||||
- **数据来源**: 由startlocation接口触发的定位结果
|
||||
- **数据结构**: MaplocationInfo对象的JSON序列化
|
||||
- **前置条件**: 需要先调用startlocation启动定位服务
|
||||
- **数据字段**: 包含经纬度、地址、行政区划等完整位置信息
|
||||
- **缓存机制**: App内存中保存最新一次定位结果
|
||||
|
||||
---
|
||||
|
||||
## 3. 音频播放接口 (mediaTypeAudio)
|
||||
|
||||
### 接口概述
|
||||
当WebView需要播放音频文件时，通过此接口实现音频的播放控制。支持普通音频和历史音频两种类型，具有防重复播放机制，播放开始时会调用gameui_play_voice通知，播放完成后会自动通知WebView。
|
||||
|
||||
### 工作流程
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant WebView as WebView
|
||||
participant App as App
|
||||
participant MediaPlayer as 媒体播放器
|
||||
participant AudioSystem as 音频系统
|
||||
participant Server as 音频服务器
|
||||
|
||||
User->>WebView: 触发音频播放
|
||||
WebView->>App: 调用mediaTypeAudio接口
|
||||
App->>App: 解析音频参数(audiourl/type/user)
|
||||
App->>App: 检查防重复播放标志
|
||||
|
||||
alt 可以播放音频
|
||||
App->>App: 验证音频URL格式
|
||||
App->>Server: 下载音频文件(如果是网络URL)
|
||||
Server->>App: 返回音频数据
|
||||
App->>MediaPlayer: 初始化播放器
|
||||
App->>WebView: 调用gameui_play_voice通知播放开始
|
||||
MediaPlayer->>AudioSystem: 开始播放音频
|
||||
|
||||
Note over MediaPlayer,AudioSystem: 播放过程中
|
||||
MediaPlayer->>App: 播放状态回调
|
||||
App->>App: 更新播放标志状态
|
||||
|
||||
alt 播放完成
|
||||
MediaPlayer->>App: 播放完成回调
|
||||
App->>WebView: 调用gameui_stop_voice通知
|
||||
App->>App: 重置播放状态
|
||||
else 播放错误
|
||||
MediaPlayer->>App: 播放错误回调
|
||||
App->>App: 重置播放状态
|
||||
App->>WebView: 错误通知
|
||||
end
|
||||
|
||||
else 正在播放中
|
||||
App->>App: 添加到延时播放队列
|
||||
Note over App: 200ms后重试播放
|
||||
end
|
||||
```
|
||||
|
||||
### 参数规范
|
||||
|
||||
#### 调用格式
|
||||
```javascript
|
||||
const audioData = {
|
||||
audiourl: "https://example.com/audio.mp3",
|
||||
type: "1",
|
||||
user: "user_123"
|
||||
};
|
||||
|
||||
WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData), function(response) {
|
||||
console.log('音频播放请求已发送');
|
||||
});
|
||||
```
|
||||
|
||||
#### 参数说明
|
||||
| 参数 | 类型 | 必需 | 说明 | 示例值 |
|
||||
|------|------|------|------|--------|
|
||||
| audiourl | string | ✓ | 音频文件URL地址 | "https://cdn.example.com/sound.mp3" |
|
||||
| type | string | ✓ | 音频类型 | "1"=普通音频, "2"=历史音频 |
|
||||
| user | string | ✓ | 用户标识或动画位置 | "user_123", "avatar_position_1" |
|
||||
|
||||
#### 音频类型说明
|
||||
| 类型值 | 播放模式 | 说明 | 适用场景 |
|
||||
|--------|----------|------|----------|
|
||||
| "1" | 普通音频 | 新音频播放，支持防重复机制 | 音效、提示音 |
|
||||
| "2" | 历史音频 | 历史音频重播，无防重复限制 | 聊天记录回放 |
|
||||
|
||||
### 接口调用示例
|
||||
|
||||
#### 播放游戏音效
|
||||
```javascript
|
||||
// 播放游戏胜利音效
|
||||
function playVictorySound() {
|
||||
const audioData = {
|
||||
audiourl: "https://game.example.com/sounds/victory.mp3",
|
||||
type: "1",
|
||||
user: "game_effect_victory"
|
||||
};
|
||||
|
||||
WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData), function(response) {
|
||||
console.log('胜利音效播放中...');
|
||||
});
|
||||
}
|
||||
|
||||
// 播放按钮点击音效
|
||||
function playButtonClickSound() {
|
||||
const audioData = {
|
||||
audiourl: "https://game.example.com/sounds/button_click.mp3",
|
||||
type: "1",
|
||||
user: "ui_button_click"
|
||||
};
|
||||
|
||||
WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData), function(response) {
|
||||
console.log('按钮音效播放中...');
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
#### 完整的音频管理系统
|
||||
```javascript
|
||||
// 音频播放管理器
|
||||
const AudioManager = {
|
||||
playingAudios: new Map(), // 正在播放的音频
|
||||
audioQueue: [], // 音频播放队列
|
||||
isProcessingQueue: false,
|
||||
|
||||
// 播放音频
|
||||
playAudio(audioUrl, options = {}) {
|
||||
const audioData = {
|
||||
audiourl: audioUrl,
|
||||
type: options.type || "1",
|
||||
user: options.userId || this.generateUserId()
|
||||
};
|
||||
|
||||
// 添加到播放队列
|
||||
this.addToQueue(audioData, options.callback);
|
||||
|
||||
// 处理队列
|
||||
this.processQueue();
|
||||
|
||||
return audioData.user;
|
||||
},
|
||||
|
||||
// 生成唯一用户ID
|
||||
generateUserId() {
|
||||
return "audio_" + Date.now() + "_" + Math.random().toString(36).substr(2, 9);
|
||||
},
|
||||
|
||||
// 添加到播放队列
|
||||
addToQueue(audioData, callback) {
|
||||
this.audioQueue.push({
|
||||
audioData: audioData,
|
||||
callback: callback,
|
||||
timestamp: Date.now()
|
||||
});
|
||||
},
|
||||
|
||||
// 处理播放队列
|
||||
processQueue() {
|
||||
if (this.isProcessingQueue || this.audioQueue.length === 0) {
|
||||
return;
|
||||
}
|
||||
|
||||
this.isProcessingQueue = true;
|
||||
|
||||
const queueItem = this.audioQueue.shift();
|
||||
this.executePlayback(queueItem);
|
||||
},
|
||||
|
||||
// 执行播放
|
||||
executePlayback(queueItem) {
|
||||
const { audioData, callback } = queueItem;
|
||||
|
||||
// 记录播放状态
|
||||
this.playingAudios.set(audioData.user, {
|
||||
audioData: audioData,
|
||||
startTime: Date.now(),
|
||||
callback: callback
|
||||
});
|
||||
|
||||
console.log('开始播放音频:', audioData.audiourl);
|
||||
|
||||
WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData), (response) => {
|
||||
console.log('音频播放请求已发送:', audioData.user);
|
||||
|
||||
if (callback) {
|
||||
callback(null, audioData.user);
|
||||
}
|
||||
|
||||
// 继续处理下一个队列项
|
||||
setTimeout(() => {
|
||||
this.isProcessingQueue = false;
|
||||
this.processQueue();
|
||||
}, 200);
|
||||
});
|
||||
},
|
||||
|
||||
// 处理播放开始
|
||||
onAudioStart(userId) {
|
||||
const playingInfo = this.playingAudios.get(userId);
|
||||
|
||||
if (playingInfo) {
|
||||
console.log(`音频播放开始: ${userId}`);
|
||||
|
||||
// 触发播放开始事件
|
||||
this.triggerAudioStartEvent(userId);
|
||||
|
||||
// 调用回调
|
||||
if (playingInfo.callback) {
|
||||
playingInfo.callback(null, 'started');
|
||||
}
|
||||
} else {
|
||||
console.log(`收到播放开始通知，但未找到对应的音频记录: ${userId}`);
|
||||
}
|
||||
},
|
||||
|
||||
// 处理播放完成
|
||||
onAudioComplete(userId) {
|
||||
const playingInfo = this.playingAudios.get(userId);
|
||||
|
||||
if (playingInfo) {
|
||||
const duration = Date.now() - playingInfo.startTime;
|
||||
console.log(`音频播放完成: ${userId}, 耗时: ${duration}ms`);
|
||||
|
||||
// 移除播放记录
|
||||
this.playingAudios.delete(userId);
|
||||
|
||||
// 触发完成事件
|
||||
this.triggerAudioCompleteEvent(userId, duration);
|
||||
|
||||
// 调用回调
|
||||
if (playingInfo.callback) {
|
||||
playingInfo.callback(null, 'completed');
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 触发音频开始事件
|
||||
triggerAudioStartEvent(userId) {
|
||||
const event = new CustomEvent('audioPlayStart', {
|
||||
detail: {
|
||||
userId: userId
|
||||
}
|
||||
});
|
||||
window.dispatchEvent(event);
|
||||
},
|
||||
|
||||
// 触发音频完成事件
|
||||
triggerAudioCompleteEvent(userId, duration) {
|
||||
const event = new CustomEvent('audioPlayComplete', {
|
||||
detail: {
|
||||
userId: userId,
|
||||
duration: duration
|
||||
}
|
||||
});
|
||||
window.dispatchEvent(event);
|
||||
},
|
||||
|
||||
// 停止所有音频
|
||||
stopAllAudio() {
|
||||
this.playingAudios.clear();
|
||||
this.audioQueue = [];
|
||||
this.isProcessingQueue = false;
|
||||
console.log('已停止所有音频播放');
|
||||
},
|
||||
|
||||
// 获取播放状态
|
||||
getPlayingStatus() {
|
||||
return {
|
||||
playingCount: this.playingAudios.size,
|
||||
queueLength: this.audioQueue.length,
|
||||
isProcessing: this.isProcessingQueue
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
// 注册音频播放相关监听
|
||||
if (typeof WebViewJavascriptBridge !== 'undefined') {
|
||||
// 注册音频播放开始通知
|
||||
WebViewJavascriptBridge.registerHandler('gameui_play_voice', function(userId) {
|
||||
console.log('收到音频播放开始通知:', userId);
|
||||
AudioManager.onAudioStart(userId);
|
||||
});
|
||||
|
||||
// 注册音频播放完成通知
|
||||
WebViewJavascriptBridge.registerHandler('gameui_stop_voice', function(userId) {
|
||||
console.log('收到音频播放完成通知:', userId);
|
||||
AudioManager.onAudioComplete(userId);
|
||||
});
|
||||
}
|
||||
|
||||
// 使用示例
|
||||
const userId1 = AudioManager.playAudio('https://example.com/sound1.mp3', {
|
||||
type: '1',
|
||||
userId: 'background_music',
|
||||
callback: (error, result) => {
|
||||
if (error) {
|
||||
console.error('播放失败:', error);
|
||||
} else {
|
||||
console.log('播放结果:', result);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// 监听播放开始事件
|
||||
window.addEventListener('audioPlayStart', function(event) {
|
||||
const { userId } = event.detail;
|
||||
console.log(`音频 ${userId} 开始播放`);
|
||||
});
|
||||
|
||||
// 监听播放完成事件
|
||||
window.addEventListener('audioPlayComplete', function(event) {
|
||||
const { userId, duration } = event.detail;
|
||||
console.log(`音频 ${userId} 播放完成，耗时 ${duration}ms`);
|
||||
});
|
||||
```
|
||||
|
||||
### HarmonyOS实现要点
|
||||
- **接口名称**: `mediaTypeAudio`
|
||||
- **调用方向**: WebView → App
|
||||
- **参数格式**: JSON字符串，包含audiourl、type、user字段
|
||||
- **音频支持**: 支持各种音频格式(MP3、WAV、AAC等)
|
||||
- **防重复机制**: type为"1"时启用防重复播放检查
|
||||
- **播放队列**: 正在播放时新音频延时200ms重试
|
||||
- **开始通知**: 通过gameui_play_voice回调通知WebView播放开始
|
||||
- **完成通知**: 通过gameui_stop_voice回调通知WebView播放完成
|
||||
- **音量控制**: 受voicePlaying接口的全局音量开关影响
|
||||
- **错误处理**: 包含URL验证、格式检查、播放状态管理
|
||||
|
||||
---
|
||||
|
||||
## 文档关联
|
||||
|
||||
本文档是TSGame JSBridge接口规范的第三部分，完整文档包括：
|
||||
|
||||
1. **用户认证与页面管理** - 登录、页面跳转、语音控制
|
||||
2. **系统功能与交互** - 剪贴板、游戏状态、设备检测
|
||||
3. **位置与媒体服务** (本文档) - GPS定位、音频播放
|
||||
|
||||
---
|
||||
|
||||
**文档维护**: TSGame开发团队
|
||||
**最后更新**: 2025年7月13日
|
||||
**版本**: v1.9
|
||||
**联系方式**: 技术支持组
|
||||
154
guides/JavaScript调用原生接口文档/TSGame_JSBridge_文档总览.md
Normal file
154
guides/JavaScript调用原生接口文档/TSGame_JSBridge_文档总览.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# TSGame JSBridge 接口文档 - 总览
|
||||
|
||||
**版本**: v1.9
|
||||
**更新时间**: 2025年7月13日
|
||||
**文档类型**: 接口规范文档总览
|
||||
|
||||
## 文档说明
|
||||
|
||||
本文档集详细描述TSGame游戏中WebView JavaScript调用App原生功能的所有JSBridge接口规范。为了便于阅读和维护，文档按功能模块拆分为4个部分。
|
||||
|
||||
**适用平台**: Android / HarmonyOS
|
||||
**总接口数量**: 18个核心接口
|
||||
|
||||
## 文档结构
|
||||
|
||||
### 📁 文档分册
|
||||
|
||||
| 文档名称 | 接口数量 | 主要功能 | 文件名 |
|
||||
|----------|----------|----------|---------|
|
||||
| **用户认证与页面管理** | 4个 | 登录认证、页面跳转、语音控制 | `TSGame_JSBridge_用户认证与页面管理.md` |
|
||||
| **系统功能与交互** | 4个 | 剪贴板操作、游戏管理、设备检测 | `TSGame_JSBridge_系统功能与交互.md` |
|
||||
| **位置与媒体服务** | 5个 | GPS定位、音频播放 | `TSGame_JSBridge_位置与媒体服务.md` |
|
||||
| **高级功能与扩展** | 5个 | 录音控制、震动反馈、社交分享 | `TSGame_JSBridge_高级功能与扩展.md` |
|
||||
|
||||
## 完整接口清单
|
||||
|
||||
### 🔐 用户认证与页面管理
|
||||
| 接口名称 | 功能描述 | 调用方向 | 使用场景 |
|
||||
|----------|----------|----------|----------|
|
||||
| `accreditlogin` | 授权登录 | WebView→App | 微信/QQ登录 |
|
||||
| `cancellogin` | 取消登录 | WebView→App | 登录过程中取消操作 |
|
||||
| `OpenurlTitleData` | 打开新WebView页面 | WebView→App | 页面跳转、外链访问 |
|
||||
| `voicePlaying` | 语音播放开关控制 | WebView→App | 音效/语音开关设置 |
|
||||
|
||||
### 🔧 系统功能与交互
|
||||
| 接口名称 | 功能描述 | 调用方向 | 使用场景 |
|
||||
|----------|----------|----------|----------|
|
||||
| `gameCopytext` | 复制文本到剪贴板 | WebView→App | 文本复制分享功能 |
|
||||
| `gamepastetext` | 获取剪贴板内容 | WebView→App | 文本粘贴读取功能 |
|
||||
| `getGameinstall` | 检查游戏安装状态 | WebView→App | 本地游戏文件检测 |
|
||||
| `getphonestate` | 获取电话通话状态 | WebView→App | 通话状态检测 |
|
||||
| `SwitchOverGameData` | 启动指定游戏 | WebView→App | 游戏切换和启动 |
|
||||
| `backgameData` | 返回数据到上级页面 | WebView→App | 页面数据回传 |
|
||||
|
||||
### 🌍 位置与媒体服务
|
||||
| 接口名称 | 功能描述 | 调用方向 | 使用场景 |
|
||||
|----------|----------|----------|----------|
|
||||
| `startlocation` | 开始位置定位 | WebView→App | GPS定位服务 |
|
||||
| `getlocationinfo` | 获取当前位置信息 | WebView→App | 位置信息查询 |
|
||||
| `stopVoice` | 停止语音播放 | WebView→App | 音频控制 |
|
||||
| `playAudio` | 播放音频文件 | WebView→App | 音频播放 |
|
||||
| `mediaTypeAudio` | 音频播放控制 | WebView→App | 音频媒体播放 |
|
||||
|
||||
### 🚀 高级功能与扩展
|
||||
| 接口名称 | 功能描述 | 调用方向 | 使用场景 |
|
||||
|----------|----------|----------|----------|
|
||||
| `prepareaudio` | 录音准备 | WebView→App | 语音录制准备 |
|
||||
| `vibrator` | 单次震动 | WebView→App | 触觉反馈 |
|
||||
| `repeatvibrator` | 重复震动 | WebView→App | 持续触觉反馈 |
|
||||
| `canclevibrator` | 取消震动 | WebView→App | 停止震动反馈 |
|
||||
| `friendsSharetypeUrlToptitleDescript` | 社交分享 | WebView→App | 微信/抖音分享 |
|
||||
|
||||
## 接口依赖关系
|
||||
|
||||
### 🔗 接口调用链
|
||||
```mermaid
|
||||
graph TD
|
||||
A[WebView页面] --> B[用户认证]
|
||||
B --> C[accreditlogin 授权登录]
|
||||
B --> D[cancellogin 取消登录]
|
||||
|
||||
A --> E[页面管理]
|
||||
E --> F[OpenurlTitleData 页面跳转]
|
||||
E --> G[backgameData 数据返回]
|
||||
|
||||
A --> H[系统交互]
|
||||
H --> I[gameCopytext 复制文本]
|
||||
H --> J[gamepastetext 粘贴文本]
|
||||
H --> K[getGameinstall 游戏检测]
|
||||
H --> L[SwitchOverGameData 游戏启动]
|
||||
|
||||
A --> M[设备状态]
|
||||
M --> N[getphonestate 电话状态]
|
||||
M --> O[voicePlaying 音效开关]
|
||||
|
||||
A --> P[位置服务]
|
||||
P --> Q[startlocation 开始定位]
|
||||
Q --> R[getlocationinfo 获取位置]
|
||||
|
||||
A --> S[媒体播放]
|
||||
S --> T[mediaTypeAudio 音频播放]
|
||||
O --> T
|
||||
```
|
||||
|
||||
### ⚙️ 核心依赖
|
||||
- **定位服务**: `getlocationinfo` 需要先调用 `startlocation`
|
||||
- **音频播放**: `mediaTypeAudio` 受 `voicePlaying` 开关控制
|
||||
- **登录流程**: `cancellogin` 用于取消 `accreditlogin` 流程
|
||||
- **页面数据**: `backgameData` 配合 `OpenurlTitleData` 实现数据回传
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 📋 快速上手
|
||||
1. **选择相关文档**: 根据需要实现的功能选择对应的文档分册
|
||||
2. **查看接口概述**: 了解接口的基本功能和使用场景
|
||||
3. **参考工作流程**: 通过Mermaid流程图理解接口交互过程
|
||||
4. **使用代码示例**: 参考完整的代码示例进行开发
|
||||
5. **注意实现要点**: 查看HarmonyOS实现要点确保正确实现
|
||||
|
||||
### 🔧 开发最佳实践
|
||||
- **错误处理**: 每个接口都应包含完善的错误处理机制
|
||||
- **权限检查**: 使用涉及设备功能的接口前检查相应权限
|
||||
- **状态管理**: 合理管理接口调用状态，避免重复调用
|
||||
- **用户体验**: 在接口调用过程中提供适当的用户反馈
|
||||
|
||||
### 📱 HarmonyOS适配要点
|
||||
- **权限声明**: 在module.json5中声明所需权限
|
||||
- **SDK集成**: 集成必要的第三方SDK（如高德地图）
|
||||
- **API适配**: 使用HarmonyOS对应的系统API
|
||||
- **测试验证**: 在HarmonyOS设备上充分测试接口功能
|
||||
|
||||
## 版本信息
|
||||
|
||||
### 📈 版本历史
|
||||
| 版本 | 更新时间 | 主要变更 | 文档结构 |
|
||||
|------|----------|----------|----------|
|
||||
| v1.0-v1.7 | 2024-01 ~ 2024-11 | 逐步新增基础接口 | 单一文档 |
|
||||
| v1.8 | 2024-12 | 新增详细接口说明 | 单一文档 |
|
||||
| v1.9 | 2025-07 | 新增位置和音频接口，拆分文档 | 多文档结构 |
|
||||
|
||||
### 🔄 向后兼容性
|
||||
- ✅ 新版本保持对旧版本的完全兼容
|
||||
- ✅ 不会删除或修改现有接口参数
|
||||
- ✅ 新增参数使用可选方式，不影响现有实现
|
||||
- ✅ 文档拆分不影响接口规范内容
|
||||
|
||||
## 技术支持
|
||||
|
||||
### 📞 联系方式
|
||||
- **文档维护**: TSGame开发团队
|
||||
- **技术支持**: 技术支持组
|
||||
- **更新通知**: 关注版本更新日志
|
||||
|
||||
### 🐛 问题反馈
|
||||
如发现文档问题或接口实现疑问，请及时反馈：
|
||||
1. **接口功能问题**: 描述具体使用场景和遇到的问题
|
||||
2. **文档内容问题**: 指出具体位置和建议修改内容
|
||||
3. **HarmonyOS适配问题**: 提供设备信息和错误日志
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2025年7月13日
|
||||
**当前版本**: v1.9
|
||||
**总文档行数**: 约5300行 → 1800行×3份
|
||||
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
|
||||
**联系方式**: 技术支持组
|
||||
716
guides/JavaScript调用原生接口文档/TSGame_JSBridge_系统功能与交互.md
Normal file
716
guides/JavaScript调用原生接口文档/TSGame_JSBridge_系统功能与交互.md
Normal file
@@ -0,0 +1,716 @@
|
||||
# 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
|
||||
**联系方式**: 技术支持组
|
||||
1118
guides/JavaScript调用原生接口文档/TSGame_JSBridge_高级功能与扩展.md
Normal file
1118
guides/JavaScript调用原生接口文档/TSGame_JSBridge_高级功能与扩展.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user