H5 与 ArkTS 通信的完整设计模型

网罗开发 （小红书、快手、视频号同名）

大家好，我是展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验 。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员

👋 大家好，我是展菲！

📱 全网搜索"展菲"，即可纵览我在各大平台的知识足迹。

📣 公众号"Swift社区"，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。

💬 微信端添加好友"fzhanfei"，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。

📅 最新动态：2025 年 3 月 17 日

快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

文章目录

- 前言
- 通信的本质不是"能不能调"，而是"谁该知道谁"
- 三种通信方式，对应三种场景
- - 同步调用：直接拿结果
  - 异步调用：发起请求，等待结果
  - [ArkTS 主动通知 H5](#ArkTS 主动通知 H5)
- 一个推荐的整体通信分层结构
- 一个完整示例结构示意
- [methodList 本质上是"通信白名单"](#methodList 本质上是“通信白名单”)
- 通信设计中最容易踩的几个坑
- - [把 Bridge 当成业务层](#把 Bridge 当成业务层)
  - 同步接口偷偷做耗时操作
  - 没有统一的数据格式
- 一个简单但好用的通信设计原则
- 总结

前言

只要项目里引入了 Web 组件，通信设计一定会成为隐性复杂点。

一开始可能只是：

H5 想调个原生方法
原生想通知 H5 一个结果

但随着业务增长，问题会逐渐暴露出来：

同步、异步混在一起
JS 想干的事情越来越多
ArkTS 端开始变成"万能工具箱"
没人说得清这条通信链路的边界

所以这篇文章，我们不再从"怎么写代码"开始，而是先把通信模型本身理清楚。

通信的本质不是"能不能调"，而是"谁该知道谁"

在鸿蒙的 Web 场景里，H5 和 ArkTS 本质上是两个世界：

H5：偏业务表达、快速迭代
ArkTS：偏系统能力、稳定边界

通信的核心问题从来不是技术能力，而是：

哪些信息可以跨界，哪些必须隔离。

所以，一个合理的通信模型，至少要回答三件事：

调用是同步还是异步
主动权在谁
是否允许返回结果

三种通信方式，对应三种场景

在实际项目里，我会把 H5 ↔ ArkTS 的通信明确拆成三类。

同步调用：直接拿结果

代表方式：javaScriptProxy

特点非常明确：

JS 主动调用
ArkTS 同步返回
调用即完成

适合做什么？

获取登录态
获取配置
获取环境信息

不适合做什么？

网络请求
文件操作
长时间计算

你可以把它理解成：

"查询型接口"

异步调用：发起请求，等待结果

代表方式：

URL scheme
Web 消息机制

这一类通信通常是：

JS 发起动作
ArkTS 执行
执行完成后再通知 JS

适合做什么？

支付
上传
调系统能力

这里的关键不是"怎么调"，而是：

一定要有请求 ID 或状态回传机制

否则后期你会完全不知道某次调用是哪个 JS 发起的。

ArkTS 主动通知 H5

这一类在复杂项目里非常常见，但经常被忽略。

典型场景包括：

登录状态变化
网络状态变化
权限变化
页面生命周期变化

特点是：

ArkTS 是主动方
H5 是被通知方
通常没有返回值

如果你没设计好这一层，后期就会出现：

H5 不知道状态变了
原生状态和页面状态不同步
各种"看不懂的偶现问题"

一个推荐的整体通信分层结构

在中大型项目里，我强烈建议把通信结构拆成三层。

第一层：通信协议层

这一层只关心一件事：

数据怎么传

比如：

method 名
参数结构
返回值结构

不掺杂任何业务逻辑。

第二层：桥接实现层

这一层是：

javaScriptProxy
Web 消息
URL scheme

它只负责：

把 JS 请求转成 ArkTS 调用
把 ArkTS 结果转回 JS

这里不允许写业务判断。

第三层：业务能力层

真正的业务逻辑放在这里：

登录
权限
设备能力
数据处理

这一层完全不知道：

调用来自 H5 还是 ArkTS 页面

它只关心：

"这是不是一个合法的业务请求"

一个完整示例结构示意

在 ArkTS 侧，结构可以像这样：

text 复制代码

web/
 ├── bridge/
 │    ├── JsBridge.ts        // 仅定义可暴露方法
 │    └── BridgeProtocol.ts  // 参数与返回结构
 ├── service/
 │    ├── UserService.ts
 │    └── DeviceService.ts
 └── page/
      └── WebPage.ets

这样拆的好处是：

JS 能调用什么，一眼可见
业务逻辑不会被"Web 特性"污染
后期重构成本极低

methodList 本质上是"通信白名单"

回到 javaScriptProxy，很多人只是把它当成配置项。

但在架构上，它其实是：

通信权限控制点

ts 复制代码

methodList: ['getUserId', 'getEnv']

意味着：

JS 只能访问这两个能力
ArkTS 内部再复杂，也不会泄露

这一步非常关键，尤其是在：

多人协作
外包 H5
活动页频繁更新的项目里

通信设计中最容易踩的几个坑

把 Bridge 当成业务层

结果就是：

一个类几十个方法
什么都往里塞
谁都不敢改

同步接口偷偷做耗时操作

表面看没问题，实际是：

Web 偶发卡死
定位极其困难

没有统一的数据格式

JS 端各种判断：

js 复制代码

if (res === true)
if (res.code === 0)
if (res.success)

最后没人知道"标准结果"长什么样。

一个简单但好用的通信设计原则

如果你只记住一句话，我建议是这一句：

同步只做查询，异步只做动作，Bridge 只做边界。

这个原则，在鸿蒙 Web 项目里，几乎不会出错。

总结

H5 和 ArkTS 的通信问题，

本质上是一个边界设计问题。

不是"怎么连"，而是：

哪些能力该暴露
哪些状态该同步
哪些事情必须隔离

当你把通信模型想清楚，

具体用 javaScriptProxy 还是消息机制，反而只是实现细节。