跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客GitHub 精选镜像工具UI配色美学隐私政策关于联系
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
TypeScript大前端

HarmonyOS ArkWeb 开发指南:Hybrid 应用鸿蒙化与 JSBridge

HarmonyOS ArkWeb 开发涉及 Hybrid 应用鸿蒙化方案。架构包含 Ark 进程、Webview 进程及 JSBridge 通信机制。双端通信推荐使用 JavaScriptProxy 代理注入方式,相比 WebMessagePort 更便捷。JSBridge 设计建议分层为通信层、通道层和方法层。API 鸿蒙化需封装系统高阶接口,规范参数返回值类型,参考小程序框架设计 func/on/offFunc/getXxManager 三种格式。该方案提升组件性能与交互体验,实现 Web 与原生能力融合。

链路追踪发布于 2026/4/12更新于 2026/6/325 浏览

背景

Hybrid 应用开发是介于 Web 应用和系统应用两者之间的应用开发技术,兼具"系统应用良好交互体验"的优势和"Web 应用跨平台开发"的优势。

其主要原理是由 Native 通过 JSBridge 通道提供统一的 API,然后用 Html/CSS 实现界面,JS 来写业务逻辑,能够调用系统 API,最终的页面在 WebView 中显示。

ArkWeb 开发的几个核心话题包括 Hybrid 应用鸿蒙化方案、同层渲染 Web、基于 Web 的视频适配、网页跨域解决方案以及 Web 组件拦截能力。


Hybrid 应用鸿蒙化方案

整体架构

Hybrid 应用鸿蒙化方案的整体架构包含三个核心部分:

Ark 进程:

  • 由 ArkTS 引擎提供运行时,具备调用系统 API 的能力
  • 应用启动从 Ark 进程进入,完成 EntryAbility 的初始化并创建 HarmonyOS 应用页面
  • Ark 进程可以动态或者静态创建 Webview 运行时环境,并加载 html/css/js 资源文件

Webview 进程:

  • 默认支持标准 W3C API,对 ArkTS 侧资源的访问有限制
  • Webview 渲染能力主要由 Web 组件提供
  • 用户可以通过 Web 组件的属性配置是否开启同层渲染能力、是否允许执行 JavaScript 脚本等

JSBridge:

  • 上述两种进程的通讯机制,允许数据双向流动
  • Webview 进程通过 JSBridge 通道访问拓展 API
方案设计

Hybrid 应用鸿蒙化方案主要集中在三个方面:

  1. 双端通信 JSBridge 实现:前端与 ArkTS 进行双向通信的桥梁
  2. 拓展接口实现:针对 JS 侧平台相关的 API,提供一套 HarmonyOS 版本的实现
  3. 基于同层渲染的原生组件实现:使用系统提供的同层渲染能力,把部分性能要求比较高的前端组件改成 ArkTS 实现
业务实现中的关键点

Hybrid 应用鸿蒙化方案主要围绕双端通信、API 鸿蒙化、组件鸿蒙化三方面进行开发:

  • 双端通信:JS 侧使用 ArkTS 的通道,是鸿蒙化的基石
  • API 鸿蒙化:针对 JS 侧平台相关的 API,提供一套 HarmonyOS 版本的实现
  • 组件鸿蒙化:针对 Web 组件,以同层渲染的方式提供替代组件,以提升组件的性能与交互体验

双端通信(JSBridge)

JSBridge 扮演 Webview 进程与 ArkUI 主进程沟通的桥梁,是一种双向通信的机制。

HarmonyOS 系统提供 Web 组件以及@ohos.web.webview 等 ArkWeb API 来进行 Web 开发。可以通过 WebMessagePort 以及 javaScriptProxy 代理的方式实现 JSBridge。

WebMessagePort

WebMessagePort 是一种比较基础的消息发送以及接收机制,支持的消息类型为 string 和 ArrayBuffer。

