# 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  
**联系方式**: 技术支持组