JSBridge SDK

轻量级、高性能的 JSBridge SDK，用于 Web 与原生 App 之间的通信。

特性

- 🚀 高性能：轻量级设计，无外部依赖，体积小巧
- 🔄 双向通信：支持 H5 调用原生方法，也支持原生调用 H5 方法
- 📱 多平台支持：同时支持 iOS (WKWebView) 和 Android (JavaScriptInterface)
- 🔄 队列管理：内置队列机制，确保顺序调用，避免并发问题
- 💾 缓存支持：可配置接口缓存，提高频繁调用的性能
- 📊 调试友好：内置日志系统，支持不同级别的调试输出
- 🔌 事件系统：提供订阅/发布模式的事件系统，方便原生向 H5 推送消息
- 🔄 Promise 支持：支持 Promise 方式调用，代码更简洁
- 🧩 TypeScript：使用 TypeScript 编写，提供完整类型定义
- 🛡️ 框架兼容：适用于各种前端框架 (Vue, React, Angular 等)

安装

``bash
npm install jsbridge-sdk --save
`

或者使用 CDN 直接引入：

`html

`

基本用法

$3

`javascript
import JSBridge from 'jsbridge-sdk';

// 初始化 JSBridge
JSBridge.init({
debug: true, // 是否开启调试模式
timeout: 15000, // 请求超时时间（毫秒）
enableCache: true // 是否启用缓存
});
`

$3

`javascript
// 方式 1：回调方式
JSBridge.call('getDeviceInfo', function(result) {
console.log('设备信息：', result);
});

// 方式 2：带参数
JSBridge.call('getLocation', { type: 'gcj02' }, function(result) {
console.log('位置信息：', result);
});

// 方式 3：Promise 方式
JSBridge.callAsync('getNetworkStatus')
.then(result => {
console.log('网络状态：', result);
})
.catch(error => {
console.error('获取网络状态失败：', error);
});
`

$3

`javascript
// 注册方法
JSBridge.register('updateUI', function(data) {
console.log('收到原生传来的数据：', data);
// 更新界面逻辑
return {
success: true,
message: '界面已更新'
};
});

// 注销方法
JSBridge.unregister('updateUI');
`

$3

`javascript
// 监听事件
function networkChangeHandler(data) {
console.log('网络状态变化：', data);
}
JSBridge.on('networkChange', networkChangeHandler);

// 取消监听
JSBridge.off('networkChange', networkChangeHandler);
`

在 Vue 中使用

$3

`javascript
// src/plugins/jsbridge.js
import JSBridge from 'jsbridge-sdk';

export default {
install(app, options = {}) {
// 初始化 JSBridge
JSBridge.init({
debug: options.debug || false,
enableCache: options.enableCache !== false,
timeout: options.timeout || 15000
});

// 添加全局属性 $jsbridge
app.config.globalProperties.$jsbridge = JSBridge;

// 提供 JSBridge
app.provide('jsbridge', JSBridge);
}
};

// 导出 JSBridge 单例，方便直接使用
export { JSBridge };
`

$3

`javascript
import { createApp } from 'vue';
import App from './App.vue';
import JSBridgePlugin from './plugins/jsbridge';

const app = createApp(App);
app.use(JSBridgePlugin, { debug: true });
app.mount('#app');
`

$3

`javascript
// 选项式 API
export default {
methods: {
getDeviceInfo() {
this.$jsbridge.call('getDeviceInfo', result => {
this.deviceInfo = result;
});
}
}
};

// 组合式 API
import { inject } from 'vue';

export default {
setup() {
const jsbridge = inject('jsbridge');

const getDeviceInfo = async () => {
try {
const result = await jsbridge.callAsync('getDeviceInfo');
// 处理结果
} catch (err) {
// 处理错误
}
};

return { getDeviceInfo };
}
};
`

原生端实现

本 SDK 提供 JavaScript 端的实现，原生端需要实现相应的接口才能完成通信。

$3

`swift
// 简化示例
extension ViewController: WKScriptMessageHandler {
func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
guard let body = message.body as? [String: Any],
let methodName = body["method"] as? String,
let params = body["params"] as? [String: Any],
let callbackId = body["callbackId"] as? String else {
return
}

// 处理方法调用
handleJSBridgeCall(methodName: methodName, params: params, callbackId: callbackId)
}

