Hybrid基础

Hybrid基础

Hybrid基础概念

Hybrid是一种混合开发技术，它结合了原生开发和Web开发的特点，可以实现跨平台开发。Hybrid开发技术通常包括以下几个方面：

• 原生开发：原生开发是指使用原生语言开发应用程序，如iOS使用Objective-C或Swift，Android使用Java或Kotlin。
• Web开发：Web开发是指使用Web技术开发应用程序，如HTML、CSS、JavaScript。
• 混合开发：混合开发是指使用原生语言和Web技术开发应用程序，如使用HTML、CSS、JavaScript开发应用程序，然后使用原生语言进行打包。

Hybrid APP本质

Hybrid APP的本质是：在原生（Native）中嵌入一个WebView作为容器来承载Web页面，然后使用Web技术开发应用程序，然后使用原生语言进行打包。

Hybrid应用架构图

flowchart TD
    subgraph 手机设备["手机设备"]
        style 手机设备 fill:#1e3a8a,stroke:#fff,stroke-width:3px,color:#fff
        subgraph NativeApp["Native App"]
            style NativeApp fill:#fff,stroke:#000,stroke-width:2px,color:#000
            subgraph WebView["WebView"]
                style WebView fill:#60a5fa,stroke:#000,stroke-width:2px,color:#fff
                WebPage["Web网页"]
                style WebPage fill:#9ca3af,stroke:#000,stroke-width:2px,color:#000
            end
        end
    end

苹果商城要求原生UI与外部UI的比重至少为二比八，即原生页面至少占20%。 上架灵活性: 若网页端能做到与原生近乎相同的交互体验，即使APP全部由网页内容开发，也有机会上架

Hybrid APP核心

Hybrid APP 的核心在于将 Web 技术和 Native 能力有机结合，通过关键技术组件实现跨平台开发和原生体验的平衡。理解这些核心要素，是构建高质量 Hybrid 应用的基础。

核心组成要素

Hybrid APP 由三大核心要素构成，它们相互配合形成完整的技术体系。

graph TB
    A[Hybrid APP核心] --> B[WebView容器]
    A --> C[JSBridge通讯层]
    A --> D[Native能力层]

    B --> B1[承载Web内容]
    B --> B2[渲染引擎]
    B --> B3[JavaScript引擎]
    B --> B4[资源管理]

    C --> C1[双向通讯机制]
    C --> C2[协议约定]
    C --> C3[数据传输]
    C --> C4[回调管理]

    D --> D1[系统API调用]
    D --> D2[设备能力访问]
    D --> D3[原生UI组件]
    D --> D4[数据存储]

    style A fill:#4A90E2,color:#fff
    style B fill:#7ED321
    style C fill:#F5A623
    style D fill:#50E3C2

1. WebView 容器

WebView 是 Hybrid APP 的载体，负责加载和渲染 Web 页面。

核心职责：

• 解析和渲染 HTML/CSS
• 执行 JavaScript 代码
• 管理页面生命周期
• 处理用户交互事件

关键配置：

// WebView 基础配置示例
class WebViewConfig {
  static setup(webView) {
    const settings = webView.getSettings();

    // 基础能力
    settings.setJavaScriptEnabled(true);           // 启用JS
    settings.setDomStorageEnabled(true);           // 启用DOM存储
    settings.setDatabaseEnabled(true);             // 启用数据库

    // 缓存配置
    settings.setCacheMode(WebSettings.LOAD_DEFAULT);
    settings.setAppCacheEnabled(true);
    settings.setAppCachePath(getCachePath());

    // 视口配置
    settings.setUseWideViewPort(true);             // 支持viewport meta
    settings.setLoadWithOverviewMode(true);        // 缩放至屏幕大小

    // 性能优化
    settings.setRenderPriority(RenderPriority.HIGH);
    settings.setEnableSmoothTransition(true);

    return webView;
  }
}

2. JSBridge 通讯层

JSBridge 是连接 Native 和 Web 的桥梁，是 Hybrid APP 的核心中的核心。

双向通讯机制：

sequenceDiagram
    participant W as Web层
    participant B as JSBridge
    participant N as Native层

    rect rgb(240, 248, 255)
        Note over W,N: 通讯机制核心流程
        W->>B: 调用Native能力
        B->>B: 协议解析
        B->>N: 转发请求
        N->>N: 执行Native方法
        N->>B: 返回结果
        B->>B: 数据封装
        B->>W: 触发回调
    end

    rect rgb(255, 250, 240)
        Note over W,N: Native主动通知
        N->>B: 发起通知
        B->>W: 触发事件
        W->>W: 处理事件
    end

JSBridge 核心实现：

// JSBridge 核心类
class JSBridgeCore {
  constructor() {
    this.messageQueue = [];       // 消息队列
    this.callbacks = new Map();   // 回调映射
    this.handlers = new Map();    // 处理器映射
    this.callbackId = 0;
  }

  // 注册Native能力处理器
  registerHandler(name, handler) {
    this.handlers.set(name, handler);
  }

  // 调用Native能力
  callNative(method, params = {}) {
    return new Promise((resolve, reject) => {
      const callbackId = `cb_${this.callbackId++}_${Date.now()}`;

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

      // 构造消息
      const message = {
        method,
        params,
        callbackId,
        timestamp: Date.now()
      };

      // 发送消息
      this.sendMessage(message);

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

  // 发送消息到Native
  sendMessage(message) {
    if (window.NativeBridge) {
      // Android
      window.NativeBridge.postMessage(JSON.stringify(message));
    } else if (window.webkit?.messageHandlers?.bridge) {
      // iOS
      window.webkit.messageHandlers.bridge.postMessage(message);
    } else {
      console.error('Bridge not available');
    }
  }

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

  // 处理Native调用Web
  handleNativeCall(handlerName, data) {
    const handler = this.handlers.get(handlerName);
    if (handler) {
      return handler(data);
    } else {
      console.warn(`Handler ${handlerName} not found`);
    }
  }
}

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

3. Native 能力层

Native 能力层提供 Web 无法直接访问的系统级功能。

核心能力清单：

mindmap
  root((Native能力))
    设备能力
      相机
      相册
      麦克风
      GPS定位
      传感器
      蓝牙
      NFC
    系统能力
      文件系统
      通讯录
      日历
      剪贴板
      推送通知
      应用信息
    网络能力
      网络状态
      请求代理
      证书验证
      SSL Pinning
    UI能力
      导航栏
      状态栏
      Toast提示
      ActionSheet
      原生弹窗
    数据能力
      本地存储
      数据库
      安全存储
      加密解密

Native 能力封装示例：

// Native 能力统一封装
class NativeCapabilities {
  // 设备能力：获取定位
  static async getLocation(options = {}) {
    return JSBridge.callNative('getLocation', {
      timeout: options.timeout || 10000,
      enableHighAccuracy: options.highAccuracy || false
    });
  }

  // 设备能力：拍照
  static async takePhoto(options = {}) {
    return JSBridge.callNative('takePhoto', {
      quality: options.quality || 0.8,
      allowEdit: options.allowEdit || false,
      sourceType: 'camera'
    });
  }

  // 设备能力：选择图片
  static async chooseImage(options = {}) {
    return JSBridge.callNative('takePhoto', {
      quality: options.quality || 0.8,
      allowEdit: options.allowEdit || false,
      sourceType: 'album',
      count: options.count || 1
    });
  }

  // 系统能力：获取网络状态
  static async getNetworkType() {
    return JSBridge.callNative('getNetworkType');
  }

  // 系统能力：设置剪贴板
  static async setClipboard(text) {
    return JSBridge.callNative('setClipboard', { text });
  }

  // 系统能力：获取剪贴板
  static async getClipboard() {
    return JSBridge.callNative('getClipboard');
  }

  // UI能力：显示Toast
  static async showToast(message, duration = 'short') {
    return JSBridge.callNative('showToast', {
      message,
      duration: duration === 'long' ? 3000 : 1500
    });
  }

  // UI能力：显示Loading
  static async showLoading(message = '加载中...') {
    return JSBridge.callNative('showLoading', { message });
  }

  // UI能力：隐藏Loading
  static async hideLoading() {
    return JSBridge.callNative('hideLoading');
  }

  // 数据能力：安全存储
  static async setSecureStorage(key, value) {
    return JSBridge.callNative('setSecureStorage', { key, value });
  }

  // 数据能力：安全读取
  static async getSecureStorage(key) {
    return JSBridge.callNative('getSecureStorage', { key });
  }
}

// 使用示例
async function getUserLocation() {
  try {
    await NativeCapabilities.showLoading('获取位置中...');
    const location = await NativeCapabilities.getLocation({
      timeout: 5000,
      highAccuracy: true
    });
    await NativeCapabilities.hideLoading();
    console.log('当前位置:', location);
    return location;
  } catch (error) {
    await NativeCapabilities.hideLoading();
    await NativeCapabilities.showToast('获取位置失败');
    throw error;
  }
}

核心通讯协议

为了保证 Native 和 Web 之间通讯的规范性和可维护性，需要定义统一的通讯协议。

协议数据结构

// 请求协议
interface BridgeRequest {
  method: string;        // 方法名
  params: object;        // 参数对象
  callbackId: string;    // 回调ID
  timestamp: number;     // 时间戳
}

// 响应协议
interface BridgeResponse {
  callbackId: string;    // 回调ID
  error: string | null;  // 错误信息
  result: any;           // 返回结果
  timestamp: number;     // 时间戳
}

// 事件协议
interface BridgeEvent {
  event: string;         // 事件名称
  data: any;            // 事件数据
  timestamp: number;     // 时间戳
}

协议示例

// Web调用Native：获取用户信息
const request = {
  method: 'getUserInfo',
  params: { userId: '123' },
  callbackId: 'cb_1_1640000000000',
  timestamp: 1640000000000
};

// Native返回结果
const response = {
  callbackId: 'cb_1_1640000000000',
  error: null,
  result: {
    userId: '123',
    nickname: '张三',
    avatar: 'https://example.com/avatar.jpg'
  },
  timestamp: 1640000001000
};

// Native主动通知Web：网络状态变化
const event = {
  event: 'networkChange',
  data: {
    type: 'wifi',
    isConnected: true
  },
  timestamp: 1640000002000
};

核心生命周期

Hybrid APP 的生命周期管理是保证应用稳定运行的关键。

stateDiagram-v2
    [*] --> 初始化
    初始化 --> WebView创建: 创建容器
    WebView创建 --> 资源加载: 加载页面
    资源加载 --> DOM解析: 解析HTML
    DOM解析 --> 渲染: 构建渲染树
    渲染 --> 就绪: DOMContentLoaded
    就绪 --> 运行: 页面可交互

    运行 --> 后台: 切换到后台
    后台 --> 运行: 返回前台

    运行 --> 暂停: 页面隐藏
    暂停 --> 运行: 页面显示

    运行 --> 销毁: 关闭页面
    销毁 --> [*]

    note right of 初始化
        预创建WebView
        注册JSBridge
        初始化配置
    end note

    note right of 运行
        监听页面事件
        处理用户交互
        执行业务逻辑
    end note

    note right of 销毁
        清理监听器
        释放资源
        回收WebView
    end note

生命周期管理实现：

// Hybrid 页面生命周期管理
class HybridPageLifecycle {
  constructor() {
    this.state = 'init';
    this.listeners = new Map();
    this.setupLifecycleHooks();
  }

  setupLifecycleHooks() {
    // 页面加载开始
    window.addEventListener('DOMContentLoaded', () => {
      this.setState('ready');
      this.emit('ready');
    });

    // 页面加载完成
    window.addEventListener('load', () => {
      this.setState('loaded');
      this.emit('loaded');
    });

    // 页面显示/隐藏
    document.addEventListener('visibilitychange', () => {
      if (document.hidden) {
        this.setState('hidden');
        this.emit('hidden');
      } else {
        this.setState('visible');
        this.emit('visible');
      }
    });

    // 页面卸载
    window.addEventListener('beforeunload', () => {
      this.setState('unload');
      this.emit('unload');
    });

    // Native生命周期事件
    JSBridge.registerHandler('onAppBackground', () => {
      this.setState('background');
      this.emit('background');
    });

    JSBridge.registerHandler('onAppForeground', () => {
      this.setState('foreground');
      this.emit('foreground');
    });
  }

  setState(state) {
    const oldState = this.state;
    this.state = state;
    console.log(`Lifecycle: ${oldState} -> ${state}`);
  }

  on(event, callback) {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, []);
    }
    this.listeners.get(event).push(callback);
  }

  emit(event) {
    const callbacks = this.listeners.get(event) || [];
    callbacks.forEach(callback => callback());
  }

  destroy() {
    this.listeners.clear();
    this.setState('destroyed');
  }
}

// 使用示例
const lifecycle = new HybridPageLifecycle();

lifecycle.on('ready', () => {
  console.log('页面已就绪，可以初始化业务逻辑');
  initApp();
});

lifecycle.on('loaded', () => {
  console.log('页面完全加载，可以进行数据请求');
  fetchData();
});

lifecycle.on('background', () => {
  console.log('应用进入后台，暂停音视频播放');
  pauseMedia();
});

lifecycle.on('foreground', () => {
  console.log('应用返回前台，恢复音视频播放');
  resumeMedia();
});

核心安全机制

Hybrid APP 需要建立完善的安全机制，保护用户数据和应用安全。

graph LR
    A[安全机制] --> B[通讯安全]
    A --> C[数据安全]
    A --> D[代码安全]
    A --> E[网络安全]

