HarmonyOS 7 · ArkWeb 混合应用开发手记 01做混合应用时很多人第一次接 ArkWeb代码大概都是这样Web({src:https://example.com,controller:this.controller})页面能开任务似乎就完成了。但只要项目真的开始跑你很快会碰到一串问题首屏一直转圈加载失败后白屏返回页面又重新请求H5明明已经打开了原生侧还在显示 Loading更麻烦的是有些逻辑放在aboutToAppear里能跑换到另一个页面就不稳定。这时候问题通常不在H5 能不能加载而在于我们根本没有把 Web页的加载过程和 ArkUI 页面的生命周期分清楚。这篇就从这里开始。1. 先别急着封装先搞清楚两套生命周期一个 ArkWeb 页面里其实同时存在两套节奏。第一套是 ArkUI 页面自己的生命周期。比如组件什么时候出现、什么时候离开。第二套是 Web 内容的加载生命周期。比如 Web控制器什么时候真正挂上组件、页面什么时候开始加载、什么时候结束、什么时候收到错误。这两套东西有关联但不是一回事。最容易踩的坑就是把它们硬绑在一起。比如aboutToAppear():void{this.loadingtrue}这段代码没错但它只能说明 ArkUI 组件准备出现了并不能说明某个 H5 URL此刻真的开始加载。如果用户在当前 Web 组件里从 A 页面跳到 B 页面aboutToAppear不一定重新执行但 Web 页面已经开始了新一轮加载。所以 Loading 状态如果只靠aboutToAppear控制迟早会乱。更稳的思路是ArkUI 页面生命周期负责页面级资源和状态Web组件自己的加载回调负责 URL加载、进度、成功、失败和重试。职责拆开以后很多偶现问题会直接消失。2. WebviewController 不是装饰品先从最小页面开始。import{webview}fromkit.ArkWebEntryComponentstruct WebPage{privatecontroller:webview.WebviewControllernewwebview.WebviewController()build(){Column(){Web({src:https://example.com,controller:this.controller}).width(100%).height(100%)}}}这里真正值得注意的不是src而是controller。WebviewController可以理解成原生侧握住 Web页面的方向盘。后面刷新、加载新地址以及其他针对 Web页面的控制动作都会围绕它展开。所以我不建议在业务代码里到处临时创建 controller。一个 Web容器对应一个清晰的 controller后续排查问题会轻松很多。例如做一个最简单的刷新Button(重新加载).onClick((){this.controller.refresh()})或者切换地址Button(打开帮助页).onClick((){this.controller.loadUrl(https://example.com/help)})这比通过修改一堆外部状态逼着 Web 重建更直接。但这里还有一个关键点controller 创建出来不等于它已经可以随便操作Web。3.onControllerAttached先确认方向盘真的装上了ArkWeb 提供了onControllerAttached。它很适合处理那些必须等 controller和 Web 组件建立关联以后再做的事情。Web({src:this.url,controller:this.controller}).onControllerAttached((){console.info([ArkWeb] controller attached)})我在项目里通常会把这个节点单独记日志。原因很简单如果以后碰到controller明明有值调用却不符合预期的问题你至少能先判断控制器有没有完成挂载而不是对着URL 和网络抓瞎。可以再加一个状态StatecontrollerReady:booleanfalse.onControllerAttached((){this.controllerReadytrue})然后对依赖 controller 的主动操作做保护privatereloadPage():void{if(!this.controllerReady){console.warn([ArkWeb] controller is not ready)return}this.controller.refresh()}别嫌这个判断啰嗦。混合页面最烦的就是十次有九次正常。把时序条件写清楚比靠运气稳定得多。4.onPageBegin和onPageEnd才适合管 Loading接下来处理最常见的加载状态。Stateloading:booleanfalseStatecurrentUrl:stringWeb({src:this.url,controller:this.controller}).onPageBegin((event){this.loadingtruethis.currentUrlevent?.url??console.info([ArkWeb] begin:${this.currentUrl})}).onPageEnd((event){this.loadingfalseconsole.info([ArkWeb] end:${event?.url??})})思路很直接onPageBegin到了说明一次页面加载开始了onPageEnd到了把 Loading 收掉。然后 UI 层只负责展示状态Stack(){Web({src:this.url,controller:this.controller})if(this.loading){Column(){LoadingProgress().width(32).height(32)Text(页面加载中…).fontSize(14).margin({top:12})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}这样做最大的好处是 Loading 跟着 Web的实际加载走而不是跟着我猜它应该开始加载了走。不过要提醒一句onPageEnd适合当作页面加载阶段的重要结束信号但业务上所谓的页面完全可用可能还有自己的条件。比如 H5 首屏出来以后还要异步拉接口、渲染列表。那就不能简单地把onPageEnd当成业务页面全部准备完毕。原生加载状态和 H5业务状态最好继续分开。5. 别只处理成功白屏往往是错误态没接住很多 Demo 到onPageEnd就结束了线上项目不能这么写。网络断开、域名异常、超时、资源错误都可能让用户看到一个很尴尬的页面。最差的处理方式就是Loading一直转或者直接留一块白色区域。我们加一个错误状态。Stateloading:booleanfalseStateloadError:booleanfalseprivatestartLoading():void{this.loadingtruethis.loadErrorfalse}privatefinishLoading():void{this.loadingfalse}再接到 Web 上Web({src:this.url,controller:this.controller}).onPageBegin((){this.startLoading()}).onPageEnd((){this.finishLoading()}).onErrorReceive((event){this.loadingfalsethis.loadErrortrueconstmessageevent.error.getErrorInfo()console.error([ArkWeb] load error:${message})})UI 上别搞太复杂一个错误提示加重试按钮就够用if(this.loadError){Column({space:12}){Text(页面暂时打不开).fontSize(18)Text(检查网络后再试一次).fontSize(14)Button(重新加载).onClick((){this.loadErrorfalsethis.controller.refresh()})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}注意顺序。重试时先把错误层收掉再调用refresh()。新的加载开始后onPageBegin会再次接管Loading。这样状态流是闭环的不需要在按钮里复制一堆加载逻辑。6. 再加一个超时兜底别让用户无限等真实网络环境没那么讲武德。有时请求没有马上给你一个漂亮的失败结果但用户已经等了十几秒。技术上还在加载体验上其实已经挂了。可以加一个简单的超时兜底。privateloadTimer:number-1privatestartLoadTimer():void{this.clearLoadTimer()this.loadTimersetTimeout((){this.loadingfalsethis.loadErrortrueconsole.error([ArkWeb] load timeout)},15000)}privateclearLoadTimer():void{if(this.loadTimer!-1){clearTimeout(this.loadTimer)this.loadTimer-1}}然后把它放进加载节点.onPageBegin((){this.loadingtruethis.loadErrorfalsethis.startLoadTimer()}).onPageEnd((){this.clearLoadTimer()this.loadingfalse}).onErrorReceive((){this.clearLoadTimer()this.loadingfalsethis.loadErrortrue})15秒不是标准答案。你的页面如果是公司内网、弱网业务或者首屏资源特别重这个值要按真实数据调整。这里的重点不是必须15 秒而是一定要有退出机制。否则 LoadingProgress 转得再丝滑也只是一个精致的死循环。7. 页面离开以后定时器和临时状态要收前面说了ArkUI 生命周期和 Web 加载生命周期不要混在一起。但这不代表ArkUI 生命周期没用了。组件离开时正适合处理页面级资源。aboutToDisappear():void{this.clearLoadTimer()}如果页面里还有事件监听、业务侧回调、临时资源也应该在对应的生命周期里解除。这里有个很实用的判断方法它是跟着一次 URL 加载的还是跟着这个ArkUI 页面实例的跟 URL 加载走的放到 Web 加载回调附近。跟页面实例走的放到 ArkUI生命周期附近。一旦按这个标准拆代码会清楚很多。8. 我更喜欢把加载状态收成一个小状态机写到这里你会发现几个布尔值很容易互相打架。比如loading true和loadError true理论上可以同时出现但 UI到底显示 Loading还是错误页项目再复杂一点还会有空页面、登录过期、离线页。布尔值越堆越多组合就越离谱。所以实际项目里我更喜欢直接定义状态enumWebLoadState{Idle,Loading,Success,Error}StatewebState:WebLoadStateWebLoadState.Idle生命周期里只切状态.onPageBegin((){this.webStateWebLoadState.Loading}).onPageEnd((){this.webStateWebLoadState.Success}).onErrorReceive((){this.webStateWebLoadState.Error})UI 也跟着状态走if(this.webStateWebLoadState.Loading){LoadingProgress()}if(this.webStateWebLoadState.Error){Button(重新加载).onClick(()this.controller.refresh())}这就是一个很小的状态机。听起来像个大词其实一点都不玄学一个时刻只允许页面处于一种明确状态。9. 给日志加统一前缀排错效率差很多混合应用还有一个典型痛点日志太杂。ArkTS 一份H5一份网络一份。真出问题的时候控制台滚得像弹幕。最简单的改进是先统一前缀privatelog(stage:string,message:string):void{console.info([ArkWeb][${stage}]${message})}使用时.onControllerAttached(()this.log(ATTACHED)).onPageBegin((event)this.log(BEGIN,event?.url??)).onPageEnd((event)this.log(END,event?.url??)).onErrorReceive((event){this.log(ERROR,event.error.getErrorInfo())})一次正常加载你希望看到的顺序大致是[ArkWeb][ATTACHED] [ArkWeb][BEGIN] https://example.com [ArkWeb][END] https://example.com如果只有BEGIN没有后续你就知道应该继续看网络、超时或页面加载过程。如果连ATTACHED都没看到那排查方向就完全不同。这也是为什么我前面一直强调不要只看页面有没有显示要把关键节点留下来。10. 最后整理成一个能继续扩展的版本把前面的逻辑合起来核心结构可以保持得很干净import{webview}fromkit.ArkWebenumWebLoadState{Idle,Loading,Success,Error}EntryComponentstruct ArkWebPage{privatecontroller:webview.WebviewControllernewwebview.WebviewController()StatewebState:WebLoadStateWebLoadState.IdleStatecontrollerReady:booleanfalseprivateurl:stringhttps://example.comprivateloadTimer:number-1privateclearTimer():void{if(this.loadTimer!-1){clearTimeout(this.loadTimer)this.loadTimer-1}}privatestartTimer():void{this.clearTimer()this.loadTimersetTimeout((){this.webStateWebLoadState.Error},15000)}aboutToDisappear():void{this.clearTimer()}build(){Stack(){Web({src:this.url,controller:this.controller}).width(100%).height(100%).onControllerAttached((){this.controllerReadytrueconsole.info([ArkWeb][ATTACHED])}).onPageBegin((event){this.webStateWebLoadState.Loadingthis.startTimer()console.info([ArkWeb][BEGIN]${event?.url??})}).onPageEnd((event){this.clearTimer()this.webStateWebLoadState.Successconsole.info([ArkWeb][END]${event?.url??})}).onErrorReceive((event){this.clearTimer()this.webStateWebLoadState.Errorconsole.error([ArkWeb][ERROR]${event.error.getErrorInfo()})})if(this.webStateWebLoadState.Loading){LoadingProgress().width(36).height(36)}if(this.webStateWebLoadState.Error){Column({space:12}){Text(页面加载失败).fontSize(18)Button(重新加载).onClick((){if(this.controllerReady){this.controller.refresh()}})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}.width(100%).height(100%)}}这个版本还不算企业级封装但已经把最关键的边界理顺了controller有自己的就绪节点Web 加载有自己的开始、结束和失败节点ArkUI页面离开时负责清理页面级资源UI 不再到处改loading而是根据一个明确的加载状态渲染。11. 几个特别容易写错的地方第一不要用aboutToAppear代替 Web 的加载开始。它们描述的不是同一件事。页面实例出现不等于每一次 URL导航都从这里开始。第二不要看到 controller 已经new了就默认 Web 已经可操作。对时序敏感的操作先关注 controller 与 Web 的挂载节点。第三不要只写成功路径。错误页、重试、超时兜底最好在第一版 Web容器里就放进去。等线上白屏以后再补通常会补得很狼狈。第四不要让多个布尔值随便组合。页面状态一多尽早改成枚举状态。代码看起来多了两行后面会少很多 if。第五不要把onPageEnd直接理解成业务全部加载完成。它描述的是Web 页面加载过程中的节点。你的 H5 如果还有接口请求和业务渲染业务 Ready应该有自己的定义。小结这一篇没有讲 JSBridge也没有讲缓存、预加载和性能优化。因为这些东西都建立在一个前提上你得先知道 Web 组件现在处于什么状态。把WebviewController、onControllerAttached、onPageBegin、onPageEnd、错误处理和页面清理这几个点串起来ArkWeb就不再是一个能打开网页就行的黑盒而是一个可以观察、可以控制、也可以排错的业务容器。你可以给自己留一个小练习把示例里的错误页再加一个复制当前URL或者返回上一页的动作同时把每次加载耗时打印出来。下一篇再往前走H5 和 ArkTS 到底怎么稳定通信JSBridge应该在哪个时机注册。