15 跨端与多端复用
  ├─ 前置：06 框架与组件化、08 路由与渲染
  ├─ 紧接：16 可视化（自绘引擎）、11 性能（端上指标）
  ├─ 交叉：05 浏览器（内核差异）、12 安全（WebView 安全）
  └─ 长期：17 架构（多端架构治理）

要最快触达、可分享 → H5
要平台流量与能力 → 小程序
要 App 内高性能多页 → RN
要强一致 UI 与动效 → Flutter
要桌面 → Electron（重）/ Tauri（轻）

H5 页面 ──调用──▶ Bridge（JS 侧）──▶ 原生容器 ──▶ 系统能力
        ◀──回调──                  ◀──

// 1) 原生向 WebView 注入全局对象（Android addJavascriptInterface / iOS WKScriptMessageHandler）
window.NativeBridge.invoke('camera.open', { quality: 'high' }, callbackId);

// 2) URL Scheme 拦截（老方案，兼容好但性能差）
location.href = 'app://camera/open?callbackId=123';

/**
 * 一个健壮的 Bridge 封装：回调、超时、异常、队列。
 * 这是 Hybrid 应用最容易出「偶发无响应」的地方。
 */
const pending = new Map();
let seq = 0;

function invoke(method, params = {}, { timeout = 5000 } = {}) {
  return new Promise((resolve, reject) => {
    const id = `cb_${++seq}`;

    const timer = setTimeout(() => {
      pending.delete(id);
      reject(new Error(`Bridge 超时: ${method}`));
    }, timeout);

    pending.set(id, {
      resolve: (data) => { clearTimeout(timer); resolve(data); },
      reject: (err) => { clearTimeout(timer); reject(err); },
    });

    try {
      // 真实环境：Android/iOS 注入的对象名不同，需要适配
      window.NativeBridge?.invoke(method, JSON.stringify(params), id);
      if (!window.NativeBridge) {
        // 没有容器时降级为 H5 能力
        window.NativeBridgeFallback?.(method, params);
      }
    } catch (err) {
      clearTimeout(timer);
      pending.delete(id);
      reject(err);
    }
  });
}

/** 原生调用此方法回传结果。 */
window.__bridgeCallback = (id, ok, payload) => {
  const cb = pending.get(id);
  if (!cb) return;          // 已超时，丢弃
  pending.delete(id);
  ok ? cb.resolve(payload) : cb.reject(new Error(payload?.message ?? 'native error'));
};

/* 现代方案：优先用视口单位 + clamp，减少 JS 计算 */
.title {
  font-size: clamp(16px, 4vw, 22px);
}

/* 安全区：刘海屏/底部横条 */
.footer {
  padding-bottom: calc(12px + env(safe-area-inset-bottom));
}

/**
 * ❌ UA 判断脆弱：容器可以伪装、版本会变
 */
const isIOS = /iPhone/.test(navigator.userAgent);

/**
 * ✅ 能力探测：关心「能不能用」，而不是「是什么」
 */
const canUseCamera = Boolean(navigator.mediaDevices?.getUserMedia);
const canUseShare = Boolean(navigator.share);

/** 平台只用于「交互习惯」这类无法探测的差异。 */
function getPlatform() {
  if (typeof wx !== 'undefined' && wx.getSystemInfoSync) return 'miniprogram';
  if (window.ReactNativeWebView) return 'rn-webview';
  if (/Electron/.test(navigator.userAgent)) return 'electron';
  return 'web';
}

渲染层（WebView）：WXML + WXSS
逻辑层（JSCore）：JS
两者通过 setData 通信（跨线程，数据要序列化）

/**
 * setData 优化：只传变化的字段，用路径语法。
 */
// ❌ 整棵树重传
this.setData({ list: newList });

// ✅ 只更新某一项
this.setData({ [`list[${index}].status`]: 'done' });

<link rel="manifest" href="/manifest.webmanifest" />

{
  "name": "订单助手",
  "short_name": "订单",
  "start_url": "/",
  "display": "standalone",
  "icons": [{ "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" }]
}

/** Service Worker：离线缓存与后台能力 */
self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((cached) => cached ?? fetch(event.request)),
  );
});

/**
 * JSBridge 调用封装：注入等待、超时、回调管理与错误规范化。
 * @param {{call: (method: string, params: object, cb: Function) => void}} native
 */
