ZLH5 Bridge SDK

H5与App桥接SDK，支持iOS/Android原生和Flutter环境，基于WebViewJavascriptBridge和Flutter_inappwebview。

简介

ZLH5 Bridge SDK是一个功能强大的JavaScript库，专为H5页面与原生App之间的通信而设计。它支持多种环境，包括：

• iOS原生应用（基于WebViewJavascriptBridge）
• Android原生应用（基于WebViewJavascriptBridge）
• Flutter应用（基于flutter_inappwebview）

该SDK提供了统一的API接口，简化了跨平台开发的复杂性，并具备以下特性：

• 自动环境检测
• 请求超时和重试机制
• 完善的错误处理
• 详细的日志记录
• 类型安全支持

安装

npm install zlh5-bridge-sdk

或

yarn add zlh5-bridge-sdk

快速开始

初始化SDK

import zLH5Bridge from 'zlh5-bridge-sdk';

// 基本初始化
const bridge = new zLH5Bridge();

// 带配置的初始化
const bridge = new zLH5Bridge({
  timeout: 5000,
  maxRetryCount: 2,
  logLevel: 3 // 开发模式
});

调用原生方法

// 使用预设方法
const location = await bridge.initPresetMethods('getLocation');

// 直接调用原生方法
const result = await bridge.callNative('shareLocation', {
  latitude: 39.9042,
  longitude: 116.4074
});

注册H5方法供原生调用

// 注册方法
bridge.register('onUserInfoUpdate', (data) => {
  console.log('User info updated:', data);
});

// 注销方法
bridge.unregister('onUserInfoUpdate');

API参考

核心类：zLH5Bridge

构造函数

new zLH5Bridge(config, instanceConfig)

参数：

• config: 全局配置对象
  • timeout: 请求超时时间（毫秒），默认5000
  • maxRetryCount: 最大重试次数，默认0
  • logLevel: 日志等级，默认0（生产环境）
• instanceConfig: 实例配置对象，应用于该实例的所有请求

方法

callNative(bridgeName, params, config)

调用原生方法

参数：

• bridgeName: 原生方法名
• params: 传递给原生方法的参数
• config: 请求配置（可选）

返回： Promise

register(methodName, callback)

注册H5方法供原生调用

参数：

• methodName: 方法名
• callback: 回调函数

unregister(methodName)

注销H5方法

参数：

• methodName: 方法名

返回： boolean

isFullyInit()

检查是否完全初始化

返回： Promise

getInitStatus()

获取初始化状态

返回： 'not_init' | 'partially_init' | 'fully_init'

getPendingRequestCount()

获取待处理请求数量

返回： number

initPresetMethods(bridgeName, params, config)

初始化预置方法

参数：

• bridgeName: 预置方法名
• params: 请求参数（可选）
• config: 请求配置（可选）

返回： Promise

updateConfig(newConfig)

更新配置

参数：

• newConfig: 新的配置对象

getConfig()

获取当前配置

返回： SDKConfig

destroy()

销毁实例

预设方法

SDK提供了一系列预设方法，方便快速调用常用的原生功能：

1. getLocation - 获取定位信息
2. goBack - 返回/后退
3. getUserInfo - 获取用户信息
4. shareH5 - H5分享
5. getDeviceInfo - 获取设备信息
6. callPhoneNumber - 拨打电话
7. checkBridge - 检查当前App是否存在某个桥
8. refreshToken - 刷新Token
9. login - 登录
10. logout - 登出

工具函数和枚举

SDK还导出了以下工具函数和枚举：

• getEnvironment() - 获取当前环境
• logger - 日志工具
• LogLevel - 日志等级枚举
• PresetBridgeNames - 预设方法名枚举

配置说明

日志等级

import { LogLevel } from 'zlh5-bridge-sdk';

// 可选的日志等级
LogLevel.PRODUCTION    // 0 - 生产环境，只输出错误日志
LogLevel.PRE_RELEASE   // 1 - 预发布环境，输出错误和警告日志
LogLevel.TEST          // 2 - 测试环境，输出错误、警告和信息日志
LogLevel.DEVELOPMENT   // 3 - 开发环境，输出除调试外的所有日志
LogLevel.DEBUG         // 4 - 调试环境，输出所有日志

预设方法名枚举

import { PresetBridgeNames } from 'zlh5-bridge-sdk';

// 可选的预设方法名
PresetBridgeNames.GET_LOCATION     // 'getLocation'
PresetBridgeNames.GO_BACK          // 'goBack'
PresetBridgeNames.GET_USER_INFO    // 'getUserInfo'
PresetBridgeNames.SHARE_H5         // 'shareH5'
PresetBridgeNames.GET_DEVICE_INFO  // 'getDeviceInfo'
PresetBridgeNames.CALL_PHONE_NUMBER // 'callPhoneNumber'
PresetBridgeNames.CHECK_BRIDGE     // 'checkBridge'
PresetBridgeNames.REFRESH_TOKEN    // 'refreshToken'
PresetBridgeNames.LOGIN            // 'login'
PresetBridgeNames.LOGOUT           // 'logout'

错误处理

SDK定义了以下错误码：

• TIMEOUT - 请求超时
• NETWORK_ERROR - 网络错误
• BRIDGE_NOT_READY - 桥接未就绪
• INVALID_PARAMS - 参数错误
• METHOD_NOT_FOUND - 方法未找到
• UNKNOWN_ERROR - 未知错误

构建和开发

构建项目

npm run build

开发模式

npm run dev

类型检查

npm run type-check

浏览器兼容性

• Chrome 50+
• Firefox 50+
• Safari 10+
• Edge 15+
• iOS WebView 10+
• Android WebView 50+

许可证

MIT

贡献

欢迎提交Issue和Pull Request来帮助改进这个项目。