Hybrid之JSBridge原理

Hybrid之JSBridge原理

引言

在移动应用开发中，Hybrid混合开发模式因其跨平台特性和开发效率优势而被广泛采用。JSBridge作为连接JavaScript与Native代码的桥梁，是Hybrid应用的核心技术之一。它使得Web页面能够调用原生功能（如相机、定位、支付等），同时Native也能向Web注入数据和方法，实现双向通信。

本文将深入剖析JSBridge的工作原理、实现方式、最佳实践以及在现代应用中的演进趋势。

---

一、什么是JSBridge

1.1 核心概念

JSBridge（JavaScript Bridge）是一种在Hybrid应用中实现JavaScript与Native代码双向通信的技术方案。它解决了Web技术无法直接访问设备原生能力的限制。

核心作用：

• JavaScript调用Native：Web页面通过JSBridge调用原生API（如扫码、拍照、获取定位等）
• Native调用JavaScript：原生代码向WebView注入数据或执行JavaScript函数

1.2 应用场景

// 示例：通过JSBridge调用原生分享功能
window.JSBridge.callNative('share', {
  title: '精彩文章',
  content: '这是一篇关于JSBridge的技术文章',
  url: 'https://example.com/article'
}, (result) => {
  console.log('分享结果:', result);
});

典型应用场景包括：

• 设备能力调用（相机、相册、GPS、传感器）
• 原生UI组件（导航栏、Toast、ActionSheet）
• 数据存储（本地数据库、文件系统）
• 性能优化（图片加载、网络请求）
• 支付与安全（指纹认证、人脸识别、加密）

---

二、JSBridge的实现原理

2.1 整体通信流程

下图展示了JSBridge完整的通信机制：

sequenceDiagram
    participant H5 as H5页面
    participant Bridge as JSBridge
    participant Native as Native层

    H5->>Bridge: 1. 调用JSBridge方法
    Bridge->>Native: 2. 通过协议发送请求
    Native->>Native: 3. 解析协议并执行
    Native->>Bridge: 4. 返回执行结果
    Bridge->>H5: 5. 触发回调函数

2.2 JavaScript调用Native的实现方式

方式一：URL Scheme拦截（主流方案）

原理说明： H5端通过创建隐藏的iframe或修改window.location，触发一个自定义URL Scheme（如jsbridge://）。Native端的WebView拦截这个URL请求，解析其中的方法名和参数，执行对应的原生方法后通过回调返回结果。

JavaScript端实现：

// JSBridge核心实现
class JSBridge {
  constructor() {
    this.callbackId = 0;
    this.callbacks = {};
  }

  // 调用Native方法
  callNative(method, params, callback) {
    const callbackId = `cb_${this.callbackId++}`;

    // 保存回调函数
    if (callback) {
      this.callbacks[callbackId] = callback;
    }

    // 构造协议URL
    const url = `jsbridge://${method}?params=${encodeURIComponent(JSON.stringify(params))}&callbackId=${callbackId}`;

    // 通过iframe触发
    const iframe = document.createElement('iframe');
    iframe.style.display = 'none';
    iframe.src = url;
    document.body.appendChild(iframe);

    setTimeout(() => {
      document.body.removeChild(iframe);
    }, 200);
  }

  // Native调用的回调入口
  handleCallback(callbackId, result) {
    const callback = this.callbacks[callbackId];
    if (callback) {
      callback(result);
      delete this.callbacks[callbackId];
    }
  }
}

// 全局实例
window.JSBridge = new JSBridge();

Android端拦截实现（Kotlin）：

// Android WebViewClient伪代码示例
webView.setWebViewClient(object : WebViewClient() {
  override fun shouldOverrideUrlLoading(view: WebView, url: String): Boolean {
    if (url.startsWith("jsbridge://")) {
      // 解析URL
      val uri = Uri.parse(url)
      val method = uri.host
      val params = uri.getQueryParameter("params")
      val callbackId = uri.getQueryParameter("callbackId")

      // 执行原生方法
      val result = executeNativeMethod(method, params)

      // 回调给JS
      view.evaluateJavascript(
        "window.JSBridge.handleCallback('$callbackId', $result)", null
      )
      return true
    }
    return super.shouldOverrideUrlLoading(view, url)
  }
})

iOS端拦截实现（Swift）：

