鸿蒙中级课程笔记6—使用ArkWeb开发

开发者可以使用Web组件加载本地或者在线网页。Web组件提供生命周期回调接口，用于感知状态变化和处理业务。Web组件的状态主要包括：Controller绑定到Web组件、网页加载开始、网页加载进度、网页加载结束、页面即将可见。Web页面保活可以参考。自定义组件析构销毁时执行函数，Web组件会被销毁，Web组件与WebviewController解绑，js运行环境也会一并销毁。Web组件网页正常加载

BlackWolfSky

24人浏览 · 2026-01-30 10:18:02

BlackWolfSky · 2026-01-30 10:18:02 发布

Web组件的生命周期

概述

开发者可以使用Web组件加载本地或者在线网页。

Web组件提供生命周期回调接口，用于感知状态变化和处理业务。

Web组件的状态主要包括：Controller绑定到Web组件、网页加载开始、网页加载进度、网页加载结束、页面即将可见。

Web页面保活可以参考使用离线Web组件。

自定义组件析构销毁时执行aboutToDisappear函数，Web组件会被销毁，Web组件与WebviewController解绑，js运行环境也会一并销毁。

图1 Web组件网页正常加载过程中的回调事件

Web组件网页正常加载过程所涉及的状态说明

aboutToAppear函数：在创建自定义组件的新实例后，在执行其build函数前执行。建议在此设置WebDebug调试模式、自定义协议URL的权限、Cookie等。
onControllerAttached事件：当Controller成功绑定到Web组件时触发该回调，且禁止在该事件回调前调用Web组件相关的接口，否则会抛出js-error异常。建议在此事件中注入JS对象、设置自定义用户代理，使用操作网页不相关的接口。但因该回调调用时网页还未加载，因此无法在回调中使用有关操作网页的接口，例如zoomIn、zoomOut等。
onLoadIntercept事件：当Web组件加载url之前触发该回调，用于判断是否阻止此次访问。默认允许加载。
onInterceptRequest事件：当Web组件加载url之前触发该回调，用于拦截url并返回响应数据。
onPageBegin事件：网页开始加载时触发该回调，且只在主frame（表示一个用于展示HTML页面的元素）触发。如果是iframe或者frameset（用于包含frame的HTML标签）的内容加载时则不会触发此回调。多frame页面可能同时加载，主frame加载结束时子frame可能仍在加载。同一页面导航或失败的导航不会触发该回调。
onProgressChange事件：告知开发者当前页面加载的进度。多frame页面或者子frame可能还在继续加载而主frame已经加载结束，所以在onPageEnd事件后仍可能收到该事件。
onPageEnd事件：网页加载完成时触发该回调，且只在主frame触发。多frame页面有可能同时开始加载，即使主frame已经加载结束，子frame也有可能才开始或者继续加载中。同一页面导航或失败的导航不会触发该回调。建议在此回调中执行JavaScript脚本。注意，收到该回调不能保证下一帧反映DOM状态。

Web组件网页异常加载过程所涉及的状态说明

onOverrideUrlLoading事件：当URL将要加载到当前Web中时，让宿主应用程序有机会获得控制权，回调函数返回true将导致当前Web中止加载URL，而返回false则会导致Web继续照常加载URL。onLoadIntercept接口和onOverrideUrlLoading接口行为不一致，触发时机也不同，所以在应用场景上存在一定区别。onLoadIntercept事件在LoadUrl和iframe加载时触发，但onOverrideUrlLoading事件在LoadUrl和特定iframe加载时不会触发。
onPageVisible事件：Web回调事件。渲染流程中当HTTP响应的主体开始加载，新页面即将可见时触发该回调。此时文档加载还处于早期，因此链接的资源比如在线CSS、在线图片等可能尚不可用。
onRenderExited事件：应用渲染进程异常退出时触发该回调，可以在此回调中进行系统资源的释放、数据的保存等操作。如果应用希望异常恢复，需要调用loadUrl接口重新加载页面。详细用法参考应用如何避免Web组件渲染子进程异常退出导致的页面卡死问题。
onDisAppear事件：组件卸载消失时触发此回调。该事件在组件卸载时触发。

应用侧代码举例参考Web组件的生命周期

应用如何避免Web组件渲染子进程异常退出导致的页面卡死问题

ArkWeb（方舟Web）是一个Web组件平台，旨在为应用程序提供展示Web页面内容的功能，并向开发者提供一系列的能力，如页面加载、交互和调试等功能。使用ArkWeb相关应用时，可能因各种原因（例如前端偶现异常导致ArkWeb渲染子进程崩溃，或是打开的应用较多，系统资源紧张导致后台ArkWeb渲染子进程被终止）而出现页面卡死的问题，这时需要重新打开页面或重启应用来解决。

在ArkWeb渲染子进程异常退出导致页面卡死后，应用可通过监听onRenderExited事件来获取具体的退出原因RenderExitReason，并在异常回调中根据退出的具体原因，执行相应的异常处理。

开发实践案例参考Web组件的生命周期

应用侧调用前端页面函数

应用侧可以通过runJavaScript()和runJavaScriptExt()方法调用前端页面的JavaScript相关函数。

runJavaScript()和runJavaScriptExt()在参数类型上有以下差异：runJavaScriptExt()支持string和ArrayBuffer类型参数，而runJavaScript()仅支持string类型参数。

在下面的示例中，点击应用侧的“runJavaScript”按钮时，触发前端页面的htmlTest()方法。

前端页面代码。

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<button type="button" onclick="callArkTS()">Click Me!</button>
<h1 id="text">这是一个测试信息，默认字体为黑色，调用runJavaScript方法后字体为黄色、调用runJavaScriptParam方法后字体为绿色、调用runJavaScriptCodePassed方法后字体为红色</h1>
<script>
    // 有参函数。
    var param = "param: JavaScript Hello World!";
    function htmlTestParam(param) {
        document.getElementById('text').style.color = 'green';
        console.info(param);
    }
    // 无参函数。
    function htmlTest() {
        document.getElementById('text').style.color = 'yellow';
    }
    // 点击“Click Me！”按钮，触发前端页面callArkTS()函数执行JavaScript传递的代码。
    function callArkTS() {
        changeColor();
    }
</script>
</body>
</html>

应用侧代码。

import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebComponent {
  webviewController: webview.WebviewController = new webview.WebviewController();

  aboutToAppear() {
    // 配置Web开启调试模式
    webview.WebviewController.setWebDebuggingAccess(true);
  }

  build() {
    Column() {
      Button('runJavaScriptParam')
        .onClick(() => {
          // 调用前端页面有参函数。
          this.webviewController.runJavaScript('htmlTestParam(param)');
        })
      Button('runJavaScript')
        .onClick(() => {
          // 调用前端页面无参函数。
          this.webviewController.runJavaScript('htmlTest()');
        })
      Button('runJavaScriptCodePassed')
        .onClick(() => {
          // 传递runJavaScript侧代码方法。
          this.webviewController.runJavaScript(
            `function changeColor(){document.getElementById('text').style.color = 'red'}`);
        })
      Web({ src: $rawfile('index.html'), controller: this.webviewController })
    }
  }
}