鸿蒙与 H5 通信使用的方法及原理

鸿蒙（HarmonyOS）与 H5 的通信主要通过 ‌**Web 组件（WebView）**‌ 实现，支持多种机制以满足不同场景需求。

‌一、通信方法‌

• ‌1. runJavaScript() 方法（原生 → H5） ‌

  鸿蒙原生侧通过 WebviewController.runJavaScript() 执行 H5 页面中的 JavaScript 代码，可调用全局函数、获取或修改页面数据。

  ‌特点 ‌：简单直接，适用于单向调用或轻量交互

  ‌示例‌：

  this.webviewController.runJavaScript('window.updateUI("data")');

• ‌2. registerJavaScriptProxy() / addJavaScriptObject()（H5 → 原生） ‌

  在鸿蒙侧将 ArkTS 方法或对象暴露给 H5，H5 通过全局对象（如 JSBridge）直接调用原生能力。

  ‌特点 ‌：支持双向异步通信，需注意命名冲突与安全风险

  ‌示例‌：

  @State jsBridge = new JsBridge();
  Web({
    src: $rawfile('index.html'),
    controller: this.controller
  })
  .javaScriptProxy({ object: this.jsBridge, name: 'JSBridge', methodList: ['nativeMethod'] });

• ‌3. postMessage() + WebMessagePort（双向异步通信） ‌

  基于 HTML5 的 postMessage 机制，通过 createWebMessagePorts() 创建一对消息端口，实现高效、安全的双向事件驱动通信。

  ‌特点 ‌：适合高频、大数据量或复杂交互场景，推荐用于生产环境

  ‌流程‌：

  1. 鸿蒙侧创建端口对 [port1, port2]
  2. 将 port2 发送给 H5（postMessage('initPort', [port2])）
  3. H5 缓存端口并监听消息
  4. 双方可通过 port.postMessage() 主动通信

• ‌**4. 第三方桥接库（如 DSBridge）**‌

‌二、通信原理‌

方式	通信方向	机制	适用场景
runJavaScript	原生 → H5	执行 JS 脚本	简单指令、数据注入
JSBridge 注入	H5 → 原生	暴露原生方法为全局对象	H5 调用原生功能（如相机、定位）
postMessage + MessagePort	双向	事件通道异步通信	高频、复杂、实时交互
DSBridge	双向	封装原生-JS 桥接	跨平台项目、快速集成

‌三、注意事项‌

• ‌异步为主‌：绝大多数通信为异步操作，H5 不能同步等待原生返回结果
• ‌数据序列化 ‌：传递的数据需为 JSON 兼容类型（字符串、数字、对象等），‌不能传递函数或 DOM 对象‌
• ‌安全防护 ‌：
  • 仅注入必要原生接口
  • 验证 postMessage 消息来源（检查 event.origin 或 event.source）
  • 避免动态拼接 JS 字符串以防注入攻击
• ‌生命周期管理‌：确保在 H5 页面加载完成后才发起通信，避免调用未定义的函数或对象