// iOS WKNavigationDelegate伪代码示例
func webView(_ webView: WKWebView,
             decidePolicyFor navigationAction: WKNavigationAction,
             decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {

    guard let url = navigationAction.request.url,
          url.scheme == "jsbridge" else {
        decisionHandler(.allow)
        return
    }

    // 解析并执行
    let method = url.host
    let params = parseParams(url)
    let result = executeNativeMethod(method, params)

    // 回调
    webView.evaluateJavaScript(
      "window.JSBridge.handleCallback('\(callbackId)', \(result))"
    )

    decisionHandler(.cancel)
}

方式二：API注入（高性能方案）

原理说明： Native端直接向WebView的JavaScript上下文注入对象或方法，使JavaScript可以同步调用。Android使用addJavascriptInterface，iOS使用WKScriptMessageHandler。

技术对比：

graph LR
    A[JS调用Native方案] --> B[URL Scheme拦截]
    A --> C[API注入]
    A --> D[prompt/console劫持]

    B --> B1[兼容性: ⭐⭐⭐⭐⭐]
    B --> B2[性能: ⭐⭐⭐]
    B --> B3[安全性: ⭐⭐⭐⭐]

    C --> C1[兼容性: ⭐⭐⭐⭐]
    C --> C2[性能: ⭐⭐⭐⭐⭐]
    C --> C3[安全性: ⭐⭐]

    D --> D1[兼容性: ⭐⭐⭐]
    D --> D2[性能: ⭐⭐⭐⭐]
    D --> D3[安全性: ⭐⭐⭐]

Android注入示例：

// Android端注入对象（需注意安全性）
class NativeBridge {
  @JavascriptInterface
  fun getDeviceInfo(): String {
    return JSONObject().apply {
      put("model", Build.MODEL)
      put("version", Build.VERSION.RELEASE)
    }.toString()
  }

  @JavascriptInterface
  fun showToast(message: String) {
    Toast.makeText(context, message, Toast.LENGTH_SHORT).show()
  }
}

// 注入到WebView
webView.addJavascriptInterface(NativeBridge(), "NativeAPI")

JavaScript调用注入的API：

// H5端直接调用
const deviceInfo = JSON.parse(window.NativeAPI.getDeviceInfo());
console.log('设备信息:', deviceInfo);

window.NativeAPI.showToast('Hello from H5!');

方式三：prompt/console劫持（备选方案）

原理说明： 通过重写JavaScript的原生方法（如prompt、console.log等），将调用参数传递给Native。这种方式可以实现同步返回结果，但会影响原有功能。

JavaScript端实现：

// 劫持prompt方法
const originalPrompt = window.prompt;

window.prompt = function(message) {
  // 检测是否是JSBridge调用
  if (message && message.startsWith('jsbridge://')) {
    try {
      const data = JSON.parse(message.substring(11));
      // Native会拦截并返回结果
      return nativeHandler(data);
    } catch (e) {
      console.error('JSBridge调用失败:', e);
    }
  }
  return originalPrompt.apply(window, arguments);
};

// 使用
const result = prompt('jsbridge://' + JSON.stringify({
  module: 'Device',
  method: 'getInfo'
}));

Android端拦截：

// 重写WebChromeClient的onJsPrompt方法
webView.setWebChromeClient(object : WebChromeClient() {
  override fun onJsPrompt(
    view: WebView,
    url: String,
    message: String,
    defaultValue: String,
    result: JsPromptResult
  ): Boolean {
    if (message.startsWith("jsbridge://")) {
      val data = message.substring(11)
      val response = handleBridgeCall(data)
      result.confirm(response)
      return true
    }
    return super.onJsPrompt(view, url, message, defaultValue, result)
  }
})

iOS注入示例（WKScriptMessageHandler）：

// iOS端注册消息处理器
let userContentController = WKUserContentController()
userContentController.add(self, name: "nativeHandler")

// JavaScript调用
window.webkit.messageHandlers.nativeHandler.postMessage({
  method: 'showAlert',
  params: { message: 'Hello' }
})

2.3 Native调用JavaScript

实现方式： Native端通过WebView提供的API直接执行JavaScript代码字符串。

Android实现：

// Android通过evaluateJavascript执行JS
webView.evaluateJavascript(
  "window.onNativeEvent('userLogin', {userId: 12345})",
  { result ->
    println("JS执行结果: $result")
  }
)

iOS实现：

// iOS通过WKWebView执行JS
webView.evaluateJavaScript("window.onNativeEvent('userLogin', {userId: 12345})") { result, error in
  if let result = result {
    print("JS执行结果: \(result)")
  }
}

H5端接收Native调用：

// 全局事件监听函数
window.onNativeEvent = function(eventType, data) {
  switch(eventType) {
    case 'userLogin':
      console.log('用户登录:', data.userId);
      updateUserUI(data);
      break;
    case 'networkChange':
      handleNetworkChange(data.status);
      break;
  }
};

---

三、JSBridge的技术架构

3.1 完整架构图

3.2 核心组件设计

graph TB
    A[H5应用] --> B[JSBridge SDK]
    B --> C{通信方式}
    C -->|URL Scheme| D[协议拦截器]
    C -->|API注入| E[原生接口]
    D --> F[Native处理器]
    E --> F
    F --> G[能力模块]
    G --> H[设备API]
    G --> I[UI组件]
    G --> J[数据存储]
    F --> K[回调管理器]
    K --> B

3.3 消息队列与异步处理

原理说明： 由于某些Native操作是异步的（如网络请求、用户授权），JSBridge需要实现消息队列和回调管理机制。

// 增强版JSBridge with消息队列
class AdvancedJSBridge {
  constructor() {
    this.messageQueue = [];
    this.callbacks = new Map();
    this.callbackId = 0;
    this.isReady = false;
  }

  // 初始化完成标记
  ready() {
    this.isReady = true;
    this.flushMessageQueue();
  }

  // 调用Native方法
  invoke(module, method, params = {}) {
    return new Promise((resolve, reject) => {
      const callbackId = `${module}_${method}_${this.callbackId++}`;

      // 保存回调
      this.callbacks.set(callbackId, { resolve, reject });

      const message = {
        callbackId,
        module,
        method,
        params,
        timestamp: Date.now()
      };

      // 如果未就绪，加入队列
      if (!this.isReady) {
        this.messageQueue.push(message);
      } else {
        this.sendMessage(message);
      }

      // 超时处理
      setTimeout(() => {
        if (this.callbacks.has(callbackId)) {
          this.callbacks.get(callbackId).reject(new Error('Timeout'));
          this.callbacks.delete(callbackId);
        }
      }, 30000);
    });
  }

  // 发送消息到Native
  sendMessage(message) {
    const url = `jsbridge://dispatch?data=${encodeURIComponent(JSON.stringify(message))}`;

    const iframe = document.createElement('iframe');
    iframe.style.display = 'none';
    iframe.src = url;
    document.body.appendChild(iframe);
    setTimeout(() => document.body.removeChild(iframe), 100);
  }

  // 刷新消息队列
  flushMessageQueue() {
    while (this.messageQueue.length > 0) {
      const message = this.messageQueue.shift();
      this.sendMessage(message);
    }
  }

  // Native回调处理
  handleNativeResponse(callbackId, error, result) {
    const callback = this.callbacks.get(callbackId);
    if (callback) {
      error ? callback.reject(error) : callback.resolve(result);
      this.callbacks.delete(callbackId);
    }
  }
}

window.bridge = new AdvancedJSBridge();

使用示例：

// Promise风格的调用
async function getUserLocation() {
  try {
    const location = await window.bridge.invoke('Device', 'getLocation', {
      accuracy: 'high',
      timeout: 10000
    });

    console.log('当前位置:', location.latitude, location.longitude);
    return location;
  } catch (error) {
    console.error('获取位置失败:', error);
    return null;
  }
}

// 调用多个Native能力
Promise.all([
  window.bridge.invoke('Device', 'getDeviceInfo'),
  window.bridge.invoke('Storage', 'getItem', { key: 'userToken' }),
  window.bridge.invoke('Network', 'getNetworkType')
]).then(([deviceInfo, token, networkType]) => {
  console.log('设备信息:', deviceInfo);
  console.log('用户Token:', token);
  console.log('网络类型:', networkType);
});

---

四、主流JSBridge框架解析

4.1 WebViewJavascriptBridge

简介： WebViewJavascriptBridge是最早也是最成熟的开源JSBridge方案之一，支持iOS和Android双平台。

核心特性：

• 支持双向通信（JS ↔ Native）
• 消息队列机制
• 自动处理回调
• 支持同步/异步调用

使用示例：

// iOS端初始化
function setupWebViewJavascriptBridge(callback) {
  if (window.WebViewJavascriptBridge) {
    return callback(WebViewJavascriptBridge);
  }
  if (window.WVJBCallbacks) {
    return window.WVJBCallbacks.push(callback);
  }
  window.WVJBCallbacks = [callback];

  const WVJBIframe = document.createElement('iframe');
  WVJBIframe.style.display = 'none';
  WVJBIframe.src = 'https://__bridge_loaded__';
  document.documentElement.appendChild(WVJBIframe);
  setTimeout(() => document.documentElement.removeChild(WVJBIframe), 0);
}

// 调用Native方法
setupWebViewJavascriptBridge(function(bridge) {
  // 注册JS方法供Native调用
  bridge.registerHandler('getUserInfo', function(data, responseCallback) {
    const userInfo = { name: '张三', age: 25 };
    responseCallback(userInfo);
  });

  // 调用Native方法
  bridge.callHandler('scanQRCode', { needResult: true }, function(response) {
    console.log('扫码结果:', response);
  });
});

4.2 DSBridge

简介： DSBridge是由阿里巴巴开发的跨平台JSBridge方案，支持同步调用和进度回调。

核心优势：

• 支持同步返回（其他方案大多仅支持异步）
• 支持进度回调（适用于文件上传等场景）
• API简洁，学习成本低
• 性能优异

架构设计：

graph TB
    A[H5页面] --> B[dsBridge.call]
    B --> C{调用类型}
    C -->|同步| D[dsBridge.call]
    C -->|异步| E[dsBridge.call with callback]
    D --> F[Native同步方法]
    E --> G[Native异步方法]
    F --> H[返回结果]
    G --> I[回调返回]
    H --> A
    I --> A

JavaScript端使用：

// 同步调用
const deviceInfo = dsBridge.call('getDeviceInfo');
console.log('设备信息:', deviceInfo);

// 异步调用
dsBridge.call('getLocation', { accuracy: 'high' }, function(location) {
  console.log('位置:', location);
});

// 进度回调
dsBridge.call('uploadFile', {
  file: fileData,
  onProgress: function(progress) {
    console.log('上传进度:', progress + '%');
  }
}, function(result) {
  console.log('上传完成:', result);
});

// 注册方法供Native调用
dsBridge.register('updateUserStatus', function(status) {
  console.log('用户状态更新:', status);
  return { success: true };
});

Android端实现：

// Kotlin实现
class JsApi {
  // 同步方法
  @JavascriptInterface
  fun getDeviceInfo(): String {
    return JSONObject().apply {
      put("model", Build.MODEL)
      put("brand", Build.BRAND)
      put("version", Build.VERSION.RELEASE)
    }.toString()
  }

  // 异步方法
  @JavascriptInterface
  fun getLocation(params: String, callback: CompletionHandler<String>) {
    LocationManager.requestLocation { location ->
      callback.complete(JSONObject().apply {
        put("latitude", location.latitude)
        put("longitude", location.longitude)
      }.toString())
    }
  }
}

// 注册到WebView
dsBridge.addJavascriptObject(JsApi(), "api")

4.3 JsBridge（marcuswestin实现）

特点：

• 轻量级设计
• 基于URL Scheme
• 支持iOS和Android
• 广泛应用于中小型项目

消息传递流程：

sequenceDiagram
    participant JS as JavaScript
    participant Queue as 消息队列
    participant Native as Native层
    participant Handler as 消息处理器

    JS->>Queue: 添加消息到队列
    JS->>Native: 触发队列刷新信号
    Native->>Queue: 获取消息队列
    Queue->>Native: 返回消息列表
    Native->>Handler: 逐个处理消息
    Handler->>Handler: 执行原生方法
    Handler->>JS: 执行回调函数

完整实现示例：

// JavaScript端完整实现
(function() {
  const CUSTOM_PROTOCOL_SCHEME = 'jsbridge';
  const QUEUE_HAS_MESSAGE = '__QUEUE_MESSAGE__';

  const messagingIframe;
  const sendMessageQueue = [];
  const receiveMessageQueue = [];
  const messageHandlers = {};
  const responseCallbacks = {};
  let uniqueId = 1;

  // 创建隐藏iframe
  function _createQueueReadyIframe(doc) {
    messagingIframe = doc.createElement('iframe');
    messagingIframe.style.display = 'none';
    doc.documentElement.appendChild(messagingIframe);
  }

  // 初始化
  function init(messageHandler) {
    if (WebViewJavascriptBridge._messageHandler) {
      throw new Error('WebViewJavascriptBridge.init called twice');
    }
    WebViewJavascriptBridge._messageHandler = messageHandler;
    const receivedMessages = receiveMessageQueue;
    receiveMessageQueue = null;
    receivedMessages.forEach(message => {
      _dispatchMessageFromNative(message);
    });
  }

  // 发送消息
  function send(data, responseCallback) {
    _doSend({ data: data }, responseCallback);
  }

  // 调用Handler
  function callHandler(handlerName, data, responseCallback) {
    _doSend({
      handlerName: handlerName,
      data: data
    }, responseCallback);
  }

  // 注册Handler
  function registerHandler(handlerName, handler) {
    messageHandlers[handlerName] = handler;
  }

  // 内部发送实现
  function _doSend(message, responseCallback) {
    if (responseCallback) {
      const callbackId = 'cb_' + (uniqueId++) + '_' + new Date().getTime();
      responseCallbacks[callbackId] = responseCallback;
      message.callbackId = callbackId;
    }
    sendMessageQueue.push(message);
    messagingIframe.src = CUSTOM_PROTOCOL_SCHEME + '://' + QUEUE_HAS_MESSAGE;
  }

  // Native调用此方法获取消息
  function _fetchQueue() {
    const messageQueueString = JSON.stringify(sendMessageQueue);
    sendMessageQueue = [];
    return messageQueueString;
  }

  // 处理Native发来的消息
  function _dispatchMessageFromNative(messageJSON) {
    setTimeout(() => {
      const message = JSON.parse(messageJSON);

      if (message.responseId) {
        // 这是一个回调响应
        const responseCallback = responseCallbacks[message.responseId];
        responseCallback(message.responseData);
        delete responseCallbacks[message.responseId];
      } else {
        // 这是一个新消息
        const handler = messageHandlers[message.handlerName];
        if (!handler) {
          console.warn('No handler for message:', message);
          return;
        }

        handler(message.data, function(responseData) {
          if (message.callbackId) {
            _doSend({
              responseId: message.callbackId,
              responseData: responseData
            });
          }
        });
      }
    });
  }

  // 暴露API
  window.WebViewJavascriptBridge = {
    init: init,
    send: send,
    registerHandler: registerHandler,
    callHandler: callHandler,
    _fetchQueue: _fetchQueue,
    _handleMessageFromNative: _dispatchMessageFromNative
  };

  _createQueueReadyIframe(document);
})();

4.4 企业级JSBridge实践

微信JSSDK

功能模块：

• 基础接口（分享、扫一扫、图像接口等）
• 微信支付
• 设备信息
• 地理位置
• 界面操作

使用示例：

// 引入微信JS-SDK
wx.config({
  debug: false,
  appId: 'your_app_id',
  timestamp: 1234567890,
  nonceStr: 'random_string',
  signature: 'signature_string',
  jsApiList: ['scanQRCode', 'chooseImage', 'getLocation']
});

wx.ready(function() {
  // 调用扫一扫接口
  wx.scanQRCode({
    needResult: 1,
    scanType: ['qrCode', 'barCode'],
    success: function(res) {
      const result = res.resultStr;
      console.log('扫码结果:', result);
    }
  });

  // 获取地理位置
  wx.getLocation({
    type: 'gcj02',
    success: function(res) {
      const latitude = res.latitude;
      const longitude = res.longitude;
      console.log('当前位置:', latitude, longitude);
    }
  });
});

支付宝JSAPI

核心能力：

// 支付宝容器检测
if (window.AlipayJSBridge) {
  ready();
} else {
  document.addEventListener('AlipayJSBridgeReady', ready, false);
}

function ready() {
  // 调用支付接口
  AlipayJSBridge.call('tradePay', {
    orderStr: 'order_string_from_server'
  }, function(result) {
    if (result.resultCode === '9000') {
      console.log('支付成功');
    }
  });

  // 调用扫一扫
  AlipayJSBridge.call('scan', {
    type: 'qr'
  }, function(result) {
    console.log('扫码结果:', result.qrCode);
  });

  // 获取用户信息
  AlipayJSBridge.call('getAuthCode', {
    scopeNicks: ['auth_user']
  }, function(result) {
    console.log('授权码:', result.authCode);
  });
}

钉钉JSAPI

企业级功能：

dd.ready(function() {
  // 设置导航栏
  dd.biz.navigation.setTitle({
    title: '页面标题'
  });

  // 调用企业通讯录
  dd.biz.contact.choose({
    multiple: true,
    users: [],
    corpId: 'your_corp_id',
    onSuccess: function(result) {
      console.log('选择的用户:', result);
    }
  });

  // 图片预览
  dd.biz.util.previewImage({
    urls: ['image1.jpg', 'image2.jpg'],
    current: 'image1.jpg',
    onSuccess: function() {
      console.log('预览成功');
    }
  });
});

---

五、实战案例与性能优化

5.1 电商应用完整实战

场景描述： 构建一个Hybrid电商应用，需要实现商品浏览、购物车、支付、分享等功能。

架构设计：

graph TB
    subgraph H5层
        A1[商品列表页]
        A2[商品详情页]
        A3[购物车页]
        A4[订单页]
    end

    subgraph JSBridge层
        B1[商品模块]
        B2[支付模块]
        B3[分享模块]
        B4[存储模块]
    end

    subgraph Native层
        C1[网络请求]
        C2[本地存储]
        C3[第三方SDK]
        C4[相机/相册]
    end

    A1 --> B1
    A2 --> B2
    A2 --> B3
    A3 --> B4
    A4 --> B2

    B1 --> C1
    B2 --> C3
    B3 --> C3
    B4 --> C2

完整实现代码：

// 电商JSBridge SDK
class EcommerceBridge {
  constructor() {
    this.bridge = window.bridge || window.WebViewJavascriptBridge;
    this.init();
  }

  init() {
    this.setupHandlers();
  }

  // 注册Native调用的方法
  setupHandlers() {
    this.bridge.registerHandler('onPaymentSuccess', (data) => {
      this.handlePaymentSuccess(data);
    });

    this.bridge.registerHandler('onShareComplete', (data) => {
      this.handleShareComplete(data);
    });
  }

  // 商品模块
  async getProductList(params) {
    try {
      const result = await this.bridge.invoke('Product', 'getList', params);
      return result.products;
    } catch (error) {
      console.error('获取商品列表失败:', error);
      return [];
    }
  }

  async getProductDetail(productId) {
    return await this.bridge.invoke('Product', 'getDetail', { productId });
  }

  // 购物车模块
  async addToCart(product, quantity) {
    const cartItem = {
      productId: product.id,
      name: product.name,
      price: product.price,
      quantity: quantity,
      image: product.image
    };

    const result = await this.bridge.invoke('Cart', 'add', cartItem);

    if (result.success) {
      this.showToast('已添加到购物车');
      this.updateCartBadge();
    }

    return result;
  }

  async getCartItems() {
    return await this.bridge.invoke('Cart', 'getItems');
  }

  async updateCartItemQuantity(itemId, quantity) {
    return await this.bridge.invoke('Cart', 'updateQuantity', {
      itemId,
      quantity
    });
  }

  async removeCartItem(itemId) {
    return await this.bridge.invoke('Cart', 'remove', { itemId });
  }

  // 支付模块
  async createOrder(items, addressId) {
    const orderData = {
      items: items,
      addressId: addressId,
      totalAmount: items.reduce((sum, item) => sum + item.price * item.quantity, 0)
    };

    return await this.bridge.invoke('Order', 'create', orderData);
  }

  async pay(orderId, paymentMethod) {
    const payParams = {
      orderId: orderId,
      method: paymentMethod, // 'alipay', 'wechat', 'apple_pay'
      timestamp: Date.now()
    };

    try {
      const result = await this.bridge.invoke('Payment', 'pay', payParams);
      return result;
    } catch (error) {
      if (error.code === 'USER_CANCEL') {
        this.showToast('支付已取消');
      } else if (error.code === 'PAYMENT_FAILED') {
        this.showToast('支付失败，请重试');
      }
      throw error;
    }
  }

  handlePaymentSuccess(data) {
    console.log('支付成功:', data);
    // 跳转到订单详情页
    this.navigateToOrderDetail(data.orderId);
    // 清空购物车
    this.clearCart();
  }

  // 分享模块
  async shareProduct(product) {
    const shareData = {
      title: product.name,
      description: product.description,
      image: product.image,
      url: `https://example.com/product/${product.id}`,
      platforms: ['wechat', 'moments', 'weibo', 'qq']
    };

    try {
      const result = await this.bridge.invoke('Share', 'show', shareData);
      return result;
    } catch (error) {
      console.error('分享失败:', error);
    }
  }

  handleShareComplete(data) {
    if (data.success) {
      this.showToast(`已分享到${data.platform}`);
      // 分享成功奖励
      this.rewardSharePoints();
    }
  }

  // 图片上传（用户评价）
  async uploadReviewImages() {
    // 调用原生相册选择
    const images = await this.bridge.invoke('Media', 'chooseImages', {
      count: 9,
      sourceType: ['album', 'camera']
    });

    // 上传图片
    const uploadPromises = images.map(image =>
      this.bridge.invoke('Upload', 'image', {
        file: image,
        onProgress: (progress) => {
          console.log(`上传进度: ${progress}%`);
        }
      })
    );

    const uploadedUrls = await Promise.all(uploadPromises);
    return uploadedUrls;
  }

  // 地址选择
  async selectAddress() {
    const location = await this.bridge.invoke('Map', 'selectLocation', {
      latitude: 0,
      longitude: 0
    });

    return {
      address: location.address,
      latitude: location.latitude,
      longitude: location.longitude
    };
  }

  // UI工具方法
  showToast(message) {
    this.bridge.invoke('UI', 'showToast', { message });
  }

  showLoading(text = '加载中...') {
    this.bridge.invoke('UI', 'showLoading', { text });
  }

  hideLoading() {
    this.bridge.invoke('UI', 'hideLoading');
  }

  updateCartBadge() {
    this.getCartItems().then(items => {
      const count = items.reduce((sum, item) => sum + item.quantity, 0);
      this.bridge.invoke('UI', 'setBadge', { count });
    });
  }

  // 导航方法
  navigateToOrderDetail(orderId) {
    this.bridge.invoke('Navigation', 'push', {
      url: `/order/detail?id=${orderId}`
    });
  }

  async clearCart() {
    await this.bridge.invoke('Cart', 'clear');
    this.updateCartBadge();
  }

  async rewardSharePoints() {
    await this.bridge.invoke('User', 'addPoints', {
      points: 10,
      reason: 'share_product'
    });
    this.showToast('分享成功，获得10积分');
  }
}

// 全局实例
window.EcommerceBridge = new EcommerceBridge();

// 使用示例
async function handleBuyNow(product) {
  const bridge = window.EcommerceBridge;

  // 显示加载
  bridge.showLoading('处理中...');

  try {
    // 添加到购物车
    await bridge.addToCart(product, 1);

    // 获取购物车项
    const cartItems = await bridge.getCartItems();

    // 创建订单
    const order = await bridge.createOrder(cartItems, selectedAddressId);

    // 发起支付
    const paymentResult = await bridge.pay(order.id, 'wechat');

    if (paymentResult.success) {
      console.log('购买成功');
    }
  } catch (error) {
    console.error('购买失败:', error);
    bridge.showToast('购买失败，请重试');
  } finally {
    bridge.hideLoading();
  }
}

5.2 URL长度限制处理

问题描述： URL Scheme方式传递参数时，URL长度有限制（iOS约2MB，Android约2-10KB），大数据传输可能失败。

解决方案：

// 数据分片传输
class ChunkedBridge {
  constructor(maxChunkSize = 2048) {
    this.maxChunkSize = maxChunkSize;
    this.chunks = new Map();
  }

  // 发送大数据
  sendLargeData(method, data) {
    const dataString = JSON.stringify(data);

    if (dataString.length <= this.maxChunkSize) {
      // 数据量小，直接发送
      return this.send(method, data);
    }

    // 数据量大，分片发送
    const chunkId = this.generateChunkId();
    const chunks = this.splitIntoChunks(dataString);

    return new Promise((resolve, reject) => {
      // 先告知Native准备接收分片数据
      this.send('prepareChunks', {
        chunkId: chunkId,
        totalChunks: chunks.length,
        method: method
      }).then(() => {
        // 逐个发送分片
        const promises = chunks.map((chunk, index) =>
          this.send('sendChunk', {
            chunkId: chunkId,
            index: index,
            data: chunk,
            isLast: index === chunks.length - 1
          })
        );

        Promise.all(promises)
          .then(() => {
            // 通知Native合并分片
            return this.send('mergeChunks', { chunkId: chunkId });
          })
          .then(resolve)
          .catch(reject);
      });
    });
  }

  splitIntoChunks(data) {
    const chunks = [];
    for (let i = 0; i < data.length; i += this.maxChunkSize) {
      chunks.push(data.substring(i, i + this.maxChunkSize));
    }
    return chunks;
  }

  generateChunkId() {
    return `chunk_${Date.now()}_${Math.random().toString(36).substring(2)}`;
  }

  send(method, params) {
    // 调用底层Bridge
    return window.bridge.invoke('System', method, params);
  }
}

// 使用示例
const chunkedBridge = new ChunkedBridge();

// 发送大图片数据
chunkedBridge.sendLargeData('uploadImage', {
  image: largeBase64Image,
  fileName: 'photo.jpg'
}).then(result => {
  console.log('上传成功:', result);
});

5.3 性能优化深度实践

通信频率控制

// 节流优化：限制高频调用
class ThrottledBridge {
  constructor(bridge, interval = 100) {
    this.bridge = bridge;
    this.interval = interval;
    this.timers = new Map();
  }

  invoke(module, method, params) {
    const key = `${module}.${method}`;

    // 清除之前的定时器
    if (this.timers.has(key)) {
      clearTimeout(this.timers.get(key));
    }

    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => {
        this.bridge.invoke(module, method, params)
          .then(resolve)
          .catch(reject)
          .finally(() => this.timers.delete(key));
      }, this.interval);

      this.timers.set(key, timer);
    });
  }
}

