daoqi/youle_app_zhuoyitong

Fork 0

Files

Joywayer c458f3c707 first commit

2026-02-16 18:24:19 +08:00

50 KiB

Raw Permalink Blame History

TSGame JSBridge 原生调用JavaScript接口规范文档

文档说明

本文档详细描述TSGame游戏中App原生调用WebView JavaScript的所有JSBridge接口规范。专注于接口工作流程、参数格式、调用时机等核心规范，便于开发者准确复制接口功能到HarmonyOS应用中。

适用平台: Android / HarmonyOS
文档类型: 接口规范文档
文档版本: v2.2
更新日期: 2025年7月13日

接口分类

接口名称	调用方向	主要功能	调用频率
`sharesuccess`	App→WebView	分享结果通知	按需调用
`sharelogin`	App→WebView	微信登录回调	按需调用
`getphoneinfo`	App→WebView	设备信息返回	按需调用
`appservice`	App→WebView	前后台状态通知	自动调用
`getaudiourl`	App→WebView	录音上传结果	按需调用
`gameui_play_voice`	App→WebView	语音播放控制	按需调用
`gameui_stop_voice`	App→WebView	语音停止控制	按需调用
`phonestate`	App→WebView	电话状态通知	自动调用
`getBattery`	App→WebView	电池电量通知	自动调用/按需调用
`getwifiLevel`	App→WebView	WiFi信号强度通知	自动调用/按需调用
`getnetwork`	App→WebView	网络连接状态通知	自动调用/按需调用
`getlocationinfo`	App→WebView	位置信息通知	按需调用/自动调用
`getWebdata`	App→WebView	页面数据传递	按需调用

1. 分享结果通知接口 (sharesuccess)

接口概述

当用户完成分享操作后，App通过此接口向WebView通知分享结果，包括成功、失败、取消等状态。

工作流程

sequenceDiagram
    participant User as 用户
    participant App as App
    participant Platform as 分享平台
    participant WebView as WebView
    
    User->>App: 触发分享
    App->>Platform: 调用分享SDK
    Platform->>User: 显示分享界面
    User->>Platform: 完成/取消分享
    Platform->>App: 返回分享结果
    App->>WebView: 调用sharesuccess
    WebView->>WebView: 更新UI状态

参数规范

标准数据格式

{
    "success": 1,
    "type": 2
}

参数说明

参数	类型	必需	说明	取值
success	number	✓	分享结果状态	1=成功, 0=失败, -1=取消
type	number	✓	分享平台类型	1=微信好友, 2=微信朋友圈, 3=QQ好友, 4=QQ空间, 5=微博

调用时机

✅ 分享操作完成后立即调用
✅ 收到分享平台SDK回调后调用
❌ 不要在分享操作开始时调用
❌ 不要重复调用

接口调用示例

成功分享调用

sharesuccess('{"success": 1, "type": 2}');

失败分享调用

sharesuccess('{"success": 0, "type": 1}');

取消分享调用

sharesuccess('{"success": -1, "type": 3}');


### HarmonyOS实现要点
- 接口名称: `sharesuccess`
- 调用方式: 通过WebView的JavaScript执行接口调用
- 数据格式: JSON字符串或JavaScript对象
- 调用时机: 分享操作完成后立即调用

---

## 2. 微信登录回调接口 (sharelogin)

### 接口概述
微信登录完成后，App通过此接口向WebView传递用户信息，包括用户头像、昵称、openid等数据。

### 工作流程
```mermaid
sequenceDiagram
    participant User as 用户
    participant App as App
    participant WeChat as 微信
    participant WebView as WebView
    
    User->>App: 点击微信登录
    App->>WeChat: 调用微信授权
    WeChat->>User: 显示授权页面
    User->>WeChat: 确认授权
    WeChat->>App: 返回授权码
    App->>WeChat: 获取用户信息
    WeChat->>App: 返回用户数据
    App->>WebView: 调用sharelogin
    WebView->>WebView: 保存用户信息

参数规范

标准数据格式

{
    "openid": "ox7w6s_abc123def456",
    "headimgurl": "https://thirdwx.qlogo.cn/mmopen/vi_32/xxx.jpg",
    "nickname": "游戏玩家",
    "sex": "1",
    "city": "深圳",
    "province": "广东",
    "unionid": "oGRTHuB4Y_abc123def456"
}

参数说明

参数	类型	必需	说明	示例值
openid	string	✓	微信用户唯一标识	"ox7w6s_abc123def456"
headimgurl	string	✓	用户头像URL	"https://thirdwx.qlogo.cn/..."
nickname	string	✓	用户昵称	"游戏玩家"
sex	string	✓	性别	"1"=男, "2"=女, "0"=未知
city	string	○	用户所在城市	"深圳"
province	string	○	用户所在省份	"广东"
unionid	string	○	UnionID标识	"oGRTHuB4Y_abc123def456"

调用时机

✅ 微信授权成功且获取用户信息后
✅ 微信登录流程完全结束后
❌ 不要在授权过程中调用
❌ 不要在获取用户信息失败时调用

接口调用示例

微信登录成功调用

sharelogin('{"openid": "ox7w6s_abc123def456", "headimgurl": "https://thirdwx.qlogo.cn/mmopen/vi_32/xxx.jpg", "nickname": "游戏玩家", "sex": "1", "city": "深圳", "province": "广东", "unionid": "oGRTHuB4Y_abc123def456"}');

最小必需信息调用

sharelogin('{"openid": "ox7w6s_abc123def456", "headimgurl": "https://thirdwx.qlogo.cn/mmopen/vi_32/xxx.jpg", "nickname": "游戏玩家", "sex": "1"}');


### HarmonyOS实现要点
- 接口名称: `sharelogin`
- 调用方式: 微信登录完成后调用此接口传递用户信息
- 数据格式: JSON格式的用户信息对象
- 必需字段: openid, headimgurl, nickname, sex

---

## 3. 设备信息返回接口 (getphoneinfo)

### 接口概述
当WebView请求设备信息后，App通过此接口返回设备的硬件和系统信息。

### 工作流程
```mermaid
sequenceDiagram
    participant WebView as WebView
    participant App as App
    participant System as 系统API
    
    WebView->>App: 调用getphoneinfo
    App->>System: 获取系统版本
    App->>System: 获取设备型号
    App->>System: 获取MAC地址
    App->>System: 获取运营商信息
    System->>App: 返回各项信息
    App->>WebView: 调用getphoneinfo返回数据

