一、前言：为什么需要鸿蒙和H5通信？

现在大部分鸿蒙商用项目、政企项目、混合开发项目，都是 原生页面 + H5页面混合开发 的模式：

  • 活动页、公告页、帮助中心、协议页面，用H5开发，迭代快、无需发包

  • 核心功能、相机、定位、文件上传、支付、蓝牙等能力，必须依赖鸿蒙原生

这就出现了核心需求：H5需要调用鸿蒙原生能力，鸿蒙原生也需要给H5传值、通知H5刷新页面。

很多开发者踩坑：通信调用无反应、参数接收错乱、页面销毁报错、重复注册、H5回调失效、白屏报错等。

本文用最简单的语言、最全可运行案例，彻底讲透鸿蒙 <> H5 双向通信所有场景，零基础也能看懂，代码直接复制可用。

二、通信核心原理（一句话听懂）

2.1 两个核心角色

  • 鸿蒙端（ArkTS）：Web组件容器，承载H5页面，注册原生方法供H5调用

  • H5端（JS）：页面业务逻辑，主动调用原生能力、接收原生推送消息

2.2 两种通信场景

  1. H5 → 鸿蒙：H5触发事件，调用鸿蒙原生方法（如H5点击按钮唤起鸿蒙相机、弹窗、分享）

  2. 鸿蒙 → 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.ets
import web from '@ohos.web.webview'

@Component
struct 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>
<html lang="zh-CN">
<head>
    <meta charset="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>
    <button onclick="callHarmonyToast()">H5调用鸿蒙弹窗</button>
    <button onclick="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(`鸿蒙传递参数：姓名${name}，年龄${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调用鸿蒙弹窗】按钮：鸿蒙弹出原生Toast提示

  • 点击H5【H5调用鸿蒙获取设备信息】按钮：H5弹窗展示鸿蒙返回的设备数据

五、核心案例二：鸿蒙主动调用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 运行效果

  • 点击第一个按钮：鸿蒙主动推送消息，H5弹窗接收提示

  • 点击第二个按钮：鸿蒙传递姓名、年龄参数给H5，H5弹窗展示参数，同时返回回调信息，鸿蒙弹窗展示回调结果

六、高阶案例：双向通信实战（业务场景复刻）

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页面新增按钮和方法：


<button onclick="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'

@Component
export 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 双向通信核心流程

  • H5调用鸿蒙：鸿蒙Web组件开启JS权限 → 页面加载完成后注册全局方法 → H5通过window全局对象调用原生能力

  • 鸿蒙调用H5：H5提前挂载全局JS方法 → 鸿蒙通过runJavaScript执行H5方法，支持传参和接收回调

9.2 核心注意点

  • 必须开启JavaScript权限，否则通信完全失效

  • 方法注册需在页面加载完成后执行，注册后刷新容器生效

  • 页面销毁必须释放Web资源、删除注册方法，避免内存泄漏

  • 双向传参支持基础数据、对象、异步Promise回调，适配绝大多数业务场景

十、总结

鸿蒙与H5双向通信核心就两个能力：注册方法供H5调用、执行H5全局方法。

本文覆盖了 基础单向通信、双向传参、异步回调、业务场景实战、避坑方案、资源释放 全场景，所有代码均可直接复制运行，无需复杂改造，完全适配企业混合开发项目。

掌握这套逻辑，可轻松解决H5嵌套、混合开发、原生能力赋能H5的所有业务问题。

# harmonyos # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

ArkTS 核心语法精讲：运算符、空安全与流程控制

avatar HarmonyOS开发者社区

#基于HarmonyOS API 24实战解析投资理财记账应用深度技术解析,开闭原则（对扩展开放、对修改关闭）的实践，是构建可维护软件系统的黄金准则

在移动互联网与智能穿戴设备高度普及的今天，"习惯养成"已经从一个模糊的自我管理理念，演变为一个可量化、可追踪、可视化的数字化产品赛道。越来越多的人希望借助手中的智能终端，把"早起、冥想、阅读、运动"这些抽象的自律行为，转化为一条条清晰的数据曲线和一张张可触摸的打卡卡片。而鸿蒙生态（HarmonyOS）凭借其跨设备协同、分布式软总线以及声明式 UI 开发框架 ArkUI，为这类注重"轻量化交互 +

avatar HarmonyOS开发者社区

#基于HarmonyOS API 24实战解析投资理财记账应用深度技术解析,开闭原则（对扩展开放、对修改关闭）的实践，是构建可维护软件系统的黄金准则

在移动互联网与智能穿戴设备高度普及的今天，"习惯养成"已经从一个模糊的自我管理理念，演变为一个可量化、可追踪、可视化的数字化产品赛道。越来越多的人希望借助手中的智能终端，把"早起、冥想、阅读、运动"这些抽象的自律行为，转化为一条条清晰的数据曲线和一张张可触摸的打卡卡片。而鸿蒙生态（HarmonyOS）凭借其跨设备协同、分布式软总线以及声明式 UI 开发框架 ArkUI，为这类注重"轻量化交互 +

avatar HarmonyOS开发者社区