// 防抖优化：合并连续调用
class DebouncedBridge {
  constructor(bridge, delay = 300) {
    this.bridge = bridge;
    this.delay = delay;
    this.pending = new Map();
  }

  invoke(module, method, params) {
    const key = `${module}.${method}`;

    return new Promise((resolve, reject) => {
      // 取消之前的调用
      if (this.pending.has(key)) {
        const { timer, reject: prevReject } = this.pending.get(key);
        clearTimeout(timer);
        prevReject(new Error('Cancelled by newer call'));
      }

      const timer = setTimeout(() => {
        this.bridge.invoke(module, method, params)
          .then(resolve)
          .catch(reject)
          .finally(() => this.pending.delete(key));
      }, this.delay);

      this.pending.set(key, { timer, reject });
    });
  }
}

// 使用示例：搜索建议
const debouncedBridge = new DebouncedBridge(window.bridge, 300);

function onSearchInput(keyword) {
  debouncedBridge.invoke('Search', 'getSuggestions', { keyword })
    .then(suggestions => {
      displaySuggestions(suggestions);
    })
    .catch(error => {
      if (error.message !== 'Cancelled by newer call') {
        console.error(error);
      }
    });
}

数据压缩传输

// 使用LZ-String进行数据压缩
class CompressedBridge {
  constructor(bridge) {
    this.bridge = bridge;
  }