    B --> B1[协议加密]
    B --> B2[签名验证]
    B --> B3[白名单机制]

    C --> C1[敏感数据加密]
    C --> C2[安全存储]
    C --> C3[数据脱敏]

    D --> D1[代码混淆]
    D --> D2[防注入]
    D --> D3[XSS防护]

    E --> E1[HTTPS强制]
    E --> E2[证书校验]
    E --> E3[域名白名单]

    style A fill:#4A90E2,color:#fff
    style B fill:#F56565
    style C fill:#F5A623
    style D fill:#7ED321
    style E fill:#50E3C2

安全机制实现：

// Hybrid 安全管理
class HybridSecurity {
  // 1. URL白名单验证
  static validateUrl(url) {
    const allowedDomains = [
      'https://app.example.com',
      'https://api.example.com',
      'https://cdn.example.com'
    ];

    try {
      const urlObj = new URL(url);
      const origin = urlObj.origin;

      return allowedDomains.some(domain =>
        origin === domain || origin.startsWith(domain)
      );
    } catch (e) {
      return false;
    }
  }

  // 2. 敏感数据加密
  static encryptData(data, key) {
    // 使用AES加密
    return JSBridge.callNative('encrypt', {
      data: JSON.stringify(data),
      key,
      algorithm: 'AES-256-GCM'
    });
  }

  // 3. 敏感数据解密
  static decryptData(encrypted, key) {
    return JSBridge.callNative('decrypt', {
      data: encrypted,
      key,
      algorithm: 'AES-256-GCM'
    });
  }

  // 4. XSS防护：转义HTML
  static escapeHtml(text) {
    const div = document.createElement('div');
    div.textContent = text;
    return div.innerHTML;
  }

  // 5. CSP策略配置
  static setupCSP() {
    const meta = document.createElement('meta');
    meta.httpEquiv = 'Content-Security-Policy';
    meta.content = [
      "default-src 'self'",
      "script-src 'self' 'unsafe-inline' https://cdn.example.com",
      "style-src 'self' 'unsafe-inline'",
      "img-src 'self' data: https:",
      "connect-src 'self' https://api.example.com"
    ].join('; ');
    document.head.appendChild(meta);
  }

  // 6. 请求签名
  static signRequest(params) {
    const timestamp = Date.now();
    const nonce = Math.random().toString(36).substr(2);
    const data = { ...params, timestamp, nonce };

    // 按key排序并拼接
    const keys = Object.keys(data).sort();
    const str = keys.map(k => `${k}=${data[k]}`).join('&');

    // 使用HMAC-SHA256签名
    return JSBridge.callNative('hmacSign', {
      data: str,
      key: 'secret_key',
      algorithm: 'HMAC-SHA256'
    });
  }
}

// 使用示例
// 1. URL验证
if (HybridSecurity.validateUrl(targetUrl)) {
  window.location.href = targetUrl;
} else {
  console.error('非法URL');
}

// 2. 敏感数据加密存储
const userData = { userId: '123', token: 'xxx' };
const encrypted = await HybridSecurity.encryptData(userData, 'key');
await NativeCapabilities.setSecureStorage('user', encrypted);

// 3. XSS防护
const userInput = '<script>alert("XSS")</script>';
const safeText = HybridSecurity.escapeHtml(userInput);
document.getElementById('output').innerHTML = safeText;

核心能力矩阵

不同平台的 Hybrid 能力支持情况对比：

能力类别	Android WebView	iOS WKWebView	实现难度	兼容性
基础渲染	✅ 完整支持	✅ 完整支持	⭐ 低	优秀
JavaScript执行	✅ V8引擎	✅ JavaScriptCore	⭐ 低	优秀
本地存储	✅ LocalStorage/IndexedDB	✅ LocalStorage/IndexedDB	⭐ 低	优秀
JSBridge通讯	✅ addJavascriptInterface	✅ WKScriptMessageHandler	⭐⭐ 中	良好
文件访问	✅ file:// 协议	⚠️ 需配置权限	⭐⭐ 中	一般
视频播放	⚠️ 部分机型问题	✅ 完整支持	⭐⭐ 中	良好
同层渲染	✅ x5内核支持	✅ 原生支持	⭐⭐⭐ 高	一般
离线缓存	✅ 支持	✅ 支持	⭐⭐ 中	良好
推送通知	✅ 通过Native	✅ 通过Native	⭐⭐ 中	优秀
生物识别	✅ 通过Native	✅ 通过Native	⭐⭐ 中	优秀

核心设计原则

构建高质量 Hybrid APP 需要遵循以下核心设计原则：

mindmap
  root((设计原则))
    性能优先
      首屏优化
      资源预加载
      按需加载
      缓存策略
    体验为王
      接近原生
      流畅交互
      快速响应
      友好提示
    安全第一
      数据加密
      通讯验证
      权限控制
      安全存储
    可维护性
      模块化设计
      统一接口
      版本管理
      错误监控
    扩展性
      插件机制
      能力抽象
      协议标准
      向后兼容

设计原则实践：

1. 性能优先：WebView 预创建、资源离线包、图片懒加载
2. 体验为王：骨架屏、Loading 动画、错误兜底、离线提示
3. 安全第一：HTTPS、数据加密、白名单、CSP 策略
4. 可维护性：统一 SDK、规范协议、版本控制、日志上报
5. 扩展性：插件化架构、能力注册、协议扩展、降级方案

通过深入理解 Hybrid APP 的核心要素，我们可以构建出性能优秀、体验流畅、安全可靠的跨平台应用。这些核心组件和机制相互配合，形成了完整的 Hybrid 技术体系。

Hybrid技术原理

Hybrid 技术的核心是在原生应用中嵌入 WebView 容器，通过 WebView 加载和渲染 Web 页面，同时建立 Native 与 Web 之间的双向通讯机制。理解 Hybrid 的技术原理，有助于我们更好地设计和优化 Hybrid 应用。

Hybrid 技术架构层次

Hybrid 应用采用分层架构，从底层到上层依次为：系统层、容器层、桥接层、业务层。

graph TB
    subgraph 业务层
        A1[Web业务代码<br/>HTML/CSS/JS]
        A2[Native业务代码<br/>原生UI组件]
    end

    subgraph 桥接层
        B1[JSBridge SDK]
        B2[Native Bridge API]
    end

    subgraph 容器层
        C1[WebView容器]
        C2[Web引擎<br/>Chromium/WebKit]
    end

    subgraph 系统层
        D1[Android系统]
        D2[iOS系统]
    end

    A1 --> B1
    A2 --> B2
    B1 <--> B2
    B1 --> C1
    C1 --> C2
    C2 --> D1
    C2 --> D2

    style A1 fill:#FFE4B5
    style A2 fill:#FFE4B5
    style B1 fill:#87CEEB
    style B2 fill:#87CEEB
    style C1 fill:#90EE90
    style C2 fill:#90EE90
    style D1 fill:#D3D3D3
    style D2 fill:#D3D3D3

各层职责：

层级	职责	技术组成
业务层	实现具体业务逻辑	Web 页面（Vue/React）+ Native 页面
桥接层	Native 与 Web 通讯	JSBridge SDK + Native API 封装
容器层	承载和渲染 Web 内容	WebView + 渲染引擎
系统层	提供底层能力	Android/iOS 操作系统

WebView 工作原理

WebView 是 Hybrid 应用的核心容器，它本质上是一个嵌入式浏览器，能够解析和渲染 HTML/CSS/JavaScript。

WebView 渲染流程

sequenceDiagram
    participant App as Native App
    participant WV as WebView
    participant Engine as 渲染引擎
    participant Network as 网络层
    participant Server as Web服务器

    App->>WV: loadUrl(url)
    WV->>Network: 发起HTTP请求
    Network->>Server: GET /index.html
    Server-->>Network: 返回HTML
    Network-->>WV: 接收资源

    WV->>Engine: 解析HTML
    Engine->>Engine: 构建DOM树

    Engine->>Network: 请求CSS/JS/图片
    Network->>Server: 批量请求资源
    Server-->>Network: 返回资源
    Network-->>Engine: 接收资源