参数规范

标准数据格式

{
    "PhoneVersion": "Android 12",
    "PhoneAdresseMAC": "02:00:00:00:00:00",
    "PhoneModel": "SM-G9910",
    "PhoneDeviceBrand": "samsung",
    "PhoneProvidersName": "中国移动",
    "PhoneIMEI": "863123456789012",
    "PhoneIMSI": "460123456789012"
}

参数说明

参数	类型	必需	说明	示例值
PhoneVersion	string	✓	系统版本信息	"Android 12" / "HarmonyOS 5.0"
PhoneAdresseMAC	string	✓	设备MAC地址	"02:00:00:00:00:00"
PhoneModel	string	✓	设备型号	"SM-G9910"
PhoneDeviceBrand	string	✓	设备品牌	"samsung" / "HUAWEI"
PhoneProvidersName	string	✓	运营商名称	"中国移动"
PhoneIMEI	string	○	设备IMEI	"863123456789012"
PhoneIMSI	string	○	SIM卡IMSI	"460123456789012"

调用时机

✅ 响应WebView的getphoneinfo请求时调用
✅ 设备信息收集完成后立即调用
❌ 不要主动调用，仅响应WebView请求

接口调用示例

完整设备信息调用

getphoneinfo('{"PhoneVersion": "Android 12", "PhoneAdresseMAC": "02:00:00:00:00:00", "PhoneModel": "SM-G9910", "PhoneDeviceBrand": "samsung", "PhoneProvidersName": "中国移动", "PhoneIMEI": "863123456789012", "PhoneIMSI": "460123456789012"}');

基本设备信息调用

getphoneinfo('{"PhoneVersion": "HarmonyOS 5.0", "PhoneAdresseMAC": "02:00:00:00:00:00", "PhoneModel": "Mate 60", "PhoneDeviceBrand": "HUAWEI", "PhoneProvidersName": "中国移动"}');


### HarmonyOS实现要点
- 接口名称: `getphoneinfo`
- 调用方式: 响应WebView请求时调用此接口返回设备信息
- 数据格式: 包含设备信息的JSON对象
- 必需字段: PhoneVersion, PhoneModel, PhoneDeviceBrand, PhoneAdresseMAC, PhoneProvidersName

---

## 4. 应用状态通知接口 (appservice)

### 接口概述
App前后台状态发生变化时，通过此接口通知WebView，便于游戏暂停/恢复等处理。

### 工作流程
```mermaid
stateDiagram-v2
    [*] --> 前台状态
    前台状态 --> 后台状态: 应用切换到后台
    后台状态 --> 前台状态: 应用切换到前台
    前台状态 --> 前台状态: 屏幕解锁
    后台状态 --> 后台状态: 屏幕锁定
    
    前台状态: 发送 appservice(1)
    后台状态: 发送 appservice(2)

参数规范

标准数据格式

// 直接传递数字参数
appservice("1");  // 前台状态
appservice("2");  // 后台状态

参数说明

参数值	含义	触发场景
"1"	前台状态	App回到前台、屏幕解锁、用户交互
"2"	后台状态	App切换到后台、屏幕锁定、电话来电

调用时机

✅ Activity.onResume() - 应用恢复前台
✅ Activity.onPause() - 应用进入后台
✅ 屏幕锁定/解锁事件
✅ 电话状态变化时

接口调用示例

应用回到前台

appservice("1");

应用进入后台

appservice("2");


### HarmonyOS实现要点
- 接口名称: `appservice`
- 调用方式: 应用前后台状态变化时自动调用
- 参数格式: 字符串类型的状态值
- 状态值: "1"=前台状态, "2"=后台状态

---

## 5. 录音结果通知接口 (getaudiourl)

### 接口概述
用户完成录音后，App将录音文件上传到云端，然后通过此接口返回录音文件的URL和时长信息。

### 工作流程
```mermaid
sequenceDiagram
    participant User as 用户
    participant WebView as WebView
    participant App as App
    participant Cloud as 云存储
    
    User->>WebView: 开始录音
    WebView->>App: 调用prepareaudio
    App->>App: 开始录音
    User->>App: 结束录音
    App->>Cloud: 上传录音文件
    Cloud->>App: 返回文件URL
    App->>WebView: 调用getaudiourl
    WebView->>WebView: 显示录音消息

参数规范

成功时数据格式

{
    "audiourl": "http://gameaudio.daoqi88.cn/audio_20231201_143022.amr",
    "time": 3.5
}

重置时数据格式

{
    "audiourl": "",
    "time": 0
}

参数说明

参数	类型	必需	说明	示例值
audiourl	string	✓	录音文件URL，空字符串表示重置	"http://gameaudio.daoqi88.cn/xxx.amr"
time	number	✓	录音时长(秒)，0表示重置	3.5

调用时机

✅ 录音上传成功后立即调用
✅ 录音被取消或重置时调用(传空值)
❌ 不要在录音过程中调用
❌ 不要在上传失败时传递错误URL

接口调用示例

录音上传成功

getaudiourl('{"audiourl": "http://gameaudio.daoqi88.cn/audio_20231201_143022.amr", "time": 3.5}');

录音重置/取消

getaudiourl('{"audiourl": "", "time": 0}');


### HarmonyOS实现要点
- 接口名称: `getaudiourl`
- 调用方式: 录音上传完成后调用此接口通知结果
- 数据格式: 包含录音URL和时长的JSON对象
- 重置调用: 传递空URL和0时长表示录音重置

---

## 6. 语音播放控制接口 (gameui_play_voice / gameui_stop_voice)

### 接口概述
控制游戏中语音消息的播放和停止，包括显示播放动画和停止播放效果。

