JSBridge原理与实现全解析
JSBridge 是用于连接 JavaScript（H5） 和原生应用（iOS/Android）的桥梁，允许它们之间相互调用方法。
🌉 一、JSBridge 双向通信流程图
⚙️二、基本调用模式
1. JavaScript桥接层
jsbridge-demo.js
// JS 调用原生方法
const callNativeMethod = (methodName, params, callback) => {// 生成唯一回调 IDconst callbackId = `cb_${Date.now()}_${Math.random().toString(36).substr(2, 5)}`;// 保存回调函数window.JSBridge.callbacks[callbackId] = callback;// 构造调用数据const data = {method: methodName,params: params,callbackId: callbackId};// 不同平台的调用方式if (/(iPhone|iPad|iPod|iOS)/i.test(navigator.userAgent)) {// iOS: 通过 WebView 的 URL Scheme 调用window.webkit.messageHandlers.JSBridge.postMessage(data);} else if (/(Android)/i.test(navigator.userAgent)) {// Android: 通过 addJavascriptInterface 提供的对象调用window.AndroidJSBridge.call(JSON.stringify(data));}
}// 原生调用 JS 回调的方法
window.JSBridge = {callbacks: {},// 原生通过此方法回调 JSinvokeCallback: (callbackId, result) => {const callback = window.JSBridge.callbacks[callbackId];if (callback && typeof callback === 'function') {callback(result);// 执行后删除回调，避免内存泄漏delete window.JSBridge.callbacks[callbackId];}}
};// 示例1：调用原生获取设备信息
callNativeMethod('getDeviceInfo', {}, function(result) {console.log('设备信息:', result);document.getElementById('deviceInfo').innerText = JSON.stringify(result);
});// 示例2：调用原生分享功能
document.getElementById('shareBtn').addEventListener('click', function() {callNativeMethod('share', {title: '分享标题',content: '分享内容',url: 'https://example.com'}, function(success) {if (success) {alert('分享成功');} else {alert('分享取消');}});
});2. 原生端桥阶层实现
Android端（Java）
AndroidJSBridge.java
package com.example.jsbridge;import android.content.Context;
import android.os.Build;
import android.webkit.JavascriptInterface;
import android.webkit.WebView;
import org.json.JSONException;
import org.json.JSONObject;public class AndroidJSBridge {private final Context mContext;private final WebView mWebView;// 构造函数，接收上下文和WebView实例public AndroidJSBridge(Context context, WebView webView) {this.mContext = context;this.mWebView = webView;}// 暴露给JS调用的方法，必须加@JavascriptInterface注解@JavascriptInterfacepublic void call(String data) {try {// 解析JS传递的JSON数据JSONObject jsonData = new JSONObject(data);String method = jsonData.getString("method");JSONObject params = jsonData.getJSONObject("params");String callbackId = jsonData.getString("callbackId");// 根据方法名处理不同逻辑switch (method) {case "getDeviceInfo":handleGetDeviceInfo(callbackId);break;case "share":handleShare(params, callbackId);break;default:sendErrorCallback(callbackId, "Method not found: " + method);}} catch (JSONException e) {e.printStackTrace();}}// 处理获取设备信息private void handleGetDeviceInfo(String callbackId) {try {JSONObject result = new JSONObject();result.put("model", Build.MODEL); // 设备型号result.put("brand", Build.BRAND); // 设备品牌result.put("system", "Android " + Build.VERSION.RELEASE); // 系统版本result.put("sdkInt", Build.VERSION.SDK_INT); // SDK版本sendSuccessCallback(callbackId, result);} catch (JSONException e) {e.printStackTrace();sendErrorCallback(callbackId, "Failed to get device info");}}// 处理分享功能private void handleShare(JSONObject params, String callbackId) {try {String title = params.getString("title");String content = params.getString("content");String url = params.getString("url");// 这里只是模拟分享成功，实际项目中应调用系统分享功能boolean shareSuccess = true;// 回调JS告知结果sendSuccessCallback(callbackId, new JSONObject().put("success", shareSuccess));} catch (JSONException e) {e.printStackTrace();sendErrorCallback(callbackId, "Share parameters error");}}// 发送成功回调private void sendSuccessCallback(String callbackId, JSONObject result) {String js = String.format("window.JSBridge.invokeCallback('%s', %s)",callbackId, result.toString());runOnMainThread(js);}// 发送错误回调private void sendErrorCallback(String callbackId, String errorMsg) {try {JSONObject error = new JSONObject();error.put("error", errorMsg);String js = String.format("window.JSBridge.invokeCallback('%s', %s)",callbackId, error.toString());runOnMainThread(js);} catch (JSONException e) {e.printStackTrace();}}// 在主线程执行JS代码private void runOnMainThread(final String js) {mWebView.post(() -> mWebView.evaluateJavascript(js, null));}
}MainActivity.java
package com.example.jsbridge;import android.os.Bundle;
import android.webkit.WebSettings;
import android.webkit.WebView;
import androidx.appcompat.app.AppCompatActivity;public class MainActivity extends AppCompatActivity {private WebView mWebView;@Overrideprotected void onCreate(Bundle savedInstanceState) {super.onCreate(savedInstanceState);setContentView(R.layout.activity_main);mWebView = findViewById(R.id.webView);initWebView();}private void initWebView() {WebSettings webSettings = mWebView.getSettings();// 启用JavaScriptwebSettings.setJavaScriptEnabled(true);// 允许通过file协议加载的JS访问其他文件webSettings.setAllowFileAccessFromFileURLs(true);// 允许通过http协议加载的JS访问文件webSettings.setAllowUniversalAccessFromFileURLs(true);// 注册JSBridgemWebView.addJavascriptInterface(new AndroidJSBridge(this, mWebView), "AndroidJSBridge");// 加载本地HTML文件或远程URLmWebView.loadUrl("file:///android_asset/index.html");}@Overrideprotected void onDestroy() {super.onDestroy();// 销毁WebView防止内存泄漏if (mWebView != null) {mWebView.destroy();}}
}iOS端（Swift）
IOSJSBridge.swift
import UIKit
import WebKitclass IOSJSBridge: NSObject, WKScriptMessageHandler {private weak var webView: WKWebView?init(webView: WKWebView) {self.webView = webViewsuper.init()}// 处理JS发送的消息func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {guard message.name == "JSBridge",let data = message.body as? [String: Any],let method = data["method"] as? String,let callbackId = data["callbackId"] as? String else {return}let params = data["params"] as? [String: Any] ?? [:]// 根据方法名处理不同逻辑switch method {case "getDeviceInfo":handleGetDeviceInfo(callbackId: callbackId)case "share":handleShare(params: params, callbackId: callbackId)default:sendErrorCallback(callbackId: callbackId, errorMsg: "Method not found: \(method)")}}// 处理获取设备信息private func handleGetDeviceInfo(callbackId: String) {let device = UIDevice.currentlet result: [String: Any] = ["model": device.model,"name": device.name,"system": "iOS \(device.systemVersion)","identifierForVendor": device.identifierForVendor?.uuidString ?? ""]sendSuccessCallback(callbackId: callbackId, result: result)}// 处理分享功能private func handleShare(params: [String: Any], callbackId: String) {guard let title = params["title"] as? String,let content = params["content"] as? String,let url = params["url"] as? String else {sendErrorCallback(callbackId: callbackId, errorMsg: "Invalid share parameters")return}// 这里只是模拟分享成功，实际项目中应调用系统分享功能let shareSuccess = truesendSuccessCallback(callbackId: callbackId, result: ["success": shareSuccess])}// 发送成功回调private func sendSuccessCallback(callbackId: String, result: [String: Any]) {guard let jsonData = try? JSONSerialization.data(withJSONObject: result),let jsonString = String(data: jsonData, encoding: .utf8),let webView = webView else {return}let js = "window.JSBridge.invokeCallback('\(callbackId)', \(jsonString))"webView.evaluateJavaScript(js, completionHandler: nil)}// 发送错误回调private func sendErrorCallback(callbackId: String, errorMsg: String) {let error = ["error": errorMsg]sendSuccessCallback(callbackId: callbackId, result: error)}
}WebViewController.swift
import UIKit
import WebKitclass WebViewController: UIViewController {private var webView: WKWebView!override func viewDidLoad() {super.viewDidLoad()setupWebView()loadWebContent()}private func setupWebView() {// 配置WebViewlet config = WKWebViewConfiguration()let userContentController = WKUserContentController()// 创建JSBridge处理器并注册let iOSJSBridgeHandler = IOSJSBridge(webView: webView)userContentController.add(iOSJSBridgeHandler, name: "JSBridge")config.userContentController = userContentControllerwebView = WKWebView(frame: view.bounds, configuration: config)webView.navigationDelegate = selfwebView.autoresizingMask = [.flexibleWidth, .flexibleHeight]view.addSubview(webView)}private func loadWebContent() {// 加载本地HTML文件或远程URLif let url = Bundle.main.url(forResource: "index", withExtension: "html") {webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent())} else {// 备用：加载远程URLlet url = URL(string: "https://example.com")!webView.load(URLRequest(url: url))}}
}// 实现WKNavigationDelegate协议
extension WebViewController: WKNavigationDelegate {// 可以在这里处理页面加载事件
}🛡️ 三、安全与性能优化建议
-
安全防护
- 方法白名单校验：原生端只响应预注册的方法名
if (!allowedMethods.contains(method)) { sendError(callbackId, "Method forbidden"); }- 输入消毒：对JS传入参数进行正则校验
- HTTPS 通信：防止中间人攻击
-
性能优化
- 避免主线程阻塞：Android 使用
Handler处理耗时操作 - 回调超时机制：JS 端设置 5s 超时清理回调函数
setTimeout(() => {delete JSBridge.callbacks[callbackId]; }, 5000);- 大数据分片传输：超过 1MB 数据使用分块传输
- 避免主线程阻塞：Android 使用
-
跨平台兼容
- 统一调用接口：封装
JSBridge.invoke()抹平平台差异 - 版本检测逻辑：
const isIOS = /(iPhone|iPad)/i.test(navigator.userAgent); const isNewIOS = isIOS && !!window.webkit?.messageHandlers; - 统一调用接口：封装
💻 四、完整调用示例
通过该设计，JSBridge 实现了 跨平台调用标准化（Android/iOS 接口统一）、双向通信可靠化（回调ID机制）、安全控制精细化（方法白名单+参数校验）。实际开发建议使用开源库（如https://github.com/marcuswestin/WebViewJavascriptBridge）减少底层适配成本。