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

代码实例如下：

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()');
  });

方法层（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 都汇聚到一个对象作为属性字段存在，方便在切面视角增加统一的参数、返回值加工处理，拦截处理。

总结

本文介绍了 Hybrid 应用鸿蒙化方案和双端通信：

Hybrid 应用鸿蒙化方案

• 整体架构（Ark 进程、Webview 进程、JSBridge）
• 方案设计（双端通信、拓展接口、同层渲染）
• 业务实现关键点（双端通信、API 鸿蒙化、组件鸿蒙化）

双端通信（JSBridge）

• WebMessagePort（基础消息机制）
• JavaScriptProxy 代理（注入对象方式）
• JSBridge 分层设计（通信层、通道层、方法层）

API 鸿蒙化

• 系统高阶 API 封装
• 三种规范格式（func/on-offFunc/getXxManager）

后续将介绍组件鸿蒙化（同层渲染）、基于 Web 的视频适配、网页跨域解决方案、Web 组件拦截能力。