### 工作流程 - 播放语音
```mermaid
sequenceDiagram
    participant User as 用户
    participant App as App
    participant WebView as WebView
    participant Audio as 音频引擎
    
    User->>App: 点击语音消息
    App->>Audio: 开始播放音频
    App->>WebView: 调用gameui_play_voice
    WebView->>WebView: 显示播放动画
    Audio->>App: 播放完成
    App->>WebView: 调用gameui_stop_voice
    WebView->>WebView: 停止播放动画

参数规范

gameui_play_voice 参数

// 直接传递用户位置参数
gameui_play_voice("2");  // 播放用户位置2的语音

gameui_stop_voice 参数

// 直接传递用户位置参数
gameui_stop_voice("2");  // 停止用户位置2的语音

参数说明

参数	类型	必需	说明	示例值
userPosition	string	✓	用户在游戏中的位置标识	"1", "2", "3", "4"

调用时机

gameui_play_voice调用时机:

✅ 开始播放语音文件时立即调用
✅ 语音播放器准备就绪后调用
❌ 不要在播放结束时调用

gameui_stop_voice调用时机:

✅ 语音播放完成时调用
✅ 用户主动停止播放时调用
✅ 播放出错需要停止时调用

接口调用示例

开始播放语音

gameui_play_voice("2");  // 播放用户位置2的语音

停止播放语音

gameui_stop_voice("2");  // 停止用户位置2的语音

多用户语音控制

gameui_play_voice("1");   // 用户1开始播放
gameui_play_voice("3");   // 用户3开始播放
gameui_stop_voice("1");   // 用户1停止播放
gameui_stop_voice("3");   // 用户3停止播放


### HarmonyOS实现要点
- 接口名称: `gameui_play_voice` / `gameui_stop_voice`
- 调用方式: 语音播放开始时调用play接口，播放结束时调用stop接口
- 参数格式: 字符串类型的用户位置标识
- 位置标识: "1", "2", "3", "4", "5", "6" 等数字字符串

---

## 7. 电话状态通知接口 (phonestate)

### 接口概述
当设备电话状态发生变化时，App通过此接口通知WebView，便于游戏在通话时暂停。

### 工作流程
```mermaid
stateDiagram-v2
    [*] --> 空闲状态
    空闲状态 --> 来电状态: 电话来电
    来电状态 --> 通话状态: 接听电话
    来电状态 --> 空闲状态: 拒绝/未接
    通话状态 --> 空闲状态: 挂断电话
    
    空闲状态: 发送 phonestate(0)
    来电状态: 发送 phonestate(1)  
    通话状态: 发送 phonestate(2)

参数规范

标准数据格式

// 直接传递状态码
phonestate("0");  // 空闲状态
phonestate("1");  // 来电状态  
phonestate("2");  // 通话状态

参数说明

状态码	含义	说明	游戏处理建议
"0"	CALL_STATE_IDLE	空闲/挂断电话	恢复游戏
"1"	CALL_STATE_RINGING	来电响铃	暂停游戏
"2"	CALL_STATE_OFFHOOK	通话中	暂停游戏

调用时机

✅ 电话状态监听器检测到状态变化时
✅ 系统广播电话状态变化时
❌ 不要重复发送相同状态
❌ 不要在状态未确认变化时调用

接口调用示例

电话空闲状态

phonestate("0");  // 电话挂断或空闲

电话来电状态

phonestate("1");  // 电话响铃

电话通话状态

phonestate("2");  // 正在通话


### HarmonyOS实现要点
- 接口名称: `phonestate`
- 调用方式: 电话状态变化时自动调用此接口
- 参数格式: 字符串类型的状态码
- 状态码: "0"=空闲, "1"=来电响铃, "2"=通话中

---

## 8. 电池电量通知接口 (getBattery)

### 接口概述
当设备电池电量发生变化时，App自动通过此接口通知WebView当前电量百分比。同时WebView也可以主动请求获取当前电量信息。

### 工作流程