func handleJSBridgeCall(methodName: String, params: [String: Any], callbackId: String) {
// 根据方法名执行相应的原生操作
var result: [String: Any] = [:]

switch methodName {
case "getDeviceInfo":
// 获取设备信息
result = ["platform": "iOS", "version": UIDevice.current.systemVersion]
// 其他方法...
default:
result = ["error": "方法不存在"]
}

// 返回结果给 JS
let script = "window.JSBridgeCallback('\(callbackId)', \(toJSONString(result)))"
webView.evaluateJavaScript(script, completionHandler: nil)
}

// 调用 JS 方法
func callJSMethod(name: String, data: [String: Any], completion: ((Any?) -> Void)? = nil) {
let script = "window.JSBridgeInvoke('\(name)', \(toJSONString(data)))"
webView.evaluateJavaScript(script) { (result, error) in
completion?(result)
}
}

// 触发事件
func triggerJSEvent(eventName: String, data: [String: Any]) {
let script = "window.JSBridgeEvent('\(eventName)', \(toJSONString(data)))"
webView.evaluateJavaScript(script, completionHandler: nil)
}
}
`

$3

`java
// 简化示例
public class JSBridgeInterface {
private WebView webView;
private Context context;

public JSBridgeInterface(WebView webView, Context context) {
this.webView = webView;
this.context = context;
}

@JavascriptInterface
public void call(String message) {
try {
JSONObject jsonObject = new JSONObject(message);
String method = jsonObject.getString("method");
JSONObject params = jsonObject.optJSONObject("params");
String callbackId = jsonObject.getString("callbackId");

// 根据方法名执行相应操作
JSONObject result = handleMethod(method, params);

// 返回结果给 JS
callJSCallback(callbackId, result);
} catch (JSONException e) {
e.printStackTrace();
}
}

private JSONObject handleMethod(String method, JSONObject params) throws JSONException {
JSONObject result = new JSONObject();

switch (method) {
case "getDeviceInfo":
// 获取设备信息
result.put("platform", "Android");
result.put("version", Build.VERSION.RELEASE);
break;
// 其他方法...
default:
result.put("error", "方法不存在");
}

return result;
}

// 在主线程中调用 JS 回调
private void callJSCallback(final String callbackId, final JSONObject result) {
webView.post(() -> {
webView.evaluateJavascript(
"window.JSBridgeCallback('" + callbackId + "', " + result.toString() + ")",
null
);
});
}

// 在主线程中调用 JS 方法
public void callJSMethod(String name, JSONObject data, ValueCallback callback) {
webView.post(() -> {
webView.evaluateJavascript(
"window.JSBridgeInvoke('" + name + "', " + data.toString() + ")",
callback
);
});
}

// 在主线程中触发 JS 事件
public void triggerJSEvent(String eventName, JSONObject data) {
webView.post(() -> {
webView.evaluateJavascript(
"window.JSBridgeEvent('" + eventName + "', " + data.toString() + ")",
null
);
});
}

@JavascriptInterface
public void onJSBridgeReady() {
// Bridge 已就绪
Log.d("JSBridge", "Bridge is ready");
}
}
`

示例

查看 examples 目录中的完整示例：

- examples/basic.html - 基本用法示例
- examples/vue-demo/ - Vue 集成示例

API 文档

$3

#### 方法

- init(options?: JSBridgeOptions): JSBridgeInterface - 初始化 JSBridge
- call(method: string, params?: any, callback?: CallbackFunction): JSBridgeInterface - 调用原生方法
- callAsync(method: string, params?: any): Promise - Promise 风格的原生方法调用
- register(name: string, handler: MethodHandler): JSBridgeInterface - 注册 H5 方法供原生调用
- unregister(name: string): JSBridgeInterface - 注销 H5 方法
- on(eventName: string, handler: EventHandler): JSBridgeInterface - 监听原生事件
- off(eventName: string, handler?: EventHandler): JSBridgeInterface - 取消监听原生事件
- setDebug(enabled: boolean, options?: Partial): JSBridgeInterface - 设置调试模式
- clearCache(): JSBridgeInterface - 清除所有缓存

#### 类型定义

`typescript
interface JSBridgeOptions {
debug?: boolean;
timeout?: number;
enableCache?: boolean;
}

type CallbackFunction = (data: any) => void;
type MethodHandler = (data: any) => any | Promise;
type EventHandler = (data: any) => void;

interface DebugOptions {
enabled: boolean;
logLevel?: string;
useConsole?: boolean;
}
`

构建与开发

`bash

安装依赖

npm install

开发模式

npm run dev

构建

npm run build

运行示例

npm run example:basic
``