    Engine->>Engine: 解析CSS<br/>构建CSSOM树
    Engine->>Engine: 合并DOM+CSSOM<br/>生成渲染树
    Engine->>Engine: 布局计算<br/>Layout
    Engine->>Engine: 绘制渲染<br/>Paint
    Engine-->>App: 页面渲染完成

WebView 核心组件

WebView 包含多个核心组件，各司其职：

graph LR
    A[WebView] --> B[WebSettings<br/>配置管理]
    A --> C[WebViewClient<br/>页面加载监听]
    A --> D[WebChromeClient<br/>浏览器特性]
    A --> E[JavascriptInterface<br/>JS交互]

    B --> B1[JavaScript开关]
    B --> B2[缓存策略]
    B --> B3[视口配置]

    C --> C1[页面开始加载]
    C --> C2[页面加载完成]
    C --> C3[资源拦截]

    D --> D1[进度回调]
    D --> D2[标题变化]
    D --> D3[弹窗处理]

    E --> E1[注入对象]
    E --> E2[方法调用]
    E --> E3[参数传递]

    style A fill:#4A90E2,color:#fff
    style B fill:#7ED321
    style C fill:#F5A623
    style D fill:#50E3C2
    style E fill:#BD10E0

组件配置示例：

// Android WebView 核心组件配置
public class HybridWebView {
  private WebView webView;

  public void init(Context context) {
    webView = new WebView(context);

    // 1. WebSettings：基础配置
    WebSettings settings = webView.getSettings();
    settings.setJavaScriptEnabled(true);           // 启用JS
    settings.setDomStorageEnabled(true);           // 启用DOM存储
    settings.setCacheMode(WebSettings.LOAD_DEFAULT); // 缓存策略

    // 2. WebViewClient：页面加载监听
    webView.setWebViewClient(new WebViewClient() {
      @Override
      public void onPageStarted(WebView view, String url, Bitmap favicon) {
        // 页面开始加载
        showLoading();
      }

      @Override
      public void onPageFinished(WebView view, String url) {
        // 页面加载完成
        hideLoading();
        injectBridge();
      }

      @Override
      public WebResourceResponse shouldInterceptRequest(WebView view, String url) {
        // 资源拦截，可实现离线缓存
        return getCachedResource(url);
      }
    });

    // 3. WebChromeClient：浏览器特性
    webView.setWebChromeClient(new WebChromeClient() {
      @Override
      public void onProgressChanged(WebView view, int progress) {
        // 加载进度：0-100
        updateProgressBar(progress);
      }

      @Override
      public void onReceivedTitle(WebView view, String title) {
        // 页面标题变化
        setTitle(title);
      }
    });

    // 4. JavascriptInterface：JS交互
    webView.addJavascriptInterface(new JSBridge(), "NativeBridge");
  }
}

页面加载机制

Hybrid 应用的页面加载分为本地加载和远程加载两种模式。

加载模式对比

graph TB
    A[页面加载模式] --> B[本地加载<br/>Local]
    A --> C[远程加载<br/>Remote]

    B --> B1[优势]
    B --> B2[劣势]
    B1 --> B1A[加载速度快]
    B1 --> B1B[离线可用]
    B1 --> B1C[无网络依赖]
    B2 --> B2A[更新需发版]
    B2 --> B2B[包体积增大]
    B2 --> B2C[维护成本高]

    C --> C1[优势]
    C --> C2[劣势]
    C1 --> C1A[动态更新]
    C1 --> C1B[包体积小]
    C1 --> C1C[维护方便]
    C2 --> C2A[首次加载慢]
    C2 --> C2B[依赖网络]
    C2 --> C2C[白屏时间长]

    style B fill:#90EE90
    style C fill:#87CEEB
    style B1 fill:#7ED321
    style B2 fill:#F56565
    style C1 fill:#7ED321
    style C2 fill:#F56565

本地加载方案

将 Web 资源打包到 APP 中，通过 file:// 协议加载。

// Android 本地加载
public void loadLocalPage() {
  // 方式一：从 assets 目录加载
  webView.loadUrl("file:///android_asset/index.html");

  // 方式二：从 SD 卡加载
  String path = Environment.getExternalStorageDirectory() + "/app/index.html";
  webView.loadUrl("file://" + path);
}

// iOS 本地加载
func loadLocalPage() {
  // 从 Bundle 加载
  if let url = Bundle.main.url(forResource: "index", withExtension: "html") {
    webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent())
  }
}

远程加载方案

从服务器加载 Web 资源，支持动态更新。

// 远程加载
public void loadRemotePage() {
  webView.loadUrl("https://example.com/app/index.html");
}

// 带缓存策略的远程加载
public void loadWithCache(String url) {
  WebSettings settings = webView.getSettings();

  if (isNetworkAvailable()) {
    // 有网络：优先使用网络资源
    settings.setCacheMode(WebSettings.LOAD_DEFAULT);
  } else {
    // 无网络：使用缓存
    settings.setCacheMode(WebSettings.LOAD_CACHE_ELSE_NETWORK);
  }

  webView.loadUrl(url);
}

混合加载方案（推荐）

结合本地加载和远程加载的优势，实现增量更新。

// 混合加载策略
class HybridLoader {
  constructor() {
    this.localVersion = '1.0.0';
    this.remoteVersion = null;
  }

  async load() {
    // 1. 检查远程版本
    this.remoteVersion = await this.checkRemoteVersion();

    // 2. 比较版本，决定加载方式
    if (this.needUpdate()) {
      // 需要更新：下载新版本
      await this.downloadAndCache();
      this.loadFromCache();
    } else if (this.hasCachedVersion()) {
      // 有缓存：加载缓存版本
      this.loadFromCache();
    } else {
      // 无缓存：加载本地版本
      this.loadFromLocal();
    }
  }

  loadFromLocal() {
    webView.loadUrl('file:///android_asset/index.html');
  }

  loadFromCache() {
    const cachedPath = getCachePath() + '/index.html';
    webView.loadUrl('file://' + cachedPath);
  }

  async downloadAndCache() {
    const html = await fetch('https://example.com/app/index.html');
    await saveToCache(html);
  }
}

资源管理机制

Hybrid 应用需要合理管理 Web 资源，包括 HTML、CSS、JavaScript、图片等。

资源加载流程

flowchart TD
    A[资源请求] --> B{检查本地缓存}
    B -->|有缓存| C{缓存是否过期}
    B -->|无缓存| E[发起网络请求]

    C -->|未过期| D[使用缓存]
    C -->|已过期| E

    E --> F{网络请求成功?}
    F -->|成功| G[返回资源]
    F -->|失败| H{有过期缓存?}

    H -->|有| I[使用过期缓存]
    H -->|无| J[加载失败]

    G --> K[存入缓存]
    K --> L[渲染页面]
    D --> L
    I --> L

    style D fill:#90EE90
    style G fill:#90EE90
    style J fill:#F56565
    style L fill:#FFD700

缓存策略实现

// Android 资源拦截与缓存
webView.setWebViewClient(new WebViewClient() {
  @Override
  public WebResourceResponse shouldInterceptRequest(WebView view,
                                                    WebResourceRequest request) {
    String url = request.getUrl().toString();

    // 1. 检查是否为可缓存资源
    if (isCacheableResource(url)) {
      // 2. 尝试从缓存获取
      WebResourceResponse cachedResponse = loadFromCache(url);
      if (cachedResponse != null) {
        return cachedResponse;
      }

      // 3. 从网络加载并缓存
      try {
        WebResourceResponse response = loadFromNetwork(url);
        saveToCache(url, response);
        return response;
      } catch (Exception e) {
        // 4. 网络失败，返回降级资源
        return loadFallbackResource();
      }
    }

    return super.shouldInterceptRequest(view, request);
  }

  private boolean isCacheableResource(String url) {
    // 缓存静态资源：js, css, 图片等
    return url.endsWith(".js") ||
           url.endsWith(".css") ||
           url.endsWith(".png") ||
           url.endsWith(".jpg");
  }
});

离线包方案

将完整的 Web 应用打包成离线包，通过差量更新实现快速加载。

// 离线包管理
class OfflinePackageManager {
  constructor() {
    this.packages = new Map();
    this.basePath = '/sdcard/offline_packages/';
  }

  // 检查并下载离线包
  async checkAndDownload(appId) {
    const localVersion = this.getLocalVersion(appId);
    const remoteVersion = await this.getRemoteVersion(appId);

    if (remoteVersion > localVersion) {
      // 下载差量包
      const patch = await this.downloadPatch(appId, localVersion, remoteVersion);
      await this.applyPatch(appId, patch);
      this.updateVersion(appId, remoteVersion);
    }
  }

  // 加载离线包
  loadPackage(appId) {
    const packagePath = this.basePath + appId + '/index.html';
    webView.loadUrl('file://' + packagePath);
  }

  // 应用差量更新
  async applyPatch(appId, patch) {
    const basePath = this.basePath + appId + '/';

    for (const file of patch.files) {
      if (file.action === 'add' || file.action === 'modify') {
        await this.saveFile(basePath + file.path, file.content);
      } else if (file.action === 'delete') {
        await this.deleteFile(basePath + file.path);
      }
    }
  }
}

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

// 应用启动时检查更新
await packageManager.checkAndDownload('app_home');

// 加载离线包
packageManager.loadPackage('app_home');

Native 与 Web 通讯原理

Hybrid 的核心是实现 Native 与 Web 的双向通讯，这涉及到不同语言之间的相互调用。

通讯方式对比

graph TB
    A[通讯方式] --> B[Native调用Web]
    A --> C[Web调用Native]

    B --> B1[evaluateJavascript<br/>执行JS代码]
    B --> B2[loadUrl<br/>加载JS协议URL]

    C --> C1[注入对象<br/>addJavascriptInterface]
    C --> C2[URL拦截<br/>shouldOverrideUrlLoading]
    C --> C3[弹窗拦截<br/>onJsPrompt]

    B1 --> B1A[优点：可获取返回值]
    B1 --> B1B[缺点：Android 4.4+]

    B2 --> B2A[优点：兼容性好]
    B2 --> B2B[缺点：无返回值]

    C1 --> C1A[优点：简单直接<br/>支持同步返回]
    C1 --> C1B[缺点：需注解保证安全]

    C2 --> C2A[优点：兼容性好]
    C2 --> C2B[缺点：URL长度限制]

    C3 --> C3A[优点：支持同步返回]
    C3 --> C3B[缺点：劫持原生弹窗]

    style B1 fill:#90EE90
    style C1 fill:#90EE90
    style B1A fill:#7ED321
    style B1B fill:#F56565
    style C1A fill:#7ED321
    style C1B fill:#F56565

通讯时序完整流程

