一、前言：为什么需要鸿蒙和H5通信？
现在大部分鸿蒙商用项目、政企项目、混合开发项目，都是 原生页面 + H5页面混合开发 的模式：
这就出现了核心需求：H5需要调用鸿蒙原生能力，鸿蒙原生也需要给H5传值、通知H5刷新页面。
很多开发者踩坑：通信调用无反应、参数接收错乱、页面销毁报错、重复注册、H5回调失效、白屏报错等。
本文用最简单的语言、最全可运行案例，彻底讲透鸿蒙 <> H5 双向通信所有场景，零基础也能看懂，代码直接复制可用。
二、通信核心原理（一句话听懂）
2.1 两个核心角色
2.2 两种通信场景
H5 → 鸿蒙：H5触发事件，调用鸿蒙原生方法（如H5点击按钮唤起鸿蒙相机、弹窗、分享）
鸿蒙 → H5：鸿蒙主动给H5传值、通知H5刷新页面、传递登录态、设备信息
2.3 核心API
鸿蒙注册方法：web.registerJavaScriptProxy（给H5暴露原生方法）
鸿蒙调用H5方法：web.runJavaScript（主动执行H5的JS函数）
H5调用鸿蒙方法：直接调用鸿蒙注册的全局对象方法
H5接收鸿蒙消息：提前挂载全局JS方法等待原生调用
三、前置准备：搭建Web容器基础页面
所有通信都基于鸿蒙 Web组件，先搭建基础承载页面，后续所有通信案例都基于此页面扩展。
无需额外配置，默认支持本地HTML、网络HTML加载。
3.1 鸿蒙基础Web页面（完整可运行）
// Index.etsimport web from '@ohos.web.webview'@Componentstruct H5WebPage { // Web组件控制器 @State webController: web.WebController = new web.WebController() build() { Column() { // H5承载容器 Web({ src: 'local:///index.html', // 本地H5页面，后文提供源码 controller: this.webController }) .width('100%') .height('100%') // 开启JS执行权限（必须开启，否则通信失效） .javaScriptAccess(true) // 允许跨域、混合内容 .mixedContentMode(web.MixedContentMode.ALLOW_ALL) } }}
3.2 新建本地H5页面
在项目 src/main/resources/rawfile 目录下新建 index.html 文件，用于测试双向通信，完整源码如下：
<!DOCTYPE html><htmllang="zh-CN"><head> <metacharset="UTF-8"> <title>鸿蒙H5通信测试</title> <style> body { text-align: center; padding-top: 50px; } button { padding: 10px 20px; margin: 10px; font-size: 16px; } </style></head><body> <h3>鸿蒙 <> H5 双向通信测试</h3> <buttononclick="callHarmonyToast()">H5调用鸿蒙弹窗</button> <buttononclick="callHarmonyGetInfo()">H5调用鸿蒙获取设备信息</button> <script> // 1. H5调用鸿蒙弹窗方法 function callHarmonyToast() { // 调用鸿蒙注册的全局方法 window.harmonyApi.showToast('H5主动调用鸿蒙弹窗成功！') } // 2. H5调用鸿蒙获取设备信息 async function callHarmonyGetInfo() { let res = await window.harmonyApi.getDeviceInfo() alert('收到鸿蒙设备信息：' + JSON.stringify(res)) } // 3. 供鸿蒙原生调用的JS方法（全局挂载） window.h5RefreshPage = function(msg) { alert('鸿蒙主动通知H5：' + msg) } // 4. 接收鸿蒙传递的参数并回调 window.h5GetParams = function(name, age) { alert(`鸿蒙传递参数：姓名{age}`) return "H5参数接收成功，已完成回调" } </script></body></html>
四、核心案例一：H5 调用鸿蒙原生方法（最常用）
场景：H5页面点击按钮，触发鸿蒙原生弹窗、获取设备信息、跳转原生页面等能力。
实现逻辑：鸿蒙提前注册全局方法 → H5直接调用全局方法
4.1 鸿蒙端注册可被H5调用的方法
在Web组件初始化完成后，注册 harmonyApi 全局对象，包含两个常用原生方法：弹窗提示、获取设备信息。
// 补充在Web组件同级，初始化监听.onWebLoadComplete(() => { // 页面加载完成后注册方法（必须加载完成再注册，避免失效） this.registerHarmonyMethod()})// 注册供H5调用的原生方法registerHarmonyMethod() { // 注册全局对象：harmonyApi this.webController.registerJavaScriptProxy( 'harmonyApi', // H5调用的全局对象名 { // 方法1：原生Toast弹窗 showToast: (msg: string) => { promptAction.showToast({ message: msg }) }, // 方法2：返回原生设备信息 getDeviceInfo: (): object => { return { deviceName: '鸿蒙测试设备', systemVersion: 'HarmonyOS 4.0', deviceType: '手机' } } }, true // 是否持久生效 ) // 刷新Web使注册生效 this.webController.refresh()}
4.2 运行效果
五、核心案例二：鸿蒙主动调用H5方法、双向传参回调
场景：鸿蒙原生按钮点击，主动通知H5刷新页面、给H5传递参数，并接收H5的回调结果。
5.1 鸿蒙端完整调用代码
在鸿蒙页面新增两个原生按钮，分别实现 无参通知H5、带参调用H5并接收回调。
Button('鸿蒙主动通知H5刷新') .margin(10) .onClick(() => { // 调用H5全局方法 h5RefreshPage this.webController.runJavaScript(`h5RefreshPage("页面数据已刷新！")`) })Button('鸿蒙传参给H5，并接收回调') .margin(10) .onClick(async () => { // 调用H5带参方法，接收H5返回结果 let res = await this.webController.runJavaScript(`h5GetParams("鸿蒙开发者", 25)`) promptAction.showToast({ message: 'H5回调结果：' + res }) })
5.2 运行效果
六、高阶案例：双向通信实战（业务场景复刻）
6.1 场景：H5调用鸿蒙拍照，返回图片给H5展示
真实业务高频场景：H5页面需要拍照上传，依赖鸿蒙原生相机能力，拍照后将图片路径回传给H5。
1、鸿蒙新增拍照注册方法
// 在registerHarmonyMethod中新增方法takePhoto: async (): Promise<string> => { // 模拟原生相机拍照逻辑（可替换为真实相机API） return new Promise((resolve) => { setTimeout(() => { let imgPath = '/storage/photo/test.png' resolve(imgPath) }, 1000) })}
2、H5调用拍照方法并接收图片路径
在H5页面新增按钮和方法：
<buttononclick="h5TakePhoto()">H5调用鸿蒙拍照</button><script>async function h5TakePhoto() { alert('正在调用鸿蒙相机...') let imgPath = await window.harmonyApi.takePhoto() alert('拍照成功，图片路径：' + imgPath) // 可在此处实现H5预览图片、上传图片逻辑}</script>
七、必看避坑指南（解决90%通信失效问题）
7.1 通信失效常见原因
未开启JS权限：未配置 .javaScriptAccess(true)，所有通信直接失效
注册时机过早：页面未加载完成就注册方法，建议在 onWebLoadComplete 中注册
未刷新Web容器：注册方法后必须执行 refresh() 生效
方法名不统一：鸿蒙注册的方法名、H5调用的方法名必须完全一致（大小写敏感）
页面销毁未释放：反复进出页面会重复注册，导致报错
7.2 页面销毁释放资源（终极防错）
页面退出时销毁Web控制器，避免重复注册、内存泄漏、后台报错。
import web from '@ohos.web.webview'import promptAction from '@ohos.promptAction'@Componentexport struct H5WebCommunicationPage { @State webController: web.WebController = new web.WebController() // 注册H5可调用的原生方法 registerHarmonyMethod() { this.webController.registerJavaScriptProxy( 'harmonyApi', { showToast: (msg: string) => { promptAction.showToast({ message: msg }) }, getDeviceInfo: (): object => { return { deviceName: '鸿蒙测试设备', systemVersion: 'HarmonyOS 4.0', deviceType: '手机' } }, takePhoto: async (): Promise<string> => { return new Promise((resolve) => { setTimeout(() => { resolve('/storage/photo/test.png') }, 1000) }) } }, true ) this.webController.refresh() } // 鸿蒙主动调用H5无参方法 callH5Refresh() { this.webController.runJavaScript(`h5RefreshPage("鸿蒙原生主动刷新H5页面")`) } // 鸿蒙主动调用H5带参方法并接收回调 async callH5WithParams() { let res = await this.webController.runJavaScript(`h5GetParams("鸿蒙开发者", 25)`) promptAction.showToast({ message: 'H5回调结果：' + res }) } build() { Column() { Row() { Button('通知H5刷新') .width('45%') .onClick(() => this.callH5Refresh()) Button('传参调用H5') .width('45%') .onClick(() => this.callH5WithParams()) } .justifyContent(FlexAlign.SpaceAround) .margin(10) Web({ src: 'local:///index.html', controller: this.webController }) .width('100%') .layoutWeight(1) .javaScriptAccess(true) .mixedContentMode(web.MixedContentMode.ALLOW_ALL) .onWebLoadComplete(() => { this.registerHarmonyMethod() }) } .width('100%') .height('100%') } // 页面销毁释放资源 aboutToDisappear() { this.webController.deleteJavaScriptProxy('harmonyApi') this.webController.destroy() }}
九、面试核心总结（直接背诵）
9.1 双向通信核心流程
9.2 核心注意点
必须开启JavaScript权限，否则通信完全失效
方法注册需在页面加载完成后执行，注册后刷新容器生效
页面销毁必须释放Web资源、删除注册方法，避免内存泄漏
双向传参支持基础数据、对象、异步Promise回调，适配绝大多数业务场景
十、总结
鸿蒙与H5双向通信核心就两个能力：注册方法供H5调用、执行H5全局方法。
本文覆盖了 基础单向通信、双向传参、异步回调、业务场景实战、避坑方案、资源释放 全场景，所有代码均可直接复制运行，无需复杂改造，完全适配企业混合开发项目。
掌握这套逻辑，可轻松解决H5嵌套、混合开发、原生能力赋能H5的所有业务问题。
10个月宝宝每天需要喝多少奶粉？