function createBridge(native) {
  const pending = new Map();
  let seq = 0;

  /** 等待原生注入，最多 3 秒 */
  const ready = new Promise((resolve, reject) => {
    const start = Date.now();
    const timer = setInterval(() => {
      if (native?.call) {
        clearInterval(timer);
        resolve();
      } else if (Date.now() - start > 3000) {
        clearInterval(timer);
        reject(new Error('bridge timeout'));
      }
    }, 50);
  });

  /**
   * 调用原生能力。
   * @param {string} method 方法名
   * @param {object} [params] 参数
   * @param {number} [timeout=8000] 超时毫秒
   */
  const invoke = async (method, params = {}, timeout = 8000) => {
    await ready;
    const id = ++seq;

    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => {
        pending.delete(id);
        reject(new Error(`bridge timeout: ${method}`));
      }, timeout);

      pending.set(id, { resolve, reject, timer });

      native.call(method, { ...params, callbackId: id }, (result) => {
        const task = pending.get(id);
        if (!task) return; // 已超时，忽略迟到回调
        pending.delete(id);
        clearTimeout(task.timer);
        if (result?.code === 0) task.resolve(result.data);
        else task.reject(new Error(result?.message ?? 'native error'));
      });
    });
  };

  return { ready, invoke };
}

离线包流程：
构建 → 上传 CDN → 客户端检查版本 → 下载 → 校验 → 解压 → WebView 加载本地文件

旧架构：JS 线程 ──Bridge（异步、序列化）──▶ 原生 UI 线程
新架构（Fabric + JSI）：
  JS ←─ 同步调用（JSI，C++ 层）─→ 原生
  渲染用 Shadow Tree + 并发特性

┌─────────────────────────────┐
│ 业务逻辑 / 状态 / 校验       │  100% 复用（纯 JS/TS）
├─────────────────────────────┤
│ 数据请求 / 领域模型          │  90% 复用（适配层隔离差异）
├─────────────────────────────┤
│ 组件结构 / 交互逻辑          │  60% 复用（平台组件映射）
├─────────────────────────────┤
│ 样式 / 布局 / 动效           │  30% 复用（单位与能力差异）
├─────────────────────────────┤
│ 端能力（相机/支付/分享）      │  0% 复用（抽象接口 + 多实现）
└─────────────────────────────┘

/**
 * 端能力抽象层：业务只依赖接口，各端提供实现。
 * 这是跨端项目最重要的架构决策。
 */
export interface PlatformAdapter {
  openCamera(options: { quality: 'low' | 'high' }): Promise<string>;
  share(payload: { title: string; url: string }): Promise<void>;
  getSafeArea(): { top: number; bottom: number };
  toast(message: string): void;
}

// web.ts / miniprogram.ts / native.ts 各自实现
export const platform: PlatformAdapter = createAdapter();

/**
 * 用「同名组件 + 平台实现」屏蔽差异。
 * 业务只写 <Page><Button/></Page>。
 */
// components/index.web.tsx
export const Button = ({ children, onClick }) => (
  <button className="btn" onClick={onClick}>{children}</button>
);

// components/index.miniprogram.tsx
export const Button = ({ children, onClick }) => (
  <View className="btn" onClick={onClick}>{children}</View>
);

{
  "pages": ["pages/index/index"],
  "subpackages": [
    { "root": "packageOrder", "pages": ["list/index", "detail/index"] },
    { "root": "packageUser", "pages": ["profile/index"] }
  ],
  "preloadRule": {
    "pages/index/index": { "network": "all", "packages": ["packageOrder"] }
  }
}

/* 必须配合 viewport-fit=cover 才生效 */
.page {
  padding-top: env(safe-area-inset-top);
  padding-bottom: calc(env(safe-area-inset-bottom) + 16px);
}

/* 底部固定操作栏 */
.action-bar {
  position: fixed;
  inset: auto 0 0 0;
  padding-bottom: env(safe-area-inset-bottom);
}

:root {
  --color-bg: #ffffff;
  --color-text: #1f2329;
  --space-2: 8px;
  --radius-md: 8px;
  --font-body: clamp(14px, 3.8vw, 16px);
  --duration-fast: 150ms;
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #111418;
    --color-text: #e6e8eb;
  }
}

/* 逻辑属性适配 RTL，不用写两套 */
.card {
  padding-inline: var(--space-2);
  border-start-start-radius: var(--radius-md);
}

收益：像素级一致、复杂动效流畅、跨平台行为统一
代价：包体大（引擎）、原生控件需自实现、无障碍与输入法适配难、生态较小

/**
 * 能力注册表：支持多实现、按环境选择、可测试。
 */
type CapabilityMap = {
  camera: { open(opts: { quality: 'low' | 'high' }): Promise<string> };
  payment: { pay(orderId: string): Promise<{ status: 'ok' | 'cancel' | 'fail' }> };
};

const registry = new Map<string, unknown>();

export function register<K extends keyof CapabilityMap>(name: K, impl: CapabilityMap[K]) {
  registry.set(name, impl);
}

export function use<K extends keyof CapabilityMap>(name: K): CapabilityMap[K] {
  const impl = registry.get(name);
  if (!impl) throw new Error(`能力未注册: ${String(name)}`);
  return impl as CapabilityMap[K];
}