具体业务消息内容的封装和解析需要从零设计,存在上手难、工作量大的特点。

JavaScriptProxy 代理

JavaScriptProxy 代理机制注入 ArkUI 主进程对象(如命名为 native)到 Webview 中,在 Webview 的 window 上生成对应代理对象,业务可以直接调用该代理对象的方法,相关的操作将作用到 ArkUI 主进程的 native 对象。

代码实例如下:

Web({ src:this.., :. }).().(.).().({ : ., : ., : .}).({(event?..()===){.().().({ :$r(), : .});}(event?..()===){.().().({ :$r(), : .});}}).({(event?. === .){. =;(.);. =-;}}).({ :., :, :[], :. })
param
path
controller
this
webController
zoomAccess
false
width
Const
WEB_CONSTANT_WIDTH
aspectRatio
1
margin
left
Const
WEB_CONSTANT_MARGIN_LEFT
right
Const
WEB_CONSTANT_MARGIN_RIGHT
top
Const
WEB_CONSTANT_MARGIN_TOP
onErrorReceive
(event)=>
if
error
getErrorInfo
'ERR_INTERNET_DISCONNECTED'
this
getUIContext
getPromptAction
showToast
message
'app.string.internet_err'
duration
Const
WEB_CONSTANT_DURATION
if
error
getErrorInfo
'ERR_CONNECTION_TIMED_OUT'
this
getUIContext
getPromptAction
showToast
message
'app.string.internet_err'
duration
Const
WEB_CONSTANT_DURATION
onProgressChange
(event)=>
if
newProgress
Const
WEB_CONSTANT_PROGRESS_MAX
this
isLoading
false
clearInterval
this
intervalLoading
this
intervalLoading
1
javaScriptProxy
object
this
linkObj
name
'linkObj'
methodList
'messageFromHtml'
controller
this
webController

前端可以使用 native.makePhoneCall(…) 的方式进行调用。且方法的参数支持基本类型、字典对象、函数等,对于 JSBridge 的设计提供了便利。

通过对比,javaScriptProxy 注入对象的方式构造 JSBridge 是一个比较好的技术选型。

JSBridge 分层设计

建议 JSBridge 的实现基于注入机制进行设计,并考虑分层设计来提高其通用性和灵活性:

通信层:

  • 对上层屏蔽具体的通信机制,主要负责 Web 侧和 ArkTS 侧数据的传递
  • 但不解析数据的业务含义,不关注传递的数据内容
  • 数据可以序列化为字符串进行传递或者以 object 对象进行传递

通道层(Channel):

  • 允许注册多种方法层通道
  • 该层的 JS 侧实现负责把方法层的 API 信息对象(包含名称、参数、返回值类型等信息)打包成通信层识别的信息数据,交给通信层传递到 ArkTS 侧
  • ArkTS 侧的实现包含两个主要功能:
    • 把信息数据解包出 API 的信息,并交给 ArkTS 侧的方法层调用具体的 API
    • 执行 jsCall,ArkTS 侧通过 WebviewController.runJavaScript() 方法在执行 JS 侧的回调函数

在 JS 侧,nativeCall() 方法提供打包转换能力:

function openDialog(){ linkObj.messageFromHtml(prizesArr[prizesPosition]);}

在 ArkTS 侧,通过 runJavaScript() 执行 JS 侧方法:

Button($r('app.string.btnValue')).fontSize(Const.WEB_CONSTANT_BUTTON_FONT_SIZE).fontColor($r('app.color.start_window_background')).margin({ top: Const.WEB_CONSTANT_BUTTON_MARGIN_TOP}).width(Const.WEB_CONSTANT_BUTTON_WIDTH).height(Const.WEB_CONSTANT_BUTTON_HEIGHT).backgroundColor($r('app.color.blue')).borderRadius(Const.WEB_CONSTANT_BUTTON_BORDER_RADIUS).onClick(()=>{this.webController.runJavaScript('startDraw()');})