  async invoke(module, method, params) {
    // 序列化参数
    const paramsString = JSON.stringify(params);

    // 如果数据超过阈值，进行压缩
    if (paramsString.length > 1024) {
      const compressed = LZString.compressToBase64(paramsString);

      // 发送压缩标记
      const result = await this.bridge.invoke(module, method, {
        _compressed: true,
        _data: compressed
      });

      // 解压返回结果
      if (result._compressed) {
        const decompressed = LZString.decompressFromBase64(result._data);
        return JSON.parse(decompressed);
      }

      return result;
    }

    // 数据量小，直接发送
    return await this.bridge.invoke(module, method, params);
  }
}

请求缓存优化

// 带缓存的Bridge
class CachedBridge {
  constructor(bridge, cacheDuration = 60000) {
    this.bridge = bridge;
    this.cacheDuration = cacheDuration;
    this.cache = new Map();
  }

  invoke(module, method, params, options = {}) {
    const { useCache = true, cacheKey } = options;

    if (!useCache) {
      return this.bridge.invoke(module, method, params);
    }

    const key = cacheKey || this.generateCacheKey(module, method, params);
    const cached = this.cache.get(key);

    // 检查缓存
    if (cached && Date.now() - cached.timestamp < this.cacheDuration) {
      console.log('使用缓存:', key);
      return Promise.resolve(cached.data);
    }

    // 发起请求
    return this.bridge.invoke(module, method, params).then(result => {
      // 存入缓存
      this.cache.set(key, {
        data: result,
        timestamp: Date.now()
      });
      return result;
    });
  }