端上首屏链路：
点击 → 容器创建 → WebView 初始化 → 加载 HTML → 解析 → JS 执行 → 请求数据 → 渲染
      ↑ 预创建可省            ↑ 离线包可省        ↑ 预取可省

App 容器版本：8.0 / 8.1 / 8.2
  × JS bundle：b120 / b121 / b122
  × 接口版本：v1 / v2
  × 配置开关：on / off

/**
 * 稳定分桶：同一 userId 在任意端、任意次都得到同一结果。
 * @param {string} userId
 * @param {number} percent 0–100
 */
function inGray(userId, percent) {
  let hash = 0;
  for (let i = 0; i < userId.length; i += 1) {
    hash = (hash * 31 + userId.charCodeAt(i)) >>> 0;
  }
  return hash % 100 < percent;
}

阶段 1：H5 兜底（快速上线）
阶段 2：核心页做离线包/RN（提升体验）
阶段 3：抽公共逻辑与组件库（降低重复）
阶段 4：能力层标准化（新增端成本最低）

packages/
├─ domain/          纯 TS：会员模型、等级计算、权益规则（100% 复用）
├─ data/            请求与缓存（复用，适配不同网关）
├─ ui/              组件（平台映射：View/div，Button 双实现）
├─ platform/        能力实现（share/pay/toast/safeArea）
└─ apps/
   ├─ web/          H5 入口
   ├─ miniprogram/  小程序入口
   └─ app-webview/  App 内嵌入口

/**
 * 等级计算放 domain：三端共用同一套规则，避免「H5 说 gold，小程序说 silver」。
 */
export function calcLevel(points: number): 'bronze' | 'silver' | 'gold' {
  if (points >= 5000) return 'gold';
  if (points >= 1000) return 'silver';
  return 'bronze';
}

/**
 * 能力差异只在 platform 层出现。
 */
export const platform = {
  async share(payload: { title: string; url: string }) {
    if (typeof wx !== 'undefined') {
      return wx.shareAppMessage({ title: payload.title, path: payload.url });
    }
    if (navigator.share) return navigator.share(payload);
    await copyToClipboard(payload.url); // 降级
  },
};

:root {
  --space-4: 16px;
  --font-title: 20px;
}
/* 小程序：rpx 映射由构建处理；RN：StyleSheet 由适配层转换 */

/**
 * 简化 JSBridge：H5 调用原生，按 callbackId 回调。
 * 原生侧需在完成后调用 window.__bridgeCallback(id, payload)。
 */
const bridge = (() => {
  let seq = 0;
  /** @type {Map<string, {resolve: Function, timer: number}>} */
  const pending = new Map();

  // 原生回调入口
  window.__bridgeCallback = (id, payload) => {
    const item = pending.get(id);
    if (!item) return;
    pending.delete(id);
    clearTimeout(item.timer);
    item.resolve(payload);
  };

  /**
   * 调用原生方法。
   * @param {string} method 方法名
   * @param {object} [params] 参数（必须可 JSON 序列化）
   * @param {{timeout?: number}} [options]
   * @returns {Promise<any>}
   */
  const call = (method, params = {}, { timeout = 5000 } = {}) =>
    new Promise((resolve, reject) => {
      const id = `cb_${Date.now()}_${++seq}`;
      const timer = setTimeout(() => {
        pending.delete(id);
        reject(new Error(`bridge timeout: ${method}`));
      }, timeout);
      pending.set(id, { resolve, timer });

      const message = JSON.stringify({ id, method, params });
      if (window.webkit?.messageHandlers?.bridge) {
        window.webkit.messageHandlers.bridge.postMessage({ id, method, params });
      } else if (window.androidBridge?.postMessage) {
        window.androidBridge.postMessage(message);
      } else {
        clearTimeout(timer);
        pending.delete(id);
        reject(new Error('bridge unavailable'));
      }
    });

  return { call };
})();

/**
 * 计算两次数据的最小变更路径，供 setData 使用。
 * @param {object} prev 旧数据
 * @param {object} next 新数据
 * @param {string} [prefix=''] 路径前缀
 * @returns {Record<string, any>} 路径 → 新值
 */
function diffData(prev, next, prefix = '') {
  const patch = {};

  Object.keys(next).forEach((key) => {
    const path = prefix ? `${prefix}.${key}` : key;
    const a = prev?.[key];
    const b = next[key];

    if (b === a) return;

    const bothObject =
      a && b && typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b);

    if (bothObject) {
      Object.assign(patch, diffData(a, b, path));
    } else {
      patch[path] = b;
    }
  });

  // 被删除的键要显式置 undefined
  Object.keys(prev ?? {}).forEach((key) => {
    if (!(key in (next ?? {}))) {
      patch[prefix ? `${prefix}.${key}` : key] = undefined;
    }
  });

  return patch;
}