1650 lines
50 KiB
Markdown
1650 lines
50 KiB
Markdown
# 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通知分享结果，包括成功、失败、取消等状态。
|
||
|
||
### 工作流程
|
||
```mermaid
|
||
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状态
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 标准数据格式
|
||
```json
|
||
{
|
||
"success": 1,
|
||
"type": 2
|
||
}
|
||
```
|
||
|
||
#### 参数说明
|
||
| 参数 | 类型 | 必需 | 说明 | 取值 |
|
||
|------|------|------|------|------|
|
||
| success | number | ✓ | 分享结果状态 | 1=成功, 0=失败, -1=取消 |
|
||
| type | number | ✓ | 分享平台类型 | 1=微信好友, 2=微信朋友圈, 3=QQ好友, 4=QQ空间, 5=微博 |
|
||
|
||
#### 调用时机
|
||
- ✅ 分享操作完成后立即调用
|
||
- ✅ 收到分享平台SDK回调后调用
|
||
- ❌ 不要在分享操作开始时调用
|
||
- ❌ 不要重复调用
|
||
|
||
### 接口调用示例
|
||
|
||
#### 成功分享调用
|
||
```javascript
|
||
sharesuccess('{"success": 1, "type": 2}');
|
||
```
|
||
|
||
#### 失败分享调用
|
||
```javascript
|
||
sharesuccess('{"success": 0, "type": 1}');
|
||
```
|
||
|
||
#### 取消分享调用
|
||
```javascript
|
||
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: 保存用户信息
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 标准数据格式
|
||
```json
|
||
{
|
||
"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" |
|
||
|
||
#### 调用时机
|
||
- ✅ 微信授权成功且获取用户信息后
|
||
- ✅ 微信登录流程完全结束后
|
||
- ❌ 不要在授权过程中调用
|
||
- ❌ 不要在获取用户信息失败时调用
|
||
|
||
### 接口调用示例
|
||
|
||
#### 微信登录成功调用
|
||
```javascript
|
||
sharelogin('{"openid": "ox7w6s_abc123def456", "headimgurl": "https://thirdwx.qlogo.cn/mmopen/vi_32/xxx.jpg", "nickname": "游戏玩家", "sex": "1", "city": "深圳", "province": "广东", "unionid": "oGRTHuB4Y_abc123def456"}');
|
||
```
|
||
|
||
#### 最小必需信息调用
|
||
```javascript
|
||
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返回数据
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 标准数据格式
|
||
```json
|
||
{
|
||
"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请求
|
||
|
||
### 接口调用示例
|
||
|
||
#### 完整设备信息调用
|
||
```javascript
|
||
getphoneinfo('{"PhoneVersion": "Android 12", "PhoneAdresseMAC": "02:00:00:00:00:00", "PhoneModel": "SM-G9910", "PhoneDeviceBrand": "samsung", "PhoneProvidersName": "中国移动", "PhoneIMEI": "863123456789012", "PhoneIMSI": "460123456789012"}');
|
||
```
|
||
|
||
#### 基本设备信息调用
|
||
```javascript
|
||
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)
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 标准数据格式
|
||
```javascript
|
||
// 直接传递数字参数
|
||
appservice("1"); // 前台状态
|
||
appservice("2"); // 后台状态
|
||
```
|
||
|
||
#### 参数说明
|
||
| 参数值 | 含义 | 触发场景 |
|
||
|--------|------|----------|
|
||
| "1" | 前台状态 | App回到前台、屏幕解锁、用户交互 |
|
||
| "2" | 后台状态 | App切换到后台、屏幕锁定、电话来电 |
|
||
|
||
#### 调用时机
|
||
- ✅ Activity.onResume() - 应用恢复前台
|
||
- ✅ Activity.onPause() - 应用进入后台
|
||
- ✅ 屏幕锁定/解锁事件
|
||
- ✅ 电话状态变化时
|
||
|
||
### 接口调用示例
|
||
|
||
#### 应用回到前台
|
||
```javascript
|
||
appservice("1");
|
||
```
|
||
|
||
#### 应用进入后台
|
||
```javascript
|
||
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: 显示录音消息
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 成功时数据格式
|
||
```json
|
||
{
|
||
"audiourl": "http://gameaudio.daoqi88.cn/audio_20231201_143022.amr",
|
||
"time": 3.5
|
||
}
|
||
```
|
||
|
||
#### 重置时数据格式
|
||
```json
|
||
{
|
||
"audiourl": "",
|
||
"time": 0
|
||
}
|
||
```
|
||
|
||
#### 参数说明
|
||
| 参数 | 类型 | 必需 | 说明 | 示例值 |
|
||
|------|------|------|------|--------|
|
||
| audiourl | string | ✓ | 录音文件URL，空字符串表示重置 | "http://gameaudio.daoqi88.cn/xxx.amr" |
|
||
| time | number | ✓ | 录音时长(秒)，0表示重置 | 3.5 |
|
||
|
||
#### 调用时机
|
||
- ✅ 录音上传成功后立即调用
|
||
- ✅ 录音被取消或重置时调用(传空值)
|
||
- ❌ 不要在录音过程中调用
|
||
- ❌ 不要在上传失败时传递错误URL
|
||
|
||
### 接口调用示例
|
||
|
||
#### 录音上传成功
|
||
```javascript
|
||
getaudiourl('{"audiourl": "http://gameaudio.daoqi88.cn/audio_20231201_143022.amr", "time": 3.5}');
|
||
```
|
||
|
||
#### 录音重置/取消
|
||
```javascript
|
||
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 参数
|
||
```javascript
|
||
// 直接传递用户位置参数
|
||
gameui_play_voice("2"); // 播放用户位置2的语音
|
||
```
|
||
|
||
#### gameui_stop_voice 参数
|
||
```javascript
|
||
// 直接传递用户位置参数
|
||
gameui_stop_voice("2"); // 停止用户位置2的语音
|
||
```
|
||
|
||
#### 参数说明
|
||
| 参数 | 类型 | 必需 | 说明 | 示例值 |
|
||
|------|------|------|------|--------|
|
||
| userPosition | string | ✓ | 用户在游戏中的位置标识 | "1", "2", "3", "4" |
|
||
|
||
#### 调用时机
|
||
**gameui_play_voice调用时机:**
|
||
- ✅ 开始播放语音文件时立即调用
|
||
- ✅ 语音播放器准备就绪后调用
|
||
- ❌ 不要在播放结束时调用
|
||
|
||
**gameui_stop_voice调用时机:**
|
||
- ✅ 语音播放完成时调用
|
||
- ✅ 用户主动停止播放时调用
|
||
- ✅ 播放出错需要停止时调用
|
||
|
||
### 接口调用示例
|
||
|
||
#### 开始播放语音
|
||
```javascript
|
||
gameui_play_voice("2"); // 播放用户位置2的语音
|
||
```
|
||
|
||
#### 停止播放语音
|
||
```javascript
|
||
gameui_stop_voice("2"); // 停止用户位置2的语音
|
||
```
|
||
|
||
#### 多用户语音控制
|
||
```javascript
|
||
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)
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 标准数据格式
|
||
```javascript
|
||
// 直接传递状态码
|
||
phonestate("0"); // 空闲状态
|
||
phonestate("1"); // 来电状态
|
||
phonestate("2"); // 通话状态
|
||
```
|
||
|
||
#### 参数说明
|
||
| 状态码 | 含义 | 说明 | 游戏处理建议 |
|
||
|--------|------|------|--------------|
|
||
| "0" | CALL_STATE_IDLE | 空闲/挂断电话 | 恢复游戏 |
|
||
| "1" | CALL_STATE_RINGING | 来电响铃 | 暂停游戏 |
|
||
| "2" | CALL_STATE_OFFHOOK | 通话中 | 暂停游戏 |
|
||
|
||
#### 调用时机
|
||
- ✅ 电话状态监听器检测到状态变化时
|
||
- ✅ 系统广播电话状态变化时
|
||
- ❌ 不要重复发送相同状态
|
||
- ❌ 不要在状态未确认变化时调用
|
||
|
||
### 接口调用示例
|
||
|
||
#### 电话空闲状态
|
||
```javascript
|
||
phonestate("0"); // 电话挂断或空闲
|
||
```
|
||
|
||
#### 电话来电状态
|
||
```javascript
|
||
phonestate("1"); // 电话响铃
|
||
```
|
||
|
||
#### 电话通话状态
|
||
```javascript
|
||
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: 更新电量显示
|
||
```
|
||
|
||
#### 主动电量查询流程
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant WebView as WebView
|
||
participant App as App
|
||
participant System as 系统
|
||
|
||
WebView->>App: 调用getbattery请求
|
||
App->>System: 获取电池状态
|
||
System->>App: 返回电量信息
|
||
App->>App: 计算电量百分比
|
||
App->>WebView: 调用getBattery返回结果
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 标准数据格式
|
||
```javascript
|
||
// 直接传递电量百分比字符串
|
||
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请求获取当前电量：
|
||
```javascript
|
||
// WebView端发起请求
|
||
window.jsBridge.callHandler('getbattery', null, function(response) {
|
||
// 处理返回的电量信息
|
||
});
|
||
```
|
||
|
||
#### 2. App返回电量 (getBattery)
|
||
App通过此接口向WebView返回电量信息：
|
||
```javascript
|
||
// App调用WebView的getBattery接口
|
||
getBattery("0.75"); // 返回75%电量
|
||
```
|
||
|
||
### 接口调用示例
|
||
|
||
#### 高电量通知
|
||
```javascript
|
||
getBattery("0.90"); // 90%电量
|
||
```
|
||
|
||
#### 中等电量通知
|
||
```javascript
|
||
getBattery("0.45"); // 45%电量
|
||
```
|
||
|
||
#### 低电量警告
|
||
```javascript
|
||
getBattery("0.15"); // 15%电量，需要提醒充电
|
||
```
|
||
|
||
#### 满电状态
|
||
```javascript
|
||
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信息。
|
||
|
||
### 工作流程
|
||
|
||
#### 自动信号强度通知流程
|
||
```mermaid
|
||
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信息查询流程
|
||
```mermaid
|
||
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返回结果
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 标准数据格式
|
||
```json
|
||
{
|
||
"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信息：
|
||
```javascript
|
||
// WebView端发起请求
|
||
window.jsBridge.callHandler('getwifiLevel', null, function(response) {
|
||
// 处理返回的WiFi信息
|
||
});
|
||
```
|
||
|
||
#### 2. App返回WiFi信息 (getwifiLevel响应)
|
||
App通过此接口向WebView返回WiFi信息：
|
||
```javascript
|
||
// App调用WebView的getwifiLevel接口
|
||
getwifiLevel('{"ssidname": "MyHome_WiFi_5G", "signalLevel": 4}');
|
||
```
|
||
|
||
### 接口调用示例
|
||
|
||
#### 强信号WiFi
|
||
```javascript
|
||
getwifiLevel('{"ssidname": "MyHome_WiFi_5G", "signalLevel": 4}');
|
||
```
|
||
|
||
#### 中等信号WiFi
|
||
```javascript
|
||
getwifiLevel('{"ssidname": "Office_Network", "signalLevel": 2}');
|
||
```
|
||
|
||
#### 弱信号WiFi
|
||
```javascript
|
||
getwifiLevel('{"ssidname": "Public_WiFi", "signalLevel": 1}');
|
||
```
|
||
|
||
#### 无WiFi连接
|
||
```javascript
|
||
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基本信息
|
||
```java
|
||
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);
|
||
```
|
||
|
||
#### 广播监听注册
|
||
```java
|
||
// 注册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也可以主动请求获取当前网络连接状态。
|
||
|
||
### 工作流程
|
||
|
||
#### 自动网络状态通知流程
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant System as 系统
|
||
participant App as App
|
||
participant WebView as WebView
|
||
|
||
System->>App: 网络状态变化广播
|
||
App->>App: 检测网络连接状态
|
||
App->>App: 判断网络类型
|
||
App->>WebView: 调用getnetwork
|
||
WebView->>WebView: 更新网络状态显示
|
||
```
|
||
|
||
#### 主动网络状态查询流程
|
||
```mermaid
|
||
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返回结果
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 标准数据格式
|
||
```javascript
|
||
// 直接传递网络类型代码字符串
|
||
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请求获取当前网络状态：
|
||
```javascript
|
||
// WebView端发起请求
|
||
window.jsBridge.callHandler('getnetwork', '', function(response) {
|
||
// 处理返回的网络状态
|
||
console.log('当前网络状态:', response);
|
||
});
|
||
```
|
||
|
||
#### 2. App返回网络状态 (getnetwork响应)
|
||
App通过此接口向WebView返回网络状态：
|
||
```javascript
|
||
// App调用WebView的getnetwork接口
|
||
getnetwork("2"); // 返回WiFi连接状态
|
||
```
|
||
|
||
### 接口调用示例
|
||
|
||
#### WiFi网络连接
|
||
```javascript
|
||
getnetwork("2"); // WiFi连接状态
|
||
```
|
||
|
||
#### 移动网络连接
|
||
```javascript
|
||
getnetwork("3"); // 移动网络连接状态
|
||
```
|
||
|
||
#### 网络断开
|
||
```javascript
|
||
getnetwork("1"); // 网络断开状态
|
||
```
|
||
|
||
### 网络状态检测逻辑
|
||
|
||
#### 网络连接状态判断流程
|
||
```java
|
||
// 1. 检查网络是否连接
|
||
boolean isConnected = isNetworkConnected(context);
|
||
|
||
if (!isConnected) {
|
||
return "1"; // 网络断开
|
||
}
|
||
|
||
// 2. 检查是否为WiFi连接
|
||
boolean isWiFi = isNetworkAvailable(context);
|
||
|
||
if (isWiFi) {
|
||
return "2"; // WiFi连接
|
||
} else {
|
||
return "3"; // 移动网络连接
|
||
}
|
||
```
|
||
|
||
#### 网络类型检测方法
|
||
```java
|
||
// 检查网络是否连接
|
||
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;
|
||
}
|
||
```
|
||
|
||
### 网络状态广播监听
|
||
|
||
#### 广播接收器实现
|
||
```java
|
||
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);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 广播监听注册
|
||
```java
|
||
// 注册网络状态变化监听
|
||
MyNetReceiver myNetReceiver = new MyNetReceiver();
|
||
IntentFilter filter = new IntentFilter(ConnectivityManager.CONNECTIVITY_ACTION);
|
||
registerReceiver(myNetReceiver, filter);
|
||
```
|
||
|
||
### 应用场景和处理建议
|
||
|
||
#### 不同网络状态的处理策略
|
||
| 网络状态 | 处理策略 | 具体建议 |
|
||
|----------|----------|----------|
|
||
| 网络断开(1) | 离线模式 | 显示网络错误提示，缓存用户操作，禁用网络请求 |
|
||
| WiFi连接(2) | 高质量模式 | 启用高清图片/视频，自动更新，无流量限制 |
|
||
| 移动网络(3) | 节省模式 | 压缩图片，询问大文件下载，显示流量提醒 |
|
||
|
||
#### WebView端处理示例
|
||
```javascript
|
||
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提供详细的地理位置信息，包括经纬度、地址描述、行政区划等数据。
|
||
|
||
### 工作流程
|
||
|
||
#### 自动位置信息通知流程
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant System as 定位系统
|
||
participant App as App
|
||
participant WebView as WebView
|
||
|
||
System->>App: 位置变化回调
|
||
App->>App: 解析位置数据
|
||
App->>App: 构造MaplocationInfo对象
|
||
App->>WebView: 调用getlocationinfo
|
||
WebView->>WebView: 更新位置显示
|
||
```
|
||
|
||
#### 主动位置信息查询流程
|
||
```mermaid
|
||
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返回结果
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 标准数据格式
|
||
```json
|
||
{
|
||
"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请求获取当前位置信息：
|
||
```javascript
|
||
// WebView端发起请求
|
||
window.jsBridge.callHandler('getlocationinfo', '', function(response) {
|
||
// 处理返回的位置信息
|
||
const locationData = JSON.parse(response);
|
||
console.log('当前位置:', locationData);
|
||
});
|
||
```
|
||
|
||
#### 2. App返回位置信息 (getlocationinfo响应)
|
||
App通过此接口向WebView返回位置信息：
|
||
```javascript
|
||
// App调用WebView的getlocationinfo接口
|
||
getlocationinfo('{"latitude": 22.543096, "longitude": 114.057865, "address": "广东省深圳市南山区科技园南区深南大道9988号", "country": "中国", "province": "广东省", "city": "深圳市", "district": "南山区", "street": "深南大道", "cityCode": "0755"}');
|
||
```
|
||
|
||
### 接口调用示例
|
||
|
||
#### 深圳地区位置信息
|
||
```javascript
|
||
getlocationinfo('{"latitude": 22.543096, "longitude": 114.057865, "address": "广东省深圳市南山区科技园南区深南大道9988号", "country": "中国", "province": "广东省", "city": "深圳市", "district": "南山区", "street": "深南大道", "cityCode": "0755"}');
|
||
```
|
||
|
||
#### 北京地区位置信息
|
||
```javascript
|
||
getlocationinfo('{"latitude": 39.908692, "longitude": 116.397477, "address": "北京市东城区东长安街1号", "country": "中国", "province": "北京市", "city": "北京市", "district": "东城区", "street": "东长安街", "cityCode": "010"}');
|
||
```
|
||
|
||
#### 上海地区位置信息
|
||
```javascript
|
||
getlocationinfo('{"latitude": 31.230416, "longitude": 121.473701, "address": "上海市黄浦区南京东路20号", "country": "中国", "province": "上海市", "city": "上海市", "district": "黄浦区", "street": "南京东路", "cityCode": "021"}');
|
||
```
|
||
|
||
#### 位置信息不可用时
|
||
```javascript
|
||
getlocationinfo('null'); // 定位失败或位置信息不可用
|
||
```
|
||
|
||
### 位置信息获取流程
|
||
|
||
#### 定位服务初始化
|
||
```java
|
||
// 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();
|
||
```
|
||
|
||
#### 位置信息解析
|
||
```java
|
||
// 位置变化回调处理
|
||
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秒 |
|
||
|
||
### 权限和隐私处理
|
||
|
||
#### 必需权限
|
||
```xml
|
||
<!-- 精确位置权限 -->
|
||
<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" />
|
||
```
|
||
|
||
#### 权限检查流程
|
||
```java
|
||
// 检查位置权限
|
||
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 | 网络连接异常 | 检查网络连接 |
|
||
|
||
#### 异常处理示例
|
||
```java
|
||
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返回结果的数据传递。
|
||
|
||
### 工作流程
|
||
|
||
#### 页面加载完成后数据传递流程
|
||
```mermaid
|
||
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结果返回数据传递流程
|
||
```mermaid
|
||
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: 处理返回的数据
|
||
```
|
||
|
||
### 参数规范
|
||
|
||
#### 标准数据格式
|
||
```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未准备好时调用
|
||
|
||
### 接口调用示例
|
||
|
||
#### 用户登录信息传递
|
||
```javascript
|
||
getWebdata('{"action":"user_login","userId":"12345","userName":"张三","avatar":"https://example.com/avatar.jpg","loginTime":"2025-01-13 14:30:00"}');
|
||
```
|
||
|
||
#### 游戏数据传递
|
||
```javascript
|
||
getWebdata('{"action":"game_data","gameId":"niuniu","currentScore":1500,"highScore":3200,"level":"expert","coins":5000}');
|
||
```
|
||
|
||
#### 简单状态传递
|
||
```javascript
|
||
getWebdata("page_refresh_complete");
|
||
```
|
||
|
||
#### 配置信息传递
|
||
```javascript
|
||
getWebdata('{"action":"app_config","theme":"dark","language":"zh-CN","soundEnabled":true,"notificationEnabled":false}');
|
||
```
|
||
|
||
#### 错误信息传递
|
||
```javascript
|
||
getWebdata('{"action":"error","errorCode":"E001","errorMessage":"网络连接失败","timestamp":"2025-01-13 14:30:00"}');
|
||
```
|
||
|
||
### 数据传递场景
|
||
|
||
#### 1. 页面初始化数据传递
|
||
**使用场景**: WebView页面加载完成后需要获取初始数据
|
||
```java
|
||
// 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
|
||
```java
|
||
// 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
|
||
```java
|
||
// 应用状态变化时调用
|
||
private void notifyAppStateChange(String newState) {
|
||
String stateData = '{"action":"app_state_change","state":"' + newState + '"}';
|
||
x5webview.callHandler("getWebdata", stateData, null);
|
||
}
|
||
```
|
||
|
||
### 数据处理建议
|
||
|
||
#### WebView端数据处理
|
||
```javascript
|
||
// 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);
|
||
}
|
||
```
|
||
|
||
#### 数据验证机制
|
||
```javascript
|
||
// 数据有效性验证
|
||
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未准备好时调用 | 确保页面加载完成后调用 |
|
||
| 数据过大 | 传递的数据量过大 | 分批传递或压缩数据 |
|
||
|
||
#### 异常处理示例
|
||
```java
|
||
// 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
|
||
**联系方式**: 技术支持组
|