  generateCacheKey(module, method, params) {
    return `${module}.${method}:${JSON.stringify(params)}`;
  }

  clearCache(pattern) {
    if (pattern) {
      // 清除匹配的缓存
      for (const key of this.cache.keys()) {
        if (key.includes(pattern)) {
          this.cache.delete(key);
        }
      }
    } else {
      // 清除所有缓存
      this.cache.clear();
    }
  }
}

// 使用示例
const cachedBridge = new CachedBridge(window.bridge, 300000); // 5分钟缓存

// 第一次调用，从Native获取
await cachedBridge.invoke('User', 'getProfile', { userId: 123 });

// 第二次调用，使用缓存
await cachedBridge.invoke('User', 'getProfile', { userId: 123 });

// 用户信息更新后，清除缓存
cachedBridge.clearCache('User.getProfile');

---

六、安全性与最佳实践

6.1 安全风险

主要安全威胁：

1. XSS攻击：恶意脚本通过JSBridge调用敏感Native方法
2. 中间人攻击：HTTP页面中的JSBridge调用可能被劫持
3. API注入漏洞：Android 4.2以下版本的addJavascriptInterface存在远程代码执行漏洞

6.2 安全加固方案

// 安全增强的JSBridge实现
class SecureJSBridge {
  constructor(config = {}) {
    this.whitelist = config.whitelist || []; // 白名单域名
    this.secretKey = config.secretKey; // 签名密钥
    this.callbacks = new Map();
  }

  // 验证调用来源
  validateOrigin() {
    const origin = window.location.origin;
    const isHTTPS = window.location.protocol === 'https:';
    const inWhitelist = this.whitelist.some(domain => origin.includes(domain));

    if (!isHTTPS || !inWhitelist) {
      throw new Error('Security: Invalid origin');
    }
  }

  // 生成签名
  generateSignature(data) {
    const payload = JSON.stringify(data) + this.secretKey + Date.now();
    // 实际应使用加密库，此处简化
    return btoa(payload).substring(0, 32);
  }

  // 安全调用
  secureInvoke(module, method, params) {
    this.validateOrigin();

    const timestamp = Date.now();
    const requestData = { module, method, params, timestamp };
    const signature = this.generateSignature(requestData);

    return this.invoke({
      ...requestData,
      signature
    });
  }

  // 参数校验与过滤
  sanitizeParams(params) {
    // 移除危险字段
    const dangerousKeys = ['__proto__', 'constructor', 'prototype'];
    const cleaned = { ...params };

    dangerousKeys.forEach(key => delete cleaned[key]);

    // 递归清理对象
    Object.keys(cleaned).forEach(key => {
      if (typeof cleaned[key] === 'object' && cleaned[key] !== null) {
        cleaned[key] = this.sanitizeParams(cleaned[key]);
      }
    });

    return cleaned;
  }

