一、前置思考

1.1 为什么要混合开发？

存量跨端项目 (RN/Flutter/uni-app) 要鸿蒙化:
  → 全部重写成本高、周期长、风险大
  → 渐进式鸿蒙化: 核心页面原生，存量页面先桥接

混合开发的本质:
  → 一个应用内，多个渲染引擎共存
  → 通过桥接层通信，共享业务状态和 Native 能力

1.2 混合开发的三种形态

形态A: 页面级混合
  → 原生页面 + RN/Flutter 页面互相跳转
  → 适合: 低频页面用跨端，核心体验用原生

形态B: 组件级混合
  → 原生页面内嵌入 RN/Flutter 组件
  → 适合: 复杂业务组件复用

形态C: 能力级混合
  → 跨端框架调用原生能力 (相机/支付/传感器)
  → 所有混合方案的必经之路

二、核心原理

2.1 混合渲染架构

┌─────────────────────────────────────────┐
│ ArkUI 宿主 (HarmonyOS 应用)               │
│  ┌──────────┐  ┌──────────┐  ┌────────┐  │
│  │ ArkUI 页面│  │ RN 页面   │  │ Flutter│  │
│  └────┬─────┘  └────┬─────┘  └───┬────┘  │
│       │             │            │        │
│  ┌────┴─────────────┴────────────┴─────┐ │
│  │ 桥接层 (Bridging Layer)              │ │
│  │  MethodChannel / JSI / FFI          │ │
│  └────┬───────────────────────────────┘ │
│  ┌────┴───────────────────────────────┐ │
│  │ HarmonyOS Native 能力 (Ability/API) │ │
│  └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘

渲染: 每套引擎自己渲染自己的 UI
通信: 桥接层做双向消息传递
状态: 共享业务状态通过桥接同步

2.2 桥接通信原理

ArkTS ←→ 桥接通道 ←→ RN/Flutter

双向通道:
  原生 → 跨端: 事件/状态推送 (invoke)
  跨端 → 原生: 能力调用/数据请求 (call)

消息模型:
  { method: 'takePhoto', args: { quality: 'high' }, callback: fn }
  → 桥接层序列化 → 目标端执行 → 结果回传

性能要点:
  → 批量消息: 高频小消息合并
  → 大数据: 共享内存/引用传递，避免序列化
  → 异步: 所有跨端调用异步，避免阻塞

2.3 Native 能力调用 (MethodChannel)

ReactNative 侧:
  NativeModules.CameraModule.takePhoto({quality: 'high'})
    .then(res => console.log(res.uri))

ArkTS 原生侧 (RN 桥):
  RN 的 TurboModule 实现:
    takePhoto(options, promise) {
      const uri = await this.camera.take(options);
      promise.resolve({ uri });
    }

Flutter 侧:
  MethodChannel('com.example.camera')
    .invokeMethod('takePhoto', {'quality': 'high'})

ArkTS 原生侧 (Flutter 桥):
  MethodChannel 处理器注册:
    onMethodCall(call, result) {
      if (call.method === 'takePhoto') {
        const uri = await camera.take(call.arguments);
        result.success({ uri });
      }
    }

2.4 渐进式鸿蒙化策略

第一步: 搭桥 (桥接层打通，跨端页面能跑)
第二步: 抽能力 (高频 Native 能力桥接化)
第三步: 换核心 (核心体验页面原生重写)
第四步: 缩占比 (跨端页面逐步替换，最后移除引擎)

每一阶段都可上线:
  → 先保证"能跑"，再优化"体验"，最后"替换"

三、源码/API 深度解析

3.1 桥接层设计

// 统一桥接协议 (协议中立，RN/Flutter 都走同一套)
export interface BridgeRequest {
  id: number;          // 请求 ID (用于响应匹配)
  method: string;      // 方法名: 'camera.takePhoto'
  args: Record<string, Object>;  // 参数
}

export interface BridgeResponse {
  id: number;
  ok: boolean;
  data?: Object;
  error?: string;
}

// ArkTS 侧桥接管理器
export class BridgeManager {
  private static reqSeq: number = 0;
  private static pending: Map<number, (r: BridgeResponse) => void> = new Map();

  static call(method: string, args: Record<string, Object>): Promise<Object> {
    const id = ++this.reqSeq;
    const req: BridgeRequest = { id, method, args };
    // 发送给跨端引擎
    this.postToEngine(req);
    // 返回 Promise，响应回来时 resolve
    return new Promise((resolve, reject) => {
      this.pending.set(id, (r) => r.ok ? resolve(r.data) : reject(new Error(r.error)));
    });
  }

  static onResponse(resp: BridgeResponse): void {
    const cb = this.pending.get(resp.id);
    if (cb) {
      this.pending.delete(resp.id);
      cb(resp);
    }
  }
}

3.2 共享状态同步

// 业务状态跨引擎同步: 事件广播
// 场景: 购物车数量变化 → 原生 TabBar + RN 页面同步更新

// 原生侧发布
export class StoreEventBus {
  private static listeners: Map<string, Array<(data: Object) => void>> = new Map();

  static publish(topic: string, data: Object): void {
    // 1. 通知本引擎监听者
    const list = this.listeners.get(topic);
    if (list) {
      for (const fn of list) {
        fn(data);
      }
    }
    // 2. 广播给跨端引擎
    BridgeManager.call('store.publish', { topic, data });
  }