sequenceDiagram
    participant W as Web页面
    participant B as JSBridge
    participant N as Native

    rect rgb(240, 248, 255)
        Note over W,N: 场景1：Web主动调用Native
        W->>B: bridge.call('getLocation')
        B->>B: 生成callbackId
        B->>N: 调用Native方法
        N->>N: 执行获取位置逻辑
        N->>N: 调用系统API
        N->>B: 返回位置数据
        B->>W: 触发回调函数
        W->>W: 处理位置数据
    end

    rect rgb(255, 250, 240)
        Note over W,N: 场景2：Native主动通知Web
        N->>N: 监听到系统事件<br/>(如网络变化)
        N->>B: evaluateJavascript
        B->>W: 调用Web事件处理器
        W->>W: 更新UI状态
        W-->>B: 返回处理结果
        B-->>N: 回调通知
    end

    rect rgb(240, 255, 240)
        Note over W,N: 场景3：异步数据传输
        W->>B: bridge.call('uploadFile', data)
        B->>N: 传输文件数据
        N->>N: 执行上传逻辑
        Note over N: 上传中...
        N->>B: 进度回调(30%)
        B->>W: onProgress(30%)
        N->>B: 进度回调(60%)
        B->>W: onProgress(60%)
        N->>B: 上传完成
        B->>W: onSuccess(result)
    end

双向通讯完整示例

// Native端（Android）完整实现
public class HybridBridge {
  private WebView webView;
  private Map<String, Callback> callbacks = new HashMap<>();

  // 1. 注入桥接对象
  public void inject() {
    webView.addJavascriptInterface(this, "NativeBridge");
  }

  // 2. Web调用Native：统一入口
  @JavascriptInterface
  public void invoke(String method, String params, String callbackId) {
    new Handler(Looper.getMainLooper()).post(() -> {
      try {
        // 解析参数
        JSONObject paramsJson = new JSONObject(params);

        // 执行对应方法
        Object result = executeMethod(method, paramsJson);

        // 回调Web
        callback(callbackId, null, result);
      } catch (Exception e) {
        callback(callbackId, e.getMessage(), null);
      }
    });
  }

  // 3. Native调用Web
  public void callWeb(String method, Object params) {
    String script = String.format(
      "window.handleNativeCall('%s', %s)",
      method,
      new Gson().toJson(params)
    );

    webView.evaluateJavascript(script, null);
  }

  // 4. 回调Web
  private void callback(String callbackId, String error, Object result) {
    String script = String.format(
      "window.__handleCallback('%s', %s, %s)",
      callbackId,
      error != null ? "'" + error + "'" : "null",
      new Gson().toJson(result)
    );

    webView.evaluateJavascript(script, null);
  }

  // 5. 执行具体方法
  private Object executeMethod(String method, JSONObject params) {
    switch (method) {
      case "getLocation":
        return getLocation();
      case "takePhoto":
        return takePhoto(params);
      case "showToast":
        showToast(params.getString("message"));
        return null;
      default:
        throw new IllegalArgumentException("Unknown method: " + method);
    }
  }
}

// Web端完整实现
class JSBridge {
  constructor() {
    this.callbacks = new Map();
    this.callbackId = 0;
    this.init();
  }

  init() {
    // 注册全局回调处理器
    window.__handleCallback = (callbackId, error, result) => {
      const callback = this.callbacks.get(callbackId);
      if (callback) {
        error ? callback.reject(new Error(error)) : callback.resolve(result);
        this.callbacks.delete(callbackId);
      }
    };

    // 注册Native主动调用处理器
    window.handleNativeCall = (method, params) => {
      const handler = this.nativeHandlers[method];
      if (handler) {
        handler(params);
      }
    };
  }

  // Web调用Native
  call(method, params = {}) {
    return new Promise((resolve, reject) => {
      const callbackId = String(this.callbackId++);
      this.callbacks.set(callbackId, { resolve, reject });

      if (window.NativeBridge) {
        // Android
        window.NativeBridge.invoke(method, JSON.stringify(params), callbackId);
      } else if (window.webkit?.messageHandlers?.invoke) {
        // iOS
        window.webkit.messageHandlers.invoke.postMessage({
          method,
          params,
          callbackId
        });
      } else {
        reject(new Error('Bridge not available'));
      }
    });
  }

  // 注册Native调用的处理器
  nativeHandlers = {
    onNetworkChange: (status) => {
      console.log('网络状态变化:', status);
      // 更新UI
    },
    onPushMessage: (message) => {
      console.log('收到推送:', message);
      // 显示通知
    }
  };
}

// 使用示例
const bridge = new JSBridge();

// Web调用Native获取位置
bridge.call('getLocation', { timeout: 5000 })
  .then(location => {
    console.log('当前位置:', location);
  })
  .catch(error => {
    console.error('获取位置失败:', error);
  });

// Web调用Native拍照
bridge.call('takePhoto', { quality: 0.8 })
  .then(photo => {
    document.getElementById('avatar').src = photo;
  });

性能优化原理

Hybrid 应用的性能优化需要从多个维度入手。

性能瓶颈分析

mindmap
  root((Hybrid性能瓶颈))
    网络层
      首屏加载慢
      资源请求多
      弱网体验差
    渲染层
      白屏时间长
      页面卡顿
      内存占用高
    交互层
      JSBridge调用慢
      数据传输大
      频繁通讯
    容器层
      WebView初始化慢
      多实例内存高
      缓存策略不合理

优化策略总览

graph LR
    A[性能优化] --> B[加载优化]
    A --> C[渲染优化]
    A --> D[通讯优化]
    A --> E[内存优化]

    B --> B1[WebView预创建]
    B --> B2[资源预加载]
    B --> B3[离线包]
    B --> B4[CDN加速]

    C --> C1[骨架屏]
    C --> C2[懒加载]
    C --> C3[虚拟滚动]
    C --> C4[避免重排重绘]

    D --> D1[批量调用]
    D --> D2[数据压缩]
    D --> D3[减少调用频率]
    D --> D4[异步处理]

    E --> E1[WebView复用]
    E --> E2[及时释放]
    E --> E3[图片优化]
    E --> E4[内存监控]

    style A fill:#4A90E2,color:#fff
    style B fill:#7ED321
    style C fill:#F5A623
    style D fill:#50E3C2
    style E fill:#BD10E0

WebView 预创建与复用

// WebView 对象池实现
public class WebViewPool {
  private static final int MAX_POOL_SIZE = 3;
  private static Queue<WebView> availableWebViews = new LinkedList<>();
  private static Set<WebView> usedWebViews = new HashSet<>();

  // 预创建 WebView
  public static void prepare(Context context) {
    for (int i = 0; i < MAX_POOL_SIZE; i++) {
      WebView webView = createWebView(context.getApplicationContext());
      availableWebViews.offer(webView);
    }
  }

  // 获取 WebView
  public static WebView obtain(Context context) {
    WebView webView = availableWebViews.poll();
    if (webView == null) {
      webView = createWebView(context);
    }
    usedWebViews.add(webView);
    return webView;
  }

  // 回收 WebView
  public static void recycle(WebView webView) {
    if (webView != null) {
      // 清理状态
      webView.clearHistory();
      webView.clearCache(true);
      webView.loadUrl("about:blank");

      // 移除所有View
      ViewGroup parent = (ViewGroup) webView.getParent();
      if (parent != null) {
        parent.removeView(webView);
      }

      // 放回池中
      usedWebViews.remove(webView);
      if (availableWebViews.size() < MAX_POOL_SIZE) {
        availableWebViews.offer(webView);
      } else {
        webView.destroy();
      }
    }
  }

  private static WebView createWebView(Context context) {
    WebView webView = new WebView(context);
    // 初始化配置
    initWebViewSettings(webView);
    return webView;
  }
}

// 使用示例
// 应用启动时预创建
WebViewPool.prepare(getApplicationContext());

// 使用时获取
WebView webView = WebViewPool.obtain(this);
container.addView(webView);

// 使用完毕回收
WebViewPool.recycle(webView);

首屏加载优化

// 并行加载优化策略
class FastLoadStrategy {
  async loadPage(url) {
    // 1. 并行操作
    await Promise.all([
      this.preloadWebView(),      // 预创建WebView
      this.preloadResources(),    // 预加载资源
      this.preconnect()           // 预连接服务器
    ]);

    // 2. 加载页面
    webView.loadUrl(url);

    // 3. 注入优化脚本
    this.injectOptimizeScript();
  }

  // 预加载关键资源
  async preloadResources() {
    const criticalResources = [
      'https://cdn.example.com/app.js',
      'https://cdn.example.com/app.css',
      'https://cdn.example.com/logo.png'
    ];

    // 提前下载到缓存
    for (const url of criticalResources) {
      await this.downloadToCache(url);
    }
  }

  // 注入性能优化脚本
  injectOptimizeScript() {
    const script = `
      // 1. 骨架屏自动移除
      window.addEventListener('DOMContentLoaded', () => {
        document.getElementById('skeleton')?.remove();
      });

      // 2. 图片懒加载
      const images = document.querySelectorAll('img[data-src]');
      const imageObserver = new IntersectionObserver((entries) => {
        entries.forEach(entry => {
          if (entry.isIntersecting) {
            const img = entry.target;
            img.src = img.dataset.src;
            imageObserver.unobserve(img);
          }
        });
      });
      images.forEach(img => imageObserver.observe(img));

      // 3. 首屏统计
      window.addEventListener('load', () => {
        const timing = performance.timing;
        const loadTime = timing.loadEventEnd - timing.navigationStart;
        bridge.call('reportPerformance', { loadTime });
      });
    `;

    webView.evaluateJavascript(script, null);
  }
}

Hybrid 技术演进

timeline
    title Hybrid技术发展历程
    section 早期阶段
        2008 : PhoneGap诞生
             : 简单的Web容器
    section 发展阶段
        2012 : Cordova开源
             : 插件化架构
        2015 : React Native
             : 接近原生体验
    section 成熟阶段
        2016 : Weex推出
             : 跨三端方案
        2018 : Flutter发布
             : 自绘引擎
    section 现代阶段
        2020 : 小程序盛行
             : 双线程架构
        2023 : Hybrid优化
             : 离线包+预渲染
        2025 : 技术融合
             : Hybrid+原生混合

通过深入理解 Hybrid 技术原理，我们可以更好地设计架构、优化性能、解决问题。Hybrid 技术仍在不断演进，结合现代前端框架和原生能力，为移动应用开发提供了高效灵活的解决方案。

JSBridge

JSBridge是原生（Native）和 web 端的双向通讯层（跨语言解决方案），它主要用于解决原生（Native）和 web 端之间的通讯问题。

一座用 JavaScript 搭建起来的桥，一端是 web，一端是 Native。

• 目的：解决原生（Native）和 web 端之间的通讯问题。即在 web 端调用原生（Native）的功能，或者在原生（Native）中调用 web 端的功能。

Android 与 iOS 的 JSBridge 通讯及对比