  invoke(data) {
    const cleanedParams = this.sanitizeParams(data.params);
    // 调用底层通信...
  }
}

6.3 最佳实践建议

开发规范：

// 1. 统一错误处理
window.bridge.invoke('Payment', 'pay', payParams)
  .then(result => {
    // 成功处理
  })
  .catch(error => {
    // 统一错误码处理
    switch(error.code) {
      case 'USER_CANCEL':
        showToast('用户取消支付');
        break;
      case 'NETWORK_ERROR':
        showToast('网络异常，请重试');
        break;
      default:
        reportError(error); // 上报未知错误
    }
  });

// 2. 版本兼容性处理
function invokeWithFallback(module, method, params) {
  if (window.bridge && window.bridge.invoke) {
    return window.bridge.invoke(module, method, params);
  } else if (window.NativeAPI && window.NativeAPI[method]) {
    // 降级到注入API
    return Promise.resolve(window.NativeAPI[method](params));
  } else {
    // H5降级方案
    return Promise.reject(new Error('Bridge not available'));
  }
}

// 3. 性能监控
function monitoredInvoke(module, method, params) {
  const startTime = performance.now();

  return window.bridge.invoke(module, method, params)
    .finally(() => {
      const duration = performance.now() - startTime;
      // 上报性能数据
      reportPerformance({
        module,
        method,
        duration,
        timestamp: Date.now()
      });
    });
}

---

七、跨端技术对比与选型

7.1 Hybrid与其他跨端方案对比

技术方案对比：

graph TB
    A[跨端技术选型] --> B[Hybrid方案]
    A --> C[React Native]
    A --> D[Flutter]
    A --> E[小程序]

    B --> B1[技术栈: HTML/CSS/JS]
    B --> B2[性能: ⭐⭐⭐]
    B --> B3[开发效率: ⭐⭐⭐⭐⭐]
    B --> B4[用户体验: ⭐⭐⭐]

    C --> C1[技术栈: React + Native]
    C --> C2[性能: ⭐⭐⭐⭐]
    C --> C3[开发效率: ⭐⭐⭐⭐]
    C --> C4[用户体验: ⭐⭐⭐⭐]

    D --> D1[技术栈: Dart]
    D --> D2[性能: ⭐⭐⭐⭐⭐]
    D --> D3[开发效率: ⭐⭐⭐]
    D --> D4[用户体验: ⭐⭐⭐⭐⭐]

    E --> E1[技术栈: 小程序DSL]
    E --> E2[性能: ⭐⭐⭐⭐]
    E --> E3[开发效率: ⭐⭐⭐⭐]
    E --> E4[用户体验: ⭐⭐⭐⭐]

详细对比表：

对比维度	Hybrid (JSBridge)	React Native	Flutter	小程序
渲染方式	WebView渲染	原生组件渲染	自绘引擎	双线程渲染
启动速度	较慢（WebView加载）	中等	快	快
运行性能	一般	良好	优秀	良好
包大小	小（Web资源）	中等	较大（引擎）	小
热更新	支持（Web资源）	支持（CodePush）	有限支持	平台控制
开发成本	低（Web技术栈）	中等	中等	低
生态成熟度	成熟	成熟	快速发展	生态受限
调试体验	优秀（Chrome DevTools）	良好	良好	一般
学习曲线	平缓	中等	陡峭	平缓

7.2 什么场景适合使用JSBridge

适合场景：

• 内容型应用（新闻、资讯、社区）
• 快速迭代的营销活动页面
• 对性能要求不高的业务模块
• 需要频繁热更新的功能
• 已有Web端产品，希望快速迁移到移动端

不适合场景：

• 游戏类应用
• 对动画性能要求极高的应用
• 复杂的原生交互（如相机实时滤镜）
• 需要极致用户体验的核心功能

7.3 Hybrid应用的演进路径

graph LR
    A[纯Web H5] --> B[基础Hybrid]
    B --> C[离线包Hybrid]
    C --> D[预渲染Hybrid]
    D --> E[同层渲染]

    A -->|问题: 依赖网络| B
    B -->|问题: 加载慢| C
    C -->|问题: 白屏| D
    D -->|问题: 体验差| E

各阶段特点：

// 1. 纯Web H5
// 所有资源从服务器加载，依赖网络
<script src="https://example.com/app.js"></script>

// 2. 基础Hybrid + JSBridge
// 可以调用Native能力，但资源仍需网络加载
window.bridge.invoke('Device', 'getInfo');

// 3. 离线包Hybrid
// 预下载资源到本地，大幅提升加载速度
const offlineUrl = 'file:///data/app/offline/index.html';
webView.loadUrl(offlineUrl);

// 4. 预渲染Hybrid
// Native端预创建WebView，减少白屏时间
class WebViewPool {
  constructor() {
    this.pool = [];
    this.preCreate(3); // 预创建3个WebView
  }

  preCreate(count) {
    for (let i = 0; i < count; i++) {
      const webView = createWebView();
      this.pool.push(webView);
    }
  }

  getWebView() {
    if (this.pool.length > 0) {
      return this.pool.pop();
    }
    return createWebView();
  }
}

// 5. 同层渲染
// 原生组件和H5内容同层渲染，体验接近原生
<video id="myVideo"
       src="video.mp4"
       x5-video-player-type="h5-page"></video>

---

八、现代JSBridge的演进

8.1 基于RPC的现代架构

Shopify的Mobile Bridge方案： 基于@remote-ui/rpc库实现，将WebView加载时间从6秒优化到1.4秒（P75指标提升约6倍）。

graph LR
    A[Web组件] --> B[RPC客户端]
    B --> C[消息通道]
    C --> D[RPC服务端]
    D --> E[Native模块]
    E --> F[设备能力]

    style C fill:#f9f,stroke:#333

核心特性：

• 异步函数调用支持
• 结构化数据交换
• 自动序列化/反序列化
• TypeScript类型安全

8.2 Capacitor的Native Bridge

架构组件：

// Capacitor插件定义示例
import { registerPlugin } from '@capacitor/core';

export interface CameraPlugin {
  getPhoto(options: CameraOptions): Promise<Photo>;
}

const Camera = registerPlugin<CameraPlugin>('Camera', {
  web: () => import('./web').then(m => new m.CameraWeb()),
});

// 使用
const photo = await Camera.getPhoto({
  quality: 90,
  allowEditing: true,
  resultType: CameraResultType.Uri
});

优势：

• 跨平台统一API
• Web端自动降级
• 插件生态丰富
• 强类型支持

8.3 性能优化策略

// 批量调用优化
class BatchedBridge {
  constructor() {
    this.queue = [];
    this.timer = null;
  }

  // 批量发送
  batchInvoke(module, method, params) {
    return new Promise((resolve, reject) => {
      this.queue.push({ module, method, params, resolve, reject });

      // 防抖：50ms内的调用合并
      clearTimeout(this.timer);
      this.timer = setTimeout(() => this.flush(), 50);
    });
  }

  flush() {
    if (this.queue.length === 0) return;

    const batch = this.queue.splice(0, this.queue.length);

    // 一次性发送所有请求
    const batchData = batch.map((item, index) => ({
      id: index,
      module: item.module,
      method: item.method,
      params: item.params
    }));

    this.sendBatch(batchData).then(results => {
      results.forEach((result, index) => {
        const item = batch[index];
        result.error ? item.reject(result.error) : item.resolve(result.data);
      });
    });
  }