  static subscribe(topic: string, fn: (data: Object) => void): void {
    if (!this.listeners.has(topic)) {
      this.listeners.set(topic, []);
    }
    this.listeners.get(topic)!.push(fn);
  }
}

// 跨端侧 (RN/Flutter) 订阅同一 topic
// → 无论哪端改状态，两端都收到通知，保持一致

3.3 混合工程结构

HarmonyOS 工程/
├── entry/                       # 原生宿主
│   ├── src/main/ets/            # ArkUI 页面 + 桥接层
│   └── src/main/cpp/            # 引擎集成 (RN/Flutter so)
├── react-native/                # RN 子工程 (页面包)
├── flutter_module/              # Flutter 子工程
└── bridge_spec/                 # 桥接协议定义 (共享)

关键: 桥接协议单独定义 → 两端依赖同一份契约
  → 改协议 = 两端同步改，杜绝"各说各话"

四、企业级实战落地

4.1 方案对比

维度	页面级混合	组件级混合	全量重写
成本	低 (搭桥即可)	中	高
风险	低	中	高
体验	中 (跨端受限)	较好	最好
周期	周级	月级	季度级
适用	存量快速鸿蒙化	核心组件复用	新应用

4.2 完整示例：混合开发演示

@Entry
@ComponentV2
struct HybridDevDemo {
  @Local bridgeCount: number = 0;
  @Local engine: string = 'ArkUI';
  @Local logs: string[] = [];

  private runHybridFlow(): void {
    this.logs = [];
    this.engine = '混合模式';
    this.log('🌐 混合开发架构演示');
    this.log('① ArkUI 页面: 列表页 (原生渲染)');
    this.log('② 详情页: 由 RN 渲染 (存量资产复用)');
    this.log('③ 图表组件: Flutter 渲染 (动画能力强)');
    this.log('④ 桥接调用: 购物车数量同步');
    this.bridgeCount++;
    this.log('   ArkUI 改数量 → 桥接广播 → RN 同步 ✅');
    this.log('⑤ Native 能力: RN 页面调用相机');
    this.log('   MethodChannel → 原生相机 → 回传 URI');
    this.log('⑥ 状态一致: 双端订阅同一 topic');
    this.log('⑦ 结论: 渐进式鸿蒙化可行, 核心页面原生');
  }

  build() {
    Column({ space: 12 }) {
      Text('🔗 混合开发演示').fontSize(20).fontWeight(FontWeight.Bold)
      Text('引擎: ' + this.engine + ' · 桥接次数: ' + this.bridgeCount).fontSize(13).fontColor('#4F46E5')

      Row({ space: 8 }) {
        Button('▶ 模拟混合调用').layoutWeight(1).height(40).fontSize(12)
          .onClick(() => this.runHybridFlow())
        Button('清空').height(40).fontSize(12)
          .onClick(() => this.logs = [])
      }
      .width('100%')

      Scroll() {
        Column() {
          ForEach(this.logs, (l: string) => {
            Text(l).fontSize(11).lineHeight(18).fontColor('#24292F').width('100%')
          }, (l: string, i: number) => l + i)
        }.width('100%')
      }
      .layoutWeight(1).width('100%').scrollBar(BarState.Off)
    }
    .width('100%').height('100%').padding(16)
    .backgroundColor('#F6F8FA')
  }
}

4.3 混合开发落地清单

1. 桥接协议先行: 先定协议再动工，两端同步开发
2. 能力盘点: 高频 Native 能力优先桥接
3. 性能打点: 记录桥接耗时，发现热点
4. 降级方案: 桥接失败 → 原生兜底逻辑
5. 引擎瘦身: 只保留需要的引擎，控制包体积

五、问题排查与性能优化

问题	原因	解决
页面切换卡顿	引擎切换开销	预创建引擎 + 常驻
桥接消息丢失	无确认机制	消息 ID + 超时重试
双端状态不一致	同步时机错	事件总线 + 幂等处理
包体积暴涨	引擎重复	共享引擎实例
内存压力大	多引擎共存	按需加载 + 销毁释放
通信阻塞	同步调用	全部改异步

5.1 混合性能优化

1. 引擎常驻: 避免频繁创建销毁 (创建成本高)
2. 消息合并: 高频小消息批量发送
3. 共享内存: 大数据用指针传递，不走序列化
4. 渲染分工: 动画/图表给 Flutter，列表给原生
5. 降级优先: 桥接异常时原生兜底，保证可用性

六、高阶总结与最佳实践

1. 渐进式是王道：存量项目鸿蒙化不是重写，是搭桥—换核—缩占比。
2. 协议先行：桥接契约单独定义，两端遵循同一份规范。
3. 能力复用：Native 能力桥接化后，所有引擎共享。
4. 状态要一致：事件总线 + 幂等，双端永远看到同一份业务状态。
5. 体验分场景：核心体验原生、存量页面桥接、动画图表给专业引擎。

一句话记住：混合开发 = 统一桥接协议 + 多引擎共存 + Native 能力复用 + 事件总线同步，让存量跨端资产平滑鸿蒙化，核心体验依然原生。