HarmonyOS内嵌浏览器实战：ArkWeb组件从入门到混合开发

文章目录一、项目概述二、核心概念解析2.1 用生活比喻理解核心概念2.2 两种混合开发模式三、架构与流程图四、核心代码逐行讲解4.1 基础用法加载网页4.2 监听页面事件4.3 原生调用网页 JavaScriptrunJavaScript4.4 网页调用原生代码onMessageEvent4.5 导航控制前进、后退、刷新五、小结一、项目概述ArkWeb 是什么你有没有用过微信里打开一个链接但它不是跳到系统浏览器而是在微信里面直接显示网页这种在App里面嵌入一个浏览器的功能就是 ArkWeb 做的事。打个比方你开了一家餐厅你的AppArkWeb 就是你在餐厅里设置的一台点餐平板。顾客用户不需要离开餐厅就能通过这块平板浏览菜单网页、下订单。ArkWeb也叫 Web 组件是 HarmonyOS 提供的内嵌浏览器组件让你可以在原生App中直接展示网页内容同时支持原生代码和网页之间的互相调用。二、核心概念解析2.1 用生活比喻理解核心概念技术术语生活比喻说明Web组件餐厅里的点餐平板在App中嵌入网页显示区域WebController平板的遥控器控制网页的加载、前进后退等onPageBegin平板打开新页面网页开始加载时触发onPageEnd页面加载完成网页加载结束时触发javaScriptAccess允许平板运行脚本是否允许网页执行JavaScriptdomStorageAccess允许平板记住东西是否允许网页使用本地存储onConsole平板的调试日志网页的console.log输出到这里loadUrl在平板上输入网址加载指定的网页URLrunJavaScript远程操控平板上的程序原生代码调用网页中的JS函数onMessageEvent网页给餐厅打电话网页通过JS向原生发送消息2.2 两种混合开发模式模式比喻适用场景原生为主餐厅为主偶尔看点餐平板大部分是原生页面某个页面展示网页网页为主整个餐厅都是平板操作H5应用套壳大部分内容是网页三、架构与流程图页面加载流程四、核心代码逐行讲解4.1 基础用法加载网页import{webview}fromkit.ArkWeb;Componentstruct WebViewDemo{// WebController 是整个Web组件的遥控器// 通过它来控制网页的加载、前进后退、执行JS等controller:webview.WebviewControllernewwebview.WebviewController();build(){Column(){// --- Web 组件 ---Web({src:https://www.baidu.com,// 要加载的网页地址controller:this.controller// 绑定控制器}).width(100%).height(100%)// --- 网页加载控制器可以放在底部作为导航栏 ---// .javaScriptAccess(true) // 允许执行JS默认true// .domStorageAccess(true) // 允许DOM存储默认true// .fileAccess(true) // 允许访问本地文件// .imageAccess(true) // 允许加载图片// .mixedMode(MixedMode.Compatible) // 允许加载混合内容}}}大白话你买了一个平板Web组件贴上了遥控器的标签controller然后在平板上输入了一个网址src。平板就会自动去下载并显示那个网页。4.2 监听页面事件Componentstruct WebViewEvents{controller:webview.WebviewControllernewwebview.WebviewController();// 用状态变量来更新UIStatepageTitle:string加载中...;StateloadProgress:number0;StateisPageLoading:booleantrue;build(){Column(){// 顶部标题栏Row(){Text(this.pageTitle).fontSize(18).layoutWeight(1).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis})if(this.isPageLoading){LoadingProgress().width(20).height(20)}}.width(100%).padding(15)// 进度条Progress({value:this.loadProgress,total:100}).width(100%).color(#007DFF)Web({src:https://www.baidu.com,controller:this.controller}).width(100%).layoutWeight(1)// 生命周期事件 .onPageBegin((event){/* * 网页开始加载时触发 * event.url即将加载的URL * * 适合做的事 * - 显示加载动画 * - 更新地址栏 */console.info(开始加载:${event.url});this.isPageLoadingtrue;this.pageTitle加载中...;}).onPageEnd((event){/* * 网页加载完成时触发 * 此时DOM已经渲染完毕可以安全地操作网页 * * 适合做的事 * - 隐藏加载动画 * - 获取网页标题 * - 执行初始化JS */console.info(加载完成:${event.url});this.isPageLoadingfalse;// 获取网页标题this.controller.runJavaScript(document.title).then((title){this.pageTitletitle;});}).onProgressChange((event){/* * 加载进度变化时触发 * event.newProgress当前进度0-100 */this.loadProgressevent.newProgress;}).onErrorReceive((event){/* * 加载出错时触发 * 适合显示错误提示页面 */console.error(加载失败:${event.request.getRequestUrl()}, 错误码:${event.error.getErrorCode()});this.isPageLoadingfalse;this.pageTitle加载失败;}).onConsole((event:OnConsoleEvent){/* * 网页中的 console.log() 输出到这里 * 调试网页时非常有用 */console.info([网页日志]${event.message.getMessage()});returnfalse;// false表示不拦截继续让浏览器处理})// 设置Web属性 .javaScriptAccess(true).domStorageAccess(true).cacheMode(CacheMode.Default)/* * cacheMode 缓存模式 * - Default正常缓存策略 * - None不使用缓存 * - Online有网时用缓存 * - Only只用缓存不联网 */}}}4.3 原生调用网页 JavaScriptrunJavaScriptComponentstruct NativeCallJs{controller:webview.WebviewControllernewwebview.WebviewController();StatejsResult:string等待调用...;build(){Column(){Web({// 使用 loadData 直接加载一段HTML不需要服务器src:$rawfile(test.html),// 从resources/rawfile/加载controller:this.controller}).javaScriptAccess(true).layoutWeight(1)Button(调用网页的JS函数).onClick((){/* * runJavaScript原生代码执行网页中的JS * 参数要执行的JS代码字符串 * 返回值Promiseresolve的是JS的返回值 */// 方式1直接执行JS语句this.controller.runJavaScript(document.title).then((result){console.info(网页标题:${result});}).catch((error:Error){console.error(执行JS失败:${error});});// 方式2调用网页中定义的函数this.controller.runJavaScript(getUserName()).then((name){this.jsResultname;// 更新UI显示});})Text(JS返回值:${this.jsResult}).margin(10)}}}对应的 test.html放在 resources/rawfile/ 目录下!doctypehtmlhtmllangenheadmetacharsetUTF-8metanameviewportcontentwidthdevice-width, initial-scale1titleDocument/title/headbodydivh1测试页面/h1script// 这个函数会被原生代码调用functiongetUserName(){return全栈若城;}/script/div/body/html4.4 网页调用原生代码onMessageEventComponentstruct JsCallNative{controller:webview.WebviewControllernewwebview.WebviewController();StatemessageFromWeb:string等待网页消息...;ports:webview.WebMessagePort[][];build(){Column(){Web({src:$rawfile(bridge.html),controller:this.controller}).javaScriptAccess(true).layoutWeight(1)// 网页加载完成后建立 MessageChannel 监听网页发来的消息.onPageEnd((){/* * 使用 WebMessageChannel 实现网页→原生通信 * 1. 创建消息通道得到两个端口 * 2. 在原生侧监听 ports[0] * 3. 将 ports[1] 通过 postMessage 传给网页 * 网页拿到 port 后即可用 port.postMessage() 给原生发消息 */this.portsthis.controller.createWebMessagePorts();// 监听来自网页的消息this.ports[0].onMessageEvent((result:webview.WebMessage){constdataresultasstring;console.info(收到网页消息:${JSON.stringify(data)});this.messageFromWeb收到:${data};});// 将另一个端口传给网页this.controller.postMessage(init_port,[this.ports[1]],*);})Text(网页说:${this.messageFromWeb}).margin(10)}}}对应的 bridge.html!DOCTYPEhtmlhtmlbodybuttononclicksendMessage()发送消息给原生/buttonscriptfunctionsendMessage(){// 通过 window.chrome.webview 发送消息给原生window.chrome.webview.postMessage(你好我是网页);}/script/body/html4.5 导航控制前进、后退、刷新Componentstruct WebViewNavigation{controller:webview.WebviewControllernewwebview.WebviewController();build(){Column(){// 导航栏Row({space:10}){Button(后退).onClick((){// 返回上一页this.controller.backward();})Button(前进).onClick((){// 前往下一页this.controller.forward();})Button(刷新).onClick((){// 刷新当前页面this.controller.refresh();})Button(停止).onClick((){// 停止加载this.controller.stop();})}.padding(10)Web({src:https://baidu.com,controller:this.controller}).layoutWeight(1)// 地址栏Row(){Button(跳转).onClick((){// 在当前WebView中加载新URLthis.controller.loadUrl(https://developer.huawei.com/consumer/cn/blog/recommended);})}}}}五、小结ArkWeb 内嵌浏览器的核心要点三件套Web组件显示区域WebController控制器src网址生命周期onPageBegin开始→onProgressChange进度→onPageEnd完成原生调JSrunJavaScript()— 原生代码可以执行网页中的任何JS函数JS调原生onMessageEvent— 网页通过postMessage向原生发消息导航控制backward()/forward()/refresh()— 前进后退刷新安全第一开启JS访问要谨慎处理消息要验证ArkWeb 让你可以鱼和熊掌兼得——原生App的流畅体验 网页的灵活内容展示。适合展示活动页面、用户协议、帮助文档、H5小游戏等场景。