  sendBatch(data) {
    // 发送批量请求到Native
    return window.bridge.invoke('System', 'batchExecute', { batch: data });
  }
}

---

九、高级话题与未来展望

9.1 离线包与预加载机制

离线包原理：

sequenceDiagram
    participant Server as 离线包服务器
    participant App as Native App
    participant Local as 本地存储
    participant WebView as WebView

    Server->>App: 1. 推送离线包更新
    App->>Server: 2. 下载离线包
    Server->>App: 3. 返回ZIP包
    App->>Local: 4. 解压并存储
    App->>WebView: 5. 加载本地资源
    WebView->>Local: 6. 读取HTML/JS/CSS
    Local->>WebView: 7. 返回资源内容

完整实现示例：

// 离线包管理器
class OfflinePackageManager {
  constructor() {
    this.baseDir = '/data/app/offline/';
    this.packages = new Map();
    this.init();
  }

  async init() {
    // 加载已安装的离线包信息
    const installed = await this.getInstalledPackages();
    installed.forEach(pkg => {
      this.packages.set(pkg.id, pkg);
    });

    // 检查更新
    this.checkUpdate();
  }

  // 检查离线包更新
  async checkUpdate() {
    try {
      const response = await window.bridge.invoke('Network', 'request', {
        url: 'https://api.example.com/offline-packages/check',
        method: 'GET'
      });

      const { packages } = response;

      for (const pkg of packages) {
        const installed = this.packages.get(pkg.id);

        if (!installed || installed.version < pkg.version) {
          // 需要更新
          await this.downloadAndInstall(pkg);
        }
      }
    } catch (error) {
      console.error('检查更新失败:', error);
    }
  }

  // 下载并安装离线包
  async downloadAndInstall(pkgInfo) {
    try {
      console.log(`开始下载离线包: ${pkgInfo.name} v${pkgInfo.version}`);

      // 下载ZIP文件
      const zipPath = await window.bridge.invoke('Download', 'file', {
        url: pkgInfo.downloadUrl,
        onProgress: (progress) => {
          console.log(`下载进度: ${progress}%`);
        }
      });

      // 解压到指定目录
      const targetDir = `${this.baseDir}${pkgInfo.id}/`;
      await window.bridge.invoke('FileSystem', 'unzip', {
        zipPath: zipPath,
        targetDir: targetDir
      });

      // 更新包信息
      this.packages.set(pkgInfo.id, {
        id: pkgInfo.id,
        name: pkgInfo.name,
        version: pkgInfo.version,
        path: targetDir,
        installedAt: Date.now()
      });

      // 保存到本地数据库
      await this.savePackageInfo(pkgInfo);

      console.log(`离线包安装成功: ${pkgInfo.name}`);
    } catch (error) {
      console.error('下载安装失败:', error);
    }
  }

  // 获取离线包URL
  getPackageUrl(packageId, pagePath) {
    const pkg = this.packages.get(packageId);

    if (!pkg) {
      // 降级到线上版本
      return `https://h5.example.com/${packageId}/${pagePath}`;
    }

    return `file://${pkg.path}${pagePath}`;
  }

  // 预加载关键资源
  async preloadResources(packageId) {
    const pkg = this.packages.get(packageId);
    if (!pkg) return;

    const manifest = await this.loadManifest(pkg.path);

    // 预加载关键JS/CSS
    const promises = manifest.preload.map(resource =>
      window.bridge.invoke('WebView', 'preloadResource', {
        url: `file://${pkg.path}${resource}`
      })
    );

    await Promise.all(promises);
    console.log(`预加载完成: ${packageId}`);
  }

  async loadManifest(pkgPath) {
    const manifestPath = `${pkgPath}manifest.json`;
    const content = await window.bridge.invoke('FileSystem', 'readFile', {
      path: manifestPath
    });
    return JSON.parse(content);
  }

  async getInstalledPackages() {
    return await window.bridge.invoke('Storage', 'get', {
      key: 'offline_packages'
    }) || [];
  }

  async savePackageInfo(pkgInfo) {
    const packages = await this.getInstalledPackages();
    const index = packages.findIndex(p => p.id === pkgInfo.id);

    if (index >= 0) {
      packages[index] = pkgInfo;
    } else {
      packages.push(pkgInfo);
    }

    await window.bridge.invoke('Storage', 'set', {
      key: 'offline_packages',
      value: packages
    });
  }
}

// 使用示例
const offlineManager = new OfflinePackageManager();

// 打开页面时使用离线包
function openPage(packageId, pagePath) {
  const url = offlineManager.getPackageUrl(packageId, pagePath);
  window.bridge.invoke('Navigation', 'push', { url });
}

9.2 双向事件总线

实现原理：

// 事件总线实现
class BridgeEventBus {
  constructor(bridge) {
    this.bridge = bridge;
    this.listeners = new Map();
    this.setupNativeListener();
  }

  // 监听事件
  on(eventName, handler) {
    if (!this.listeners.has(eventName)) {
      this.listeners.set(eventName, []);
    }
    this.listeners.get(eventName).push(handler);

    return () => this.off(eventName, handler);
  }

  // 取消监听
  off(eventName, handler) {
    const handlers = this.listeners.get(eventName);
    if (!handlers) return;

    const index = handlers.indexOf(handler);
    if (index > -1) {
      handlers.splice(index, 1);
    }
  }

  // 触发事件（发送给Native）
  async emit(eventName, data) {
    try {
      await this.bridge.invoke('Event', 'emit', {
        eventName,
        data,
        timestamp: Date.now()
      });
    } catch (error) {
      console.error(`事件发送失败: ${eventName}`, error);
    }
  }

  // 接收Native事件
  handleNativeEvent(eventName, data) {
    const handlers = this.listeners.get(eventName);
    if (!handlers) return;

    handlers.forEach(handler => {
      try {
        handler(data);
      } catch (error) {
        console.error(`事件处理失败: ${eventName}`, error);
      }
    });
  }

  // 设置Native事件监听
  setupNativeListener() {
    this.bridge.registerHandler('onNativeEvent', (data) => {
      this.handleNativeEvent(data.eventName, data.data);
    });
  }
}

// 使用示例
const eventBus = new BridgeEventBus(window.bridge);

// 监听用户登录事件
eventBus.on('user:login', (userInfo) => {
  console.log('用户登录:', userInfo);
  updateUI(userInfo);
});

// 监听网络状态变化
eventBus.on('network:change', (status) => {
  console.log('网络状态:', status);
  if (status === 'offline') {
    showOfflineNotice();
  }
});

// 触发自定义事件
eventBus.emit('page:view', {
  pageId: 'product_detail',
  productId: 12345
});

9.3 WebAssembly与JSBridge结合

应用场景：

• 复杂计算密集型任务（图像处理、加密解密）
• 需要高性能的算法实现
• 跨平台代码复用

实现示例：

// 加载WebAssembly模块
class WasmBridge {
  constructor(bridge) {
    this.bridge = bridge;
    this.wasmModule = null;
  }

  async loadModule(moduleName) {
    try {
      // 从Native获取WASM文件
      const wasmBuffer = await this.bridge.invoke('FileSystem', 'readWasm', {
        moduleName: moduleName
      });

      // 实例化WASM模块
      const module = await WebAssembly.instantiate(wasmBuffer, {
        env: {
          // 提供给WASM的导入函数
          callNative: (funcId, paramsPtr, paramsLen) => {
            return this.callNativeFromWasm(funcId, paramsPtr, paramsLen);
          }
        }
      });

      this.wasmModule = module.instance;
      return this.wasmModule;
    } catch (error) {
      console.error('加载WASM模块失败:', error);
      throw error;
    }
  }