#### 自动电量通知流程
```mermaid
sequenceDiagram
    participant System as 系统
    participant App as App
    participant WebView as WebView
    
    System->>App: 电量变化广播
    App->>App: 计算电量百分比
    App->>WebView: 调用getBattery
    WebView->>WebView: 更新电量显示

主动电量查询流程

sequenceDiagram
    participant WebView as WebView
    participant App as App
    participant System as 系统
    
    WebView->>App: 调用getbattery请求
    App->>System: 获取电池状态
    System->>App: 返回电量信息
    App->>App: 计算电量百分比
    App->>WebView: 调用getBattery返回结果

参数规范

标准数据格式

// 直接传递电量百分比字符串
getBattery("0.85");  // 85%电量
getBattery("0.42");  // 42%电量
getBattery("1.0");   // 100%电量

参数说明

参数	类型	必需	说明	示例值
batteryLevel	string	✓	电池电量百分比(小数形式)	"0.85" (表示85%), "0.42" (表示42%)

调用时机

自动调用时机:

✅ 设备电量发生变化时自动调用
✅ 电池状态广播接收时调用
✅ 充电状态变化时调用

主动调用时机:

✅ 响应WebView的getbattery请求时调用
✅ 应用启动时获取初始电量
❌ 不要频繁主动调用，避免性能影响

双向接口说明

1. WebView请求电量 (getbattery)

WebView向App请求获取当前电量：

// WebView端发起请求
window.jsBridge.callHandler('getbattery', null, function(response) {
    // 处理返回的电量信息
});

2. App返回电量 (getBattery)

App通过此接口向WebView返回电量信息：

// App调用WebView的getBattery接口
getBattery("0.75");  // 返回75%电量

接口调用示例

高电量通知

getBattery("0.90");  // 90%电量

中等电量通知

getBattery("0.45");  // 45%电量

低电量警告

getBattery("0.15");  // 15%电量，需要提醒充电

满电状态

getBattery("1.0");   // 100%满电

电量计算逻辑

电量百分比计算

batteryPct = level / scale

其中：

level: 当前电量值
scale: 电量最大值
batteryPct: 电量百分比(0.0-1.0)

示例计算

当前电量 level = 85
最大电量 scale = 100
电量百分比 = 85/100 = 0.85
调用: getBattery("0.85")

HarmonyOS实现要点

接口名称: getBattery (App→WebView), getbattery (WebView→App请求)
调用方式: 电量变化时自动调用，或响应WebView主动请求
参数格式: 字符串类型的电量百分比(小数形式)
监听机制: 注册电量变化广播接收器，实时监听电量状态
计算方式: level/scale得到0.0-1.0之间的小数值

9. WiFi信号强度通知接口 (getwifiLevel)

接口概述

当设备WiFi信号强度发生变化时，App自动通过此接口通知WebView当前WiFi信号强度和网络名称。同时WebView也可以主动请求获取当前WiFi信息。

工作流程

自动信号强度通知流程

sequenceDiagram
    participant System as 系统
    participant App as App
    participant WebView as WebView
    
    System->>App: WiFi信号变化广播
    App->>App: 获取WiFi信息
    App->>App: 计算信号强度等级
    App->>WebView: 调用getwifiLevel
    WebView->>WebView: 更新信号显示

主动WiFi信息查询流程

sequenceDiagram
    participant WebView as WebView
    participant App as App
    participant System as 系统
    
    WebView->>App: 调用getwifiLevel请求
    App->>System: 获取WiFi连接状态
    App->>System: 获取信号强度RSSI
    System->>App: 返回WiFi信息
    App->>App: 计算信号强度等级
    App->>WebView: 调用getwifiLevel返回结果

参数规范

标准数据格式

{
    "ssidname": "MyHome_WiFi_5G",
    "signalLevel": 4
}

参数说明

参数	类型	必需	说明	示例值
ssidname	string	✓	WiFi网络名称(SSID)	"MyHome_WiFi_5G", "OfficeNetwork"
signalLevel	number	✓	信号强度等级(0-4)	0=最弱, 1=弱, 2=一般, 3=强, 4=最强

调用时机

自动调用时机:

✅ WiFi信号强度变化时自动调用(RSSI_CHANGED_ACTION广播)
✅ WiFi连接状态变化时调用
✅ 切换WiFi网络时调用

主动调用时机:

✅ 响应WebView的getwifiLevel请求时调用
✅ 应用启动时获取初始WiFi信息
❌ 不要频繁主动调用，避免性能影响

双向接口说明

1. WebView请求WiFi信息 (getwifiLevel请求)

WebView向App请求获取当前WiFi信息：

// WebView端发起请求
window.jsBridge.callHandler('getwifiLevel', null, function(response) {
    // 处理返回的WiFi信息
});

2. App返回WiFi信息 (getwifiLevel响应)

App通过此接口向WebView返回WiFi信息：

// App调用WebView的getwifiLevel接口
getwifiLevel('{"ssidname": "MyHome_WiFi_5G", "signalLevel": 4}');

接口调用示例

强信号WiFi

getwifiLevel('{"ssidname": "MyHome_WiFi_5G", "signalLevel": 4}');

中等信号WiFi

getwifiLevel('{"ssidname": "Office_Network", "signalLevel": 2}');

弱信号WiFi

getwifiLevel('{"ssidname": "Public_WiFi", "signalLevel": 1}');

无WiFi连接

getwifiLevel('{"ssidname": "", "signalLevel": 0}');

信号强度计算逻辑

信号强度等级计算

signalLevel = WifiManager.calculateSignalLevel(rssi, 5)

其中：

rssi: WiFi信号强度原始值(负数，如-50dBm)
5: 信号等级分档数量(0-4共5个等级)
signalLevel: 信号强度等级(0-4)

信号强度等级说明

等级	信号质量	RSSI范围(大概)	说明
0	无信号/很弱	< -80dBm	无法正常使用
1	弱	-80dBm ~ -70dBm	连接不稳定
2	一般	-70dBm ~ -60dBm	基本可用
3	良好	-60dBm ~ -50dBm	连接稳定
4	优秀	> -50dBm	信号很强

WiFi信息获取流程

获取WiFi基本信息

WifiManager wifiManager = getSystemService(WIFI_SERVICE);
WifiInfo wifiInfo = wifiManager.getConnectionInfo();

// WiFi名称
String ssid = wifiInfo.getSSID();

// 信号强度RSSI值
int rssi = wifiInfo.getRssi();

// 计算信号强度等级(0-4)
int signalLevel = WifiManager.calculateSignalLevel(rssi, 5);

广播监听注册

// 注册WiFi信号变化监听
IntentFilter filter = new IntentFilter(WifiManager.RSSI_CHANGED_ACTION);
registerReceiver(wifiChangeReceiver, filter);

HarmonyOS实现要点

接口名称: getwifiLevel (双向接口，同时用于请求和响应)
调用方式: WiFi信号变化时自动调用，或响应WebView主动请求
数据格式: JSON格式包含网络名称和信号强度等级
监听机制: 注册WiFi信号变化广播接收器(RSSI_CHANGED_ACTION)
信号计算: 使用系统API将RSSI值转换为0-4等级
权限要求: 需要ACCESS_WIFI_STATE和ACCESS_FINE_LOCATION权限

10. 网络连接状态通知接口 (getnetwork)

接口概述

当设备网络连接状态发生变化时，App自动通过此接口通知WebView当前网络连接类型。同时WebView也可以主动请求获取当前网络连接状态。

工作流程

自动网络状态通知流程

sequenceDiagram
    participant System as 系统
    participant App as App
    participant WebView as WebView
    
    System->>App: 网络状态变化广播
    App->>App: 检测网络连接状态
    App->>App: 判断网络类型
    App->>WebView: 调用getnetwork
    WebView->>WebView: 更新网络状态显示

主动网络状态查询流程

sequenceDiagram
    participant WebView as WebView
    participant App as App
    participant System as 系统
    
    WebView->>App: 调用getnetwork请求
    App->>System: 获取网络连接信息
    App->>System: 检查WiFi连接状态
    App->>System: 检查移动网络状态
    System->>App: 返回网络信息
    App->>App: 判断网络类型
    App->>WebView: 调用getnetwork返回结果

参数规范

标准数据格式

// 直接传递网络类型代码字符串
getnetwork("1");  // 网络断开
getnetwork("2");  // WiFi连接
getnetwork("3");  // 移动网络连接

参数说明

参数	类型	必需	说明	示例值
networkType	string	✓	网络连接类型代码	"1"=断开, "2"=WiFi, "3"=移动网络

网络类型说明

类型码	网络状态	说明	应用建议
"1"	网络断开	无任何网络连接	显示离线模式，禁用网络功能
"2"	WiFi连接	连接到WiFi网络	启用高质量内容，无流量限制
"3"	移动网络	连接到蜂窝移动网络	节省流量模式，压缩内容

调用时机

自动调用时机:

✅ 网络连接状态变化时自动调用(CONNECTIVITY_ACTION广播)
✅ WiFi开关状态变化时调用
✅ 移动数据开关状态变化时调用
✅ 网络类型切换时调用

主动调用时机:

✅ 响应WebView的getnetwork请求时调用
✅ 应用启动时获取初始网络状态
❌ 不要频繁主动调用，避免性能影响

双向接口说明

1. WebView请求网络状态 (getnetwork请求)

WebView向App请求获取当前网络状态：

// WebView端发起请求
window.jsBridge.callHandler('getnetwork', '', function(response) {
    // 处理返回的网络状态
    console.log('当前网络状态:', response);
});

2. App返回网络状态 (getnetwork响应)

App通过此接口向WebView返回网络状态：

// App调用WebView的getnetwork接口
getnetwork("2");  // 返回WiFi连接状态

接口调用示例

WiFi网络连接

getnetwork("2");  // WiFi连接状态

移动网络连接

getnetwork("3");  // 移动网络连接状态

网络断开

getnetwork("1");  // 网络断开状态

网络状态检测逻辑

网络连接状态判断流程

// 1. 检查网络是否连接
boolean isConnected = isNetworkConnected(context);

if (!isConnected) {
    return "1";  // 网络断开
}

// 2. 检查是否为WiFi连接
boolean isWiFi = isNetworkAvailable(context);

if (isWiFi) {
    return "2";  // WiFi连接
} else {
    return "3";  // 移动网络连接
}

网络类型检测方法

// 检查网络是否连接
public static boolean isNetworkConnected(Context context) {
    ConnectivityManager cm = (ConnectivityManager) context
            .getSystemService(Context.CONNECTIVITY_SERVICE);
    NetworkInfo info = cm.getActiveNetworkInfo();
    return info != null && info.isConnected();
}

// 检查是否为WiFi连接
public static boolean isNetworkAvailable(Context context) {
    ConnectivityManager manager = (ConnectivityManager) context
            .getSystemService(Context.CONNECTIVITY_SERVICE);
    NetworkInfo networkInfo = manager.getActiveNetworkInfo();
    return networkInfo != null && 
           networkInfo.getType() == ConnectivityManager.TYPE_WIFI;
}

网络状态广播监听

广播接收器实现

private class MyNetReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        String action = intent.getAction();
        if (action.equals(ConnectivityManager.CONNECTIVITY_ACTION)) {
            
            ConnectivityManager cm = (ConnectivityManager) 
                getSystemService(Context.CONNECTIVITY_SERVICE);
            NetworkInfo netInfo = cm.getActiveNetworkInfo();
            
            int type = 1; // 默认断开状态
            
            if (netInfo != null && netInfo.isAvailable()) {
                if (netInfo.getType() == ConnectivityManager.TYPE_WIFI) {
                    type = 2; // WiFi网络
                } else if (netInfo.getType() == ConnectivityManager.TYPE_MOBILE) {
                    type = 3; // 移动网络
                }
            }
            
            // 通知WebView网络状态变化
            webview.callHandler("getnetwork", String.valueOf(type), null);
        }
    }
}

广播监听注册

// 注册网络状态变化监听
MyNetReceiver myNetReceiver = new MyNetReceiver();
IntentFilter filter = new IntentFilter(ConnectivityManager.CONNECTIVITY_ACTION);
registerReceiver(myNetReceiver, filter);

应用场景和处理建议

不同网络状态的处理策略

网络状态	处理策略	具体建议
网络断开(1)	离线模式	显示网络错误提示，缓存用户操作，禁用网络请求
WiFi连接(2)	高质量模式	启用高清图片/视频，自动更新，无流量限制
移动网络(3)	节省模式	压缩图片，询问大文件下载，显示流量提醒

WebView端处理示例

function handleNetworkChange(networkType) {
    switch(networkType) {
        case "1":
            // 网络断开
            showOfflineMessage();
            disableNetworkFeatures();
            break;
        case "2":
            // WiFi连接
            enableHighQualityMode();
            hideDataWarning();
            break;
        case "3":
            // 移动网络
            enableDataSavingMode();
            showDataUsageWarning();
            break;
    }
}

HarmonyOS实现要点

接口名称: getnetwork (双向接口，同时用于请求和响应)
调用方式: 网络状态变化时自动调用，或响应WebView主动请求
参数格式: 字符串类型的网络类型代码
监听机制: 注册网络连接状态变化广播接收器(CONNECTIVITY_ACTION)
状态判断: 通过ConnectivityManager检测网络连接状态和类型
权限要求: 需要ACCESS_NETWORK_STATE权限

11. 位置信息通知接口 (getlocationinfo)

接口概述

当设备位置信息发生变化或WebView主动请求位置信息时，App通过此接口向WebView提供详细的地理位置信息，包括经纬度、地址描述、行政区划等数据。

工作流程

自动位置信息通知流程

sequenceDiagram
    participant System as 定位系统
    participant App as App
    participant WebView as WebView
    
    System->>App: 位置变化回调
    App->>App: 解析位置数据
    App->>App: 构造MaplocationInfo对象
    App->>WebView: 调用getlocationinfo
    WebView->>WebView: 更新位置显示

主动位置信息查询流程

sequenceDiagram
    participant WebView as WebView
    participant App as App
    participant LocationService as 定位服务
    
    WebView->>App: 调用getlocationinfo请求
    App->>LocationService: 启动定位服务
    LocationService->>LocationService: GPS/网络定位
    LocationService->>App: 返回位置信息
    App->>App: 构造位置数据
    App->>WebView: 调用getlocationinfo返回结果

参数规范

标准数据格式

{
    "latitude": 22.543096,
    "longitude": 114.057865,
    "address": "广东省深圳市南山区科技园南区深南大道9988号",
    "country": "中国",
    "province": "广东省",
    "city": "深圳市",
    "district": "南山区",
    "street": "深南大道",
    "cityCode": "0755"
}

参数说明

参数	类型	必需	说明	示例值
latitude	number	✓	纬度坐标	22.543096
longitude	number	✓	经度坐标	114.057865
address	string	✓	详细地址描述	"广东省深圳市南山区科技园南区深南大道9988号"
country	string	✓	国家名称	"中国"
province	string	✓	省份名称	"广东省"
city	string	✓	城市名称	"深圳市"
district	string	✓	城区名称	"南山区"
street	string	✓	街道名称	"深南大道"
cityCode	string	○	城市区号	"0755"

调用时机

自动调用时机:

✅ 设备位置发生变化时自动调用(AMapLocationListener回调)
✅ 定位服务获取到新的位置信息时调用
✅ 应用启动时完成首次定位后调用

主动调用时机:

✅ 响应WebView的getlocationinfo请求时调用
✅ 用户手动刷新位置信息时调用
❌ 不要在定位权限未授权时调用
❌ 不要在定位服务未启动时调用

双向接口说明

1. WebView请求位置信息 (getlocationinfo请求)

WebView向App请求获取当前位置信息：

// WebView端发起请求
window.jsBridge.callHandler('getlocationinfo', '', function(response) {
    // 处理返回的位置信息
    const locationData = JSON.parse(response);
    console.log('当前位置:', locationData);
});

2. App返回位置信息 (getlocationinfo响应)

App通过此接口向WebView返回位置信息：

// App调用WebView的getlocationinfo接口
getlocationinfo('{"latitude": 22.543096, "longitude": 114.057865, "address": "广东省深圳市南山区科技园南区深南大道9988号", "country": "中国", "province": "广东省", "city": "深圳市", "district": "南山区", "street": "深南大道", "cityCode": "0755"}');

接口调用示例

深圳地区位置信息

getlocationinfo('{"latitude": 22.543096, "longitude": 114.057865, "address": "广东省深圳市南山区科技园南区深南大道9988号", "country": "中国", "province": "广东省", "city": "深圳市", "district": "南山区", "street": "深南大道", "cityCode": "0755"}');

北京地区位置信息

getlocationinfo('{"latitude": 39.908692, "longitude": 116.397477, "address": "北京市东城区东长安街1号", "country": "中国", "province": "北京市", "city": "北京市", "district": "东城区", "street": "东长安街", "cityCode": "010"}');

上海地区位置信息

getlocationinfo('{"latitude": 31.230416, "longitude": 121.473701, "address": "上海市黄浦区南京东路20号", "country": "中国", "province": "上海市", "city": "上海市", "district": "黄浦区", "street": "南京东路", "cityCode": "021"}');

位置信息不可用时

getlocationinfo('null');  // 定位失败或位置信息不可用

位置信息获取流程

定位服务初始化

// 1. 初始化定位客户端
AMapLocationClient mLocationClient = new AMapLocationClient(context);

// 2. 配置定位参数
AMapLocationClientOption mLocationOption = new AMapLocationClientOption();
mLocationOption.setLocationMode(AMapLocationMode.Hight_Accuracy); // 高精度模式
mLocationOption.setOnceLocation(true);  // 单次定位
mLocationOption.setOnceLocationLatest(true);  // 返回最高精度结果
mLocationOption.setNeedAddress(true);  // 返回地址信息

// 3. 设置定位监听器
mLocationClient.setLocationOption(mLocationOption);
mLocationClient.setLocationListener(locationListener);
mLocationClient.startLocation();

位置信息解析

// 位置变化回调处理
public void onLocationChanged(AMapLocation amapLocation) {
    MaplocationInfo location = new MaplocationInfo();
    
    // 设置坐标信息
    location.setLatitude(amapLocation.getLatitude());   // 纬度
    location.setLongitude(amapLocation.getLongitude()); // 经度
    
    // 设置地址信息
    location.setAddress(amapLocation.getAddress());     // 详细地址
    location.setCountry(amapLocation.getCountry());     // 国家
    location.setProvince(amapLocation.getProvince());   // 省份
    location.setCity(amapLocation.getCity());           // 城市
    location.setDistrict(amapLocation.getDistrict());   // 城区
    location.setStreet(amapLocation.getStreet());       // 街道
    location.setCityCode(amapLocation.getCityCode());   // 城市编码
    
    // 转换为JSON并通知WebView
    Gson gson = new Gson();
    String json = gson.toJson(location);
    webview.callHandler("getlocationinfo", json, null);
}

定位模式和精度说明

定位模式类型

模式	精度	功耗	说明	适用场景
Hight_Accuracy	高	高	GPS+网络+基站定位	导航、精确位置需求
Battery_Saving	中	低	网络+基站定位	一般位置需求
Device_Sensors	最高	最高	仅GPS定位	户外精确定位

定位精度指标

指标	说明	典型值
精度半径	定位结果的误差范围	10-50米
定位时间	首次定位完成时间	2-10秒
更新频率	位置更新的时间间隔	1-5秒

权限和隐私处理

必需权限

<!-- 精确位置权限 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- 粗略位置权限 -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- 网络访问权限 -->
<uses-permission android:name="android.permission.INTERNET" />

权限检查流程

// 检查位置权限
private boolean checkLocationPermission() {
    return ActivityCompat.checkSelfPermission(this, 
        Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED;
}

// 请求位置权限
private void requestLocationPermission() {
    ActivityCompat.requestPermissions(this, 
        new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, 
        LOCATION_PERMISSION_REQUEST_CODE);
}

错误处理和异常情况

常见错误类型

错误类型	错误码	说明	处理建议
权限被拒绝	12	用户拒绝位置权限	引导用户开启权限
定位失败	1	GPS/网络定位失败	重试定位或使用缓存位置
服务不可用	2	定位服务暂时不可用	稍后重试
网络异常	4	网络连接异常	检查网络连接

异常处理示例

public void onLocationChanged(AMapLocation amapLocation) {
    if (amapLocation != null) {
        if (amapLocation.getErrorCode() == 0) {
            // 定位成功，处理位置信息
            processLocationData(amapLocation);
        } else {
            // 定位失败，处理错误
            handleLocationError(amapLocation.getErrorCode(), 
                               amapLocation.getErrorInfo());
        }
    }
}

HarmonyOS实现要点

接口名称: getlocationinfo (双向接口，同时用于请求和响应)
调用方式: 位置变化时自动调用，或响应WebView主动请求
数据格式: JSON格式包含完整的位置信息对象
定位服务: 集成高德地图定位SDK或系统定位服务
权限管理: 需要精确位置权限(ACCESS_FINE_LOCATION)
隐私保护: 遵循位置信息使用规范，明确告知用户位置用途
性能优化: 合理设置定位频率，避免过度消耗电量
错误处理: 完善的权限检查和定位失败处理机制

12. 页面数据传递接口 (getWebdata)

接口概述

当App需要向WebView传递数据时，通过此接口将数据传递给WebView，主要用于页面加载完成后的数据初始化、页面间的数据通信以及Activity返回结果的数据传递。

工作流程

页面加载完成后数据传递流程

sequenceDiagram
    participant Activity as Activity
    participant WebView as WebView
    participant JavaScript as JavaScript
    
    Activity->>Activity: 获取Intent传递的data
    Activity->>WebView: 页面开始加载
    WebView->>WebView: 页面加载进度监控
    WebView->>Activity: onProgressChanged(100%)
    Activity->>JavaScript: 调用getWebdata(data)
    JavaScript->>JavaScript: 处理传入的数据

Activity结果返回数据传递流程

sequenceDiagram
    participant SubActivity as 子Activity
    participant MainActivity as 主Activity
    participant WebView as WebView
    participant JavaScript as JavaScript
    
    SubActivity->>MainActivity: 返回结果(resultCode=101)
    MainActivity->>MainActivity: 从Intent获取data
    MainActivity->>JavaScript: 调用getWebdata(data)
    JavaScript->>JavaScript: 处理返回的数据

参数规范

标准数据格式

// 直接传递字符串数据
getWebdata("userdata_12345");

// 传递JSON格式数据
getWebdata('{"userId":"12345","userName":"张三","gameLevel":10}');

// 传递游戏状态数据
getWebdata('{"gameId":"niuniu","score":1500,"level":"expert"}');

参数说明

参数	类型	必需	说明	示例值
data	string	✓	需要传递给WebView的数据	任意字符串或JSON格式数据

数据内容类型

数据类型	用途	格式	示例
用户信息	传递用户基本信息	JSON字符串	`{"userId":"12345","userName":"张三"}`
游戏数据	传递游戏状态和设置	JSON字符串	`{"gameId":"niuniu","score":1500}`
配置参数	传递应用配置信息	JSON字符串	`{"theme":"dark","language":"zh-CN"}`
简单标识	传递简单的标识符	普通字符串	`"user_login_success"`

调用时机

页面加载时调用:

✅ WebView页面加载完成后(onProgressChanged=100%)
✅ 页面首次初始化需要数据时
✅ 页面刷新重新加载后

Activity返回时调用:

✅ 子Activity返回结果时(onActivityResult)
✅ 其他页面返回数据时(resultCode=101)
✅ 页面间数据传递时

数据更新时调用:

✅ App状态发生变化需要通知WebView时
✅ 用户信息更新后需要同步时
❌ 不要在页面加载过程中调用
❌ 不要在WebView未准备好时调用

接口调用示例

用户登录信息传递

getWebdata('{"action":"user_login","userId":"12345","userName":"张三","avatar":"https://example.com/avatar.jpg","loginTime":"2025-01-13 14:30:00"}');

游戏数据传递

getWebdata('{"action":"game_data","gameId":"niuniu","currentScore":1500,"highScore":3200,"level":"expert","coins":5000}');

简单状态传递

getWebdata("page_refresh_complete");

配置信息传递

getWebdata('{"action":"app_config","theme":"dark","language":"zh-CN","soundEnabled":true,"notificationEnabled":false}');

错误信息传递

getWebdata('{"action":"error","errorCode":"E001","errorMessage":"网络连接失败","timestamp":"2025-01-13 14:30:00"}');

数据传递场景

1. 页面初始化数据传递

使用场景: WebView页面加载完成后需要获取初始数据

// Activity中页面加载完成后调用
@Override
public void onProgressChanged(WebView view, int newProgress) {
    if (newProgress == 100 && !isLoadingFinished) {
        isLoadingFinished = true;
        
        // 传递初始化数据
        String initData = '{"userId":"12345","gameMode":"multiplayer"}';
        x5webview.callHandler("getWebdata", initData, null);
    }
}

2. Activity返回结果数据传递

使用场景: 子Activity返回结果数据给WebView

// Activity结果处理
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (resultCode == 101) {
        Bundle bundle = data.getExtras();
        String resultData = bundle.getString("data");
        
        // 传递返回结果数据
        x5webview.callHandler("getWebdata", resultData, new CallBackFunction() {
            @Override
            public void onCallBack(String response) {
                // 处理WebView的响应
            }
        });
    }
}

3. 应用状态变化数据传递

使用场景: App状态发生变化需要通知WebView

// 应用状态变化时调用
private void notifyAppStateChange(String newState) {
    String stateData = '{"action":"app_state_change","state":"' + newState + '"}';
    x5webview.callHandler("getWebdata", stateData, null);
}

数据处理建议

WebView端数据处理

// WebView端接收数据的处理函数
function getWebdata(data) {
    try {
        // 尝试解析JSON数据
        const parsedData = JSON.parse(data);
        
        // 根据action类型处理不同的数据
        switch(parsedData.action) {
            case 'user_login':
                handleUserLogin(parsedData);
                break;
            case 'game_data':
                handleGameData(parsedData);
                break;
            case 'app_config':
                handleAppConfig(parsedData);
                break;
            default:
                handleGenericData(parsedData);
        }
    } catch (e) {
        // 非JSON数据，按字符串处理
        handleStringData(data);
    }
}

// 处理用户登录数据
function handleUserLogin(userData) {
    document.getElementById('username').textContent = userData.userName;
    document.getElementById('userId').textContent = userData.userId;
    // 更新UI显示用户信息
}

// 处理游戏数据
function handleGameData(gameData) {
    updateGameScore(gameData.currentScore);
    updateHighScore(gameData.highScore);
    updateUserLevel(gameData.level);
}

数据验证机制

// 数据有效性验证
function validateData(data) {
    // 检查数据是否为空
    if (!data || data.trim() === '') {
        console.warn('Received empty data');
        return false;
    }
    
    // 检查JSON格式数据的必需字段
    try {
        const parsedData = JSON.parse(data);
        if (parsedData.action && !isValidAction(parsedData.action)) {
            console.warn('Invalid action type:', parsedData.action);
            return false;
        }
    } catch (e) {
        // 非JSON数据，按字符串处理
    }
    
    return true;
}

错误处理和异常情况

常见错误类型

错误类型	说明	处理建议
空数据	传递的data为null或空字符串	检查数据有效性，提供默认值
JSON解析错误	数据格式不是有效的JSON	按字符串处理或提供错误提示
时机错误	在WebView未准备好时调用	确保页面加载完成后调用
数据过大	传递的数据量过大	分批传递或压缩数据

异常处理示例

// App端异常处理
private void safeCallGetWebdata(String data) {
    try {
        if (x5webview != null && data != null) {
            // 检查数据大小，避免传递过大数据
            if (data.length() > MAX_DATA_SIZE) {
                Log.w("GetWebdata", "Data size too large: " + data.length());
                // 分批传递或压缩数据
                return;
            }
            
            x5webview.callHandler("getWebdata", data, new CallBackFunction() {
                @Override
                public void onCallBack(String response) {
                    // 处理成功响应
                    Log.d("GetWebdata", "Data sent successfully");
                }
            });
        } else {
            Log.w("GetWebdata", "WebView not ready or data is null");
        }
    } catch (Exception e) {
        Log.e("GetWebdata", "Error calling getWebdata", e);
    }
}

性能优化建议

数据传递优化

数据压缩: 对于大型JSON数据，考虑使用压缩算法
批量传递: 将多个小数据合并为一次传递
异步处理: 使用异步方式处理数据，避免阻塞UI线程
缓存机制: 对频繁使用的数据进行缓存

调用频率控制

避免重复调用: 检查数据是否发生变化再决定是否调用
节流机制: 对于频繁的状态变化，使用节流避免过度调用
优先级管理: 重要数据优先传递，非关键数据可延后

HarmonyOS实现要点

接口名称: getWebdata
调用方式: App向WebView传递数据时主动调用
参数格式: 字符串类型，支持普通字符串和JSON格式
调用时机: 页面加载完成后、Activity返回结果时、应用状态变化时
数据处理: WebView端需要实现getWebdata函数来接收和处理数据
错误处理: 需要处理空数据、JSON解析错误、调用时机错误等异常情况
性能考虑: 控制数据大小、调用频率，使用异步处理避免阻塞

接口实现规范

1. 通用调用规范

接口调用方式: 通过WebView的JavaScript执行接口
数据传递格式: JSON字符串或JavaScript基本类型
字符编码: UTF-8编码
调用时机: 严格按照各接口定义的调用时机执行

2. 数据格式要求

JSON格式: 复杂数据使用标准JSON格式
字符串转义: 正确处理特殊字符和换行符
类型一致性: 确保参数类型与接口定义完全匹配
字段完整性: 必需字段不可缺失，可选字段可省略

3. 双向接口处理

请求响应模式: 如getBattery、getwifiLevel、getnetwork接口支持WebView主动请求和App主动推送
接口命名规范: 双向接口使用相同命名，通过调用上下文区分请求和响应
状态同步: 确保双向接口的状态信息保持一致
频率控制: 避免高频率的双向调用造成性能问题

4. 系统监听机制

广播接收器: 电量、WiFi信号、电话状态、网络连接等需要注册相应的系统广播监听器
生命周期管理: 正确注册和注销广播接收器，避免内存泄漏
权限处理: 确保获取系统信息所需的权限已正确申请
异常处理: 处理系统API调用可能出现的异常情况

5. 接口兼容性要求

接口名称: 与Android版本保持完全一致
参数结构: 参数名称、类型、取值范围保持一致
调用频率: 遵循相同的调用时机和频率限制
错误处理: 异常情况下的处理方式保持一致

6. 实现验证要点

功能验证: 确保接口调用产生预期的WebView响应
数据验证: 验证传递的数据格式和内容正确性
时序验证: 验证接口调用的时机和顺序正确
兼容验证: 确保与现有WebView代码完全兼容

版本兼容性说明

接口版本历史

版本	更新内容	影响范围
v1.0	初始版本，基础接口定义	全部接口
v1.1	增加错误处理参数	sharelogin接口
v2.0	标准化参数格式和文档	全部接口
v2.1	新增getlocationinfo位置信息接口	位置定位功能
v2.2	新增getWebdata页面数据传递接口	数据通信功能

向后兼容性

新版本保持对旧版本的完全兼容
不会删除或修改现有接口参数
新增参数使用可选方式，不影响现有实现

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

50 KiB Raw Permalink Blame History Unescape Escape

TSGame JSBridge 原生调用JavaScript接口规范文档

文档说明

接口分类

1. 分享结果通知接口 (sharesuccess)

接口概述

工作流程

参数规范

标准数据格式

参数说明

调用时机

接口调用示例

成功分享调用

失败分享调用

取消分享调用

参数规范

标准数据格式

参数说明

调用时机

接口调用示例

微信登录成功调用

最小必需信息调用

参数规范

标准数据格式

参数说明

调用时机

接口调用示例

完整设备信息调用

基本设备信息调用

参数规范

标准数据格式

参数说明

调用时机

接口调用示例

应用回到前台

应用进入后台

参数规范

成功时数据格式

重置时数据格式

参数说明

调用时机

接口调用示例

录音上传成功

录音重置/取消

参数规范

gameui_play_voice 参数

gameui_stop_voice 参数

参数说明

调用时机

接口调用示例

开始播放语音

停止播放语音

多用户语音控制

参数规范

标准数据格式

参数说明

调用时机

接口调用示例

电话空闲状态

电话来电状态

电话通话状态

主动电量查询流程

参数规范

标准数据格式

参数说明

调用时机

双向接口说明

1. WebView请求电量 (getbattery)

2. App返回电量 (getBattery)

接口调用示例

高电量通知

中等电量通知

低电量警告

满电状态

电量计算逻辑

电量百分比计算

示例计算

HarmonyOS实现要点

9. WiFi信号强度通知接口 (getwifiLevel)

接口概述

50 KiB

Raw Permalink Blame History