方法层(MethodChannel):

  • 可以针对一类 API 格式封装成一种 MethodChannel
  • 同种 MethodChannel 的 API 具备一致的参数规范、返回值规范,比如小程序 API 规范
  • 这样便于把 API 的调用信息封装成结构化的信息对象,供给通道层进行传递

JSBridge 的设计是否合理关系到应用的性能,开发者也可以考虑是否需要批量缓存请求再统一发送请求来减少请求次数,或者把不变的请求结果进行缓存等等。


API 鸿蒙化

H5 业务设计中除了使用 W3C API 外,还可以使用 ArkTS 侧 API 拓展来访问设备。

系统高阶 API 是对系统 API 的一层封装,实现更符合业务要求的接口。

拓展 API 的规范设计具有较大的灵活性,建议对 API 的参数,返回值类型格式进行限制,使用基本类型或者简单的字典对象,尽量避免使用复杂的类型的参数或返回值。

可以参考比较成熟的小程序框架,其规范格式可以分成三种类型:

  1. func(paramObj):其中 paramObj 包含基本类型的数据属性以及 success/fail/complete() 回调函数
  2. on/offFunc(callback):注册和移除监听函数
  3. getXxManager(): obj:获取某类功能的全局单例管理器,如文件管理器。管理器的方法也遵守上述两点规范

设计过程中可以把 API 都汇聚到一个对象作为属性字段存在,方便在切面视角增加统一的参数、返回值加工处理,拦截处理。

目录

  1. 背景
  2. Hybrid 应用鸿蒙化方案
  3. 整体架构
  4. 方案设计
  5. 业务实现中的关键点
  6. 双端通信(JSBridge)
  7. WebMessagePort
  8. JavaScriptProxy 代理
  9. JSBridge 分层设计
  10. API 鸿蒙化
  • 💰 8折买阿里云服务器限时8折了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 🤖 一键搭建Deepseek满血版了解详情
  • 一键打造专属AI 智能体了解详情
极客日志微信公众号二维码

微信扫一扫,关注极客日志

微信公众号「极客日志V2」,在微信中扫描左侧二维码关注。展示文案:极客日志V2 zeeklog

更多推荐文章

查看全部
  • SpringBoot 校园志愿者管理系统
  • PyInstaller 将 Python 脚本打包为 exe 文件实战指南
  • Linux TCP 协议详解:报文结构、连接状态与流量控制
  • Python 环境安装与配置 Gurobi 求解器
  • 网络安全工程师职业发展路径与行业现状分析
  • Linux 进程信号保存机制解析
  • AI 入门:人工智能核心概念速通教程
  • AI Agent 自动化工作流系统架构与实现
  • DeepSeek 与通义万相结合制作 AI 视频实战详解
  • Java 开发者转向 AI 应用开发的学习路径与实战指南
  • Git 版本控制基础指令与常用操作指南
  • Z-Image-Turbo:输入文字秒出图的 AI 绘画工具解析
  • Gaussian Grouping:在三维场景中分割与编辑任意物体
  • Stable Diffusion 整合包 v4.10 与 ComfyUI 整合包使用指南
  • OpenClaw Zero Token 浏览器自动化实现大模型免 Token 调用
  • Redis Cluster 核心原理与 3 主 3 从集群搭建实战
  • 基于 WebGL 的广义相对论黑洞吸积盘着色器实现
  • VR 华夏神舟:沉浸式航天科普体验设备介绍
  • 基于 DeepSeek 与 Cursor 构建智能代码审查工具实战
  • Git-RSCLIP 镜像免配置部署:解决 PyTorch 与 transformers 环境冲突

相关免费在线工具

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online

  • Markdown转HTML

    将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online

  • HTML转Markdown

    将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online

  • JSON 压缩

    通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online

  • JSON美化和格式化

    将JSON字符串修饰为友好的可读格式。 在线工具,JSON美化和格式化在线工具,online