  // WASM调用Native
  async callNativeFromWasm(funcId, paramsPtr, paramsLen) {
    // 从WASM内存读取参数
    const memory = new Uint8Array(this.wasmModule.exports.memory.buffer);
    const paramsBytes = memory.slice(paramsPtr, paramsPtr + paramsLen);
    const params = JSON.parse(new TextDecoder().decode(paramsBytes));

    // 调用Native方法
    const result = await this.bridge.invoke('Wasm', 'call', {
      funcId,
      params
    });

    return result;
  }

  // 调用WASM函数
  call(funcName, ...args) {
    if (!this.wasmModule) {
      throw new Error('WASM module not loaded');
    }

    const func = this.wasmModule.exports[funcName];
    if (!func) {
      throw new Error(`Function ${funcName} not found in WASM module`);
    }

    return func(...args);
  }
}

// 使用示例：图像处理
async function processImage(imageData) {
  const wasmBridge = new WasmBridge(window.bridge);

  // 加载图像处理WASM模块
  await wasmBridge.loadModule('image-processor');

  // 调用WASM函数处理图像
  const processedData = wasmBridge.call('applyFilter', imageData, 'blur');

  return processedData;
}

---

十、调试与问题排查

10.1 调试工具

Chrome DevTools远程调试：

// Android启用调试
WebView.setWebContentsDebuggingEnabled(true);

// H5端添加日志
window.bridgeLogger = {
  log: (type, data) => {
    console.log(`[Bridge ${type}]`, data);
    // 同步发送到Native
    window.bridge?.invoke('Debug', 'log', { type, data });
  }
};

10.2 常见问题

问题流程图：

flowchart TD
    A[JSBridge调用失败] --> B{检查Bridge是否初始化}
    B -->|未初始化| C[等待ready事件]
    B -->|已初始化| D{检查协议是否正确}
    D -->|协议错误| E[修正URL Scheme]
    D -->|协议正确| F{检查参数格式}
    F -->|格式错误| G[JSON序列化验证]
    F -->|格式正确| H{检查Native方法}
    H -->|方法不存在| I[更新Native代码]
    H -->|方法存在| J[检查回调ID]
    J --> K[调试Native端]

解决方案示例：

// 健壮的Bridge初始化检测
function waitForBridge(timeout = 5000) {
  return new Promise((resolve, reject) => {
    if (window.bridge && window.bridge.isReady) {
      resolve(window.bridge);
      return;
    }

    let timeoutId;
    const checkInterval = setInterval(() => {
      if (window.bridge && window.bridge.isReady) {
        clearInterval(checkInterval);
        clearTimeout(timeoutId);
        resolve(window.bridge);
      }
    }, 100);

    timeoutId = setTimeout(() => {
      clearInterval(checkInterval);
      reject(new Error('Bridge initialization timeout'));
    }, timeout);
  });
}

// 使用
waitForBridge()
  .then(bridge => {
    return bridge.invoke('Device', 'getInfo');
  })
  .then(info => {
    console.log('设备信息:', info);
  })
  .catch(error => {
    console.error('Bridge不可用:', error);
    // 降级到H5方案
    useH5Fallback();
  });

---

十一、总结与展望

11.1 核心要点

JSBridge作为Hybrid应用的核心技术，其本质是建立JavaScript与Native之间的通信管道。主要实现方式包括：

• URL Scheme拦截：兼容性好，适用于大多数场景
• API注入：性能优异，但需注意安全性
• 现代RPC方案：类型安全、性能更优，代表未来趋势

11.2 技术趋势

timeline
    title JSBridge技术演进时间线
    2010-2015 : URL Scheme拦截
              : JavascriptInterface
    2015-2018 : WKWebView
              : 消息队列优化
    2018-2022 : 开源框架兴起
              : Capacitor/Ionic
    2022-2025 : RPC架构
              : TypeScript支持
              : 性能极致优化

随着Web技术的发展（WebAssembly、Progressive Web Apps）和Native能力的增强（Android WebView、iOS WKWebView），JSBridge将朝着更高性能、更强类型安全、更好开发体验的方向演进。

11.3 未来发展方向

技术演进预测：

// 1. 基于TypeScript的类型安全JSBridge
interface BridgeAPI {
  Device: {
    getInfo(): Promise<DeviceInfo>;
    getLocation(options: LocationOptions): Promise<Location>;
  };
  Payment: {
    pay(params: PaymentParams): Promise<PaymentResult>;
  };
}

// 编译时类型检查
const bridge: BridgeAPI = window.bridge;
const deviceInfo = await bridge.Device.getInfo(); // 类型安全

// 2. 基于Proxy的自动桥接
const autoBridge = new Proxy({}, {
  get(target, moduleName) {
    return new Proxy({}, {
      get(target, methodName) {
        return (...args) => {
          return window.bridge.invoke(moduleName, methodName, ...args);
        };
      }
    });
  }
});

// 无需手动注册，自动调用
await autoBridge.Device.getInfo();
await autoBridge.Payment.pay({ amount: 100 });

// 3. 基于WebCodecs的高性能媒体处理
async function processVideoWithBridge(videoStream) {
  const decoder = new VideoDecoder({
    output: async (frame) => {
      // 发送给Native处理
      const processedFrame = await window.bridge.invoke('Video', 'processFrame', {
        data: frame
      });
      encoder.encode(processedFrame);
    },
    error: (e) => console.error(e)
  });

  // 与Native深度集成的媒体处理pipeline
}

新兴技术融合：

• WebGPU + JSBridge：在WebView中进行GPU加速计算
• Service Worker + JSBridge：离线优先的Hybrid应用
• WebRTC + JSBridge：实时音视频通信能力
• WebXR + JSBridge：AR/VR混合现实应用

性能优化趋势：

graph LR
    A[当前JSBridge性能] --> B[序列化优化]
    B --> C[SharedArrayBuffer]
    C --> D[零拷贝传输]
    D --> E[GPU直通]

    style E fill:#90EE90,stroke:#333

11.4 最佳实践总结

架构设计原则：

1. 模块化设计：按功能模块划分Bridge API
2. 统一错误处理：标准化错误码和错误信息
3. 版本管理：支持API版本兼容和平滑升级
4. 性能监控：建立完善的性能追踪体系
5. 安全优先：从源头防范安全风险

开发效率提升：

// 使用代码生成工具自动生成Bridge代码
// bridge.config.js
module.exports = {
  modules: {
    Device: {
      methods: ['getInfo', 'getLocation', 'getBattery']
    },
    Payment: {
      methods: ['pay', 'refund']
    }
  }
};

// 自动生成类型定义和调用代码
// npm run generate-bridge

// 生成的代码（示例）
class DeviceModule {
  constructor(bridge) {
    this.bridge = bridge;
  }

  async getInfo() {
    return await this.bridge.invoke('Device', 'getInfo');
  }

  async getLocation(options) {
    return await this.bridge.invoke('Device', 'getLocation', options);
  }
}

---

参考资料

本文在撰写过程中参考了以下技术资源和最新文档（截至2025年）：

• Shopify Engineering - Mobile Bridge: Making WebViews Feel Native
• Apache Cordova - Architectural Overview (2025)
• Alibaba Cloud - In-depth Profiling of JSBridge
• Capacitor Documentation - Native Bridge
• Android Developers - WebView Documentation
• Chrome WebView Architecture