HarmonyOS鸿蒙Next中关于原生与H5通信方式

鸿蒙原生应用与内嵌 H5 页面通信机制详解

在鸿蒙（HarmonyOS）应用开发中，原生模块与内嵌 Web 组件（WebView）中的 H5 页面进行交互是常见需求。鸿蒙系统提供了两种主要通信机制，各有其适用场景和特点：

1. 基于消息端口的双向异步通信 (类似 postMessage 机制)

这是最灵活、推荐用于复杂或频繁交互的通信方式，其核心在于建立一对消息端口 (MessagePorts) 作为双向通道。

步骤详解：

创建端口对：

在原生端，通过 WebviewController 的 createMessagePorts() 方法创建一对相互关联的消息端口。例如：

let ports = webviewController.createMessagePorts(); // ports[0] 和 ports[1]

传递端口到 H5：

原生端将其中一个端口（如 ports[1]）通过 WebviewController 的 postMessage() 方法发送到 H5 页面。此步骤相当于将通信的“钥匙”交给 H5。

webviewController.postMessage("initPort", [ports[1]], "*");

H5 接收并缓存端口：

H5 页面在 window 对象上监听 'message' 事件。当收到携带端口信息的消息（如事件名为 "initPort"）时，提取该端口对象并全局缓存（例如存储在 window 或一个模块变量中）。

window.addEventListener('message', (event) => {
  if (event.data && event.data.type === 'initPort') {
    window.harmonyPort = event.ports[0]; // 存储接收到的端口
  }
});

H5 通过端口发送消息：

H5 使用缓存的端口 (window.harmonyPort) 的 postMessage() 方法向原生端发送消息。

window.harmonyPort.postMessage({ action: 'h5Event', data: ... });

原生端监听端口消息：

原生端持有另一个端口（如 ports[0]），在其上设置 onMessage 监听器，接收来自 H5 的消息。

ports[0].onMessage((message) => {
  // 处理来自 H5 的消息: message.data
});

原生端通过端口回复/发起通信：

原生端同样可以使用 ports[0].postMessage() 主动向 H5 发送消息。H5 端也需要在缓存的端口 (window.harmonyPort) 上设置 onmessage 监听器来接收。

// H5 端监听原生发来的消息
window.harmonyPort.onmessage = (event) => {
  // 处理来自原生的消息: event.data
};

特点：

• 真正的双向异步：双方都可以主动发起通信，无需对方事先调用某个特定方法。
• 安全隔离：通过专门的端口通信，遵循 Web 的安全模型。
• 灵活性强：适合传输复杂数据结构，实现事件驱动型交互。

2. 基于 API 注入与脚本执行的双向调用

这种方式更直接，侧重于方法调用，但也需要处理好异步问题。

H5 调用原生方法 (JavaScriptProxy 注入)：

原生注册 API：

在原生端，使用 WebviewController 的 registerJavaScriptProxy() 方法，将一个包含特定方法集合的 Java/JS 对象注入到 H5 页面的 window 对象中（通常是一个命名空间对象，如 window.harmonyBridge）。

MyJsProxy jsProxy = new MyJsProxy(); // 包含 getLocation(), showToast() 等方法
webviewController.registerJavaScriptProxy(jsProxy, "harmonyBridge");

H5 直接调用：

H5 页面加载完成后，即可通过注入的全局对象（如 window.harmonyBridge）直接调用其暴露的方法。

window.harmonyBridge.getLocation(); // 同步调用

处理异步结果：

如果原生方法执行是异步的（如需要网络请求、硬件操作），H5 无法直接获得返回值。此时需要采用回调函数 (Callback) 机制：

• H5 调用原生异步方法时，传递一个回调函数作为参数。
• 原生方法执行完成（成功或失败）后，主动调用这个传递进来的回调函数，并将结果作为参数传回 H5。

// H5 调用
window.harmonyBridge.asyncFetchData((result) => {
  console.log('Received data from native:', result);
});

// 原生端 (MyJsProxy 类中)
public void asyncFetchData(JsCallback callback) {
    // ... 执行异步操作 ...
    new Handler(Looper.getMainLooper()).post(() -> {
        callback.call("Data from native async task");
    });
}

原生调用 H5 方法 (runJavaScript)：

原生端可以通过 WebviewController 的 runJavaScript() 方法，直接执行一段在 H5 页面上下文中运行的 JavaScript 代码。

这种方式通常用于：

• 调用 H5 页面中定义的全局函数 (window.myH5Function())，并传递参数。
• 设置 H5 页面的状态或变量。
• 获取 H5 页面的返回值（runJavaScript() 本身可以异步返回执行结果）。

// 原生调用 H5 的全局函数 updateUI(data)
String jsCode = "window.updateUI(" + jsonData + ");";
webviewController.runJavaScript(jsCode, (result) -> {
    // 可选：处理 jsCode 执行后的返回值 (如果有 return)
});

// 原生获取 H5 页面标题
webviewController.runJavaScript("document.title", (result) -> {
    String title = result != null ? result.toString() : "";
    // 使用 title...
});

特点：

• 简单直接：调用方式直观，类似本地函数调用。
• H5 调用原生：依赖注入，注入的方法在 H5 全局可见（需注意命名冲突和安全风险）。
• 原生调用 H5：需要知道 H5 全局函数或变量的确切名称。
• 异步处理：原生异步方法必须通过回调将结果传回 H5；runJavaScript 本身是异步操作，结果通过回调返回给原生。

关键注意事项总结：

1. 异步通信是常态：无论是消息端口还是 API 调用，原生与 H5 之间的通信绝大多数是异步的。切勿在 H5 中期望同步获取原生异步操作的结果，必须使用回调、Promise（如果封装支持）或监听端口消息来处理结果。
2. 端口管理：使用消息端口机制时，务必妥善管理端口的创建、传递、监听和关闭（通过 close() 方法）。避免内存泄漏和端口误用。
3. 注入安全：使用 registerJavaScriptProxy 时，仅注入 H5 必需的最小功能集，避免暴露过多原生能力或敏感接口，防止安全漏洞（如恶意脚本滥用注入的方法）。
4. 脚本执行安全：runJavaScript 功能强大但需谨慎。避免执行来源不可信或可能破坏 H5 页面逻辑的脚本。动态构建 JS 字符串时注意转义，防止注入攻击。
5. 生命周期协调：确保在原生组件（如承载 WebView 的 Ability/Page）和 H5 页面生命周期匹配时进行通信（例如，避免在 H5 卸载后尝试向其发送消息或调用其方法）。
6. 数据类型：通信时传递的数据需要是可序列化的（JSON 兼容类型：字符串、数字、布尔值、数组、普通对象）。复杂对象（如函数、DOM 元素）无法直接传递。
7. 命名空间：注入的全局对象名称（如 harmonyBridge）应具有唯一性，避免与 H5 现有全局变量或第三方库冲突。

总结：

鸿蒙原生与 H5 的通信主要依托两种模型：

• 消息端口 (MessagePorts)：提供安全、灵活、双向、事件驱动的通信通道，是处理复杂交互或需要原生主动通知 H5 场景的推荐方式。
• API 注入与脚本执行：
  • JavaScriptProxy 注入：使 H5 能直接调用暴露的原生方法，需处理好异步回调。
  • runJavaScript：使原生能直接执行 H5 脚本或调用 H5 全局函数/获取变量。

开发者应根据具体交互需求（如方向性、同步/异步、复杂度、安全性）选择最合适的通信机制，并始终牢记异步特性和安全最佳实践。