HarmonyOS ArkWeb 开发完整指南（上篇）：Hybrid 应用鸿蒙化与 JSBridge

Hybrid 应用开发是介于 Web 应用和系统应用两者之间的应用开发技术，兼具"系统应用良好交互体验"的优势和"Web 应用跨平台开发"的优势。其主要原理是由 Native 通过 JSBridge 通道提供统一的 API，然后用 Html/CSS 实现界面，JS 来写业务逻辑，能够调用系统 API，最终的页面在 WebView 中显示。这篇文章聊聊 ArkWeb 开发的几个核心话题：本文是上篇，

程序猿直通车

187人浏览 · 2026-03-30 10:24:34

程序猿直通车 · 2026-03-30 10:24:34 发布

背景

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

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

这篇文章聊聊 ArkWeb 开发的几个核心话题：

Hybrid 应用鸿蒙化方案（架构设计、JSBridge、API 鸿蒙化、组件鸿蒙化）
同层渲染 Web（原理、实现、生命周期）
基于 Web 的视频适配
网页跨域解决方案
Web 组件拦截能力

本文是上篇，主要介绍 Hybrid 应用鸿蒙化方案、双端通信（JSBridge）和 API 鸿蒙化。下篇将介绍组件鸿蒙化（同层渲染）、视频适配、跨域解决方案和 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 应用鸿蒙化方案主要集中在三个方面：

双端通信 JSBridge 实现：前端与 ArkTS 进行双向通信的桥梁
拓展接口实现：针对 JS 侧平台相关的 API，提供一套 HarmonyOS 版本的实现
基于同层渲染的原生组件实现：使用系统提供的同层渲染能力，把部分性能要求比较高的前端组件改成 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.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 (event?.error.getErrorInfo() === 'ERR_INTERNET_DISCONNECTED') {
      this.getUIContext().getPromptAction().showToast({
        message: $r('app.string.internet_err'),
        duration: Const.WEB_CONSTANT_DURATION
      });
    }
    if (event?.error.getErrorInfo() === 'ERR_CONNECTION_TIMED_OUT') {
      this.getUIContext().getPromptAction().showToast({
        message: $r('app.string.internet_err'),
        duration: Const.WEB_CONSTANT_DURATION
      });
    }
  })
  .onProgressChange((event) => {
    if (event?.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()');
  })