JSBridge 作为 Native 与 Web 之间的桥梁，在 Android 和 iOS 平台上有着不同的实现方式。理解两个平台的差异，有助于我们设计出更加健壮和高效的跨平台通讯方案。

Android 平台的 JSBridge 实现

Android 平台主要通过 WebView 组件来承载 Web 页面，提供了多种 Native 与 JavaScript 交互的方式。

1. Android 调用 JavaScript

Android 原生代码可以通过以下方式调用 JavaScript 代码：

原生端调用web端代码方法，方法必须是挂载到web端的window对象上。

方式一：loadUrl（Android 4.4 以下）

loadUrl 是最基础的调用方式，通过加载一段 javascript: 协议的 URL 来执行 JS 代码。

// Android 端代码（Java/Kotlin）
webView.loadUrl("javascript:window.nativeCallback('hello from native')");

// Web 端代码
window.nativeCallback = function(data) {
  console.log('收到Native消息:', data);
}

特点：

• 无法获取 JavaScript 执行的返回值
• 会刷新页面（仅调用 JS 不会，但需注意使用场景）
• 在 Android 4.4 以下版本使用

方式二：evaluateJavascript（Android 4.4+，推荐）

evaluateJavascript 是更现代的方式，支持获取 JavaScript 的返回值。

// Android 端代码
webView.evaluateJavascript("getUserInfo()", new ValueCallback<String>() {
  @Override
  public void onReceiveValue(String value) {
    // value 为 JS 返回的结果
    Log.d("JSBridge", "JS返回值: " + value);
  }
});

// Web 端代码
function getUserInfo() {
  return JSON.stringify({
    name: '张三',
    age: 25
  });
}

特点：

• 可以获取 JavaScript 的返回值
• 执行效率更高
• Android 4.4+ 支持

2. JavaScript 调用 Android

JavaScript 调用 Android 原生方法有三种主流方式：

方式一：addJavascriptInterface（推荐）

通过 addJavascriptInterface 将 Java/Kotlin 对象注入到 JavaScript 上下文中。

// Android 端代码
public class JSBridge {
  private Context context;

  public JSBridge(Context context) {
    this.context = context;
  }

  @JavascriptInterface
  public void showToast(String message) {
    Toast.makeText(context, message, Toast.LENGTH_SHORT).show();
  }

  @JavascriptInterface
  public String getUserToken() {
    return "token_abc123";
  }
}

// 注入对象
webView.addJavascriptInterface(new JSBridge(this), "NativeBridge");

// Web 端调用
NativeBridge.showToast('Hello Native!');
const token = NativeBridge.getUserToken();
console.log('获取到的token:', token);

特点：

• 简单直接，调用方便
• Android 4.2+ 需要添加 @JavascriptInterface 注解以防止安全漏洞
• 支持同步返回值

方式二：拦截 URL Scheme

通过拦截特定协议的 URL 来实现通讯。

// Android 端代码
webView.setWebViewClient(new WebViewClient() {
  @Override
  public boolean shouldOverrideUrlLoading(WebView view, String url) {
    if (url.startsWith("jsbridge://")) {
      // 解析 URL 参数
      Uri uri = Uri.parse(url);
      String method = uri.getHost();
      String params = uri.getQuery();

      // 处理调用
      handleJSBridgeCall(method, params);
      return true;
    }
    return super.shouldOverrideUrlLoading(view, url);
  }
});

// Web 端调用
function callNative(method, params) {
  const url = `jsbridge://${method}?${JSON.stringify(params)}`;
  window.location.href = url;
}

callNative('showToast', { message: 'Hello' });

特点：

• 兼容性好，支持所有 Android 版本
• URL 长度有限制（2MB 左右）
• 无法直接获取返回值，需要通过回调机制

方式三：拦截 prompt/alert/confirm

通过重写 WebChromeClient 的弹窗方法来实现通讯。

// Android 端代码
webView.setWebChromeClient(new WebChromeClient() {
  @Override
  public boolean onJsPrompt(WebView view, String url, String message,
                            String defaultValue, JsPromptResult result) {
    // 解析 message，执行相应操作
    if (message.startsWith("jsbridge://")) {
      result.confirm("处理结果");
      return true;
    }
    return super.onJsPrompt(view, url, message, defaultValue, result);
  }
});

// Web 端调用
function callNative(action, params) {
  const result = prompt(`jsbridge://${action}`, JSON.stringify(params));
  return result;
}

const response = callNative('getLocation', {});

特点：

• 支持同步返回值
• 会劫持原生的 prompt 方法
• 较少使用

Android JSBridge 调用流程

sequenceDiagram
    participant Web as Web页面
    participant Bridge as JSBridge
    participant Native as Android Native

    Note over Web,Native: JavaScript 调用 Native
    Web->>Bridge: NativeBridge.method(params)
    Bridge->>Native: @JavascriptInterface 方法
    Native->>Native: 执行原生逻辑
    Native-->>Bridge: 返回结果
    Bridge-->>Web: 返回值或回调

    Note over Web,Native: Native 调用 JavaScript
    Native->>Bridge: evaluateJavascript()
    Bridge->>Web: 执行 JS 函数
    Web->>Web: 执行 Web 逻辑
    Web-->>Bridge: return 结果
    Bridge-->>Native: onReceiveValue()

iOS 平台的 JSBridge 实现

iOS 平台经历了从 UIWebView 到 WKWebView 的演进，JSBridge 的实现方式也有所不同。

1. iOS 调用 JavaScript

UIWebView 方式（已废弃）

// iOS 端代码（Objective-C）
NSString *result = [webView stringByEvaluatingJavaScriptFromString:@"getUserInfo()"];

// Web 端代码
function getUserInfo() {
  return JSON.stringify({ name: '李四', age: 28 });
}

WKWebView 方式（iOS 8+，推荐）

// iOS 端代码（Swift）
webView.evaluateJavaScript("getUserInfo()") { (result, error) in
  if let data = result {
    print("JS返回值: \(data)")
  }
}

// Web 端代码
function getUserInfo() {
  return { name: '李四', age: 28 };
}

特点：

• WKWebView 性能更好，内存占用更低
• 支持异步获取返回值
• iOS 8+ 推荐使用 WKWebView

2. JavaScript 调用 iOS

方式一：WKScriptMessageHandler（WKWebView，推荐）

WKWebView 提供了原生的消息处理机制，这是最规范的方式。

// iOS 端代码（Swift）
class JSBridgeHandler: NSObject, WKScriptMessageHandler {
  func userContentController(_ userContentController: WKUserContentController,
                            didReceive message: WKScriptMessage) {
    let method = message.name
    let params = message.body

    switch method {
    case "showToast":
      if let msg = params as? String {
        showToast(message: msg)
      }
    case "getToken":
      let token = "token_xyz789"
      // 调用 JS 回调
      webView.evaluateJavaScript("window.handleTokenResponse('\(token)')") { _, _ in }
    default:
      break
    }
  }
}

// 注册消息处理器
let configuration = WKWebViewConfiguration()
configuration.userContentController.add(handler, name: "showToast")
configuration.userContentController.add(handler, name: "getToken")

// Web 端调用
window.webkit.messageHandlers.showToast.postMessage('Hello iOS!');

window.webkit.messageHandlers.getToken.postMessage({});
window.handleTokenResponse = function(token) {
  console.log('收到token:', token);
}

特点：

• 官方推荐方式，稳定可靠
• 需要提前注册消息处理器
• 无法直接同步返回值，需要通过回调

方式二：拦截 URL Scheme

与 Android 类似，通过拦截自定义协议实现。

// iOS 端代码（Swift）
func webView(_ webView: WKWebView,
             decidePolicyFor navigationAction: WKNavigationAction,
             decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
  guard let url = navigationAction.request.url else {
    decisionHandler(.allow)
    return
  }

  if url.scheme == "jsbridge" {
    let method = url.host
    let params = url.query
    handleJSBridgeCall(method: method, params: params)
    decisionHandler(.cancel)
    return
  }

  decisionHandler(.allow)
}

// Web 端调用
function callNative(method, params) {
  const iframe = document.createElement('iframe');
  iframe.style.display = 'none';
  iframe.src = `jsbridge://${method}?${encodeURIComponent(JSON.stringify(params))}`;
  document.body.appendChild(iframe);
  setTimeout(() => iframe.remove(), 100);
}

callNative('showToast', { message: 'Hello' });

特点：

• 兼容 UIWebView 和 WKWebView
• 使用 iframe 方式更稳定（不会影响页面历史记录）
• URL 长度限制约 2MB

iOS JSBridge 调用流程

sequenceDiagram
    participant Web as Web页面
    participant Bridge as JSBridge
    participant Native as iOS Native

    Note over Web,Native: JavaScript 调用 Native
    Web->>Bridge: webkit.messageHandlers.method.postMessage()
    Bridge->>Native: WKScriptMessageHandler
    Native->>Native: 执行原生逻辑
    Native->>Bridge: evaluateJavaScript(callback)
    Bridge->>Web: 执行回调函数

    Note over Web,Native: Native 调用 JavaScript
    Native->>Bridge: evaluateJavaScript()
    Bridge->>Web: 执行 JS 函数
    Web->>Web: 执行 Web 逻辑
    Web-->>Bridge: 异步返回结果
    Bridge-->>Native: completionHandler

Android 与 iOS JSBridge 对比

对比维度	Android	iOS
主要容器	WebView	UIWebView（废弃）/ WKWebView
Native 调 JS	evaluateJavascript()	evaluateJavaScript()
JS 调 Native（推荐）	addJavascriptInterface	WKScriptMessageHandler
注入对象方式	直接注入 Java 对象到 window	通过 webkit.messageHandlers 命名空间
注入对象访问	window.NativeBridge.method()	window.webkit.messageHandlers.method.postMessage()
传递数据格式	支持基本类型和字符串，需手动序列化对象	仅支持可序列化的 JSON 对象
返回值支持	支持同步/异步返回	仅支持异步返回
返回值获取方式	同步：直接返回；异步：ValueCallback	异步回调：需通过 evaluateJavaScript 调用 JS 回调
URL Scheme	支持，需拦截 URL	支持，使用 iframe 更稳定
安全性	需添加 @JavascriptInterface 注解（4.2+）	WKWebView 安全性更高
性能	一般	WKWebView 性能优秀
兼容性	Android 4.4+ 功能完善	iOS 8+ 推荐 WKWebView

详细对比说明

1. 注入对象的区别

Android 注入方式：

• 使用 addJavascriptInterface 直接将 Java/Kotlin 对象注入到 JavaScript 的全局作用域
• 注入的对象可以直接挂载到 window 对象下，访问方式简洁
• 可以注入多个对象，每个对象有独立的命名空间

// Android 端注入
webView.addJavascriptInterface(new JSBridge(this), "NativeBridge");
webView.addJavascriptInterface(new PaymentBridge(this), "PaymentBridge");

