大家好，我是展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。
图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG
我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。
展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！
文章目录
- 前言
- 通信的本质不是“能不能调”，而是“谁该知道谁”
- 三种通信方式，对应三种场景
- 同步调用：直接拿结果
- 异步调用：发起请求，等待结果
- ArkTS 主动通知 H5
- 一个推荐的整体通信分层结构
- 第一层：通信协议层
- 第二层：桥接实现层
- 第三层：业务能力层
- 一个完整示例结构示意
- methodList 本质上是“通信白名单”
- 通信设计中最容易踩的几个坑
- 把 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 侧，结构可以像这样：
web/ ├── bridge/ │ ├── JsBridge.ts // 仅定义可暴露方法 │ └── BridgeProtocol.ts // 参数与返回结构 ├── service/ │ ├── UserService.ts │ └── DeviceService.ts └── page/ └── WebPage.ets这样拆的好处是：
- JS 能调用什么，一眼可见
- 业务逻辑不会被“Web 特性”污染
- 后期重构成本极低
methodList 本质上是“通信白名单”
回到javaScriptProxy，很多人只是把它当成配置项。
但在架构上，它其实是：
通信权限控制点
methodList:['getUserId','getEnv']意味着：
- JS 只能访问这两个能力
- ArkTS 内部再复杂，也不会泄露
这一步非常关键，尤其是在：
- 多人协作
- 外包 H5
- 活动页频繁更新的项目里
通信设计中最容易踩的几个坑
把 Bridge 当成业务层
结果就是：
- 一个类几十个方法
- 什么都往里塞
- 谁都不敢改
同步接口偷偷做耗时操作
表面看没问题，实际是：
- Web 偶发卡死
- 定位极其困难
没有统一的数据格式
JS 端各种判断：
if(res===true)if(res.code===0)if(res.success)最后没人知道“标准结果”长什么样。
一个简单但好用的通信设计原则
如果你只记住一句话，我建议是这一句：
同步只做查询，异步只做动作，Bridge 只做边界。
这个原则，在鸿蒙 Web 项目里，几乎不会出错。
总结
H5 和 ArkTS 的通信问题，
本质上是一个边界设计问题。
不是“怎么连”，而是：
- 哪些能力该暴露
- 哪些状态该同步
- 哪些事情必须隔离
当你把通信模型想清楚，
具体用javaScriptProxy还是消息机制，反而只是实现细节。
