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

背景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 组件以同层渲染的方式提供替代组件以提升组件的性能与交互体验双端通信JSBridgeJSBridge 扮演 Webview 进程与 ArkUI 主进程沟通的桥梁是一种双向通信的机制。HarmonyOS 系统提供 Web 组件以及ohos.web.webview 等 ArkWeb API 来进行 Web 开发。可以通过 WebMessagePort 以及 javaScriptProxy 代理的方式实现 JSBridge。WebMessagePortWebMessagePort 是一种比较基础的消息发送以及接收机制支持的消息类型为 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?.newProgressConst.WEB_CONSTANT_PROGRESS_MAX){this.isLoadingfalse;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执行 jsCallArkTS 侧通过 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 的参数返回值类型格式进行限制使用基本类型或者简单的字典对象尽量避免使用复杂的类型的参数或返回值。可以参考比较成熟的小程序框架其规范格式可以分成三种类型func(paramObj)其中 paramObj 包含基本类型的数据属性以及 success/fail/complete() 回调函数on/offFunc(callback)注册和移除监听函数getXxManager(): obj获取某类功能的全局单例管理器如文件管理器。管理器的方法也遵守上述两点规范设计过程中可以把 API 都汇聚到一个对象作为属性字段存在方便在切面视角增加统一的参数、返回值加工处理拦截处理。上篇总结上篇介绍了 Hybrid 应用鸿蒙化方案和双端通信Hybrid 应用鸿蒙化方案整体架构Ark 进程、Webview 进程、JSBridge方案设计双端通信、拓展接口、同层渲染业务实现关键点双端通信、API 鸿蒙化、组件鸿蒙化双端通信JSBridgeWebMessagePort基础消息机制JavaScriptProxy 代理注入对象方式JSBridge 分层设计通信层、通道层、方法层API 鸿蒙化系统高阶 API 封装三种规范格式func/on-offFunc/getXxManager下篇预告组件鸿蒙化同层渲染、基于 Web 的视频适配、网页跨域解决方案、Web 组件拦截能力。