// Web 端调用
window.NativeBridge.showToast('Hello');
window.PaymentBridge.pay({ amount: 100 });

iOS 注入方式：

• WKWebView 不直接注入对象，而是注册消息处理器（Message Handler）
• 所有处理器都在 webkit.messageHandlers 命名空间下
• 需要预先注册处理器名称，动态性较弱

// iOS 端注册
let configuration = WKWebViewConfiguration()
configuration.userContentController.add(handler, name: "showToast")
configuration.userContentController.add(handler, name: "pay")

// Web 端调用
window.webkit.messageHandlers.showToast.postMessage('Hello');
window.webkit.messageHandlers.pay.postMessage({ amount: 100 });

核心差异：

graph TB
    subgraph Android注入机制
        A1[Java对象] -->|addJavascriptInterface| A2[window.NativeBridge]
        A2 --> A3[直接方法调用]
        A3 --> A4[可同步返回]
    end

    subgraph iOS注入机制
        B1[Message Handler] -->|注册到| B2[webkit.messageHandlers.xxx]
        B2 --> B3[postMessage发送]
        B3 --> B4[仅异步回调]
    end

    style A1 fill:#90EE90
    style B1 fill:#87CEEB
    style A4 fill:#FFD700
    style B4 fill:#FFA500

2. 传递数据格式对比

Android 数据传递：

支持的数据类型更丰富，但需要注意类型转换。

// Android 端接收参数
@JavascriptInterface
public void sendData(String text) { }           // 字符串

@JavascriptInterface
public void sendNumber(int num) { }             // 数字

@JavascriptInterface
public void sendBoolean(boolean flag) { }       // 布尔值

@JavascriptInterface
public void sendObject(String jsonStr) {        // 对象（需序列化为字符串）
  JSONObject obj = new JSONObject(jsonStr);
}

// Web 端调用
NativeBridge.sendData('Hello');
NativeBridge.sendNumber(42);
NativeBridge.sendBoolean(true);
NativeBridge.sendObject(JSON.stringify({ name: 'Alice', age: 25 }));

iOS 数据传递：

仅支持可 JSON 序列化的数据类型，但会自动处理序列化。

// iOS 端接收参数
func userContentController(_ userContentController: WKUserContentController,
                          didReceive message: WKScriptMessage) {
  let body = message.body  // 自动解析为对应类型

  if let text = body as? String { }              // 字符串
  if let num = body as? Int { }                  // 数字
  if let flag = body as? Bool { }                // 布尔值
  if let obj = body as? [String: Any] { }        // 对象（自动反序列化）
  if let arr = body as? [Any] { }                // 数组
}

// Web 端调用（无需手动序列化）
webkit.messageHandlers.method.postMessage('Hello');
webkit.messageHandlers.method.postMessage(42);
webkit.messageHandlers.method.postMessage(true);
webkit.messageHandlers.method.postMessage({ name: 'Alice', age: 25 });
webkit.messageHandlers.method.postMessage([1, 2, 3]);

数据格式对比表：

数据类型	Android	iOS
字符串	✅ 直接支持	✅ 直接支持
数字	✅ 支持 int, long, float, double	✅ 支持 Int, Double
布尔值	✅ 支持 boolean	✅ 支持 Bool
对象	⚠️ 需手动序列化为 JSON 字符串	✅ 自动序列化/反序列化
数组	⚠️ 需手动序列化为 JSON 字符串	✅ 自动序列化/反序列化
null/undefined	⚠️ 转为 "null" 字符串	✅ 正确处理
二进制数据	❌ 不支持，需 Base64 编码	❌ 不支持，需 Base64 编码

3. 返回值机制对比

Android 返回值机制：

Android 支持同步和异步两种返回方式。

// Android 端：同步返回
@JavascriptInterface
public String getUserToken() {
  return "token_abc123";  // 直接返回
}

@JavascriptInterface
public int calculate(int a, int b) {
  return a + b;
}

// Web 端：同步获取
const token = NativeBridge.getUserToken();
console.log('Token:', token);  // 立即得到结果

const result = NativeBridge.calculate(10, 20);
console.log('Result:', result);  // 30

// Android 端：异步返回
public void getUserInfo(String userId) {
  // 异步操作
  new Thread(() -> {
    String userInfo = fetchUserInfo(userId);

    // 调用 JS 回调
    runOnUiThread(() -> {
      webView.evaluateJavascript(
        "window.handleUserInfo('" + userInfo + "')",
        null
      );
    });
  }).start();
}

// Web 端：异步接收
window.handleUserInfo = function(userInfo) {
  console.log('User Info:', userInfo);
};
NativeBridge.getUserInfo('user123');

iOS 返回值机制：

iOS 仅支持异步返回，必须通过 evaluateJavaScript 回调。

// iOS 端：异步返回（方式一：直接调用 JS 函数）
func userContentController(_ userContentController: WKUserContentController,
                          didReceive message: WKScriptMessage) {
  if message.name == "getUserToken" {
    let token = "token_xyz789"

    // 调用 JS 回调函数
    let script = "window.handleToken('\(token)')"
    webView.evaluateJavaScript(script) { (result, error) in
      if let error = error {
        print("Error: \(error)")
      }
    }
  }
}

// Web 端：定义回调
window.handleToken = function(token) {
  console.log('Token:', token);
};
webkit.messageHandlers.getUserToken.postMessage({});

// iOS 端：异步返回（方式二：使用 Promise 封装）
func userContentController(_ userContentController: WKUserContentController,
                          didReceive message: WKScriptMessage) {
  if message.name == "calculate" {
    if let params = message.body as? [String: Int],
       let a = params["a"],
       let b = params["b"],
       let callbackId = params["callbackId"] as? String {

      let result = a + b

      // 调用统一回调处理函数
      let script = "window.__bridge_callback('\(callbackId)', null, \(result))"
      webView.evaluateJavaScript(script, completionHandler: nil)
    }
  }
}

// Web 端：Promise 封装
function callNative(method, params) {
  return new Promise((resolve, reject) => {
    const callbackId = Date.now() + Math.random();

    window.__bridge_callback = function(id, error, result) {
      if (id === callbackId) {
        error ? reject(error) : resolve(result);
      }
    };

    webkit.messageHandlers[method].postMessage({
      ...params,
      callbackId
    });
  });
}

// 使用
callNative('calculate', { a: 10, b: 20 }).then(result => {
  console.log('Result:', result);  // 30
});

返回值对比流程：

sequenceDiagram
    participant W as Web
    participant A as Android
    participant I as iOS

    Note over W,A: Android 同步返回
    W->>A: NativeBridge.getToken()
    A->>A: 执行方法
    A-->>W: return "token"
    Note over W: 立即得到返回值

    Note over W,A: Android 异步返回
    W->>A: NativeBridge.async()
    A->>A: 异步执行
    Note over W: 继续执行其他代码
    A->>W: evaluateJavascript(callback)
    W->>W: 执行回调函数

    Note over W,I: iOS 异步返回（唯一方式）
    W->>I: messageHandlers.method.postMessage()
    I->>I: 异步执行
    Note over W: 继续执行其他代码
    I->>W: evaluateJavaScript(callback)
    W->>W: 执行回调函数

返回值机制总结：

特性	Android	iOS
同步返回	✅ 支持，方法直接 return	❌ 不支持
异步返回	✅ 支持，需手动回调 JS	✅ 唯一方式
返回值类型	支持基本类型和字符串	通过 JS 回调，类型灵活
错误处理	可抛出异常或返回错误码	通过回调参数传递错误信息
性能影响	同步调用会阻塞 JS 线程	异步调用不阻塞

最佳实践建议：

// 统一使用异步 Promise 封装，抹平平台差异
class JSBridge {
  call(method, params = {}) {
    return new Promise((resolve, reject) => {
      const callbackId = this.generateCallbackId();
      this.callbacks[callbackId] = { resolve, reject };

      if (this.isAndroid()) {
        // Android：即使是同步方法，也封装为异步
        try {
          const result = window.NativeBridge[method](JSON.stringify(params));
          this.handleCallback(callbackId, null, result);
        } catch (error) {
          this.handleCallback(callbackId, error.message, null);
        }
      } else if (this.isiOS()) {
        // iOS：发送消息，等待回调
        window.webkit.messageHandlers.invoke.postMessage({
          method,
          params,
          callbackId
        });
      }
    });
  }

  handleCallback(callbackId, error, result) {
    const callback = this.callbacks[callbackId];
    if (callback) {
      error ? callback.reject(new Error(error)) : callback.resolve(result);
      delete this.callbacks[callbackId];
    }
  }
}

// 统一调用方式
const bridge = new JSBridge();
bridge.call('getUserInfo', { userId: '123' })
  .then(userInfo => console.log(userInfo))
  .catch(error => console.error(error));

通过统一的 Promise 封装，可以屏蔽 Android 同步/异步和 iOS 纯异步的差异，为上层业务提供一致的调用体验。

统一 JSBridge 封装设计

为了抹平平台差异，通常需要设计一套统一的 JSBridge SDK。

统一调用接口设计

// JSBridge SDK 封装
class JSBridge {
  constructor() {
    this.callbacks = {};
    this.callbackId = 0;
  }

  // 调用原生方法
  call(method, params = {}) {
    return new Promise((resolve, reject) => {
      const callbackId = this.callbackId++;
      this.callbacks[callbackId] = { resolve, reject };

      const data = {
        method,
        params,
        callbackId
      };

      if (this.isAndroid()) {
        // Android 调用
        window.NativeBridge.invoke(JSON.stringify(data));
      } else if (this.isiOS()) {
        // iOS 调用
        window.webkit.messageHandlers.invoke.postMessage(data);
      } else {
        reject(new Error('不支持的平台'));
      }
    });
  }

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

  // 平台检测
  isAndroid() {
    return /Android/i.test(navigator.userAgent);
  }

  isiOS() {
    return /iPhone|iPad|iPod/i.test(navigator.userAgent);
  }
}

// 使用示例
const bridge = new JSBridge();

// 调用原生方法
bridge.call('getLocation', { timeout: 5000 })
  .then(location => {
    console.log('位置信息:', location);
  })
  .catch(error => {
    console.error('获取位置失败:', error);
  });

// 调用拍照功能
bridge.call('takePhoto', { quality: 0.8 })
  .then(photoData => {
    document.getElementById('photo').src = photoData;
  });

通讯协议设计

graph TD
    A[Web发起调用] --> B{检测平台}
    B -->|Android| C[NativeBridge.invoke]
    B -->|iOS| D[webkit.messageHandlers.invoke]
    C --> E[Native接收并解析]
    D --> E
    E --> F[执行对应功能]
    F --> G{是否需要返回}
    G -->|是| H[调用JS回调函数]
    G -->|否| I[结束]
    H --> J[Web Promise resolve]
    J --> I

