HarmonyOS Next开发学习手册——ArkWeb

ArkWeb（方舟Web）提供了Web组件，用于在应用程序中显示Web页面内容，为开发者提供页面加载、页面交互、页面调试等能力。

• 页面加载：Web组件提供基础的前端页面加载的能力，包括加载网络页面、本地页面、html格式文本数据。

• 页面交互：Web组件提供丰富的页面交互的方式，包括：设置前端页面深色模式，新窗口中加载页面，位置权限管理，Cookie管理，应用侧使用前端页面JavaScript等能力。

• 页面调试：Web组件支持使用 Devtools工具 调试前端页面。

下面通过常见使用场景举例，来具体介绍Web组件功能特性。

Web组件的生命周期

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

Web组件提供了丰富的组件生命周期回调接口，通过这些回调接口，开发者可以感知Web组件的生命周期状态变化，进行相关的业务处理。

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

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

Web组件网页加载的状态说明

• aboutToAppear 函数：在创建自定义组件的新实例后，在执行其build函数前执行。一般建议在此设置WebDebug调试模式 setWebDebuggingAccess 、设置Web内核自定义协议URL的跨域请求与fetch请求的权限 customizeSchemes 、设置Cookie configCookie 等。

• onControllerAttached 事件：当Controller成功绑定到Web组件时触发该回调，推荐在此事件中注入JS对象 registerJavaScriptProxy 、设置自定义用户代理 setCustomUserAgent ，可以在回调中使用 loadUrl ， getWebId 等操作网页不相关的接口。但因该回调调用时网页还未加载，因此无法在回调中使用有关操作网页的接口，例如 zoomIn 、 zoomOut 等。

• onLoadIntercept 事件：当Web组件加载url之前触发该回调，用于判断是否阻止此次访问。默认允许加载。

• onOverrideUrlLoading 事件：当URL将要加载到当前Web中时，让宿主应用程序有机会获得控制权，回调函数返回true将导致当前Web中止加载URL，而返回false则会导致Web继续照常加载URL。onLoadIntercept接口和onOverrideUrlLoading接口行为不一致，触发时机也不同，所以在应用场景上存在一定区别。主要是在LoadUrl和iframe（HTML标签，表示HTML内联框架元素，用于将另一个页面嵌入到当前页面中）加载时，onLoadIntercept事件会正常回调到，但onOverrideUrlLoading事件则不会回调到。详细介绍请见 onLoadIntercept 和 onOverrideUrlLoading 的说明。

• onInterceptRequest 事件：当Web组件加载url之前触发该回调，用于拦截url并返回响应数据。

• onPageBegin 事件：网页开始加载时触发该回调，且只在主frame（表示一个HTML元素，用于展示HTML页面的HTML元素）触发。如果是iframe或者frameset（用于包含frame的HTML标签）的内容加载时则不会触发此回调。多frame页面有可能同时开始加载，即使主frame已经加载结束，子frame也有可能才开始或者继续加载中。同一页面导航（片段、历史状态等）或者在提交前失败、被取消的导航等也不会触发该回调。

• onProgressChange 事件：告知开发者当前页面加载的进度。多frame页面或者子frame有可能还在继续加载而主frame可能已经加载结束，所以在 onPageEnd 事件后依然有可能收到该事件。

• onPageEnd 事件：网页加载完成时触发该回调，且只在主frame触发。多frame页面有可能同时开始加载，即使主frame已经加载结束，子frame也有可能才开始或者继续加载中。同一页面导航࿰