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

优质文章学习记录

— 7 min read

背景

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

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

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

  1. Hybrid 应用鸿蒙化方案（架构设计、JSBridge、API 鸿蒙化、组件鸿蒙化）
  2. 同层渲染 Web（原理、实现、生命周期）
  3. 基于 Web 的视频适配
  4. 网页跨域解决方案
  5. 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 应用鸿蒙化方案主要集中在三个方面：

  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.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() 方法提供打包转换能力：

functionopenDialog(){ 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 组件拦截能力。

Read more

前端错误处理最佳实践：别让你的应用崩溃了！

前端错误处理最佳实践：别让你的应用崩溃了！ 毒舌时刻 错误处理？听起来就像是前端工程师为了显得自己很专业而特意搞的一套复杂流程。你以为随便加个try-catch就能解决所有错误？别做梦了！到时候你会发现，错误处理的代码比业务代码还多，维护起来比业务代码还麻烦。 你以为console.error就能记录所有错误？别天真了！console.error只会在控制台打印错误，用户根本看不到，也无法帮助你分析错误原因。还有那些所谓的错误监控工具，看起来高大上，用起来却各种问题。 为什么你需要这个 1. 提高用户体验：良好的错误处理可以避免应用崩溃，提高用户体验。 2. 减少生产环境问题：及时捕获和处理错误可以减少生产环境中的问题。 3. 便于调试：良好的错误处理可以帮助你更快地定位和解决问题。 4. 提高代码可靠性：错误处理可以提高代码的可靠性，减少意外情况的发生。 5. 监控和分析：错误处理可以帮助你监控和分析应用的运行状态，发现潜在问题。 反面教材 // 1. 忽略错误 function fetchData() { fetch('/api/data') .the
CloudBase AI ToolKit实战:从0到1开发一个智能医疗网站

CloudBase AI ToolKit实战:从0到1开发一个智能医疗网站

CloudBase AI ToolKit实战:从0到1开发一个智能医疗网站 🌟 嗨，我是IRpickstars！ 🌌 总有一行代码，能点亮万千星辰。 🔍 在技术的宇宙中，我愿做永不停歇的探索者。 ✨ 用代码丈量世界，用算法解码未来。我是摘星人，也是造梦者。 🚀 每一次编译都是新的征程，每一个bug都是未解的谜题。让我们携手，在0和1的星河中，书写属于开发者的浪漫诗篇。 目录 CloudBase AI ToolKit实战:从0到1开发一个智能医疗网站 1. 摘要 2. CloudBase AI ToolKit简介 2.1. CloudBase AI ToolKit的技术背景与定位 2.2. CloudBase AI ToolKit的核心技术架构 2.3. CloudBase AI ToolKit的创新价值与应用场景 3. CloudBase AI ToolKit 网站极速开发
【AI】免费的代价？Google AI Studio 使用指南与 Cherry Studio + MCP 实战教程

【AI】免费的代价？Google AI Studio 使用指南与 Cherry Studio + MCP 实战教程

🟢 定义速览：Google AI Studio 是使用谷歌相关模型的网页；Cherry Studio 是可以使用多种模型API Key的桌面软件。 文章目录 * 一、Google AI Studio * 1.1 和Gemini网页版的区别 * 1.2 免费层级的用量限制 * 1.3 Google AI Studio 隐私问题（重要） * 1.31 案例分享 * 1.32 Gemini API 附加服务条款 * 1.4 API Key的价格 * 1.5 Google AI Studio 使用说明 * 二、Cherry Studio * 2.1
AI的提示词专栏：使用系统指令（System Prompt）实现全局约束

AI的提示词专栏：使用系统指令（System Prompt）实现全局约束

AI的提示词专栏：使用系统指令（System Prompt）实现全局约束 本文围绕系统指令（System Prompt）展开全面解析，先明确其作为大语言模型交互中优先级高、影响范围广的 “底层规则手册” 的核心概念，对比其与用户输入的差异。接着阐述其在保证输出格式与风格统一、提升信息精准性及保障安全合规等方面的核心价值。随后详细拆解角色定义、规则约束、输出要求、例外处理四大设计要素，结合多行业实战案例说明设计方法，并指出规则模糊、冲突等常见误区及避坑技巧，提供企业客服、编程辅助等场景的可复用模板，还介绍单轮、多轮、边界三种测试调试方法。最后总结关键要点，强调系统指令对精准匹配业务需求的重要性。 人工智能专栏介绍     人工智能学习合集专栏是 AI 学习者的实用工具。它像一个全面的 AI 知识库，把提示词设计、AI 创作、智能绘图等多个细分领域的知识整合起来。无论你是刚接触 AI 的新手，还是有一定基础想提升的人，都能在这里找到合适的内容。从最基础的工具操作方法，到背后深层的技术原理，专栏都有讲解，还搭配了实例教程和实战案例。