Bridge 工作原理

本文面向需要深入理解 Native ↔ WebView 通信机制的开发者

架构概览

┌─────────────────────────────────────────────────────────────┐
│                    MiniDev Studio (Electron)                  │
│   ┌──────────────┐   Bridge   ┌────────────────────────────┐ │
│   │  Native Host │  ◄──────►  │   WebView (Mini-App 页面)  │ │
│   │  (Node.js)   │            │   import woo from 'mini-sdk'│ │
│   └──────────────┘            └────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

调用流程

当 Mini-App 代码调用 woo.showToast('Hello') 时，内部发生了什么：

Mini-App WebView                    Native Host
─────────────────                   ───────────────────────────
woo.showToast('Hello')
    │
    ├── 序列化参数
    ├── 生成 callId
    │
    ▼
window.__bridgePostMessage({        ──► 接收消息
  api: 'showToast',                     │
  params: { title: 'Hello' },           ├── 调用原生 UI
  callId: 'call_001'                    ├── 等待用户交互
})                                      │
                                        ▼
                                    window.__bridgeCallback({
    ◄───────────────────────────────    callId: 'call_001',
                                        result: {},
                                        error: null
                                    })
    │
    ▼
Promise.resolve({})

多 WebView 页面栈

每次 navigateTo 都会创建一个新的 WebView 实例：

栈操作                      WebView 状态
─────────────────────       ─────────────────────────────
navigateTo('pages/B')  →    [WebView-A(hidden), WebView-B]
navigateTo('pages/C')  →    [WebView-A(hidden), WebView-B(hidden), WebView-C]
navigateBack()         →    [WebView-A(hidden), WebView-B] ← WebView-C 销毁
navigateBack()         →    [WebView-A] ← WebView-B 销毁

onBack 回调路由机制

onBack 是实现页面间数据传递的核心机制：

// Page A (WebView-A)
woo.navigateTo({
  url: 'pages/select',
  onBack(data) {
    // ① 此回调注册在 WebView-A 的 JS 上下文中
    console.log('选择结果：', data)
  },
})

// Page B (WebView-B) — 选择完成后
await woo.navigateBack({
  data: { selectedItem: 'item_42' },
  // ② Native 销毁 WebView-B，将 data 路由回 WebView-A
  // ③ WebView-A 中的 onBack 回调被触发
})

错误码体系

范围	含义
1xxxx	SDK 内部错误（API 未注册等）
2xxxx	权限与鉴权错误
4xxxx	客户端参数 / 用户行为错误
5xxxx	Native 内部错误

完整错误码见 错误处理 章节。

模拟器 vs 真机

特性	模拟器	真机
JS 上下文	共享（SPA 模式）	独立 WebView
Bridge	模拟实现	真实 Native
路由	Hash 路由	Pathname 路由
生命周期隔离	按路径模拟	天然隔离

SDK 内部自动检测运行环境，开发者无需关心差异。