完整调用流程示例

// 数据协议格式
const protocol = {
  method: 'getLocation',      // 方法名
  params: {                   // 参数
    timeout: 5000,
    enableHighAccuracy: true
  },
  callbackId: '1234567890'   // 回调ID
};

// Native 返回格式
const response = {
  callbackId: '1234567890',
  error: null,                // 错误信息
  result: {                   // 返回结果
    latitude: 39.9042,
    longitude: 116.4074,
    accuracy: 10
  }
};

最佳实践建议

1. 安全性考虑

• Android 4.2+ 必须使用 @JavascriptInterface 注解
• 验证调用来源，防止恶意网页调用
• 敏感操作需要二次确认

// Android 端权限验证示例
@JavascriptInterface
public void deleteUser(String userId) {
  // 验证当前页面域名
  String url = webView.getUrl();
  if (!url.startsWith("https://yourdomain.com")) {
    Log.e("JSBridge", "非法调用来源: " + url);
    return;
  }

  // 执行删除操作
  performDeleteUser(userId);
}

2. 性能优化

• 减少频繁的跨语言调用
• 批量传输数据而非多次单个传输
• 对大数据使用本地存储中转

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

  enqueue(method, params) {
    return new Promise((resolve, reject) => {
      this.queue.push({ method, params, resolve, reject });
      this.scheduleFlush();
    });
  }

  scheduleFlush() {
    if (this.timer) return;
    this.timer = setTimeout(() => {
      this.flush();
    }, 16); // 一帧时间内批量处理
  }

  flush() {
    const batch = this.queue.splice(0);
    this.timer = null;

    // 批量调用
    this.bridge.call('batchInvoke', { calls: batch })
      .then(results => {
        batch.forEach((item, index) => {
          item.resolve(results[index]);
        });
      });
  }
}

3. 调试支持

// 开发环境调试工具
class JSBridgeDebugger {
  static enable() {
    const originalCall = JSBridge.prototype.call;

    JSBridge.prototype.call = function(method, params) {
      console.group(`📱 JSBridge Call: ${method}`);
      console.log('参数:', params);
      console.time('耗时');

      return originalCall.call(this, method, params)
        .then(result => {
          console.log('返回:', result);
          console.timeEnd('耗时');
          console.groupEnd();
          return result;
        })
        .catch(error => {
          console.error('错误:', error);
          console.timeEnd('耗时');
          console.groupEnd();
          throw error;
        });
    };
  }
}

// 开发环境启用
if (process.env.NODE_ENV === 'development') {
  JSBridgeDebugger.enable();
}

通讯时序总览

sequenceDiagram
    participant W as Web层
    participant JS as JSBridge SDK
    participant A as Android Native
    participant I as iOS Native

    rect rgb(240, 248, 255)
        Note over W,I: 场景1: Web 调用 Native 获取设备信息
        W->>JS: bridge.call('getDeviceInfo')
        JS->>JS: 生成 callbackId
        alt Android 平台
            JS->>A: NativeBridge.invoke(data)
            A->>A: 获取设备信息
            A->>JS: window.handleCallback(id, result)
        else iOS 平台
            JS->>I: webkit.messageHandlers.invoke
            I->>I: 获取设备信息
            I->>JS: evaluateJavaScript(callback)
        end
        JS->>W: Promise.resolve(deviceInfo)
    end

    rect rgb(255, 250, 240)
        Note over W,I: 场景2: Native 主动通知 Web
        alt Android 平台
            A->>JS: evaluateJavascript('onNetworkChange')
        else iOS 平台
            I->>JS: evaluateJavaScript('onNetworkChange')
        end
        JS->>W: 触发事件监听器
        W->>W: 更新 UI
    end

Android 和 iOS 平台的 JSBridge 虽然底层实现机制不同，但核心思想一致：建立 Native 与 Web 之间的双向通讯通道。通过统一的 SDK 封装，可以为上层业务提供一致的调用接口，屏蔽平台差异。在实际开发中，需要根据具体场景选择合适的通讯方式，并注重安全性、性能和可维护性。

WebView封装方案

腾讯x5WebView封装方案

腾讯 x5 内核是基于 Chromium 深度优化的 WebView 解决方案，专为解决 Android 系统原生 WebView 的碎片化、兼容性和性能问题而设计。通过 TBS（腾讯浏览服务）SDK 集成 x5 内核，可以为 Hybrid 应用提供统一、高性能的 Web 渲染能力。

x5 内核核心优势

mindmap
  root((x5内核))
    统一性
      统一内核版本
      抹平系统差异
      降低兼容成本
    性能
      加载速度提升30%
      渲染性能优化
      内存占用优化
    功能增强
      视频全屏播放
      文件预览
      广告拦截
    安全性
      漏洞及时修复
      HTTPS优化
      隐私保护

对比项	系统 WebView	腾讯 x5 内核
内核版本	随系统版本变化，碎片化严重	统一 Chromium 内核，自动更新
兼容性	Android 4.x-13+ 表现差异大	统一渲染标准，兼容性好
视频播放	部分机型不支持全屏	支持同层播放、全屏播放
文件预览	需要跳转第三方应用	内置 TBS 文件预览（Office、PDF）
加载性能	一般	加载速度提升 30%+
包体积	无额外体积	首次加载约 40MB（共享内核）

x5 内核集成流程

x5 内核采用按需加载策略，首次使用时会下载内核文件，后续应用共享同一内核。

graph LR
    A[应用启动] --> B{检测本地<br/>x5内核}
    B -->|已存在| C[加载x5内核]
    B -->|不存在| D[下载x5内核]
    D --> E{下载成功?}
    E -->|是| C
    E -->|否| F[降级使用<br/>系统WebView]
    C --> G[初始化WebView]
    F --> G
    G --> H[加载Web页面]

    style C fill:#90EE90
    style F fill:#FFB6C1
    style H fill:#87CEEB

集成步骤

1. 添加依赖

在 Android 项目中集成 TBS SDK：

// build.gradle (Module: app)
dependencies {
  // 腾讯 TBS SDK
  implementation 'com.tencent.tbs:tbssdk:44286'
}

// AndroidManifest.xml 添加权限
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

2. 初始化 x5 内核

在 Application 中初始化 TBS SDK，建议在应用启动时预加载内核以提升首次使用体验。

// Android 代码（Application）
public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    initX5WebView();
  }

  private void initX5WebView() {
    // x5 内核初始化配置
    QbSdk.PreInitCallback callback = new QbSdk.PreInitCallback() {
      @Override
      public void onCoreInitFinished() {
        // 内核初始化完成
        Log.d("X5", "内核初始化完成");
      }

      @Override
      public void onViewInitFinished(boolean success) {
        // WebView 初始化结果
        Log.d("X5", "内核加载" + (success ? "成功" : "失败，使用系统内核"));
      }
    };

    // 可选：设置下载策略
    QbSdk.setDownloadWithoutWifi(true); // 允许非 WiFi 下载

    // 预初始化内核
    QbSdk.initX5Environment(getApplicationContext(), callback);
  }
}

初始化配置说明：

• onCoreInitFinished()：内核初始化完成回调，此时可进行一些准备工作
• onViewInitFinished()：内核加载结果回调，success=true 表示使用 x5 内核，false 则降级使用系统 WebView
• setDownloadWithoutWifi()：控制是否允许在非 WiFi 环境下下载内核

3. 封装 X5WebView 组件

创建一个统一的 WebView 封装类，集成常用配置和 JSBridge。

// Android 代码（Java）
public class X5WebViewWrapper {
  private com.tencent.smtt.sdk.WebView webView;
  private Context context;
  private JSBridgeInterface jsBridge;

  public X5WebViewWrapper(Context context, ViewGroup container) {
    this.context = context;
    this.webView = new com.tencent.smtt.sdk.WebView(context);
    this.jsBridge = new JSBridgeInterface(context);

    initWebViewSettings();
    initJSBridge();

    container.addView(webView);
  }

  private void initWebViewSettings() {
    WebSettings settings = webView.getSettings();

    // 基础配置
    settings.setJavaScriptEnabled(true);
    settings.setDomStorageEnabled(true);
    settings.setDatabaseEnabled(true);
    settings.setAppCacheEnabled(true);

    // 缓存策略
    settings.setCacheMode(WebSettings.LOAD_DEFAULT);

    // 视口配置
    settings.setUseWideViewPort(true);
    settings.setLoadWithOverviewMode(true);

    // 缩放配置
    settings.setSupportZoom(false);
    settings.setBuiltInZoomControls(false);

    // x5 内核特性配置
    settings.setAllowFileAccess(true);

    // 视频播放配置（x5 特色功能）
    settings.setMediaPlaybackRequiresUserGesture(false);
  }

  private void initJSBridge() {
    // 注入 JSBridge
    webView.addJavascriptInterface(jsBridge, "NativeBridge");

    // 配置 WebViewClient
    webView.setWebViewClient(new com.tencent.smtt.sdk.WebViewClient() {
      @Override
      public void onPageFinished(com.tencent.smtt.sdk.WebView view, String url) {
        super.onPageFinished(view, url);
        // 页面加载完成，注入桥接代码
        injectBridgeScript();
      }
    });

    // 配置 WebChromeClient
    webView.setWebChromeClient(new com.tencent.smtt.sdk.WebChromeClient() {
      @Override
      public void onProgressChanged(com.tencent.smtt.sdk.WebView view, int progress) {
        // 加载进度回调
      }
    });
  }

  private void injectBridgeScript() {
    String bridgeScript =
      "window.bridge = {" +
      "  call: function(method, params) {" +
      "    return new Promise((resolve, reject) => {" +
      "      const callbackId = Date.now() + Math.random();" +
      "      window['cb_' + callbackId] = resolve;" +
      "      NativeBridge.invoke(method, JSON.stringify(params), callbackId);" +
      "    });" +
      "  }" +
      "};";

    webView.evaluateJavascript(bridgeScript, null);
  }

  public void loadUrl(String url) {
    webView.loadUrl(url);
  }

  public com.tencent.smtt.sdk.WebView getWebView() {
    return webView;
  }

  public void destroy() {
    if (webView != null) {
      webView.destroy();
    }
  }
}

x5 内核特色功能实现

1. 视频同层播放

x5 内核支持视频同层播放，避免视频自动全屏覆盖页面元素。

// Android 端配置
webView.getSettingsExtension().setPageCacheCapacity(IX5WebSettings.DEFAULT_CACHE_CAPACITY);

// 开启视频同层播放
Bundle params = new Bundle();
params.putBoolean("standardFullScreen", false); // 关闭标准全屏
params.putBoolean("supportLiteWnd", false);     // 关闭小窗播放
params.putInt("DefaultVideoScreen", 2);         // 1: 同层播放, 2: 全屏播放
webView.getX5WebViewExtension().invokeMiscMethod("setVideoParams", params);

