适配HarmonyOS7API26连载01/10开篇很多人踩坑的ArkWeb内存坑做鸿蒙混合开发的基本都遇到过这个问题。直接把H5页面丢进ArkWeb来回切页面用个几十次应用就开始卡顿严重直接被系统杀掉。很多人第一反应去前端查JS内存泄漏。我之前项目也是这么干查了两三天H5代码干干净净。反复排查才发现锅根本不在前端。问题根源ArkWeb内核实例和ArkUI页面生命周期根本不是一回事。旧版鸿蒙教程很多不会强调这点放到HarmonyOS7上这个问题被放大了。系统对内存管控收紧页面关掉但Web内核还在后台活着定时器、缓存、JS虚拟机全部留在内存里越堆越多。这篇手记我们就从这个真实线上问题入手一步步搞定ArkWeb页面加载把Web组件的创建、挂载、销毁完整管起来。本篇目标分清ArkUI页面、ArkWeb内核两套生命周期不再混淆实现可控H5页面加载捕获白屏、加载失败异常正确释放Web资源解决反复打开页面带来的内存堆积完成鸿蒙原生和H5之间双向JS通信基础能力拿到一份可以直接粘贴进DevEco Studio跑通的完整代码一、核心误区两个生命周期不要混为一谈ArkUI页面生命周期大家很熟aboutToAppear页面准备渲染aboutToDisappear页面即将销毁。但ArkWeb不是普通UI组件。它是一个完整浏览器内核。只要实例创建系统就分配独立JS虚拟机、缓存、网络资源。一句话类比ArkUI页面只是外壳ArkWeb内核是独立运行的浏览器。外壳关掉浏览器进程不会自动关闭你必须手动关闭它。常见错误认知❌ 页面aboutToDisappear执行Web资源自动释放✅ aboutToDisappear只是页面销毁回调必须手动调用接口销毁Web内核HarmonyOS7下ArkWeb生命周期时序aboutToAppear初始化WebController预先配置内核参数build渲染Web组件创建Web内核发起页面加载请求onPageBegin页面开始加载onPageEnd页面全部资源加载完成onError捕获网络、证书、404这类加载异常aboutToDisappear先停止加载再调用destroy销毁Web实例划重点API26文档里高频复用场景destroy不再是可选优化是硬性要求。很多网上老教程不提这个拿来直接用上线必翻车。二、项目准备DevEco新建HarmonyOS7工程新建工程模板选Empty ActivitySDK版本选API26也就是HarmonyOS7。注意不要选7.0。第一件事配置module.json5权限。加载线上H5INTERNET权限必须写很多新手卡在这页面一直白屏日志还看不出明显报错。// module.json5requestPermissions:[{name:ohos.permission.INTERNET}]简单说明访问外网H5才需要这个权限。如果只是读取工程 rawfile 本地 html不需要网络权限。三、基础代码WebController 管理页面加载WebController 是 ArkWeb 的控制器所有对 Web 实例的操作都通过它。不要在 build 函数内部 new WebController。build 会反复执行多次实例化控制器内存直接爆炸。控制器定义在组件属性只初始化一次。完整基础页面代码完整基础页面代码import{Web,WebController,WebResourceError}fromkit.ArkWeb;Entry Component struct ArkWebDemoPage{// 控制器仅实例化一次不要加StateprivatewebController:WebControllernewWebController();State isLoading:booleantrue;State errorText:string;aboutToAppear(){console.info(准备初始化ArkWeb);// 开启JS执行、本地存储大部分H5页面依赖这两项this.webController.setJavaScriptEnabled(true);this.webController.setDomStorageEnabled(true);}build(){Column(){// 加载错误提示if(this.errorText.length0){Text(加载失败${this.errorText}).fontSize(16).fontColor(Color.Red).margin(12)}Web({src:https://example.com/index.html,controller:this.webController}).onPageBegin((){this.isLoadingtrue;console.info(H5页面开始加载);}).onPageEnd((){this.isLoadingfalse;console.info(H5页面加载完成);}).onError((err:WebResourceError){this.isLoadingfalse;this.errorText错误码${err.errorCode}${err.description};console.error(页面加载异常,err);}).width(100%).layoutWeight(1)}}aboutToDisappear(){console.info(页面退出释放ArkWeb资源);// HarmonyOS7核心代码销毁Web内核this.webController.destroy();}}代码逐行解释private webController: WebController控制器作为组件私有属性全局唯一实例。不需要响应式不要加 State。setJavaScriptEnabled(true)开启 JS。静态纯展示页面可以关闭减少内存占用。onPageBegin /onPageEnd监听页面加载状态我们可以在这里写加载动画、进度条。onError 回调捕获各类加载异常给用户展示错误提示而不是一片空白。aboutToDisappear 里webController.destroy()本篇最关键一行。不写这一行反复进出页面Web 内核持续驻留内存越堆越高。吐槽一句网上很多鸿蒙 ArkWeb 示例直接省略 destroy。那些是简单 demo只打开一次页面。放到业务项目高频切换场景就是定时炸弹。四、本地 H5 资源加载很多混合应用会把静态 html、js、css 打包进应用不依赖外网。资源放到 rawfile 目录。rawfile 页面地址写法$rawfile(index.html)Web({ src: $rawfile(index.html), controller: this.webController })小提醒rawfile 里面文件名、路径不要写中文部分内核版本读取资源会直接失败。五、进阶H5 与 ArkTS 双向通信混合开发最核心能力H5 页面触发事件通知鸿蒙原生代码原生主动调用 H5 里面 JS 函数。HarmonyOS7 使用 registerJavaScriptProxy 注册 JS 桥对象。重点坑JS 代理必须在页面加载之前注册。页面加载完再注册H5 拿不到桥对象调用直接报错。修改 aboutToAppearaboutToAppear() { console.info(准备初始化ArkWeb); this.webController.setJavaScriptEnabled(true); this.webController.setDomStorageEnabled(true); // 注册JS通信桥H5中访问 window.harmonyBridge this.webController.registerJavaScriptProxy({ sendMsgToNative: (msg: string) { console.info(收到H5消息, msg); } }, harmonyBridge, [sendMsgToNative]) // 刷新页面让注册的代理生效 this.webController.refresh(); }H5 页面 index.html 里面 JS 代码script // H5调用鸿蒙原生方法 window.harmonyBridge.sendMsgToNative(来自H5表单提交消息); // 鸿蒙原生可以调用这个H5函数 function receiveNativeMsg(msg) { console.log(原生传来消息, msg); } /script鸿蒙主动调用 H5 JS 函数示例this.webController.runJavaScript(receiveNativeMsg(原生通知H5数据已保存), (res){ console.info(调用H5JS返回结果, res); })通信踩坑清单registerJavaScriptProxy注册时机必须早于页面加载方法名数组必须手动列出不写的方法 H5 无法访问尽量传递字符串复杂对象先 JSON 序列化不要直接传大对象容易出现序列化异常六、边界场景优化退出前停止页面加载有个很常见的场景页面正在加载网络资源用户快速返回退出页面。Web 还在后台请求页面销毁时网络回调回来容易出现异常、崩溃。我们在销毁内核之前先调用 stop 终止所有网络请求。aboutToDisappear() { console.info(页面退出释放ArkWeb资源); // 终止正在进行的页面请求 this.webController.stop(); // 销毁Web内核实例 this.webController.destroy(); }执行顺序不能颠倒stop 在前destroy 在后。七、真机验证看内存曲线确认泄漏修复模拟器的内存统计不准一定要真机跑测试。测试步骤打开页面等待 H5 加载完成返回关闭页面。循环 20 次观察内存。缺少 stopdestroy内存持续上涨几乎不会回落增加 stopdestroy页面关闭后内存回落至初始基线我们用 DevEco Profiler 查看内存曲线直观看到差别。调试小技巧Profiler 观察内存重点看每次页面销毁后的内存回落幅度。如果内存只涨不跌说明 Web 实例没有正常销毁。八、本篇总结 课后练习任务知识点汇总ArkWeb 是重量级浏览器内核组件ArkUI 页面生命周期不等于 Web 内核生命周期HarmonyOS7 必须手动销毁实例。WebController 单独在组件属性定义禁止在 build 内部重复实例化。线上 H5 记得配置 INTERNET 权限本地静态资源使用 $rawfile 加载。JS 双向通信桥注册动作要放在页面加载之前。页面销毁标准顺序stop 停止请求 → destroy 销毁 Web 实例规避残留资源。实践任务为下一期做铺垫基于本篇代码自行实现两点增加 H5 页面加载进度条 UI增加 URL 拦截逻辑捕获 H5 页面跳转事件接管路由。下一期手记 02我们专门讲 ArkWeb 拦截跳转链接、新窗口处理H5 路由和鸿蒙原生路由打通方案。
ArkWeb手记01｜HarmonyOS7 H5加载与生命周期管理
适配HarmonyOS7API26连载01/10开篇很多人踩坑的ArkWeb内存坑做鸿蒙混合开发的基本都遇到过这个问题。直接把H5页面丢进ArkWeb来回切页面用个几十次应用就开始卡顿严重直接被系统杀掉。很多人第一反应去前端查JS内存泄漏。我之前项目也是这么干查了两三天H5代码干干净净。反复排查才发现锅根本不在前端。问题根源ArkWeb内核实例和ArkUI页面生命周期根本不是一回事。旧版鸿蒙教程很多不会强调这点放到HarmonyOS7上这个问题被放大了。系统对内存管控收紧页面关掉但Web内核还在后台活着定时器、缓存、JS虚拟机全部留在内存里越堆越多。这篇手记我们就从这个真实线上问题入手一步步搞定ArkWeb页面加载把Web组件的创建、挂载、销毁完整管起来。本篇目标分清ArkUI页面、ArkWeb内核两套生命周期不再混淆实现可控H5页面加载捕获白屏、加载失败异常正确释放Web资源解决反复打开页面带来的内存堆积完成鸿蒙原生和H5之间双向JS通信基础能力拿到一份可以直接粘贴进DevEco Studio跑通的完整代码一、核心误区两个生命周期不要混为一谈ArkUI页面生命周期大家很熟aboutToAppear页面准备渲染aboutToDisappear页面即将销毁。但ArkWeb不是普通UI组件。它是一个完整浏览器内核。只要实例创建系统就分配独立JS虚拟机、缓存、网络资源。一句话类比ArkUI页面只是外壳ArkWeb内核是独立运行的浏览器。外壳关掉浏览器进程不会自动关闭你必须手动关闭它。常见错误认知❌ 页面aboutToDisappear执行Web资源自动释放✅ aboutToDisappear只是页面销毁回调必须手动调用接口销毁Web内核HarmonyOS7下ArkWeb生命周期时序aboutToAppear初始化WebController预先配置内核参数build渲染Web组件创建Web内核发起页面加载请求onPageBegin页面开始加载onPageEnd页面全部资源加载完成onError捕获网络、证书、404这类加载异常aboutToDisappear先停止加载再调用destroy销毁Web实例划重点API26文档里高频复用场景destroy不再是可选优化是硬性要求。很多网上老教程不提这个拿来直接用上线必翻车。二、项目准备DevEco新建HarmonyOS7工程新建工程模板选Empty ActivitySDK版本选API26也就是HarmonyOS7。注意不要选7.0。第一件事配置module.json5权限。加载线上H5INTERNET权限必须写很多新手卡在这页面一直白屏日志还看不出明显报错。// module.json5requestPermissions:[{name:ohos.permission.INTERNET}]简单说明访问外网H5才需要这个权限。如果只是读取工程 rawfile 本地 html不需要网络权限。三、基础代码WebController 管理页面加载WebController 是 ArkWeb 的控制器所有对 Web 实例的操作都通过它。不要在 build 函数内部 new WebController。build 会反复执行多次实例化控制器内存直接爆炸。控制器定义在组件属性只初始化一次。完整基础页面代码完整基础页面代码import{Web,WebController,WebResourceError}fromkit.ArkWeb;Entry Component struct ArkWebDemoPage{// 控制器仅实例化一次不要加StateprivatewebController:WebControllernewWebController();State isLoading:booleantrue;State errorText:string;aboutToAppear(){console.info(准备初始化ArkWeb);// 开启JS执行、本地存储大部分H5页面依赖这两项this.webController.setJavaScriptEnabled(true);this.webController.setDomStorageEnabled(true);}build(){Column(){// 加载错误提示if(this.errorText.length0){Text(加载失败${this.errorText}).fontSize(16).fontColor(Color.Red).margin(12)}Web({src:https://example.com/index.html,controller:this.webController}).onPageBegin((){this.isLoadingtrue;console.info(H5页面开始加载);}).onPageEnd((){this.isLoadingfalse;console.info(H5页面加载完成);}).onError((err:WebResourceError){this.isLoadingfalse;this.errorText错误码${err.errorCode}${err.description};console.error(页面加载异常,err);}).width(100%).layoutWeight(1)}}aboutToDisappear(){console.info(页面退出释放ArkWeb资源);// HarmonyOS7核心代码销毁Web内核this.webController.destroy();}}代码逐行解释private webController: WebController控制器作为组件私有属性全局唯一实例。不需要响应式不要加 State。setJavaScriptEnabled(true)开启 JS。静态纯展示页面可以关闭减少内存占用。onPageBegin /onPageEnd监听页面加载状态我们可以在这里写加载动画、进度条。onError 回调捕获各类加载异常给用户展示错误提示而不是一片空白。aboutToDisappear 里webController.destroy()本篇最关键一行。不写这一行反复进出页面Web 内核持续驻留内存越堆越高。吐槽一句网上很多鸿蒙 ArkWeb 示例直接省略 destroy。那些是简单 demo只打开一次页面。放到业务项目高频切换场景就是定时炸弹。四、本地 H5 资源加载很多混合应用会把静态 html、js、css 打包进应用不依赖外网。资源放到 rawfile 目录。rawfile 页面地址写法$rawfile(index.html)Web({ src: $rawfile(index.html), controller: this.webController })小提醒rawfile 里面文件名、路径不要写中文部分内核版本读取资源会直接失败。五、进阶H5 与 ArkTS 双向通信混合开发最核心能力H5 页面触发事件通知鸿蒙原生代码原生主动调用 H5 里面 JS 函数。HarmonyOS7 使用 registerJavaScriptProxy 注册 JS 桥对象。重点坑JS 代理必须在页面加载之前注册。页面加载完再注册H5 拿不到桥对象调用直接报错。修改 aboutToAppearaboutToAppear() { console.info(准备初始化ArkWeb); this.webController.setJavaScriptEnabled(true); this.webController.setDomStorageEnabled(true); // 注册JS通信桥H5中访问 window.harmonyBridge this.webController.registerJavaScriptProxy({ sendMsgToNative: (msg: string) { console.info(收到H5消息, msg); } }, harmonyBridge, [sendMsgToNative]) // 刷新页面让注册的代理生效 this.webController.refresh(); }H5 页面 index.html 里面 JS 代码script // H5调用鸿蒙原生方法 window.harmonyBridge.sendMsgToNative(来自H5表单提交消息); // 鸿蒙原生可以调用这个H5函数 function receiveNativeMsg(msg) { console.log(原生传来消息, msg); } /script鸿蒙主动调用 H5 JS 函数示例this.webController.runJavaScript(receiveNativeMsg(原生通知H5数据已保存), (res){ console.info(调用H5JS返回结果, res); })通信踩坑清单registerJavaScriptProxy注册时机必须早于页面加载方法名数组必须手动列出不写的方法 H5 无法访问尽量传递字符串复杂对象先 JSON 序列化不要直接传大对象容易出现序列化异常六、边界场景优化退出前停止页面加载有个很常见的场景页面正在加载网络资源用户快速返回退出页面。Web 还在后台请求页面销毁时网络回调回来容易出现异常、崩溃。我们在销毁内核之前先调用 stop 终止所有网络请求。aboutToDisappear() { console.info(页面退出释放ArkWeb资源); // 终止正在进行的页面请求 this.webController.stop(); // 销毁Web内核实例 this.webController.destroy(); }执行顺序不能颠倒stop 在前destroy 在后。七、真机验证看内存曲线确认泄漏修复模拟器的内存统计不准一定要真机跑测试。测试步骤打开页面等待 H5 加载完成返回关闭页面。循环 20 次观察内存。缺少 stopdestroy内存持续上涨几乎不会回落增加 stopdestroy页面关闭后内存回落至初始基线我们用 DevEco Profiler 查看内存曲线直观看到差别。调试小技巧Profiler 观察内存重点看每次页面销毁后的内存回落幅度。如果内存只涨不跌说明 Web 实例没有正常销毁。八、本篇总结 课后练习任务知识点汇总ArkWeb 是重量级浏览器内核组件ArkUI 页面生命周期不等于 Web 内核生命周期HarmonyOS7 必须手动销毁实例。WebController 单独在组件属性定义禁止在 build 内部重复实例化。线上 H5 记得配置 INTERNET 权限本地静态资源使用 $rawfile 加载。JS 双向通信桥注册动作要放在页面加载之前。页面销毁标准顺序stop 停止请求 → destroy 销毁 Web 实例规避残留资源。实践任务为下一期做铺垫基于本篇代码自行实现两点增加 H5 页面加载进度条 UI增加 URL 拦截逻辑捕获 H5 页面跳转事件接管路由。下一期手记 02我们专门讲 ArkWeb 拦截跳转链接、新窗口处理H5 路由和鸿蒙原生路由打通方案。