// Web 端配置（HTML5 video 标签）
// 添加以下属性实现同层播放
<video
  src="video.mp4"
  webkit-playsinline="true"
  playsinline="true"
  x5-video-player-type="h5"
  x5-video-player-fullscreen="false"
  x5-video-orientation="portraint"
></video>

x5 视频属性说明：

• x5-video-player-type="h5"：启用 H5 同层播放器
• x5-video-player-fullscreen：是否全屏播放
• x5-video-orientation：横竖屏方向（landscape / portraint）

2. 文件预览功能

x5 内核内置了 TBS 文件预览能力，支持 Office（Word、Excel、PPT）和 PDF 文件。

// Android 端调用文件预览
public void openFileReader(String filePath) {
  Bundle params = new Bundle();
  params.putString("filePath", filePath);
  params.putString("tempPath", context.getCacheDir().getPath());

  boolean result = QbSdk.getMiniQBVersion(context) != null
    && QbSdk.openFileReader(
        context,
        filePath,
        params,
        new ValueCallback<String>() {
          @Override
          public void onReceiveValue(String s) {
            Log.d("TBS", "文件预览: " + s);
          }
        }
      );

  if (!result) {
    Toast.makeText(context, "文件预览失败", Toast.LENGTH_SHORT).show();
  }
}

// Web 端调用示例
window.bridge.call('openFile', {
  url: 'https://example.com/document.pdf',
  fileName: 'document.pdf'
}).then(() => {
  console.log('文件预览已打开');
});

3. 内核调试工具

x5 提供了内核信息查询接口，便于调试和问题排查。

// Android 端获取内核信息
public Map<String, String> getX5Info() {
  Map<String, String> info = new HashMap<>();

  // 是否使用 x5 内核
  info.put("isX5Core", String.valueOf(QbSdk.isTbsCoreInited()));

  // 内核版本号
  info.put("coreVersion", String.valueOf(QbSdk.getTbsVersion(context)));

  // SDK 版本号
  info.put("sdkVersion", String.valueOf(QbSdk.getTbsSdkVersion()));

  return info;
}

// Web 端调用
window.bridge.call('getWebViewInfo').then(info => {
  console.log('WebView 信息:', info);
  // { isX5Core: "true", coreVersion: "44286", sdkVersion: "44286" }
});

x5WebView 完整调用流程

sequenceDiagram
    participant App as Android App
    participant X5 as X5WebView
    participant TBS as TBS内核
    participant Web as Web页面
    participant Server as 服务器

    App->>X5: 初始化X5WebView
    X5->>TBS: 检查内核状态

    alt 内核已加载
        TBS-->>X5: 返回内核实例
    else 内核未加载
        TBS->>Server: 下载内核文件
        Server-->>TBS: 返回内核包
        TBS->>TBS: 解压安装
        TBS-->>X5: 返回内核实例
    end

    X5->>Web: loadUrl(url)
    Web->>Server: 请求页面资源
    Server-->>Web: 返回HTML/CSS/JS
    Web->>Web: 渲染页面

    Web->>X5: 调用JSBridge
    X5->>App: 执行Native方法
    App-->>X5: 返回结果
    X5-->>Web: 触发回调

    Note over App,Web: 支持视频同层播放、文件预览等特色功能

统一 WebView 管理方案

在实际项目中，通常需要统一管理 x5 WebView 和系统 WebView，实现无缝降级。

// WebView 工厂类
class WebViewFactory {
  static createWebView(context, container) {
    if (this.isX5Available()) {
      return new X5WebViewWrapper(context, container);
    } else {
      return new SystemWebViewWrapper(context, container);
    }
  }

  static isX5Available() {
    return QbSdk.isTbsCoreInited();
  }
}

// 使用示例
const webViewWrapper = WebViewFactory.createWebView(context, container);
webViewWrapper.loadUrl('https://example.com');

// Web 端统一调用接口（自动适配）
window.bridge.call('getLocation').then(location => {
  console.log('当前位置:', location);
});

x5 内核架构设计

graph TB
    subgraph 应用层
        A1[业务代码]
        A2[JSBridge SDK]
    end

    subgraph 封装层
        B1[X5WebView<br/>Wrapper]
        B2[System WebView<br/>Wrapper]
        B3[WebView Factory]
    end

    subgraph 内核层
        C1[TBS x5内核<br/>Chromium 90+]
        C2[系统WebView<br/>随系统版本]
    end

    subgraph 能力层
        D1[视频播放]
        D2[文件预览]
        D3[广告拦截]
        D4[性能优化]
    end

    A1 --> A2
    A2 --> B3
    B3 --> B1
    B3 --> B2
    B1 --> C1
    B2 --> C2
    C1 --> D1
    C1 --> D2
    C1 --> D3
    C1 --> D4

    style B3 fill:#FFD700
    style C1 fill:#90EE90
    style C2 fill:#FFB6C1

性能优化策略

1. 内核预加载

在应用启动阶段预加载 x5 内核，提升首次 WebView 使用体验。

// 应用启动时预加载
public class SplashActivity extends Activity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // 异步预加载内核
    new Thread(() -> {
      QbSdk.preInit(getApplicationContext());

      // 预创建 WebView 实例（可选）
      runOnUiThread(() -> {
        new com.tencent.smtt.sdk.WebView(getApplicationContext());
      });
    }).start();
  }
}

2. 资源缓存策略

合理配置缓存策略，减少网络请求，提升加载速度。

// 缓存策略配置
webView.getSettings().setCacheMode(WebSettings.LOAD_DEFAULT);
webView.getSettings().setAppCachePath(context.getCacheDir().getPath());
webView.getSettings().setAppCacheMaxSize(50 * 1024 * 1024); // 50MB

// Web 端配合 Service Worker 离线缓存
// service-worker.js
self.addEventListener('install', event => {
  event.waitUntil(
    caches.open('v1').then(cache => {
      return cache.addAll([
        '/',
        '/styles.css',
        '/script.js',
        '/logo.png'
      ]);
    })
  );
});

self.addEventListener('fetch', event => {
  event.respondWith(
    caches.match(event.request).then(response => {
      return response || fetch(event.request);
    })
  );
});

3. 白屏优化

通过预渲染和骨架屏技术减少白屏时间。

// Android 端：WebView 预渲染
public class WebViewPool {
  private static Queue<com.tencent.smtt.sdk.WebView> pool = new LinkedList<>();

  public static void prepare(Context context, int count) {
    for (int i = 0; i < count; i++) {
      com.tencent.smtt.sdk.WebView webView =
        new com.tencent.smtt.sdk.WebView(context);
      pool.offer(webView);
    }
  }

  public static com.tencent.smtt.sdk.WebView obtain(Context context) {
    com.tencent.smtt.sdk.WebView webView = pool.poll();
    if (webView == null) {
      webView = new com.tencent.smtt.sdk.WebView(context);
    }
    return webView;
  }
}

// Web 端：骨架屏
// 在 HTML 中直接内联骨架屏样式
<div id="skeleton" style="
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background: #f5f5f5;
">
  <!-- 骨架屏内容 -->
</div>

<script>
  window.addEventListener('DOMContentLoaded', () => {
    document.getElementById('skeleton').remove();
  });
</script>

常见问题与解决方案

1. 内核加载失败降级

// 监听内核加载失败，自动降级
QbSdk.PreInitCallback callback = new QbSdk.PreInitCallback() {
  @Override
  public void onViewInitFinished(boolean success) {
    if (!success) {
      Log.w("X5", "x5内核加载失败，已降级到系统WebView");
      // 可选：上报统计
      reportX5LoadFailed();
    }
  }
};

2. 内核下载流量优化

// 仅在 WiFi 环境下下载内核
QbSdk.setDownloadWithoutWifi(false);

// 或者在用户确认后下载
if (!isWifiConnected()) {
  showDialog("检测到当前为移动网络，下载内核约40MB，是否继续？", () => {
    QbSdk.setDownloadWithoutWifi(true);
    QbSdk.initX5Environment(context, callback);
  });
}

3. 视频播放兼容性

// 统一视频播放配置
function setupVideoPlayer(videoElement) {
  // 检测是否为 x5 内核
  const isX5 = /TBS/i.test(navigator.userAgent);

  if (isX5) {
    // x5 内核特殊配置
    videoElement.setAttribute('x5-video-player-type', 'h5');
    videoElement.setAttribute('x5-video-player-fullscreen', 'false');
  } else {
    // iOS 内联播放
    videoElement.setAttribute('webkit-playsinline', 'true');
    videoElement.setAttribute('playsinline', 'true');
  }
}

// 使用
const video = document.createElement('video');
video.src = 'video.mp4';
setupVideoPlayer(video);

调试工具

x5 内核提供了专门的调试入口，可查看内核状态和日志。

// Android 端开启调试
if (BuildConfig.DEBUG) {
  // 开启 x5 内核调试模式
  QbSdk.setTbsLogClient(new TbsLogClient() {
    @Override
    public void writeLog(String log) {
      Log.d("TBS_LOG", log);
    }
  });

  // 开启 WebView 远程调试
  com.tencent.smtt.sdk.WebView.setWebContentsDebuggingEnabled(true);
}

// 浏览器访问 chrome://inspect 查看调试信息

调试页面访问方式：

1. 在 WebView 中访问 http://debugtbs.qq.com
2. 查看内核版本、加载状态、错误日志等信息
3. 可以手动触发内核下载、重置等操作

最佳实践总结

graph LR
    A[x5 最佳实践] --> B[初始化]
    A --> C[性能]
    A --> D[兼容性]
    A --> E[安全性]

    B --> B1[应用启动时预初始化]
    B --> B2[配置合理的下载策略]

    C --> C1[WebView 复用池]
    C --> C2[资源缓存策略]
    C --> C3[预渲染 + 骨架屏]

    D --> D1[自动降级机制]
    D --> D2[统一封装接口]
    D --> D3[视频播放兼容处理]

    E --> E1[HTTPS 优先]
    E --> E2[域名白名单]
    E --> E3[敏感接口鉴权]

    style A fill:#4A90E2,color:#fff
    style B fill:#7ED321
    style C fill:#F5A623
    style D fill:#50E3C2
    style E fill:#D0021B,color:#fff

核心要点：

1. 初始化时机：Application 中预初始化，避免首次使用卡顿
2. 降级策略：内核加载失败时自动降级到系统 WebView，保证可用性
3. 性能优化：WebView 复用、资源缓存、预加载
4. 功能增强：利用 x5 特色功能（视频同层播放、文件预览）
5. 调试支持：开发环境开启调试模式，便于问题排查
6. 流量优化：默认仅 WiFi 下载内核，节省用户流量

通过合理的封装和配置，x5 内核可以为 Android Hybrid 应用提供统一、高性能的 Web 渲染能力，显著提升用户体验。