# Web 提供具有网页显示能力的Web组件，[@ohos.web.webview](js-apis-webview.md)提供web控制能力。 > **说明：** > > - 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 > - 示例效果请以真机运行为准，当前DevEco Studio预览器不支持。 ## 需要权限 访问在线网页时需添加网络权限：ohos.permission.INTERNET，具体申请方式请参考[声明权限](../../security/AccessToken/declare-permissions.md)。 ## 子组件 无 ## 接口 Web(value: WebOptions) > **说明：** > > 不支持转场动画。 > > 同一页面的多个Web组件，必须绑定不同的WebviewController。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ---------------------------------------- | ---- | ---------------------------------------- | | value | [WebOptions](#weboptions) | 是 | 定义Web选项。 | **示例：** 加载在线网页。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) } } } ``` 隐私模式Webview加载在线网页。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller, incognitoMode: true }) } } } ``` Web组件同步渲染模式。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER }) } } } ``` Web组件指定共享渲染进程。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller, sharedRenderProcessToken: "111" }) Web({ src: 'www.w3.org', controller: this.controller, sharedRenderProcessToken: "111" }) } } } ``` 加载本地网页。 通过$rawfile方式加载。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { // 通过$rawfile加载本地资源文件。 Web({ src: $rawfile("index.html"), controller: this.controller }) } } } ``` 通过resources协议加载，适用Webview加载带有"#"路由的链接。 使用 `resource://rawfile/` 协议前缀可以避免常规 `$rawfile` 方式在处理带有"#"路由链接时的局限性。当URL中包含"#"号时，"#"后面的内容会被视为锚点（fragment）。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { // 通过resource协议加载本地资源文件。 Web({ src: "resource://rawfile/index.html#home", controller: this.controller }) } } } ``` 在“src\main\resources\rawfile”文件夹下创建index.html： ```html
``` 加载沙箱路径下的本地资源文件，需要开启应用中文件系统的访问[fileAccess](#fileaccess)权限。 1. 通过构造的单例对象GlobalContext获取沙箱路径。 ```ts // GlobalContext.ets export class GlobalContext { private constructor() {} private static instance: GlobalContext; private _objects = new Map(); public static getContext(): GlobalContext { if (!GlobalContext.instance) { GlobalContext.instance = new GlobalContext(); } return GlobalContext.instance; } getObject(value: string): Object | undefined { return this._objects.get(value); } setObject(key: string, objectClass: Object): void { this._objects.set(key, objectClass); } } ``` ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { GlobalContext } from '../GlobalContext'; let url = 'file://' + GlobalContext.getContext().getObject("filesDir") + '/index.html'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { // 加载沙箱路径文件。 Web({ src: url, controller: this.controller }) .fileAccess(true) } } } ``` 2. 修改EntryAbility.ets。 以filesDir为例，获取沙箱路径。若想获取其他路径，请参考[应用文件路径](../../application-models/application-context-stage.md#获取应用文件路径)。 ```ts // xxx.ets import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; import { webview } from '@kit.ArkWeb'; import { GlobalContext } from '../GlobalContext'; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { // 通过在GlobalContext对象上绑定filesDir，可以实现UIAbility组件与UI之间的数据同步。 GlobalContext.getContext().setObject("filesDir", this.context.filesDir); console.log("Sandbox path is " + GlobalContext.getContext().getObject("filesDir")); } } ``` 加载的html文件。 ```html

Hello World

``` ## WebOptions 通过[接口](#接口)定义Web选项。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 类型 | 必填 | 说明 | | ---------- | ---------------------------------------- | ---- | ---------------------------------------- | | src | string \| [Resource](../apis-arkui/arkui-ts/ts-types.md#resource) | 是 | 网页资源地址。如果访问本地资源文件，请使用$rawfile或者resource协议。如果加载应用包外沙箱路径的本地资源文件(文件支持html和txt类型)，请使用file://沙箱文件路径。
src不能通过状态变量（例如：@State）动态更改地址，如需更改，请通过[loadUrl()](js-apis-webview.md#loadurl)重新加载。 | | controller | [WebController](#webcontroller) \| [WebviewController9+](#webviewcontroller9) | 是 | 控制器。从API Version 9开始，WebController不再维护，建议使用WebviewController替代。 | | renderMode12+ | [RenderMode](#rendermode12枚举说明)| 否 | 表示当前Web组件的渲染方式，RenderMode.ASYNC_RENDER表示Web组件自渲染，RenderMode.SYNC_RENDER表示支持Web组件统一渲染能力，默认值RenderMode.ASYNC_RENDER, 该模式不支持动态调整。 | | incognitoMode11+ | boolean | 否 | 表示当前创建的webview是否是隐私模式。true表示创建隐私模式的webview, false表示创建正常模式的webview。
默认值：false | | sharedRenderProcessToken12+ | string | 否 | 表示当前Web组件指定共享渲染进程的token, 多渲染进程模式下，相同token的Web组件会优先尝试复用与token相绑定的渲染进程。token与渲染进程的绑定发生在渲染进程的初始化阶段。当渲染进程没有关联的Web组件时，其与token绑定关系将被移除。
默认值： "" | ## WebviewController9+ type WebviewController = WebviewController 提供Web控制器的方法。 **系统能力：** SystemCapability.Web.Webview.Core | 类型 | 说明 | | ------ | ---------- | | [WebviewController](js-apis-webview.md#webviewcontroller) | 通过WebviewController可以控制Web组件各种行为。一个WebviewController对象只能控制一个Web组件，且必须在Web组件和WebviewController绑定后，才能调用WebviewController上的方法（静态方法除外）。 | ## 属性 通用属性仅支持[aspectRatio](../apis-arkui/arkui-ts/ts-universal-attributes-layout-constraints.md#aspectratio)、[backdropBlur](../apis-arkui/arkui-ts/ts-universal-attributes-background.md#backdropblur)、[backgroundColor](../apis-arkui/arkui-ts/ts-universal-attributes-background.md#backgroundcolor)、[bindContentCover](../apis-arkui/arkui-ts/ts-universal-attributes-modal-transition.md#bindcontentcover)、[bindContextMenu](../apis-arkui/arkui-ts/ts-universal-attributes-menu.md#bindcontextmenu8)、[bindMenu ](../apis-arkui/arkui-ts/ts-universal-attributes-menu.md#bindmenu)、[bindSheet](../apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#bindsheet)、[borderColor](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#bordercolor)、[borderRadius](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#borderradius)、[borderStyle](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#borderstyle)、[borderWidth](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#borderwidth)、[clip](../apis-arkui/arkui-ts/ts-universal-attributes-sharp-clipping.md#clip)、[constraintSize](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#constraintsize)、[defaultFocus](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#defaultfocus9)、[focusable](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#focusable)、[tabIndex](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#tabindex9)、[groupDefaultFocus](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#groupdefaultfocus9)、[displayPriority](../apis-arkui/arkui-ts/ts-universal-attributes-layout-constraints.md#displaypriority)、[enabled](../apis-arkui/arkui-ts/ts-universal-attributes-enable.md#enabled)、[flexBasis](../apis-arkui/arkui-ts/ts-universal-attributes-flex-layout.md#flexbasis)、[flexShrink](../apis-arkui/arkui-ts/ts-universal-attributes-flex-layout.md#flexshrink)、[layoutWeight](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#layoutweight)、[id](../apis-arkui/arkui-ts/ts-universal-attributes-component-id.md)、[gridOffset](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md)、[gridSpan](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md)、[useSizeType](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md)、[height](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#height)、[touchable](../apis-arkui/arkui-ts/ts-universal-attributes-click.md)、[margin](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#margin)、[markAnchor](../apis-arkui/arkui-ts/ts-universal-attributes-location.md#markanchor)、[offset](../apis-arkui/arkui-ts/ts-universal-attributes-location.md#offset)、[width](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#width)、[zIndex](../apis-arkui/arkui-ts/ts-universal-attributes-z-order.md#zindex)、[visibility](../apis-arkui/arkui-ts/ts-universal-attributes-visibility.md#visibility)、[scale](../apis-arkui/arkui-ts/ts-universal-attributes-transformation.md#scale)、[translate](../apis-arkui/arkui-ts/ts-universal-attributes-transformation.md#translate)、[responseRegion](../apis-arkui/arkui-ts/ts-universal-attributes-touch-target.md#responseregion)、[size](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#size)、[opacity](../apis-arkui/arkui-ts/ts-universal-attributes-opacity.md#opacity)、[shadow](../apis-arkui/arkui-ts/ts-universal-attributes-image-effect.md#shadow)、[sharedTransition](../apis-arkui/arkui-ts/ts-transition-animation-shared-elements.md)、[transition](../apis-arkui/arkui-ts/ts-transition-animation-component.md)。 ### domStorageAccess domStorageAccess(domStorageAccess: boolean) 设置是否开启文档对象模型存储接口（DOM Storage API）权限，默认未开启。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------------- | ------- | ---- | ------------------------------------ | | domStorageAccess | boolean | 是 | 设置是否开启文档对象模型存储接口（DOM Storage API）权限。
true表示开启，false表示未开启。
默认值：false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .domStorageAccess(true) } } } ``` ### fileAccess fileAccess(fileAccess: boolean) 设置是否开启应用中文件系统的访问。[$rawfile(filepath/filename)](../../quick-start/resource-categories-and-access.md)中rawfile路径的文件不受该属性影响而限制访问。 从API version 12开始，fileAccess默认不启用。同时，当fileAccess为false的时候，仅只读资源目录/data/storage/el1/bundle/entry/resources/resfile里面的file协议资源依然可以访问，不受fileAccess管控。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------- | ---- | ---------------------- | | fileAccess | boolean | 是 | API version 11及以前：默认为true，启动应用中文件系统的访问。API version 12及以后：默认为false，不启用应用中文件系统的访问。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .fileAccess(true) } } } ``` ### imageAccess imageAccess(imageAccess: boolean) 设置是否允许自动加载图片资源，默认允许。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------- | ---- | --------------- | | imageAccess | boolean | 是 | 设置是否允许自动加载图片资源。
true表示设置允许自动加载图片资源，false表示设置不允许自动加载图片资源。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .imageAccess(true) } } } ``` ### javaScriptProxy javaScriptProxy(javaScriptProxy: JavaScriptProxy) 注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。 > **说明：** > > javaScriptProxy接口需要和deleteJavaScriptRegister接口配合使用，防止内存泄漏。 > javaScriptProxy对象的所有参数不支持更新。 > 注册对象时，同步与异步方法列表请至少选择一项不为空，可同时注册两类方法。 > 此接口只支持注册一个对象，若需要注册多个对象请使用[registerJavaScriptProxy9+](js-apis-webview.md#registerjavascriptproxy)。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ---------------------------------------- | ---- |---------------------------------------- | | javaScriptProxy | [JavaScriptProxy](#javascriptproxy12) | 是 | 参与注册的对象。只能声明方法，不能声明属性。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; class TestObj { constructor() { } test(data1: string, data2: string, data3: string): string { console.log("data1:" + data1); console.log("data2:" + data2); console.log("data3:" + data3); return "AceString"; } asyncTest(data: string): void { console.log("async data:" + data); } toString(): void { console.log('toString' + "interface instead."); } } @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); testObj = new TestObj(); build() { Column() { Button('deleteJavaScriptRegister') .onClick(() => { try { this.controller.deleteJavaScriptRegister("objName"); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) .javaScriptAccess(true) .javaScriptProxy({ object: this.testObj, name: "objName", methodList: ["test", "toString"], asyncMethodList: ["asyncTest"], controller: this.controller, }) } } } ``` ### javaScriptAccess javaScriptAccess(javaScriptAccess: boolean) 设置是否允许执行JavaScript脚本，默认允许执行。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------------- | ------- | ---- | ------------------- | | javaScriptAccess | boolean | 是 | 是否允许执行JavaScript脚本。
true表示允许执行JavaScript脚本，false表示不允许执行JavaScript脚本。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .javaScriptAccess(true) } } } ``` ### overScrollMode11+ overScrollMode(mode: OverScrollMode) 设置Web过滚动模式，默认关闭。当过滚动模式开启时，当用户在Web根页面上滑动到边缘时，Web会通过弹性动画弹回界面，根页面上的内部页面不会触发回弹。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | --------------------------------------- | ---- | ------------------ | | mode | [OverScrollMode](#overscrollmode11枚举说明) | 是 | 设置Web的过滚动模式为关闭或开启。默认值：OverScrollMode.NEVER。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State mode: OverScrollMode = OverScrollMode.ALWAYS; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .overScrollMode(this.mode) } } } ``` ### mixedMode mixedMode(mixedMode: MixedMode) 设置是否允许加载超文本传输协议（HTTP）和超文本传输安全协议（HTTPS）混合内容，默认不允许加载HTTP和HTTPS混合内容。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | --------------------------- | ---- | --------- | | mixedMode | [MixedMode](#mixedmode枚举说明) | 是 | 要设置的混合内容。默认值：MixedMode.None，表示不允许安全来源（secure origin）加载不安全来源（insecure origin）的内容。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State mode: MixedMode = MixedMode.All; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .mixedMode(this.mode) } } } ``` ### onlineImageAccess onlineImageAccess(onlineImageAccess: boolean) 设置是否允许从网络加载图片资源（通过HTTP和HTTPS访问的资源），默认允许访问。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------------- | ------- | ---- | ---------------- | | onlineImageAccess | boolean | 是 | 设置是否允许从网络加载图片资源。
true表示设置允许从网络加载图片资源，false表示设置不允许从网络加载图片资源。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onlineImageAccess(true) } } } ``` ### zoomAccess zoomAccess(zoomAccess: boolean) 设置是否支持手势进行缩放，默认允许执行缩放。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------- | ---- | ------------- | | zoomAccess | boolean | 是 | 设置是否支持手势进行缩放。
true表示设置支持手势进行缩放，false表示设置不支持手势进行缩放。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .zoomAccess(true) } } } ``` ### overviewModeAccess overviewModeAccess(overviewModeAccess: boolean) 设置是否使用概览模式加载网页，默认使用该方式。当前仅支持移动设备。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------------ | ------- | ---- | --------------- | | overviewModeAccess | boolean | 是 | 设置是否使用概览模式加载网页。
true表示设置使用概览模式加载网页，false表示设置不使用概览模式加载网页。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .overviewModeAccess(true) } } } ``` ### databaseAccess databaseAccess(databaseAccess: boolean) 设置是否开启数据库存储API权限，默认不开启。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------------- | ------- | ---- | ----------------- | | databaseAccess | boolean | 是 | 设置是否开启数据库存储API权限。
true表示设置开启数据库存储API权限，false表示设置不开启数据库存储API权限。
默认值：false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .databaseAccess(true) } } } ``` ### geolocationAccess geolocationAccess(geolocationAccess: boolean) 设置是否开启获取地理位置权限，默认开启。具体使用方式参考[管理位置权限](../../web/web-geolocation-permission.md)。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------------- | ------- | ---- | --------------- | | geolocationAccess | boolean | 是 | 设置是否开启获取地理位置权限。
true表示设置开启获取地理位置权限，false表示设置不开启获取地理位置权限。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .geolocationAccess(true) } } } ``` ### mediaPlayGestureAccess9+ mediaPlayGestureAccess(access: boolean) 设置有声视频播放是否需要用户手动点击，静音视频播放不受该接口管控，默认需要。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ------------------- | | access | boolean | 是 | 设置有声视频播放是否需要用户手动点击。
true表示设置有声视频播放需要用户手动点击，false表示设置有声视频播放不需要用户手动点击。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State access: boolean = true; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .mediaPlayGestureAccess(this.access) } } } ``` ### multiWindowAccess9+ multiWindowAccess(multiWindow: boolean) 设置是否开启多窗口权限，默认不开启。 使能多窗口权限时，需要实现onWindowNew事件，示例代码参考[onWindowNew事件](#onwindownew9)。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------- | ---- | ------------ | | multiWindow | boolean | 是 | 设置是否开启多窗口权限。
true表示设置开启多窗口权限，false表示设置不开启多窗口权限。
默认值：false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .multiWindowAccess(false) } } } ``` ### horizontalScrollBarAccess9+ horizontalScrollBarAccess(horizontalScrollBar: boolean) 设置是否显示横向滚动条，包括系统默认滚动条和用户自定义滚动条。默认显示。 > **说明：** > > - 通过@State变量控制横向滚动条的隐藏/显示后，需要调用controller.refresh()生效。 > - 通过@State变量频繁动态改变时，建议切换开关变量和Web组件一一对应。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------------- | ------- | ---- | ------------ | | horizontalScrollBar | boolean | 是 | 设置是否显示横向滚动条。
true表示设置显示横向滚动条，false表示设置不显示横向滚动条。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State isShow: boolean = true; @State btnMsg: string ="隐藏滚动条"; build() { Column() { // 通过@State变量改变横向滚动条的隐藏/显示后，需调用this.controller.refresh()后生效 Button('refresh') .onClick(() => { if(this.isShow){ this.isShow = false; this.btnMsg="显示滚动条"; }else{ this.isShow = true; this.btnMsg="隐藏滚动条"; } try { this.controller.refresh(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }).height("10%").width("40%") Web({ src: $rawfile('index.html'), controller: this.controller }).height("90%") .horizontalScrollBarAccess(this.isShow) } } } ``` 加载的html文件。 ```html Demo Scroll Test ``` ### verticalScrollBarAccess9+ verticalScrollBarAccess(verticalScrollBar: boolean) 设置是否显示纵向滚动条，包括系统默认滚动条和用户自定义滚动条。默认显示。 > **说明：** > > - 通过@State变量控制纵向滚动条的隐藏/显示后，需要调用controller.refresh()生效。 > - 通过@State变量频繁动态改变时，建议切换开关变量和Web组件一一对应。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------------- | ------- | ---- | ------------ | | verticalScrollBar | boolean | 是 | 设置是否显示纵向滚动条。
true表示设置显示纵向滚动条，false表示设置不显示纵向滚动条。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State isShow: boolean = true; @State btnMsg: string ="隐藏滚动条"; build() { Column() { // 通过@State变量改变横向滚动条的隐藏/显示后，需调用this.controller.refresh()后生效 Button(this.btnMsg) .onClick(() => { if(this.isShow){ this.isShow = false; this.btnMsg="显示滚动条"; }else{ this.isShow = true; this.btnMsg="隐藏滚动条"; } try { this.controller.refresh(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }).height("10%").width("40%") Web({ src: $rawfile('index.html'), controller: this.controller }).height("90%") .verticalScrollBarAccess(this.isShow) } } } ``` 加载的html文件。 ```html Demo Scroll Test ``` ### password(deprecated) password(password: boolean) 设置是否应保存密码。该接口为空接口。 > **说明：** > > 从API version 10开始废弃，并且不再提供新的接口作为替代。 **系统能力：** SystemCapability.Web.Webview.Core ### cacheMode cacheMode(cacheMode: CacheMode) 设置缓存模式。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | --------------------------- | ---- | --------- | | cacheMode | [CacheMode](#cachemode枚举说明) | 是 | 要设置的缓存模式。默认值：CacheMode.Default。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State mode: CacheMode = CacheMode.None; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .cacheMode(this.mode) } } } ``` ### copyOptions11+ copyOptions(value: CopyOptions) 设置剪贴板复制范围选项。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | --------------------------- | ---- | --------- | | value | [CopyOptions](../apis-arkui/arkui-ts/ts-appendix-enums.md#copyoptions9) | 是 | 要设置的剪贴板复制范围选项。默认值：CopyOptions.LocalDevice。 | **示例：** ```ts import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .copyOptions(CopyOptions.None) } } } ``` ### textZoomAtio(deprecated) textZoomAtio(textZoomAtio: number) 设置页面的文本缩放百分比，默认为100。 **系统能力：** SystemCapability.Web.Webview.Core 从API version 9开始不再维护，建议使用[textZoomRatio9+](#textzoomratio9)代替。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------ | ------ | ---- | -------------------------------- | | textZoomAtio | number | 是 | 要设置的页面的文本缩放百分比。取值为正整数。默认值：100。 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() @State ratio: number = 150 build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .textZoomAtio(this.ratio) } } } ``` ### textZoomRatio9+ textZoomRatio(textZoomRatio: number) 设置页面的文本缩放百分比，默认为100。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------- | ------ | ---- | -------------------------------- | | textZoomRatio | number | 是 | 要设置的页面的文本缩放百分比。
取值为整数，范围为(0, 2147483647]。默认值：100。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State ratio: number = 150; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .textZoomRatio(this.ratio) } } } ``` ### initialScale9+ initialScale(percent: number) 设置整体页面的缩放百分比，默认为100。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | ----------------------------- | | percent | number | 是 | 要设置的整体页面的缩放百分比。
默认值：100。取值范围：(0, 1000]。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State percent: number = 100; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .initialScale(this.percent) } } } ``` ### userAgent(deprecated) userAgent(userAgent: string) 设置用户代理。 > **说明：** > > 从API version 8开始支持，从API version 10开始废弃。建议使用[setCustomUserAgent](js-apis-webview.md#setcustomuseragent10)10+替代。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | --------- | | userAgent | string | 是 | 要设置的用户代理。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State userAgent:string = 'Mozilla/5.0 (Phone; OpenHarmony 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 ArkWeb/4.1.6.1 Mobile DemoApp'; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .userAgent(this.userAgent) } } } ``` ### blockNetwork9+ blockNetwork(block: boolean) 设置Web组件是否阻止从网络加载资源。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ------- | ---- | ------------------- | | block | boolean | 是 | 设置Web组件是否阻止从网络加载资源。
true表示设置Web组件阻止从网络加载资源，false表示设置Web组件不阻止从网络加载资源。
默认值：false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State block: boolean = true; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .blockNetwork(this.block) } } } ``` ### defaultFixedFontSize9+ defaultFixedFontSize(size: number) 设置网页的默认等宽字体大小。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------------------------- | | size | number | 是 | 设置网页的默认等宽字体大小，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。默认值：13。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State fontSize: number = 16; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .defaultFixedFontSize(this.fontSize) } } } ``` ### defaultFontSize9+ defaultFontSize(size: number) 设置网页的默认字体大小。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------------------------- | | size | number | 是 | 设置网页的默认字体大小，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。默认值：16。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State fontSize: number = 13; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .defaultFontSize(this.fontSize) } } } ``` ### minFontSize9+ minFontSize(size: number) 设置网页字体大小最小值。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------------------------- | | size | number | 是 | 设置网页字体大小最小值，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。默认值：8。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State fontSize: number = 13; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .minFontSize(this.fontSize) } } } ``` ### minLogicalFontSize9+ minLogicalFontSize(size: number) 设置网页逻辑字体大小最小值。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------------------------- | | size | number | 是 | 设置网页逻辑字体大小最小值，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。默认值：8。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State fontSize: number = 13; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .minLogicalFontSize(this.fontSize) } } } ``` ### webFixedFont9+ webFixedFont(family: string) 设置网页的fixed font字体库。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------- | | family | string | 是 | 设置网页的fixed font字体库。默认值：monospace。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State family: string = "monospace"; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .webFixedFont(this.family) } } } ``` ### webSansSerifFont9+ webSansSerifFont(family: string) 设置网页的sans serif font字体库。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------ | | family | string | 是 | 设置网页的sans serif font字体库。默认值：sans-serif。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State family: string = "sans-serif"; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .webSansSerifFont(this.family) } } } ``` ### webSerifFont9+ webSerifFont(family: string) 设置网页的serif font字体库。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------- | | family | string | 是 | 设置网页的serif font字体库。默认值：serif。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State family: string = "serif"; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .webSerifFont(this.family) } } } ``` ### webStandardFont9+ webStandardFont(family: string) 设置网页的standard font字体库。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ---------------------- | | family | string | 是 | 设置网页的standard font字体库。默认值：sans serif。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State family: string = "sans-serif"; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .webStandardFont(this.family) } } } ``` ### webFantasyFont9+ webFantasyFont(family: string) 设置网页的fantasy font字体库。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | family | string | 是 | 设置网页的fantasy font字体库。默认值：fantasy。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State family: string = "fantasy"; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .webFantasyFont(this.family) } } } ``` ### webCursiveFont9+ webCursiveFont(family: string) 设置网页的cursive font字体库。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | family | string | 是 | 设置网页的cursive font字体库。默认值：cursive。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State family: string = "cursive"; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .webCursiveFont(this.family) } } } ``` ### darkMode9+ darkMode(mode: WebDarkMode) 设置Web深色模式，默认关闭。当深色模式开启时，Web将启用媒体查询prefers-color-scheme中网页所定义的深色样式，若网页未定义深色样式，则保持原状。如需开启强制深色模式，建议配合[forceDarkAccess](#forcedarkaccess9)使用。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | -------------------------------- | ---- | ---------------------- | | mode | [WebDarkMode](#webdarkmode9枚举说明) | 是 | 设置Web的深色模式为关闭、开启或跟随系统。默认值：WebDarkMode.Off。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State mode: WebDarkMode = WebDarkMode.On; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .darkMode(this.mode) } } } ``` ### forceDarkAccess9+ forceDarkAccess(access: boolean) 设置网页是否开启强制深色模式。默认关闭。该属性仅在[darkMode](#darkmode9)开启深色模式时生效。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | --------------- | | access | boolean | 是 | 设置网页是否开启强制深色模式。
true表示设置网页开启强制深色模式，false表示设置网页不开启强制深色模式。
默认值：false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State mode: WebDarkMode = WebDarkMode.On; @State access: boolean = true; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .darkMode(this.mode) .forceDarkAccess(this.access) } } } ``` ### tableData(deprecated) tableData(tableData: boolean) 设置是否应保存表单数据。该接口为空接口。 > **说明：** > > 从API version 10开始废弃，并且不再提供新的接口作为替代。 **系统能力：** SystemCapability.Web.Webview.Core ### wideViewModeAccess(deprecated) wideViewModeAccess(wideViewModeAccess: boolean) 设置web是否支持html中meta标签的viewport属性。该接口为空接口。 > **说明：** > > 从API version 10开始废弃，并且不再提供新的接口作为替代。 **系统能力：** SystemCapability.Web.Webview.Core ### pinchSmooth9+ pinchSmooth(isEnabled: boolean) 设置网页是否开启捏合流畅模式，默认不开启。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | ------- | ---- | ------------- | | isEnabled | boolean | 是 | 网页是否开启捏合流畅模式。
true表示设置网页开启捏合流畅模式，false表示设置网页不开启捏合流畅模式。
默认值：false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .pinchSmooth(true) } } } ``` ### allowWindowOpenMethod10+ allowWindowOpenMethod(flag: boolean) 设置网页是否可以通过JavaScript自动打开新窗口。 该属性为true时，可通过JavaScript自动打开新窗口。该属性为false时，用户行为仍可通过JavaScript自动打开新窗口，但非用户行为不能通过JavaScript自动打开新窗口。此处的用户行为是指，在用户对Web组件进行点击等操作后，同时在5秒内请求打开新窗口（window.open）的行为。 该属性仅在[javaScriptAccess](#javascriptaccess)开启时生效。 该属性在[multiWindowAccess](#multiwindowaccess9)开启时打开新窗口，关闭时打开本地窗口。 该属性的默认值与系统属性persist.web.allowWindowOpenMethod.enabled 保持一致，如果未设置系统属性则默认值为false。 检查系统配置项persist.web.allowWindowOpenMethod.enabled 是否开启。 通过`hdc shell param get persist.web.allowWindowOpenMethod.enabled` 查看，若配置项为0或不存在， 可通过命令`hdc shell param set persist.web.allowWindowOpenMethod.enabled 1` 开启配置。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------- | ---- | ------------------------- | | flag | boolean | 是 | 网页是否可以通过JavaScript自动打开窗口。
true表示网页可以通过JavaScript自动打开窗口，false表示网页不可以通过JavaScript自动打开窗口。
默认值与系统参数关联，当系统参数persist.web.allowWindowOpenMethod.enabled为true时，默认值为true，否则为false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; // 在同一page页有两个Web组件。在WebComponent新开窗口时，会跳转到NewWebViewComp。 @CustomDialog struct NewWebViewComp { controller?: CustomDialogController; webviewController1: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: "", controller: this.webviewController1 }) .javaScriptAccess(true) .multiWindowAccess(false) .onWindowExit(() => { console.info("NewWebViewComp onWindowExit"); if (this.controller) { this.controller.close(); } }) } } } @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); dialogController: CustomDialogController | null = null; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .javaScriptAccess(true) // 需要使能multiWindowAccess .multiWindowAccess(true) .allowWindowOpenMethod(true) .onWindowNew((event) => { if (this.dialogController) { this.dialogController.close(); } let popController: webview.WebviewController = new webview.WebviewController(); this.dialogController = new CustomDialogController({ builder: NewWebViewComp({ webviewController1: popController }) }) this.dialogController.open(); // 将新窗口对应WebviewController返回给Web内核。 // 若不调用event.handler.setWebController接口，会造成render进程阻塞。 // 如果没有创建新窗口，调用event.handler.setWebController接口时设置成null，通知Web没有创建新窗口。 event.handler.setWebController(popController); }) } } } ``` ### mediaOptions10+ mediaOptions(options: WebMediaOptions) 设置Web媒体播放的策略，其中包括：Web中的音频在重新获焦后能够自动续播的有效期、应用内多个Web实例的音频是否独占。 > **说明：** > > - 同一Web实例中的多个音频均视为同一音频。 > - 该媒体播放策略将同时管控有声视频。 > - 属性参数更新后需重新播放音频方可生效。 > - 建议为所有Web组件设置相同的audioExclusive值。 > - 音视频互相打断在应用内和应用间生效，续播只在应用间生效。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------------- | ---- | ---------------------------------------- | | options | [WebMediaOptions](#webmediaoptions10) | 是 | 设置Web的媒体策略。其中，resumeInterval的默认值为0表示不自动续播。默认值：{resumeInterval: 0, audioExclusive: true}。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State options: WebMediaOptions = {resumeInterval: 10, audioExclusive: true}; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .mediaOptions(this.options) } } } ``` ### javaScriptOnDocumentStart11+ javaScriptOnDocumentStart(scripts: Array\) 将JavaScript脚本注入到Web组件中，当指定页面或者文档开始加载时，该脚本将在其来源与scriptRules匹配的任何页面中执行。 > **说明：** > > - 该脚本将在页面的任何JavaScript代码之前运行，并且DOM树此时可能尚未加载、渲染完毕。 > - 该脚本按照字典序执行，非数组本身顺序，若需数组本身顺序，建议使用[runJavaScriptOnDocumentStart](#runjavascriptondocumentstart15)接口。 > - 不建议与[runJavaScriptOnDocumentStart](#runjavascriptondocumentstart15)同时使用。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------- | ---- | ------------------ | | scripts | Array\<[ScriptItem](#scriptitem11)> | 是 | 需要注入的ScriptItem数组。 | **ets示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct Index { controller: webview.WebviewController = new webview.WebviewController(); private localStorage: string = "if (typeof(Storage) !== 'undefined') {" + " localStorage.setItem('color', 'Red');" + "}"; @State scripts: Array = [ { script: this.localStorage, scriptRules: ["*"] } ]; build() { Column({ space: 20 }) { Web({ src: $rawfile('index.html'), controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .backgroundColor(Color.Grey) .javaScriptOnDocumentStart(this.scripts) .width('100%') .height('100%') } } } ``` **HTML示例：** ```html Hello world!
``` ### javaScriptOnDocumentEnd11+ javaScriptOnDocumentEnd(scripts: Array\) 将JavaScript脚本注入到Web组件中，当指定页面或者文档加载完成时，该脚本将在其来源与scriptRules匹配的任何页面中执行。 > **说明：** > > - 该脚本将在页面的任何JavaScript代码之后运行，并且DOM树此时已经加载、渲染完毕。 > - 该脚本按照字典序执行，非数组本身顺序。 > - 不建议与[runJavaScriptOnDocumentEnd](#runjavascriptondocumentend15)同时使用。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------- | ---- | ------------------ | | scripts | Array\<[ScriptItem](#scriptitem11)> | 是 | 需要注入的ScriptItem数组 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct Index { controller: webview.WebviewController = new webview.WebviewController(); private jsStr: string = "window.document.getElementById(\"result\").innerHTML = 'this is msg from javaScriptOnDocumentEnd'"; @State scripts: Array = [ { script: this.jsStr, scriptRules: ["*"] } ]; build() { Column({ space: 20 }) { Web({ src: $rawfile('index.html'), controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .backgroundColor(Color.Grey) .javaScriptOnDocumentEnd(this.scripts) .width('100%') .height('100%') } } } ``` ```html Hello world!
test msg
``` ### runJavaScriptOnDocumentStart15+ runJavaScriptOnDocumentStart(scripts: Array\) 将JavaScript脚本注入到Web组件中，当指定页面或者文档开始加载时，该脚本将在其来源与scriptRules匹配的任何页面中执行。 > **说明：** > > - 该脚本将在页面的任何JavaScript代码之前运行，并且DOM树此时可能尚未加载、渲染完毕。 > - 该脚本按照数组本身顺序执行。 > - 不建议与[javaScriptOnDocumentStart](#javascriptondocumentstart11)同时使用。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------- | ---- | ------------------ | | scripts | Array\<[ScriptItem](#scriptitem11)> | 是 | 需要注入的ScriptItem数组 | **ets示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct Index { controller: webview.WebviewController = new webview.WebviewController(); private localStorage: string = "if (typeof(Storage) !== 'undefined') {" + " localStorage.setItem('color', 'Red');" + "}"; @State scripts: Array = [ { script: this.localStorage, scriptRules: ["*"] } ]; build() { Column({ space: 20 }) { Web({ src: $rawfile('index.html'), controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .backgroundColor(Color.Grey) .runJavaScriptOnDocumentStart(this.scripts) .width('100%') .height('100%') } } } ``` **HTML示例：** ```html Hello world!
``` ### runJavaScriptOnDocumentEnd15+ runJavaScriptOnDocumentEnd(scripts: Array\) 将JavaScript脚本注入到Web组件中，当指定页面或者文档加载完成时，该脚本将在其来源与scriptRules匹配的任何页面中执行。 > **说明：** > > - 该脚本将在页面的任何JavaScript代码之后运行，并且DOM树此时已经加载、渲染完毕。 > - 该脚本按照数组本身顺序执行。 > - 不建议与[javaScriptOnDocumentEnd](#javascriptondocumentend11)同时使用。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------- | ---- | ------------------ | | scripts | Array\<[ScriptItem](#scriptitem11)> | 是 | 需要注入的ScriptItem数组 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct Index { controller: webview.WebviewController = new webview.WebviewController(); private jsStr: string = "window.document.getElementById(\"result\").innerHTML = 'this is msg from runJavaScriptOnDocumentEnd'"; @State scripts: Array = [ { script: this.jsStr, scriptRules: ["*"] } ]; build() { Column({ space: 20 }) { Web({ src: $rawfile('index.html'), controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .backgroundColor(Color.Grey) .runJavaScriptOnDocumentEnd(this.scripts) .width('100%') .height('100%') } } } ``` ```html Hello world!
test msg
``` ### runJavaScriptOnHeadEnd15+ runJavaScriptOnHeadEnd(scripts: Array\) 将JavaScript脚本注入到Web组件中，当页面DOM树head标签解析完成时，该脚本将在其来源与scriptRules匹配的任何页面中执行。 > **说明：** > > - 该脚本按照数组本身顺序执行。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------- | ---- | ------------------ | | scripts | Array\<[ScriptItem](#scriptitem11)> | 是 | 需要注入的ScriptItem数组 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct Index { controller: webview.WebviewController = new webview.WebviewController(); private jsStr: string = "window.document.getElementById(\"result\").innerHTML = 'this is msg from runJavaScriptOnHeadEnd'"; @State scripts: Array = [ { script: this.jsStr, scriptRules: ["*"] } ]; build() { Column({ space: 20 }) { Web({ src: $rawfile('index.html'), controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .backgroundColor(Color.Grey) .runJavaScriptOnHeadEnd(this.scripts) .width('100%') .height('100%') } } } ``` ```html Hello world!
test msg
``` ### layoutMode11+ layoutMode(mode: WebLayoutMode) 设置Web布局模式。 > **说明：** > > 目前只支持两种Web布局模式，分别为Web布局跟随系统（WebLayoutMode.NONE）和Web组件高度基于前端页面高度的自适应网页布局（WebLayoutMode.FIT_CONTENT）。 > > Web组件高度基于前端页面自适应布局有如下限制： > - 如果Web组件宽或长度超过7680px，请在Web组件创建的时候指定RenderMode.SYNC_RENDER模式，否则会整个白屏。 > - Web组件创建后不支持动态切换layoutMode模式 > - Web组件宽高规格：指定RenderMode.SYNC_RENDER模式时，分别不超过50万px；指定RenderMode.ASYNC_RENDER模式时，分别不超过7680px。 > - 频繁更改页面宽高会触发Web组件重新布局，影响体验。 > - 不支持瀑布流网页（下拉到底部加载更多）。 > - 仅支持高度自适应，不支持宽度自适应。 > - 由于高度自适应网页高度，您无法通过修改组件高度属性来修改组件高度。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------------------------------------- | ---- | --------------------- | | mode | [WebLayoutMode](#weblayoutmode11枚举说明) | 是 | 设置web布局模式，跟随系统或自适应布局。默认值：WebLayoutMode.NONE。 | **示例：** 1、指明layoutMode为WebLayoutMode.FIT_CONTENT模式，为避免默认渲染模式下(RenderMode.ASYNC_RENDER)视口高度超过7680px导致页面渲染出错，需要显式指明渲染模式(RenderMode.SYNC_RENDER)。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); mode: WebLayoutMode = WebLayoutMode.FIT_CONTENT; build() { Column() { Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER }) .layoutMode(this.mode) } } } ``` 2、指明layoutMode为WebLayoutMode.FIT_CONTENT模式，为避免嵌套滚动场景下，Web滚动到边缘时会优先触发过滚动的过界回弹效果影响用户体验，建议指定overScrollMode为OverScrollMode.NEVER。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); layoutMode: WebLayoutMode = WebLayoutMode.FIT_CONTENT; @State overScrollMode: OverScrollMode = OverScrollMode.NEVER; build() { Column() { Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER }) .layoutMode(this.layoutMode) .overScrollMode(this.overScrollMode) } } } ``` ### nestedScroll11+ nestedScroll(value: NestedScrollOptions | NestedScrollOptionsExt) 调用以设置嵌套滚动选项。 > **说明：** > > - 可以设置上下左右四个方向，或者设置向前、向后两个方向的嵌套滚动模式，实现与父组件的滚动联动。 > - value为NestedScrollOptionsExt（上下左右四个方向）类型时，scrollUp、scrollDown、scrollLeft、scrollRight默认滚动选项为[NestedScrollMode.SELF_FIRST](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10)。 > - value为NestedScrollOptions（向前、向后两个方向）类型时，scrollForward、scrollBackward默认滚动选项为NestedScrollMode.SELF_FIRST。 > - 支持嵌套滚动的容器：[Grid](../apis-arkui/arkui-ts/ts-container-grid.md)、[List](../apis-arkui/arkui-ts/ts-container-list.md)、[Scroll](../apis-arkui/arkui-ts/ts-container-scroll.md)、[Swiper](../apis-arkui/arkui-ts/ts-container-swiper.md)、[Tabs](../apis-arkui/arkui-ts/ts-container-tabs.md)、[WaterFlow](../apis-arkui/arkui-ts/ts-container-waterflow.md)、[Refresh](../apis-arkui/arkui-ts/ts-container-refresh.md)、[bindSheet](../apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#bindsheet)。 > - 支持嵌套滚动的输入事件：使用手势、鼠标、触控板。 > - 嵌套滚动场景下，由于Web滚动到边缘时会优先触发过滚动的过界回弹效果，建议设置overScrollMode为OverScrollMode.NEVER，避免影响此场景的用户体验。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ---------------- | | value | [NestedScrollOptions](../apis-arkui/arkui-ts/ts-container-scrollable-common.md#nestedscrolloptions10对象说明) \| [NestedScrollOptionsExt](#nestedscrolloptionsext14对象说明)14+ | 是 | 可滚动组件滚动时的嵌套滚动选项。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .nestedScroll({ scrollForward: NestedScrollMode.SELF_FIRST, scrollBackward: NestedScrollMode.SELF_FIRST, }) } } } ``` ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController() build() { Scroll(){ Column() { Text("嵌套Web") .height("25%") .width("100%") .fontSize(30) .backgroundColor(Color.Yellow) Web({ src: $rawfile('index.html'), controller: this.controller }) .nestedScroll({ scrollUp: NestedScrollMode.SELF_FIRST, scrollDown: NestedScrollMode.PARENT_FIRST, scrollLeft: NestedScrollMode.SELF_FIRST, scrollRight: NestedScrollMode.SELF_FIRST, }) } } } } ``` 加载的html文件。 ```html
滚动1
滚动2
滚动3
滚动4
滚动5
滚动6
滚动7
``` ### enableNativeEmbedMode11+ enableNativeEmbedMode(mode: boolean) 设置是否开启同层渲染功能，默认不开启。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ---------------- | | mode | boolean | 是 | 是否开启同层渲染功能。
true表示开启同层渲染功能，false表示不开启同层渲染功能。
默认值：false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .enableNativeEmbedMode(true) } } } ``` ### forceDisplayScrollBar14+ forceDisplayScrollBar(enabled: boolean) 设置滚动条是否常驻。默认不常驻，在常驻状态下，当页面大小超过一页时，滚动条出现且不消失。 全量展开模式下不支持滚动条常驻，即layoutMode为WebLayoutMode.FIT_CONTENT模式时，参数enabled为false。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | -------- | ---- | ------------------ | | enabled | boolean | 是 | 滚动条是否常驻。
true表示滚动条常驻，false表示滚动条不常驻。
默认值：false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) .forceDisplayScrollBar(true) } } } ``` 加载的html文件。 ```html Demo Scroll Test ``` ### registerNativeEmbedRule12+ registerNativeEmbedRule(tag: string, type: string) 注册使用同层渲染的HTML标签名和类型。标签名仅支持使用object和embed。标签类型只能使用ASCII可显示字符。 若指定类型与w3c定义的object或embed标准类型重合，ArkWeb内核将其识别为非同层标签。 本接口同样受enableNativeEmbedMode接口控制，在未使能同层渲染时本接口无效。在不使用本接口的情况下，ArkWeb内核默认将"native/"前缀类型的embed标签识别为同层标签。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | |------|--------| ---- |------------------| | tag | string | 是 | 标签名。 | | type | string | 是 | 标签类型,内核使用前缀匹配此参数。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .enableNativeEmbedMode(true) .registerNativeEmbedRule("object", "application/view") } } } ``` ### defaultTextEncodingFormat12+ defaultTextEncodingFormat(textEncodingFormat: string) 设置网页的默认字符编码。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------------------------- | | textEncodingFormat | string | 是 | 默认字符编码。默认值："UTF-8"。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) // 设置高 .height(500) .defaultTextEncodingFormat("UTF-8") .javaScriptAccess(true) } } } ``` ```html My test html5 page hello world, 你好世界! ``` ### metaViewport12+ metaViewport(enabled: boolean) 设置meta标签的viewport属性是否可用。 > **说明：** > > - 设置false不支持meta标签viewport属性，将不解析viewport属性，进行默认布局。 > - 设置true支持meta标签viewport属性，将解析viewport属性，并根据viewport属性布局。 > - 如果设置为异常值将无效。 > - 如果设备为2in1，不支持viewport属性。设置为true或者false均不会解析viewport属性，进行默认布局。 > - 如果设备为Tablet，设置为true或false均会解析meta标签viewport-fit属性。当viewport-fit=cover时，可通过CSS属性获取安全区域大小。 > - 当前通过User-Agent中是否含有"Mobile"字段来判断是否开启前端HTML页面中meta标签的viewport属性。当User-Agent中不含有"Mobile"字段时，meta标签中viewport属性默认关闭，此时可通过显性设置metaViewport属性为true来覆盖关闭状态。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------- | ---- | -------------------------------- | | enabled | boolean | 是 | 是否支持meta标签的viewport属性。
true表示支持meta标签的viewport属性，false表示不支持meta标签的viewport属性。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) .metaViewport(true) } } } ``` ```html

hello world, 你好世界!

``` ### textAutosizing12+ textAutosizing(textAutosizing: boolean) 设置使能文本自动调整大小。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------------------------- | | textAutosizing | boolean | 是 | 文本自动调整大小。
true表示文本自动调整大小，false表示文本不自动调整大小。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .textAutosizing(false) } } } ``` ### enableNativeMediaPlayer12+ enableNativeMediaPlayer(config: NativeMediaPlayerConfig) 开启[应用接管网页媒体播放功能](../../web/app-takeovers-web-media.md)。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------| | config | [NativeMediaPlayerConfig](#nativemediaplayerconfig12) | 是 | enable: 是否开启该功能。
shouldOverlay: 该功能开启后， 应用接管网页视频的播放器画面是否覆盖网页内容。默认值：{enable: false, shouldOverlay: false}。| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .enableNativeMediaPlayer({enable: true, shouldOverlay: false}) } } } ``` ### selectionMenuOptions12+ selectionMenuOptions(expandedMenuOptions: Array\) Web组件自定义菜单扩展项接口，允许用户设置扩展项的文本内容、图标、回调方法。 该接口只支持选中纯文本，当选中内容包含图片及其他非文本内容时，action信息中会显示乱码。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------------- | ---------------------------------------------------------- | ---- | ------------- | | expandedMenuOptions | Array<[ExpandedMenuItemOptions](#expandedmenuitemoptions12)> | 是 | 扩展菜单选项。
菜单项数量，及菜单的content大小、startIcon图标尺寸，与ArkUI [Menu](../apis-arkui/arkui-ts/ts-basic-components-menu.md)组件保持一致。| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State menuOptionArray: Array = [ {content: 'Apple', startIcon: $r('app.media.icon'), action: (selectedText) => { console.info('select info ' + selectedText.toString()); }}, {content: '香蕉', startIcon: $r('app.media.icon'), action: (selectedText) => { console.info('select info ' + selectedText.toString()); }} ]; build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .selectionMenuOptions(this.menuOptionArray) } } } ``` 加载的html文件。 ```html 测试网页

selectionMenuOptions Demo

selection menu options ``` ### onAdsBlocked12+ onAdsBlocked(callback: OnAdsBlockedCallback) 一个页面发生广告过滤后，通过此回调接口通知过滤的详细信息。由于页面可能随时发生变化并不断产生网络请求，为了减少通知频次、降低对页面加载过程的影响，仅在页面加载完成时进行首次通知，此后发生的过滤将间隔1秒钟上报，无广告过滤则无通知。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnAdsBlockedCallback](#onadsblockedcallback12) | 是 | onAdsBlocked的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { @State totalAdsBlockCounts: number = 0; controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'https://www.example.com', controller: this.controller }) .onAdsBlocked((details: AdsBlockedDetails) => { if (details) { console.log(' Blocked ' + details.adsBlocked.length + ' in ' + details.url); let adList: Array = Array.from(new Set(details.adsBlocked)); this.totalAdsBlockCounts += adList.length; console.log('Total blocked counts :' + this.totalAdsBlockCounts); } }) } } } ``` ### keyboardAvoidMode12+ keyboardAvoidMode(mode: WebKeyboardAvoidMode) Web组件自定义软件键盘避让模式。 当UIContext设置的键盘避让模式为[KeyboardAvoidMode.RESIZE](../apis-arkui/js-apis-arkui-UIContext.md#keyboardavoidmode11)模式时，该接口功能不生效。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------------- | ------------------------------ | ------ | ------------- | | mode | [WebKeyboardAvoidMode](#webkeyboardavoidmode12) | 是 | Web软键盘避让模式。
默认是WebKeyboardAvoidMode.RESIZE_CONTENT避让行为。
嵌套滚动场景下不推荐使用web软键盘避让，包括RESIZE_VISUAL与RESIZE_CONTENT。| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State avoidMode: WebKeyboardAvoidMode = WebKeyboardAvoidMode.RESIZE_VISUAL; build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .keyboardAvoidMode(this.avoidMode) } } } ``` 加载的html文件。 ```html 测试网页 ``` ### editMenuOptions12+ editMenuOptions(editMenu: EditMenuOptions) Web组件自定义文本选择菜单。 用户可以通过该属性设置自定义的文本菜单。 在[onCreateMenu](../apis-arkui/arkui-ts/ts-text-common.md#oncreatemenu)中，可以修改、增加、删除菜单选项，如果希望不显示文本菜单，需要返回空数组。 在[onMenuItemClick](../apis-arkui/arkui-ts/ts-text-common.md#onmenuitemclick)中，可以自定义菜单选项的回调函数。该函数在菜单选项被点击后触发，并根据返回值决定是否执行系统默认的回调。返回true不执行系统回调，返回false继续执行系统回调。 本接口在与[selectionMenuOptions](#selectionmenuoptions12)同时使用时，会使selectionMenuOptions不生效。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------------- | ------------------------------ | ------ | ------------- | | editMenu | [EditMenuOptions](../apis-arkui/arkui-ts/ts-text-common.md#editmenuoptions) | 是 | Web自定义文本菜单选项。
菜单项数量，及菜单的content大小、icon图标尺寸，与ArkUI [Menu](../apis-arkui/arkui-ts/ts-basic-components-menu.md)组件保持一致。
菜单中系统自带的id枚举值（[TextMenuItemId](../apis-arkui/arkui-ts/ts-text-common.md#textmenuitemid12)）在Web中仅支持CUT、COPY、PASTE、SELECT_ALL四项。
onMenuItemClick函数中textRange参数在web中无意义，传入值为-1。| **示例** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); onCreateMenu(menuItems: Array): Array { let items = menuItems.filter((menuItem) => { // 过滤用户需要的系统按键 return ( menuItem.id.equals(TextMenuItemId.CUT) || menuItem.id.equals(TextMenuItemId.COPY) || menuItem.id.equals((TextMenuItemId.PASTE)) ) }); let customItem1: TextMenuItem = { content: 'customItem1', id: TextMenuItemId.of('customItem1'), icon: $r('app.media.icon') }; let customItem2: TextMenuItem = { content: $r('app.string.customItem2'), id: TextMenuItemId.of('customItem2'), icon: $r('app.media.icon') }; items.push(customItem1);// 在选项列表后添加新选项 items.unshift(customItem2);// 在选项列表前添加选项 return items; } onMenuItemClick(menuItem: TextMenuItem, textRange: TextRange): boolean { if (menuItem.id.equals(TextMenuItemId.CUT)) { // 用户自定义行为 console.log("拦截 id：CUT") return true; // 返回true不执行系统回调 } else if (menuItem.id.equals(TextMenuItemId.COPY)) { // 用户自定义行为 console.log("不拦截 id：COPY") return false; // 返回false执行系统回调 } else if (menuItem.id.equals(TextMenuItemId.of('customItem1'))) { // 用户自定义行为 console.log("拦截 id：customItem1") return true;// 用户自定义菜单选项返回true时点击后不关闭菜单，返回false时关闭菜单 } else if (menuItem.id.equals((TextMenuItemId.of($r('app.string.customItem2'))))){ // 用户自定义行为 console.log("拦截 id：app.string.customItem2") return true; } return false;// 返回默认值false } @State EditMenuOptions: EditMenuOptions = { onCreateMenu: this.onCreateMenu, onMenuItemClick: this.onMenuItemClick } build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .editMenuOptions(this.EditMenuOptions) } } } ``` 加载的html文件。 ```html 测试网页

editMenuOptions Demo

edit menu options ``` ### enableHapticFeedback13+ enableHapticFeedback(enabled: boolean) 设置Web组件长按文本选择是否开启振动，默认开启。 需配置"ohos.permission.VIBRATE"。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | --------- | ------ | ------------- | | enabled | boolean | 是 | 是否开启振动。
true表示开启振动，false表示不开启振动。
默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .enableHapticFeedback(true) } } } ``` 加载的html文件。 ```html 测试网页

enableHapticFeedback Demo

enable haptic feedback ``` ### bindSelectionMenu13+ bindSelectionMenu(elementType: WebElementType, content: CustomBuilder, responseType: WebResponseType, options?: SelectionMenuOptionsExt) 设置自定义选择菜单。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------ | ------------------------------- | ---- | ----------------------------------- | | elementType | [WebElementType](#webelementtype13枚举说明) | 是 | 菜单的类型。 | | content | [CustomBuilder](../apis-arkui/arkui-ts/ts-types.md#custombuilder8) | 是 | 菜单的内容。 | | responseType | [WebResponseType](#webresponsetype13枚举说明) | 是 | 菜单的响应类型。 | | options | [SelectionMenuOptionsExt](#selectionmenuoptionsext13) | 否 | 菜单的选项。| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; interface PreviewBuilderParam { previewImage: Resource | string | undefined; width: number; height: number; } @Builder function PreviewBuilderGlobal($$: PreviewBuilderParam) { Column() { Image($$.previewImage) .objectFit(ImageFit.Fill) .autoResize(true) }.width($$.width).height($$.height) } @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); private result: WebContextMenuResult | undefined = undefined; @State previewImage: Resource | string | undefined = undefined; @State previewWidth: number = 0; @State previewHeight: number = 0; @Builder MenuBuilder() { Menu() { MenuItem({ content: '复制', }) .onClick(() => { this.result?.copy(); this.result?.closeContextMenu(); }) MenuItem({ content: '全选', }) .onClick(() => { this.result?.selectAll(); this.result?.closeContextMenu(); }) } } build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .bindSelectionMenu(WebElementType.IMAGE, this.MenuBuilder, WebResponseType.LONG_PRESS, { onAppear: () => {}, onDisappear: () => { this.result?.closeContextMenu(); }, preview: PreviewBuilderGlobal({ previewImage: this.previewImage, width: this.previewWidth, height: this.previewHeight }), menuType: MenuType.PREVIEW_MENU }) .onContextMenuShow((event) => { if (event) { this.result = event.result; if (event.param.getLinkUrl()) { return false; } this.previewWidth = px2vp(event.param.getPreviewWidth()); this.previewHeight = px2vp(event.param.getPreviewHeight()); if (event.param.getSourceUrl().indexOf("resource://rawfile/") == 0) { this.previewImage = $rawfile(event.param.getSourceUrl().substr(19)); } else { this.previewImage = event.param.getSourceUrl(); } return true; } return false; }) } } } ``` 加载的html文件。 ```html 测试网页

bindSelectionMenu Demo

``` ### blurOnKeyboardHideMode14+ blurOnKeyboardHideMode(mode: BlurOnKeyboardHideMode) 设置当软键盘收起时Web元素失焦模式。枚举类型的默认值为SILENT，当用户手动收起软键盘时焦点仍在文本框。可更改为BLUR，当用户手动收起软键盘时，焦点会从文本框转移到Web的body上，文本框失焦。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | --------------------------------------- | ---- | ------------------ | | mode | [BlurOnKeyboardHideMode](#bluronkeyboardhidemode14枚举说明) | 是 | 设置设置当软键盘收起时Web元素失焦关闭或开启。默认值：BlurOnKeyboardHideMode.SILENT。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State blurMode: BlurOnKeyboardHideMode = BlurOnKeyboardHideMode.BLUR; build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .blurOnKeyboardHideMode(this.blurMode) } } } ``` 加载的html文件。 ```html 测试网页

blurOnKeyboardHideMode Demo

``` ### enableFollowSystemFontWeight18+ enableFollowSystemFontWeight(follow: boolean) 设置Web组件是否开启字重跟随系统设置变化，默认不开启。 > **说明：** > > 目前该能力只支持前端文本元素跟随变化，暂不支持canvas元素、内嵌docx和pdf格式中的文本跟随变化。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------ | ------------------------------- | ---- | ----------------------------------- | | follow | boolean | 是 | 设置Web组件是否开启字重跟随系统设置变化，默认值：false。设置为true时，字重跟随系统设置中的字体粗细变化，系统设置改变时字重跟随变化。设置为false时，字重不再跟随系统设置中的字体粗细变化，系统设置改变时维持当前字重不变。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: "www.example.com", controller: this.controller }) .enableFollowSystemFontWeight(true) } } } ``` ### optimizeParserBudget15+ optimizeParserBudget(optimizeParserBudget: boolean) 设置是否开启分段解析HTML优化，默认不开启。 ArkWeb内核在解析HTML文档结构时采取分段解析策略，旨在避免过多占用主线程资源，并使网页具有渐进式加载能力。ArkWeb内核默认使用解析时间作为分段点，当单次解析时间超过阈值时，会中断解析，随后进行布局和渲染操作。 开启优化后，ArkWeb内核将不仅检查解析时间是否超出限制，还会额外判断解析的Token（HTML文档的最小解析单位，例如<div>、attr="xxx"等）数量是否超过内核规定的阈值，并下调此阈值。当页面的FCP(First Contentful Paint 首次内容绘制）触发时会恢复成默认的中断判断逻辑。这将使得网页在FCP到来之前的解析操作更频繁，从而提高首帧内容被提前解析完成并进入渲染阶段的可能性，同时有效缩减首帧渲染的工作量，最终实现FCP时间提前。 由于页面的FCP触发时会恢复成默认分段解析逻辑，因此分段解析HTML优化仅对每个Web组件加载的首个页面生效。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------- | ---- | ---------------------- | | optimizeParserBudget | boolean | 是 | 设置为true时将使用解析个数代替解析时间作为HTML分段解析的分段点，并减少每段解析的个数上限。设置为false时则使用解析时间作为HTML分段解析的分段点。默认值：false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController() build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .optimizeParserBudget(true) } } } ``` ### enableWebAVSession18+ enableWebAVSession(enabled: boolean) 设置是否支持应用对接到播控中心。默认支持应用对接到播控中心。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | -------- | ---- | ------------------ | | enabled | boolean | 是 | 设置是否支持应用对接到播控中心。默认值：true。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) .enableWebAVSession(true) } } } ``` 加载的html文件。 ```html 视频播放页面

视频播放

``` ### nativeEmbedOptions16+ nativeEmbedOptions(options?: EmbedOptions) 设置同层渲染相关配置，该属性仅在[enableNativeEmbedMode](#enablenativeembedmode11)开启时生效，不支持动态修改。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------ | ------------------------------- | ---- | ----------------------------------- | | options | [EmbedOptions](#embedoptions16) | 否 | 同层渲染相关配置，默认值：{supportDefaultIntrinsicSize: false}。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); options: EmbedOptions = {supportDefaultIntrinsicSize: true}; build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .enableNativeEmbedMode(true) .nativeEmbedOptions(this.options) } } } ``` 加载的html文件 ``` 同层渲染固定大小测试html
``` ## 事件 通用事件仅支持[onAppear](../apis-arkui/arkui-ts/ts-universal-events-show-hide.md#onappear)、[onDisAppear](../apis-arkui/arkui-ts/ts-universal-events-show-hide.md#ondisappear)、[onBlur](../apis-arkui/arkui-ts/ts-universal-focus-event.md#onblur)、[onFocus](../apis-arkui/arkui-ts/ts-universal-focus-event.md#onfocus)、[onDragEnd](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondragend)、[onDragEnter](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondragenter)、[onDragStart](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondragstart)、[onDragMove](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondragmove)、[onDragLeave](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondragleave)、[onDrop](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondrop)、[onHover](../apis-arkui/arkui-ts/ts-universal-mouse-key.md#onhover)、[onMouse](../apis-arkui/arkui-ts/ts-universal-mouse-key.md#onmouse)、[onKeyEvent](../apis-arkui/arkui-ts/ts-universal-events-key.md#onkeyevent)、[onTouch](../apis-arkui/arkui-ts/ts-universal-events-touch.md#ontouch)、[onVisibleAreaChange](../apis-arkui/arkui-ts/ts-universal-component-visible-area-change-event.md#onvisibleareachange)。 ### onAlert onAlert(callback: Callback\) 网页触发alert()告警弹窗时触发回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | --------------------- | ---- | --------------- | | callback | Callback\<[OnAlertEvent](#onalertevent12), boolean\> | 是 | 网页触发alert()告警弹窗时触发
返回值boolean。当回调返回true时，应用可以调用自定义弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。当回调返回false时，函数中绘制的自定义弹窗无效。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .onAlert((event) => { if (event) { console.log("event.url:" + event.url); console.log("event.message:" + event.message); AlertDialog.show({ title: 'onAlert', message: 'text', primaryButton: { value: 'cancel', action: () => { event.result.handleCancel(); } }, secondaryButton: { value: 'ok', action: () => { event.result.handleConfirm(); } }, cancel: () => { event.result.handleCancel(); } }) } return true; }) } } } ``` 加载的html文件。 ```html

WebView onAlert Demo

``` ### onBeforeUnload onBeforeUnload(callback: Callback\) 刷新或关闭场景下，在即将离开当前页面时触发此回调。刷新或关闭当前页面应先通过点击等方式获取焦点，才会触发此回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | --------------------- | ---- | --------------- | | callback | Callback\<[OnBeforeUnloadEvent](#onbeforeunloadevent12), boolean\> | 是 | 刷新或关闭场景下，在即将离开当前页面时触发。
返回值boolean。当回调返回true时，应用可以调用自定义弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。当回调返回false时，函数中绘制的自定义弹窗无效。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .onBeforeUnload((event) => { if (event) { console.log("event.url:" + event.url); console.log("event.message:" + event.message); AlertDialog.show({ title: 'onBeforeUnload', message: 'text', primaryButton: { value: 'cancel', action: () => { event.result.handleCancel(); } }, secondaryButton: { value: 'ok', action: () => { event.result.handleConfirm(); } }, cancel: () => { event.result.handleCancel(); } }) } return true; }) } } } ``` 加载的html文件。 ```html

WebView onBeforeUnload Demo

Click here ``` ### onConfirm onConfirm(callback: Callback\) 网页调用confirm()告警时触发此回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | --------------------- | ---- | --------------- | | callback | Callback\<[OnConfirmEvent](#onconfirmevent12), boolean\> | 是 | 网页调用confirm()告警时触发
返回值boolean。当回调返回true时，应用可以调用自定义弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。当回调返回false时，函数中绘制的自定义弹窗无效。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .onConfirm((event) => { if (event) { console.log("event.url:" + event.url); console.log("event.message:" + event.message); AlertDialog.show({ title: 'onConfirm', message: 'text', primaryButton: { value: 'cancel', action: () => { event.result.handleCancel(); } }, secondaryButton: { value: 'ok', action: () => { event.result.handleConfirm(); } }, cancel: () => { event.result.handleCancel(); } }) } return true; }) } } } ``` 加载的html文件。 ```html

WebView onConfirm Demo

``` ### onPrompt9+ onPrompt(callback: Callback\) 网页调用prompt()告警时触发此回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | --------------------- | ---- | --------------- | | callback | Callback\<[OnPromptEvent](#onpromptevent12), boolean\> | 是 | 网页调用prompt()告警时触发。
返回值boolean。当回调返回true时，应用可以调用自定义弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。当回调返回false时，函数中绘制的自定义弹窗无效。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .onPrompt((event) => { if (event) { console.log("url:" + event.url); console.log("message:" + event.message); console.log("value:" + event.value); AlertDialog.show({ title: 'onPrompt', message: 'text', primaryButton: { value: 'cancel', action: () => { event.result.handleCancel(); } }, secondaryButton: { value: 'ok', action: () => { event.result.handlePromptConfirm(event.value); } }, cancel: () => { event.result.handleCancel(); } }) } return true; }) } } } ``` 加载的html文件。 ```html

WebView onPrompt Demo

``` ### onConsole onConsole(callback: Callback\) 通知宿主应用JavaScript console消息。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | --------------------------------- | ---- | --------- | | callback | Callback\<[OnConsoleEvent](#onconsoleevent12), boolean\> | 是 | 网页收到JavaScript控制台消息时触发。
返回值boolean。当返回true时，该条消息将不会再打印至控制台，反之仍会打印至控制台。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('onconsole message') .onClick(() => { this.controller.runJavaScript('myFunction()'); }) Web({ src: $rawfile('index.html'), controller: this.controller }) .onConsole((event) => { if (event) { console.log('getMessage:' + event.message.getMessage()); console.log('getSourceId:' + event.message.getSourceId()); console.log('getLineNumber:' + event.message.getLineNumber()); console.log('getMessageLevel:' + event.message.getMessageLevel()); } return false; }) } } } ``` 加载的html文件。 ```html ``` ### onDownloadStart onDownloadStart(callback: Callback\) 通知主应用开始下载一个文件。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------------ | ------ | ---- | ----------------------------------- | | callback | Callback\<[OnDownloadStartEvent](#ondownloadstartevent12)\> | 是 | 开始下载时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onDownloadStart((event) => { if (event) { console.log('url:' + event.url) console.log('userAgent:' + event.userAgent) console.log('contentDisposition:' + event.contentDisposition) console.log('contentLength:' + event.contentLength) console.log('mimetype:' + event.mimetype) } }) } } } ``` ### onErrorReceive onErrorReceive(callback: Callback\) 网页加载遇到错误时触发该回调。主资源与子资源出错都会回调该接口，可以通过request.isMainFrame来判断是否是主资源报错。出于性能考虑，建议此回调中尽量执行简单逻辑。在无网络的情况下，触发此回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | --------------- | | callback | Callback\<[OnErrorReceiveEvent](#onerrorreceiveevent12)\> | 是 | 网页收到 Web 资源加载错误时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onErrorReceive((event) => { if (event) { console.log('getErrorInfo:' + event.error.getErrorInfo()); console.log('getErrorCode:' + event.error.getErrorCode()); console.log('url:' + event.request.getRequestUrl()); console.log('isMainFrame:' + event.request.isMainFrame()); console.log('isRedirect:' + event.request.isRedirect()); console.log('isRequestGesture:' + event.request.isRequestGesture()); console.log('getRequestHeader_headerKey:' + event.request.getRequestHeader().toString()); let result = event.request.getRequestHeader(); console.log('The request header result size is ' + result.length); for (let i of result) { console.log('The request header key is : ' + i.headerKey + ', value is : ' + i.headerValue); } } }) } } } ``` ### onHttpErrorReceive onHttpErrorReceive(callback: Callback\) 网页加载资源遇到的HTTP错误（响应码>=400)时触发该回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ---------- | | callback | Callback\<[OnHttpErrorReceiveEvent](#onhttperrorreceiveevent12)\> | 是 | 网页收到加载资源加载HTTP错误时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onHttpErrorReceive((event) => { if (event) { console.log('url:' + event.request.getRequestUrl()); console.log('isMainFrame:' + event.request.isMainFrame()); console.log('isRedirect:' + event.request.isRedirect()); console.log('isRequestGesture:' + event.request.isRequestGesture()); console.log('getResponseData:' + event.response.getResponseData()); console.log('getResponseEncoding:' + event.response.getResponseEncoding()); console.log('getResponseMimeType:' + event.response.getResponseMimeType()); console.log('getResponseCode:' + event.response.getResponseCode()); console.log('getReasonMessage:' + event.response.getReasonMessage()); let result = event.request.getRequestHeader(); console.log('The request header result size is ' + result.length); for (let i of result) { console.log('The request header key is : ' + i.headerKey + ' , value is : ' + i.headerValue); } let resph = event.response.getResponseHeader(); console.log('The response header result size is ' + resph.length); for (let i of resph) { console.log('The response header key is : ' + i.headerKey + ' , value is : ' + i.headerValue); } } }) } } } ``` ### onPageBegin onPageBegin(callback: Callback\) 网页开始加载时触发该回调，且只在主frame触发，iframe或者frameset的内容加载时不会触发此回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | --------- | | callback | Callback\<[OnPageBeginEvent](#onpagebeginevent12)\> | 是 | 网页加载开始时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onPageBegin((event) => { if (event) { console.log('url:' + event.url); } }) } } } ``` ### onPageEnd onPageEnd(callback: Callback\) 网页加载完成时触发该回调，且只在主frame触发。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | --------- | | callback | Callback\<[OnPageEndEvent](#onpageendevent12)\> | 是 | 网页加载结束时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onPageEnd((event) => { if (event) { console.log('url:' + event.url); } }) } } } ``` ### onProgressChange onProgressChange(callback: Callback\) 网页加载进度变化时触发该回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | --------------------- | | callback | Callback\<[OnProgressChangeEvent](#onprogresschangeevent12)\> | 是 | 页面加载进度变化时触发的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onProgressChange((event) => { if (event) { console.log('newProgress:' + event.newProgress); } }) } } } ``` ### onTitleReceive onTitleReceive(callback: Callback\) 网页document标题更改时触发该回调，当H5未设置元素时会返回对应的URL。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ------ | ---- | ------------- | | callback | Callback\<[OnTitleReceiveEvent](#ontitlereceiveevent12)\> | 是 | 定义主应用程序文档标题更改时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onTitleReceive((event) => { if (event) { console.log('title:' + event.title); } }) } } } ``` ### onRefreshAccessedHistory onRefreshAccessedHistory(callback: Callback\) 加载网页页面完成时触发该回调，用于应用更新其访问的历史链接。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------- | ---- | ---------------------------------------- | | callback | Callback\<[OnRefreshAccessedHistoryEvent](#onrefreshaccessedhistoryevent12)\> | 是 | 在网页刷新访问历史记录时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onRefreshAccessedHistory((event) => { if (event) { console.log('url:' + event.url + ' isReload:' + event.isRefreshed); } }) } } } ``` ### onSslErrorReceive(deprecated) onSslErrorReceive(callback: (event?: { handler: Function, error: object }) => void) 通知用户加载资源时发生SSL错误。 > **说明：** > > 从API version 8开始支持，从API version 9开始废弃。建议使用[onSslErrorEventReceive9+](#onsslerroreventreceive9)替代。 **系统能力：** SystemCapability.Web.Webview.Core ### onFileSelectorShow(deprecated) onFileSelectorShow(callback: (event?: { callback: Function, fileSelector: object }) => void) 调用此函数以处理具有“文件”输入类型的HTML表单，以响应用户按下的“选择文件”按钮。 > **说明：** > > 从API version 8开始支持，从API version 9开始废弃。建议使用[onShowFileSelector9+](#onshowfileselector9)替代。 **系统能力：** SystemCapability.Web.Webview.Core ### onRenderExited9+ onRenderExited(callback: Callback\) 应用渲染进程异常退出时触发该回调。 多个Web组件可能共享单个渲染进程，每个受影响的Web组件都会触发该回调。 应用处理该回调时，可以调用绑定的webviewController相关接口来恢复页面。例如[refresh](js-apis-webview.md#refresh)、[loadUrl](js-apis-webview.md#loadurl)等。 组件生命周期回调详情可参考[Web组件的生命周期](../../web/web-event-sequence.md)。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------------- | ---------------------------------------- | ---- | ---------------- | | callback | Callback\<[OnRenderExitedEvent](#onrenderexitedevent12)\> | 是 | 渲染过程退出时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'chrome://crash/', controller: this.controller }) .onRenderExited((event) => { if (event) { console.log('reason:' + event.renderExitReason); } }) } } } ``` ### onRenderProcessNotResponding12+ onRenderProcessNotResponding(callback: OnRenderProcessNotRespondingCallback) 渲染进程无响应时触发该回调函数。如果Web组件无法处理输入事件，或者无法在合理的时间范围内导航到新的URL，则认为网页进程无响应，并将触发该回调。 只要网页进程一直无响应，此回调仍可能会持续触发，直到网页进程再次响应，此时[onRenderProcessResponding](#onrenderprocessresponding12)将会触发。 应用可以通过WebviewController接口[terminateRenderProcess](js-apis-webview.md#terminaterenderprocess12)来终止关联的渲染进程，这可能会影响同一渲染进程的其他Web组件。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | | callback | [OnRenderProcessNotRespondingCallback](#onrenderprocessnotrespondingcallback12) | 是 | 渲染进程无响应时触发的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onRenderProcessNotResponding((data) => { console.log("onRenderProcessNotResponding: [jsStack]= " + data.jsStack + ", [process]=" + data.pid + ", [reason]=" + data.reason); }) } } } ``` ### onRenderProcessResponding12+ onRenderProcessResponding(callback: OnRenderProcessRespondingCallback) 渲染进程由无响应状态变回正常运行状态时触发该回调函数,该回调表明该网页并非真正卡死。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | | callback | [OnRenderProcessRespondingCallback](#onrenderprocessrespondingcallback12) | 是 | 渲染进程由无响应状态变回正常运行状态时触发的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onRenderProcessResponding(() => { console.log("onRenderProcessResponding again"); }) } } } ``` ### onShowFileSelector9+ onShowFileSelector(callback: Callback\) 调用此函数以处理具有“文件”输入类型的HTML表单。如果不调用此函数或返回false，Web组件会提供默认的“选择文件”处理界面。如果返回true，应用可以自定义“选择文件”的响应行为。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------ | ---------------------------------------- | ---- | ----------------- | | callback | Callback\<[OnShowFileSelectorEvent](#onshowfileselectorevent12), boolean\> | 是 | 用于通知Web组件文件选择的结果。
返回值boolean。当返回值为true时，用户可以调用系统提供的弹窗能力。当回调返回false时，函数中绘制的自定义弹窗无效。 | **示例：** 1. 拉起文件选择器。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { picker } from '@kit.CoreFileKit'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController() build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) .onShowFileSelector((event) => { console.log('MyFileUploader onShowFileSelector invoked') const documentSelectOptions = new picker.DocumentSelectOptions(); let uri: string | null = null; const documentViewPicker = new picker.DocumentViewPicker(); documentViewPicker.select(documentSelectOptions).then((documentSelectResult) => { uri = documentSelectResult[0]; console.info('documentViewPicker.select to file succeed and uri is:' + uri); if (event) { event.result.handleFileList([uri]); } }).catch((err: BusinessError) => { console.error(`Invoke documentViewPicker.select failed, code is ${err.code}, message is ${err.message}`); }) return true; }) } } } ``` 2. 拉起图库选择器。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { picker } from '@kit.CoreFileKit'; import { photoAccessHelper } from '@kit.MediaLibraryKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController() async selectFile(result: FileSelectorResult): Promise { let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions(); let photoPicker = new photoAccessHelper.PhotoViewPicker(); // 过滤选择媒体文件类型为IMAGE photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_VIDEO_TYPE; // 设置最大选择数量 photoSelectOptions.maxSelectNumber = 5; let chooseFile: picker.PhotoSelectResult = await photoPicker.select(photoSelectOptions); // 获取选择的文件列表 result.handleFileList(chooseFile.photoUris); } build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) .onShowFileSelector((event) => { if (event) { this.selectFile(event.result); } return true; }) } } } ``` 3. 拉起相机选择器。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { cameraPicker, camera } from '@kit.CameraKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { common } from '@kit.AbilityKit'; let mContext = getContext(this) as common.Context; async function openCamera(callback: Callback) { try { let pickerProfile: cameraPicker.PickerProfile = { cameraPosition: camera.CameraPosition.CAMERA_POSITION_BACK }; let pickerResult: cameraPicker.PickerResult = await cameraPicker.pick(mContext, [cameraPicker.PickerMediaType.PHOTO, cameraPicker.PickerMediaType.VIDEO], pickerProfile); callback(pickerResult.resultUri); } catch (error) { let err = error as BusinessError; console.error(`the pick call failed. error code: ${err.code}`); } } @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController() build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) .onShowFileSelector((event) => { openCamera((result) => { if (event) { console.log('Title is ' + event.fileSelector.getTitle()); console.log('Mode is ' + event.fileSelector.getMode()); console.log('Accept types are ' + event.fileSelector.getAcceptType()); console.log('Capture is ' + event.fileSelector.isCapture()); console.log('Mime types are ' + event.fileSelector.getMimeTypes()); event.result.handleFileList([result]); } }) return true; }) } } } ``` 加载的html文件。 ```html
``` ### onResourceLoad9+ onResourceLoad(callback: Callback\) 通知Web组件所加载的资源文件url信息。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnResourceLoadEvent](#onresourceloadevent12)\> | 是 | 加载url时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onResourceLoad((event) => { console.log('onResourceLoad: ' + event.url); }) } } } ``` ### onScaleChange9+ onScaleChange(callback: Callback\) 当前页面显示比例的变化时触发该回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnScaleChangeEvent](#onscalechangeevent12)\> | 是 | 当前页面显示比例的变化时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onScaleChange((event) => { console.log('onScaleChange changed from ' + event.oldScale + ' to ' + event.newScale); }) } } } ``` ### onUrlLoadIntercept(deprecated) onUrlLoadIntercept(callback: (event?: { data:string | WebResourceRequest }) => boolean) 当Web组件加载url之前触发该回调，用于判断是否阻止此次访问。默认允许加载。 从API version 10开始不再维护，建议使用[onLoadIntercept10+](#onloadintercept10)代替。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | (event?: { data:string \| [WebResourceRequest](#webresourcerequest) }) => boolean | 是 | url的相关信息。返回值：boolean，true表示阻止此次加载，否则允许此次加载。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onUrlLoadIntercept((event) => { if (event) { console.log('onUrlLoadIntercept ' + event.data.toString()); } return true }) } } } ``` ### onInterceptRequest9+ onInterceptRequest(callback: Callback) 当Web组件加载url之前触发该回调，用于拦截url并返回响应数据。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnInterceptRequestEvent](#oninterceptrequestevent12), [WebResourceResponse](#webresourceresponse)\> | 是 | 当Web组件加载url之前触发。
返回值[WebResourceResponse](#webresourceresponse)。返回响应数据则按照响应数据加载，无响应数据则返回null表示按照原来的方式加载。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); responseWeb: WebResourceResponse = new WebResourceResponse(); heads: Header[] = new Array(); webData: string = "\n" + "\n" + "\n" + "intercept test\n" + "\n" + "\n" + "

intercept test

\n" + "\n" + ""; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onInterceptRequest((event) => { if (event) { console.log('url:' + event.request.getRequestUrl()); } let head1: Header = { headerKey: "Connection", headerValue: "keep-alive" } let head2: Header = { headerKey: "Cache-Control", headerValue: "no-cache" } // 将新元素追加到数组的末尾，并返回数组的新长度。 let length = this.heads.push(head1); length = this.heads.push(head2); console.log('The response header result length is :' + length); const promise: Promise = new Promise((resolve: Function, reject: Function) => { this.responseWeb.setResponseHeader(this.heads); this.responseWeb.setResponseData(this.webData); this.responseWeb.setResponseEncoding('utf-8'); this.responseWeb.setResponseMimeType('text/html'); this.responseWeb.setResponseCode(200); this.responseWeb.setReasonMessage('OK'); resolve("success"); }) promise.then(() => { console.log("prepare response ready"); this.responseWeb.setResponseIsReady(true); }) this.responseWeb.setResponseIsReady(false); return this.responseWeb; }) } } } ``` ### onHttpAuthRequest9+ onHttpAuthRequest(callback: Callback\) 通知收到http auth认证请求。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnHttpAuthRequestEvent](#onhttpauthrequestevent12), boolean\> | 是 | 当浏览器需要用户的凭据时触发。
返回值boolean。返回false表示此次认证失败，否则成功。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); httpAuth: boolean = false; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onHttpAuthRequest((event) => { if (event) { AlertDialog.show({ title: 'onHttpAuthRequest', message: 'text', primaryButton: { value: 'cancel', action: () => { event.handler.cancel(); } }, secondaryButton: { value: 'ok', action: () => { this.httpAuth = event.handler.isHttpAuthInfoSaved(); if (this.httpAuth == false) { webview.WebDataBase.saveHttpAuthCredentials( event.host, event.realm, "2222", "2222" ) event.handler.cancel(); } } }, cancel: () => { event.handler.cancel(); } }) } return true; }) } } } ``` ### onSslErrorEventReceive9+ onSslErrorEventReceive(callback: Callback\) 通知用户加载资源时发生SSL错误，只支持主资源。 如果需要支持子资源，请使用[OnSslErrorEvent](#onsslerrorevent12)接口。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnSslErrorEventReceiveEvent](#onsslerroreventreceiveevent12)\> | 是 | 当网页收到SSL错误时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { cert } from '@kit.DeviceCertificateKit'; function LogCertInfo(certChainData : Array | undefined) { if (!(certChainData instanceof Array)) { console.log('failed, cert chain data type is not array'); return; } for (let i = 0; i < certChainData.length; i++) { let encodeBlobData: cert.EncodingBlob = { data: certChainData[i], encodingFormat: cert.EncodingFormat.FORMAT_DER } cert.createX509Cert(encodeBlobData, (error, x509Cert) => { if (error) { console.error('Index : ' + i + ',createX509Cert failed, errCode: ' + error.code + ', errMsg: ' + error.message); } else { console.log('createX509Cert success'); console.log(ParseX509CertInfo(x509Cert)); } }); } return; } function Uint8ArrayToString(dataArray: Uint8Array) { let dataString = ''; for (let i = 0; i < dataArray.length; i++) { dataString += String.fromCharCode(dataArray[i]); } return dataString; } function ParseX509CertInfo(x509Cert: cert.X509Cert) { let res: string = 'getCertificate success, ' + 'issuer name = ' + Uint8ArrayToString(x509Cert.getIssuerName().data) + ', subject name = ' + Uint8ArrayToString(x509Cert.getSubjectName().data) + ', valid start = ' + x509Cert.getNotBeforeTime() + ', valid end = ' + x509Cert.getNotAfterTime(); return res; } @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onSslErrorEventReceive((event) => { LogCertInfo(event.certChainData); AlertDialog.show({ title: 'onSslErrorEventReceive', message: 'text', primaryButton: { value: 'confirm', action: () => { event.handler.handleConfirm(); } }, secondaryButton: { value: 'cancel', action: () => { event.handler.handleCancel(); } }, cancel: () => { event.handler.handleCancel(); } }) }) } } } ``` ### onSslErrorEvent12+ onSslErrorEvent(callback: OnSslErrorEventCallback) 通知用户加载资源（主资源+子资源）时发生SSL错误，如果只想处理主资源的SSL错误，请用isMainFrame字段进行区分。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnSslErrorEventCallback](#onsslerroreventcallback12) | 是 | 通知用户加载资源时发生SSL错误。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onSslErrorEvent((event: SslErrorEvent) => { console.log("onSslErrorEvent url: " + event.url); console.log("onSslErrorEvent error: " + event.error); console.log("onSslErrorEvent originalUrl: " + event.originalUrl); console.log("onSslErrorEvent referrer: " + event.referrer); console.log("onSslErrorEvent isFatalError: " + event.isFatalError); console.log("onSslErrorEvent isMainFrame: " + event.isMainFrame); AlertDialog.show({ title: 'onSslErrorEvent', message: 'text', primaryButton: { value: 'confirm', action: () => { event.handler.handleConfirm(); } }, secondaryButton: { value: 'cancel', action: () => { event.handler.handleCancel(); } }, cancel: () => { event.handler.handleCancel(); } }) }) } } } ``` ### onClientAuthenticationRequest9+ onClientAuthenticationRequest(callback: Callback\) 通知用户收到SSL客户端证书请求事件。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnClientAuthenticationEvent](#onclientauthenticationevent12)\> | 是 | 当需要用户提供的SSL客户端证书时触发的回调。 | **示例：** 未对接证书管理的双向认证。 ```ts // xxx.ets API9 import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onClientAuthenticationRequest((event) => { AlertDialog.show({ title: 'onClientAuthenticationRequest', message: 'text', primaryButton: { value: 'confirm', action: () => { event.handler.confirm("/system/etc/user.pk8", "/system/etc/chain-user.pem"); } }, secondaryButton: { value: 'cancel', action: () => { event.handler.cancel(); } }, cancel: () => { event.handler.ignore(); } }) }) } } } ``` 对接证书管理的双向认证。 1. 构造单例对象GlobalContext。 ```ts // GlobalContext.ets export class GlobalContext { private constructor() {} private static instance: GlobalContext; private _objects = new Map(); public static getContext(): GlobalContext { if (!GlobalContext.instance) { GlobalContext.instance = new GlobalContext(); } return GlobalContext.instance; } getObject(value: string): Object | undefined { return this._objects.get(value); } setObject(key: string, objectClass: Object): void { this._objects.set(key, objectClass); } } ``` 2. 实现双向认证。 ```ts // xxx.ets API10 import { webview } from '@kit.ArkWeb'; import { common, Want, bundleManager } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { GlobalContext } from '../GlobalContext'; let uri = ""; export default class CertManagerService { private static sInstance: CertManagerService; private authUri = ""; private appUid = ""; public static getInstance(): CertManagerService { if (CertManagerService.sInstance == null) { CertManagerService.sInstance = new CertManagerService(); } return CertManagerService.sInstance; } async grantAppPm(callback: (message: string) => void) { let message = ''; let bundleFlags = bundleManager.BundleFlag.GET_BUNDLE_INFO_DEFAULT | bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION; // 注：com.example.myapplication需要写实际应用名称 try { bundleManager.getBundleInfoForSelf(bundleFlags).then((data) => { console.info('getBundleInfoForSelf successfully. Data: %{public}s', JSON.stringify(data)); this.appUid = data.appInfo.uid.toString(); }).catch((err: BusinessError) => { console.error('getBundleInfoForSelf failed. Cause: %{public}s', err.message); }); } catch (err) { let message = (err as BusinessError).message; console.error('getBundleInfoForSelf failed: %{public}s', message); } // 注：需要在MainAbility.ts文件的onCreate函数里添加GlobalContext.getContext().setObject("AbilityContext", this.context) let abilityContext = GlobalContext.getContext().getObject("AbilityContext") as common.UIAbilityContext await abilityContext.startAbilityForResult( { bundleName: "com.ohos.certmanager", abilityName: "MainAbility", uri: "requestAuthorize", parameters: { appUid: this.appUid, // 传入申请应用的appUid } } as Want) .then((data: common.AbilityResult) => { if (!data.resultCode && data.want) { if (data.want.parameters) { this.authUri = data.want.parameters.authUri as string; // 授权成功后获取返回的authUri } } }) message += "after grantAppPm authUri: " + this.authUri; uri = this.authUri; callback(message) } } @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State message: string = 'Hello World' // message主要是调试观察使用 certManager = CertManagerService.getInstance(); build() { Row() { Column() { Row() { // 第一步：需要先进行授权，获取到uri Button('GrantApp') .onClick(() => { this.certManager.grantAppPm((data) => { this.message = data; }); }) // 第二步：授权后，双向认证会通过onClientAuthenticationRequest回调将uri传给web进行认证 Button("ClientCertAuth") .onClick(() => { this.controller.loadUrl('https://www.example2.com'); // 支持双向认证的服务器网站 }) } Web({ src: 'https://www.example1.com', controller: this.controller }) .fileAccess(true) .javaScriptAccess(true) .domStorageAccess(true) .onlineImageAccess(true) .onClientAuthenticationRequest((event) => { AlertDialog.show({ title: 'ClientAuth', message: 'Text', confirm: { value: 'Confirm', action: () => { event.handler.confirm(uri); } }, cancel: () => { event.handler.cancel(); } }) }) } } .width('100%') .height('100%') } } ``` ### onPermissionRequest9+ onPermissionRequest(callback: Callback\) 通知收到获取权限请求，需配置"ohos.permission.CAMERA"、"ohos.permission.MICROPHONE"权限。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnPermissionRequestEvent](#onpermissionrequestevent12)\> | 是 | 通知收到获取权限请求触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; import { abilityAccessCtrl } from '@kit.AbilityKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); aboutToAppear() { // 配置Web开启调试模式 webview.WebviewController.setWebDebuggingAccess(true); let atManager = abilityAccessCtrl.createAtManager(); atManager.requestPermissionsFromUser(getContext(this), ['ohos.permission.CAMERA', 'ohos.permission.MICROPHONE']) .then((data) => { console.info('data:' + JSON.stringify(data)); console.info('data permissions:' + data.permissions); console.info('data authResults:' + data.authResults); }).catch((error: BusinessError) => { console.error(`Failed to request permissions from user. Code is ${error.code}, message is ${error.message}`); }) } build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) .onPermissionRequest((event) => { if (event) { AlertDialog.show({ title: 'title', message: 'text', primaryButton: { value: 'deny', action: () => { event.request.deny(); } }, secondaryButton: { value: 'onConfirm', action: () => { event.request.grant(event.request.getAccessibleResource()); } }, cancel: () => { event.request.deny(); } }) } }) } } } ``` 加载的html文件。 ```html
``` ### onContextMenuShow9+ onContextMenuShow(callback: Callback\) 长按特定元素（例如图片，链接）或鼠标右键，跳出菜单。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnContextMenuShowEvent](#oncontextmenushowevent12), boolean\> | 是 | 调用时触发的回调，以允许自定义显示上下文菜单。
返回值boolean。自定义菜单返回true，触发的自定义菜单无效返回false。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { pasteboard } from '@kit.BasicServicesKit'; const TAG = 'ContextMenu'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); private result: WebContextMenuResult | undefined = undefined; @State linkUrl: string = ''; @State offsetX: number = 0; @State offsetY: number = 0; @State showMenu: boolean = false; @Builder // 构建自定义菜单及触发功能接口 MenuBuilder() { // 以垂直列表形式显示的菜单。 Menu() { // 展示菜单Menu中具体的item菜单项。 MenuItem({ content: '复制图片', }) .width(100) .height(50) .onClick(() => { this.result?.copyImage(); this.showMenu = false; }) MenuItem({ content: '剪切', }) .width(100) .height(50) .onClick(() => { this.result?.cut(); this.showMenu = false; }) MenuItem({ content: '复制', }) .width(100) .height(50) .onClick(() => { this.result?.copy(); this.showMenu = false; }) MenuItem({ content: '粘贴', }) .width(100) .height(50) .onClick(() => { this.result?.paste(); this.showMenu = false; }) MenuItem({ content: '复制链接', }) .width(100) .height(50) .onClick(() => { let pasteData = pasteboard.createData('text/plain', this.linkUrl); pasteboard.getSystemPasteboard().setData(pasteData, (error) => { if (error) { return; } }) this.showMenu = false; }) MenuItem({ content: '全选', }) .width(100) .height(50) .onClick(() => { this.result?.selectAll(); this.showMenu = false; }) } .width(150) .height(300) } build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) // 触发自定义弹窗 .onContextMenuShow((event) => { if (event) { this.result = event.result console.info("x coord = " + event.param.x()); console.info("link url = " + event.param.getLinkUrl()); this.linkUrl = event.param.getLinkUrl(); } console.info(TAG, `x: ${this.offsetX}, y: ${this.offsetY}`); this.showMenu = true; this.offsetX = 0; this.offsetY = Math.max(px2vp(event?.param.y() ?? 0) - 0, 0); return true; }) .bindPopup(this.showMenu, { builder: this.MenuBuilder(), enableArrow: false, placement: Placement.LeftTop, offset: { x: this.offsetX, y: this.offsetY }, mask: false, onStateChange: (e) => { if (!e.isVisible) { this.showMenu = false; this.result!.closeContextMenu(); } } }) } } } ``` 加载的html文件。 ```html

onContextMenuShow

链接www.example.com // rawfile下放任意一张图片命名为example.png

选中文字鼠标右键弹出菜单

``` ### onContextMenuHide11+ onContextMenuHide(callback: OnContextMenuHideCallback) 长按特定元素（例如图片，链接）或鼠标右键，隐藏菜单。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnContextMenuHideCallback](#oncontextmenuhidecallback11) | 是 | 菜单相关参数。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onContextMenuHide(() => { console.log("onContextMenuHide callback"); }) } } } ``` ### onScroll9+ onScroll(callback: Callback\) 通知网页滚动条滚动位置。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnScrollEvent](#onscrollevent12)\> | 是 | 当滚动条滑动到指定位置时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onScroll((event) => { console.info("x = " + event.xOffset); console.info("y = " + event.yOffset); }) } } } ``` ### onGeolocationShow onGeolocationShow(callback: Callback\) 通知用户收到地理位置信息获取请求。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnGeolocationShowEvent](#ongeolocationshowevent12)\> | 是 | 请求显示地理位置权限时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) .geolocationAccess(true) .onGeolocationShow((event) => { if (event) { AlertDialog.show({ title: 'title', message: 'text', confirm: { value: 'onConfirm', action: () => { event.geolocation.invoke(event.origin, true, true); } }, cancel: () => { event.geolocation.invoke(event.origin, false, true); } }) } }) } } } ``` 加载的html文件。 ```html

位置信息

``` ### onGeolocationHide onGeolocationHide(callback: () => void) 通知用户先前被调用[onGeolocationShow](#ongeolocationshow)时收到地理位置信息获取请求已被取消。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | () => void | 是 | 地理位置信息获取请求已被取消的回调函数。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .geolocationAccess(true) .onGeolocationHide(() => { console.log("onGeolocationHide..."); }) } } } ``` ### onFullScreenEnter9+ onFullScreenEnter(callback: OnFullScreenEnterCallback) 通知开发者Web组件进入全屏模式。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnFullScreenEnterCallback](#onfullscreenentercallback12) | 是 | Web组件进入全屏时的回调信息。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); handler: FullScreenExitHandler | null = null; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onFullScreenEnter((event) => { console.log("onFullScreenEnter videoWidth: " + event.videoWidth + ", videoHeight: " + event.videoHeight); // 应用可以通过 this.handler.exitFullScreen() 主动退出全屏。 this.handler = event.handler; }) } } } ``` ### onFullScreenExit9+ onFullScreenExit(callback: () => void) 通知开发者Web组件退出全屏模式。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | () => void | 是 | 退出全屏模式时的回调函数。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); handler: FullScreenExitHandler | null = null; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onFullScreenExit(() => { console.log("onFullScreenExit...") if (this.handler) { this.handler.exitFullScreen(); } }) .onFullScreenEnter((event) => { this.handler = event.handler; }) } } } ``` ### onWindowNew9+ onWindowNew(callback: Callback\) 使能multiWindowAccess情况下，通知用户新建窗口请求。 若不调用event.handler.setWebController接口，会造成render进程阻塞。 如果没有创建新窗口，调用event.handler.setWebController接口时设置成null，通知Web没有创建新窗口。 应用应谨慎的显示新窗口：不要简单的覆盖在原web组件上，防止误导用户正在查看哪个网站，如果应用显示主页的URL，请确保也以相似的方式显示新窗口的URL。否则请考虑完全禁止创建新窗口。 注意：没有可靠的方式判断哪个页面请求了新窗口，该请求可能来自第三方iframe **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnWindowNewEvent](#onwindownewevent12)\> | 是 | 网页要求用户创建窗口时触发的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; // 在同一page页有两个Web组件。在WebComponent新开窗口时，会跳转到NewWebViewComp。 @CustomDialog struct NewWebViewComp { controller?: CustomDialogController; webviewController1: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: "", controller: this.webviewController1 }) .javaScriptAccess(true) .multiWindowAccess(false) .onWindowExit(() => { console.info("NewWebViewComp onWindowExit"); if (this.controller) { this.controller.close(); } }) } } } @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); dialogController: CustomDialogController | null = null; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .javaScriptAccess(true) // 需要使能multiWindowAccess .multiWindowAccess(true) .allowWindowOpenMethod(true) .onWindowNew((event) => { if (this.dialogController) { this.dialogController.close(); } let popController: webview.WebviewController = new webview.WebviewController(); this.dialogController = new CustomDialogController({ builder: NewWebViewComp({ webviewController1: popController }) }) this.dialogController.open(); // 将新窗口对应WebviewController返回给Web内核。 // 若不调用event.handler.setWebController接口，会造成render进程阻塞。 // 如果没有创建新窗口，调用event.handler.setWebController接口时设置成null，通知Web没有创建新窗口。 event.handler.setWebController(popController); }) } } } ``` ### onWindowExit9+ onWindowExit(callback: () => void) 通知用户窗口关闭请求。和[onWindowNew](#onwindownew9)一样，从安全角度讲，应用应该确保用户可以知道他们交互的页面已关闭。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | () => void | 是 | 窗口请求关闭的回调函数。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onWindowExit(() => { console.log("onWindowExit..."); }) } } } ``` ### onSearchResultReceive9+ onSearchResultReceive(callback: Callback\) 回调通知调用方网页页内查找的结果。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnSearchResultReceiveEvent](#onsearchresultreceiveevent12)\> | 是 | 通知调用方网页页内查找的结果。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onSearchResultReceive(ret => { if (ret) { console.log("on search result receive:" + "[cur]" + ret.activeMatchOrdinal + "[total]" + ret.numberOfMatches + "[isDone]" + ret.isDoneCounting); } }) } } } ``` ### onDataResubmitted9+ onDataResubmitted(callback: Callback\) 设置网页表单可以重新提交时触发的回调函数。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnDataResubmittedEvent](#ondataresubmittedevent12)\> | 是 | 网页表单可以重新提交时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { // 在网页中点击提交之后，点击refresh按钮可以重新提交时的触发函数。 Button('refresh') .onClick(() => { try { this.controller.refresh(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: $rawfile('index.html'), controller: this.controller }) .onDataResubmitted((event) => { console.log('onDataResubmitted'); event.handler.resend(); }) } } } ``` 加载的html文件。 ```html
``` ### onPageVisible9+ onPageVisible(callback: Callback\) 设置旧页面不再呈现，新页面即将可见时触发的回调函数。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnPageVisibleEvent](#onpagevisibleevent12)\> | 是 | 旧页面不再呈现，新页面即将可见时触发的回调函数。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onPageVisible((event) => { console.log('onPageVisible url:' + event.url); }) } } } ``` ### onInterceptKeyEvent9+ onInterceptKeyEvent(callback: (event: KeyEvent) => boolean) 设置键盘事件的回调函数，该回调在被Webview使用前触发。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | (event:[KeyEvent](../apis-arkui/arkui-ts/ts-universal-events-key.md#keyevent对象说明)) => boolean | 是 | 触发的KeyEvent事件。返回值：回调函数通过返回boolean类型值来决定是否继续将该KeyEvent传入Webview内核。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onInterceptKeyEvent((event) => { if (event.keyCode == 2017 || event.keyCode == 2018) { console.info(`onInterceptKeyEvent get event.keyCode ${event.keyCode}`); return true; } return false; }) } } } ``` ### onTouchIconUrlReceived9+ onTouchIconUrlReceived(callback: Callback\) 设置接收到apple-touch-icon url地址时的回调函数。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnTouchIconUrlReceivedEvent](#ontouchiconurlreceivedevent12)\> | 是 | 接收到的apple-touch-icon url地址时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.baidu.com', controller: this.controller }) .onTouchIconUrlReceived((event) => { console.log('onTouchIconUrlReceived:' + JSON.stringify(event)); }) } } } ``` ### onFaviconReceived9+ onFaviconReceived(callback: Callback\) 设置应用为当前页面接收到新的favicon时的回调函数。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnFaviconReceivedEvent](#onfaviconreceivedevent12)\> | 是 | 当前页面接收到新的favicon时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { image } from '@kit.ImageKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State icon: image.PixelMap | undefined = undefined; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onFaviconReceived((event) => { console.log('onFaviconReceived'); this.icon = event.favicon; }) } } } ``` ### onAudioStateChanged10+ onAudioStateChanged(callback: Callback\) 设置网页上的音频播放状态发生改变时的回调函数。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnAudioStateChangedEvent](#onaudiostatechangedevent12)\> | 是 | 网页上的音频播放状态发生改变时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State playing: boolean = false; build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onAudioStateChanged(event => { this.playing = event.playing; console.debug('onAudioStateChanged playing: ' + this.playing); }) } } } ``` ### onFirstContentfulPaint10+ onFirstContentfulPaint(callback: Callback\) 设置网页首次内容绘制回调函数。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnFirstContentfulPaintEvent](#onfirstcontentfulpaintevent12)\> | 是 | 网页首次内容绘制回调函数。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onFirstContentfulPaint(event => { if (event) { console.log("onFirstContentfulPaint:" + "[navigationStartTick]:" + event.navigationStartTick + ", [firstContentfulPaintMs]:" + event.firstContentfulPaintMs); } }) } } } ``` ### onFirstMeaningfulPaint12+ onFirstMeaningfulPaint(callback: [OnFirstMeaningfulPaintCallback](#onfirstmeaningfulpaintcallback12)) 设置网页绘制页面主要内容回调函数。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnFirstMeaningfulPaintCallback](#onfirstmeaningfulpaintcallback12) | 是 | 网页绘制页面主要内容度量信息的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onFirstMeaningfulPaint((details) => { console.log("onFirstMeaningfulPaint: [navigationStartTime]= " + details.navigationStartTime + ", [firstMeaningfulPaintTime]=" + details.firstMeaningfulPaintTime); }) } } } ``` ### onLargestContentfulPaint12+ onLargestContentfulPaint(callback: [OnLargestContentfulPaintCallback](#onlargestcontentfulpaintcallback12)) 设置网页绘制页面最大内容回调函数。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnLargestContentfulPaintCallback](#onlargestcontentfulpaintcallback12) | 是 | 网页绘制页面最大内容度量信息的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onLargestContentfulPaint((details) => { console.log("onLargestContentfulPaint: [navigationStartTime]= " + details.navigationStartTime + ", [largestImagePaintTime]=" + details.largestImagePaintTime + ", [largestTextPaintTime]=" + details.largestTextPaintTime + ", [largestImageLoadStartTime]=" + details.largestImageLoadStartTime + ", [largestImageLoadEndTime]=" + details.largestImageLoadEndTime + ", [imageBPP]=" + details.imageBPP); }) } } } ``` ### onLoadIntercept10+ onLoadIntercept(callback: Callback\) 当Web组件加载url之前触发该回调，用于判断是否阻止此次访问。默认允许加载。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnLoadInterceptEvent](#onloadinterceptevent12), boolean\> | 是 | 截获资源加载时触发的回调。
返回值boolean。返回true表示阻止此次加载，否则允许此次加载。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onLoadIntercept((event) => { console.log('url:' + event.data.getRequestUrl()); console.log('isMainFrame:' + event.data.isMainFrame()); console.log('isRedirect:' + event.data.isRedirect()); console.log('isRequestGesture:' + event.data.isRequestGesture()); return true; }) } } } ``` ### onRequestSelected onRequestSelected(callback: () => void) 当Web组件获得焦点时触发该回调。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onRequestSelected(() => { console.log('onRequestSelected'); }) } } } ``` ### onScreenCaptureRequest10+ onScreenCaptureRequest(callback: Callback\) 通知收到屏幕捕获请求。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnScreenCaptureRequestEvent](#onscreencapturerequestevent12)\> | 是 | 通知收到屏幕捕获请求。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onScreenCaptureRequest((event) => { if (event) { AlertDialog.show({ title: 'title: ' + event.handler.getOrigin(), message: 'text', primaryButton: { value: 'deny', action: () => { event.handler.deny(); } }, secondaryButton: { value: 'onConfirm', action: () => { event.handler.grant({ captureMode: WebCaptureMode.HOME_SCREEN }); } }, cancel: () => { event.handler.deny(); } }) } }) } } } ``` ### onOverScroll10+ onOverScroll(callback: Callback\) 该接口在网页过度滚动时触发，用于通知网页过度滚动的偏移量。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | Callback\<[OnOverScrollEvent](#onoverscrollevent12)\> | 是 | 网页过度滚动时触发。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onOverScroll((event) => { console.info("x = " + event.xOffset); console.info("y = " + event.yOffset); }) } } } ``` ### onControllerAttached10+ onControllerAttached(callback: () => void) 当Controller成功绑定到Web组件时触发该回调，并且该Controller必须为WebviewController，且禁止在该事件回调前调用Web组件相关的接口，否则会抛出js-error异常。 因该回调调用时网页还未加载，无法在回调中使用有关操作网页的接口，例如[zoomIn](js-apis-webview.md#zoomin)、[zoomOut](js-apis-webview.md#zoomout)等，可以使用[loadUrl](js-apis-webview.md#loadurl)、[getWebId](js-apis-webview.md#getwebid)等操作网页不相关的接口。 组件生命周期详情可参考[Web组件的生命周期](../../web/web-event-sequence.md)。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** 在该回调中使用loadUrl加载网页 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: '', controller: this.controller }) .onControllerAttached(() => { this.controller.loadUrl($rawfile("index.html")); }) } } } ``` 在该回调中使用getWebId ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .onControllerAttached(() => { try { let id = this.controller.getWebId(); console.log("id: " + id); } catch (error) { let code = (error as BusinessError).code; let message = (error as BusinessError).message; console.error(`ErrorCode: ${code}, Message: ${message}`); } }) } } } ``` 加载的html文件。 ```html

Hello World

``` ### onNavigationEntryCommitted11+ onNavigationEntryCommitted(callback: [OnNavigationEntryCommittedCallback](#onnavigationentrycommittedcallback11)) 当网页跳转提交时触发该回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnNavigationEntryCommittedCallback](#onnavigationentrycommittedcallback11) | 是 | 网页跳转提交时触发的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onNavigationEntryCommitted((details) => { console.log("onNavigationEntryCommitted: [isMainFrame]= " + details.isMainFrame + ", [isSameDocument]=" + details.isSameDocument + ", [didReplaceEntry]=" + details.didReplaceEntry + ", [navigationType]=" + details.navigationType + ", [url]=" + details.url); }) } } } ``` ### onSafeBrowsingCheckResult11+ onSafeBrowsingCheckResult(callback: OnSafeBrowsingCheckResultCallback) 收到网站安全风险检查结果时触发的回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnSafeBrowsingCheckResultCallback](#onsafebrowsingcheckresultcallback11) | 是 | 收到网站安全风险检查结果时触发的回调。| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; export enum ThreatType { UNKNOWN = -1, THREAT_ILLEGAL = 0, THREAT_FRAUD = 1, THREAT_RISK = 2, THREAT_WARNING = 3, } export class OnSafeBrowsingCheckResultCallback { threatType: ThreatType = ThreatType.UNKNOWN; } @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onSafeBrowsingCheckResult((callback) => { let jsonData = JSON.stringify(callback); let json: OnSafeBrowsingCheckResultCallback = JSON.parse(jsonData); console.log("onSafeBrowsingCheckResult: [threatType]= " + json.threatType); }) } } } ``` ### onNativeEmbedLifecycleChange11+ onNativeEmbedLifecycleChange(callback: (event: NativeEmbedDataInfo) => void) 当同层标签生命周期变化时触发该回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | (event: [NativeEmbedDataInfo](#nativeembeddatainfo11)) => void | 是 | 同层标签生命周期变化时触发该回调。 | **示例：** ```ts // EntryAbility.ets import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; import { hilog } from '@kit.PerformanceAnalysisKit'; import { window } from '@kit.ArkUI'; import { webview } from '@kit.ArkWeb'; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); // API12新增：开启同层渲染BFCache开关 let features = new webview.BackForwardCacheSupportedFeatures(); features.nativeEmbed = true; features.mediaTakeOver = true; webview.WebviewController.enableBackForwardCache(features); webview.WebviewController.initializeWebEngine(); } onDestroy(): void { hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); } onWindowStageCreate(windowStage: window.WindowStage): void { // Main window is created, set main page for this ability hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); windowStage.loadContent('pages/Index', (err) => { if (err.code) { hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); return; } hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.'); }); } onWindowStageDestroy(): void { // Main window is destroyed, release UI related resources hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy'); } onForeground(): void { // Ability has brought to foreground hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground'); } onBackground(): void { // Ability has back to background hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground'); } } ``` ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { @State embedStatus: string = ''; controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { // 默认行为：点击按钮跳转页面，关闭index页面，使同层标签销毁。 // API12新增：使能同层渲染所在的页面支持BFCache后，点击按钮跳转页面，关闭index页面，使同层标签进入BFCache。 Button('Destroy') .onClick(() => { try { this.controller.loadUrl("www.example.com"); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) // API12新增：使能同层渲染所在的页面支持BFCache后，点击按钮返回页面，使同层标签离开BFCache。 Button('backward') .onClick(() => { try { this.controller.backward(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) // API12新增：使能同层渲染所在的页面支持BFCache后，点击按钮前进页面，使同层标签进入BFCache。 Button('forward') .onClick(() => { try { this.controller.forward(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) // API12新增同层标签进入离开BFCache状态：非http与https协议加载的网页，Web内核不支持进入BFCache; // 因此如果要测试ENTER_BFCACHE/LEAVE_BFCACHE状态，需要将index.html放到Web服务器上，使用http或者https协议加载，如： // Web({ src: "http://xxxx/index.html", controller: this.controller }) Web({ src: $rawfile("index.html"), controller: this.controller }) .enableNativeEmbedMode(true) .onNativeEmbedLifecycleChange((event) => { // 当加载页面中有同层标签会触发Create。 if (event.status == NativeEmbedStatus.CREATE) { this.embedStatus = 'Create'; } // 当页面中同层标签移动或者缩放时会触发Update。 if (event.status == NativeEmbedStatus.UPDATE) { this.embedStatus = 'Update'; } // 退出页面时会触发Destroy。 if (event.status == NativeEmbedStatus.DESTROY) { this.embedStatus = 'Destroy'; } // 同层标签所在的页面进入BFCache时，会触发Enter BFCache。 if (event.status == NativeEmbedStatus.ENTER_BFCACHE) { this.embedStatus = 'Enter BFCache'; } // 同层标签所在的页面离开BFCache时，会触发Leave BFCache。 if (event.status == NativeEmbedStatus.LEAVE_BFCACHE) { this.embedStatus = 'Leave BFCache'; } console.log("status = " + this.embedStatus); console.log("surfaceId = " + event.surfaceId); console.log("embedId = " + event.embedId); if (event.info) { console.log("id = " + event.info.id); console.log("type = " + event.info.type); console.log("src = " + event.info.src); console.log("width = " + event.info.width); console.log("height = " + event.info.height); console.log("url = " + event.info.url); } }) } } } ``` 加载的html文件 ``` 同层渲染测试html
``` ### onNativeEmbedGestureEvent11+ onNativeEmbedGestureEvent(callback: (event: NativeEmbedTouchInfo) => void) 当手指触摸到同层标签时触发该回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | (event: [NativeEmbedTouchInfo](#nativeembedtouchinfo11)) => void | 是 | 手指触摸到同层标签时触发该回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { NodeController, BuilderNode, NodeRenderType, FrameNode, UIContext } from "@kit.ArkUI"; declare class Params { text: string; width: number; height: number; } declare class NodeControllerParams { surfaceId: string; renderType: NodeRenderType; width: number; height: number; } class MyNodeController extends NodeController { private rootNode: BuilderNode<[Params]> | undefined | null; private surfaceId_: string = ""; private renderType_: NodeRenderType = NodeRenderType.RENDER_TYPE_DISPLAY; private width_: number = 0; private height_: number = 0; setRenderOption(params: NodeControllerParams) { this.surfaceId_ = params.surfaceId; this.renderType_ = params.renderType; this.width_ = params.width; this.height_ = params.height; } makeNode(uiContext: UIContext): FrameNode | null { this.rootNode = new BuilderNode(uiContext, { surfaceId: this.surfaceId_, type: this.renderType_ }); this.rootNode.build(wrapBuilder(ButtonBuilder), { text: "myButton", width: this.width_, height: this.height_ }); return this.rootNode.getFrameNode(); } postEvent(event: TouchEvent | undefined): boolean { return this.rootNode?.postTouchEvent(event) as boolean; } } @Component struct ButtonComponent { @Prop params: Params; @State bkColor: Color = Color.Red; build() { Column() { Button(this.params.text) .height(50) .width(200) .border({ width: 2, color: Color.Red }) .backgroundColor(this.bkColor) } .width(this.params.width) .height(this.params.height) } } @Builder function ButtonBuilder(params: Params) { ButtonComponent({ params: params }) .backgroundColor(Color.Green) } @Entry @Component struct WebComponent { @State eventType: string = ''; controller: webview.WebviewController = new webview.WebviewController(); private nodeController: MyNodeController = new MyNodeController(); build() { Column() { Stack() { NodeContainer(this.nodeController) Web({ src: $rawfile("index.html"), controller: this.controller }) .enableNativeEmbedMode(true) .onNativeEmbedLifecycleChange((embed) => { if (embed.status == NativeEmbedStatus.CREATE) { this.nodeController.setRenderOption({ surfaceId: embed.surfaceId as string, renderType: NodeRenderType.RENDER_TYPE_TEXTURE, width: px2vp(embed.info?.width), height: px2vp(embed.info?.height) }); this.nodeController.rebuild(); } }) .onNativeEmbedGestureEvent((event) => { if (event && event.touchEvent) { if (event.touchEvent.type == TouchType.Down) { this.eventType = 'Down' } if (event.touchEvent.type == TouchType.Up) { this.eventType = 'Up' } if (event.touchEvent.type == TouchType.Move) { this.eventType = 'Move' } if (event.touchEvent.type == TouchType.Cancel) { this.eventType = 'Cancel' } let ret = this.nodeController.postEvent(event.touchEvent) if (event.result) { event.result.setGestureEventResult(ret, true); } console.log("embedId = " + event.embedId); console.log("touchType = " + this.eventType); console.log("x = " + event.touchEvent.touches[0].x); console.log("y = " + event.touchEvent.touches[0].y); console.log("Component globalPos:(" + event.touchEvent.target.area.globalPosition.x + "," + event.touchEvent.target.area.globalPosition.y + ")"); console.log("width = " + event.touchEvent.target.area.width); console.log("height = " + event.touchEvent.target.area.height); } }) } } } } ``` 加载的html文件 ``` 同层渲染测试html
``` ### onIntelligentTrackingPreventionResult12+ onIntelligentTrackingPreventionResult(callback: OnIntelligentTrackingPreventionCallback) 智能防跟踪功能使能时，当追踪者cookie被拦截时触发该回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnIntelligentTrackingPreventionCallback](#onintelligenttrackingpreventioncallback12) | 是 | 智能防跟踪功能使能时，当追踪者cookie被拦截时触发的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { // 需要打开智能防跟踪功能，才会触发onIntelligentTrackingPreventionResult回调 Button('enableIntelligentTrackingPrevention') .onClick(() => { try { this.controller.enableIntelligentTrackingPrevention(true); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) .onIntelligentTrackingPreventionResult((details) => { console.log("onIntelligentTrackingPreventionResult: [websiteHost]= " + details.host + ", [trackerHost]=" + details.trackerHost); }) } } } ``` ### onOverrideUrlLoading12+ onOverrideUrlLoading(callback: OnOverrideUrlLoadingCallback) 当URL将要加载到当前Web中时，让宿主应用程序有机会获得控制权，回调函数返回true将导致当前Web中止加载URL，而返回false则会导致Web继续照常加载URL。 POST请求不会触发该回调。 iframe加载HTTP(s)协议或about:blank时不会触发该回调，加载非HTTP(s)协议的跳转可以触发。调用loadUrl(String)主动触发的跳转不会触发该回调。 不要使用相同的URL调用loadUrl(String)方法，然后返回true。这样做会不必要地取消当前的加载并重新使用相同的URL开始新的加载。继续加载给定URL的正确方式是直接返回false，而不是调用loadUrl(String)。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnOverrideUrlLoadingCallback](#onoverrideurlloadingcallback12) | 是 | onOverrideUrlLoading的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile("index.html"), controller: this.controller }) .onOverrideUrlLoading((webResourceRequest: WebResourceRequest) => { if (webResourceRequest && webResourceRequest.getRequestUrl() == "about:blank") { return true; } return false; }) } } } ``` 加载的html文件。 ```html 测试网页

onOverrideUrlLoading Demo

Click here// 访问about:blank。 ``` ### onViewportFitChanged12+ onViewportFitChanged(callback: OnViewportFitChangedCallback) 网页meta中viewport-fit配置项更改时触发该回调，应用可在此回调中自适应布局视口。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnViewportFitChangedCallback](#onviewportfitchangedcallback12) | 是 | 网页meta中viewport-fit配置项更改时触发的回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) .onViewportFitChanged((data) => { let jsonData = JSON.stringify(data); let viewportFit: ViewportFit = JSON.parse(jsonData).viewportFit; if (viewportFit === ViewportFit.COVER) { // index.html网页支持沉浸式布局，可调用expandSafeArea调整web控件布局视口覆盖避让区域(状态栏或导航条)。 } else if (viewportFit === ViewportFit.CONTAINS) { // index.html网页不支持沉浸式布局，可调用expandSafeArea调整web控件布局视口为安全区域。 } else { // 默认值，可不作处理 } }) } } } ``` 加载的html文件。 ```html
``` ### onInterceptKeyboardAttach12+ onInterceptKeyboardAttach(callback: WebKeyboardCallback) 网页中可编辑元素（如input标签）拉起软键盘之前会回调该接口，应用可以使用该接口拦截系统软键盘的弹出，配置应用定制的软键盘（应用根据该接口可以决定使用系统默认软键盘/定制enter键的系统软键盘/全部由应用自定义的软键盘）。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [WebKeyboardCallback](#webkeyboardcallback12) | 是 | 拦截网页拉起软键盘回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { inputMethodEngine } from '@kit.IMEKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); webKeyboardController: WebKeyboardController = new WebKeyboardController() inputAttributeMap: Map = new Map([ ['UNSPECIFIED', inputMethodEngine.ENTER_KEY_TYPE_UNSPECIFIED], ['GO', inputMethodEngine.ENTER_KEY_TYPE_GO], ['SEARCH', inputMethodEngine.ENTER_KEY_TYPE_SEARCH], ['SEND', inputMethodEngine.ENTER_KEY_TYPE_SEND], ['NEXT', inputMethodEngine.ENTER_KEY_TYPE_NEXT], ['DONE', inputMethodEngine.ENTER_KEY_TYPE_DONE], ['PREVIOUS', inputMethodEngine.ENTER_KEY_TYPE_PREVIOUS] ]) /** * 自定义键盘组件Builder */ @Builder customKeyboardBuilder() { // 这里实现自定义键盘组件，对接WebKeyboardController实现输入、删除、关闭等操作。 Row() { Text("完成") .fontSize(20) .fontColor(Color.Blue) .onClick(() => { this.webKeyboardController.close(); }) // 插入字符。 Button("insertText").onClick(() => { this.webKeyboardController.insertText('insert '); }).margin({ bottom: 200, }) // 从后往前删除length参数指定长度的字符。 Button("deleteForward").onClick(() => { this.webKeyboardController.deleteForward(1); }).margin({ bottom: 200, }) // 从前往后删除length参数指定长度的字符。 Button("deleteBackward").onClick(() => { this.webKeyboardController.deleteBackward(1); }).margin({ left: -220, }) // 插入功能按键。 Button("sendFunctionKey").onClick(() => { this.webKeyboardController.sendFunctionKey(6); }) } } build() { Column() { Web({ src: $rawfile('index.html'), controller: this.controller }) .onInterceptKeyboardAttach((KeyboardCallbackInfo) => { // option初始化，默认使用系统默认键盘 let option: WebKeyboardOptions = { useSystemKeyboard: true, }; if (!KeyboardCallbackInfo) { return option; } // 保存WebKeyboardController，使用自定义键盘时候，需要使用该handler控制输入、删除、软键盘关闭等行为 this.webKeyboardController = KeyboardCallbackInfo.controller let attributes: Record = KeyboardCallbackInfo.attributes // 遍历attributes let attributeKeys = Object.keys(attributes) for (let i = 0; i < attributeKeys.length; i++) { console.log('WebCustomKeyboard key = ' + attributeKeys[i] + ', value = ' + attributes[attributeKeys[i]]) } if (attributes) { if (attributes['data-keyboard'] == 'customKeyboard') { // 根据html可编辑元素的属性，判断使用不同的软键盘，例如这里如果属性包含有data-keyboard，且值为customKeyboard，则使用自定义键盘 console.log('WebCustomKeyboard use custom keyboard') option.useSystemKeyboard = false; // 设置自定义键盘builder option.customKeyboard = () => { this.customKeyboardBuilder() } return option; } if (attributes['keyboard-return'] != undefined) { // 根据html可编辑元素的属性，判断使用不同的软键盘，例如这里如果属性包含有keyboard-return，使用系统键盘，并且指定系统软键盘enterKey类型 option.useSystemKeyboard = true; let enterKeyType: number | undefined = this.inputAttributeMap.get(attributes['keyboard-return']) if (enterKeyType != undefined) { option.enterKeyType = enterKeyType } return option; } } return option; }) } } } ``` 加载的html文件。 ```html

input标签，原有默认行为：


input标签，系统键盘自定义enterKeyType属性 enter key UNSPECIFIED：


input标签，系统键盘自定义enterKeyType属性 enter key GO：


input标签，系统键盘自定义enterKeyType属性 enter key SEARCH：


input标签，系统键盘自定义enterKeyType属性 enter key SEND：


input标签，系统键盘自定义enterKeyType属性 enter key NEXT：


input标签，系统键盘自定义enterKeyType属性 enter key DONE：


input标签，系统键盘自定义enterKeyType属性 enter key PREVIOUS：


input标签，应用自定义键盘：


``` ### onNativeEmbedVisibilityChange12+ onNativeEmbedVisibilityChange(callback: OnNativeEmbedVisibilityChangeCallback) 网页中同层标签（如Embed标签或Object标签）在视口内的可见性发生变化时会触发该回调。同层标签默认不可见，如果首次进入页面可见则会上报，不可见则不会上报，当同层标签大小由非0值变为0 *0时，不会上报不可见，由0 *0变为非0值时会上报可见。同层标签全部不可见才算不可见，部分可见或全部可见算作可见。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | callback | [OnNativeEmbedVisibilityChangeCallback](#onnativeembedvisibilitychangecallback12) | 是 | 同层标签可见性变化时触发该回调。 | **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { NodeController, BuilderNode, NodeRenderType, FrameNode, UIContext } from "@kit.ArkUI"; declare class Params { text: string; width: number; height: number; } declare class NodeControllerParams { surfaceId: string; renderType: NodeRenderType; width: number; height: number; } class MyNodeController extends NodeController { private rootNode: BuilderNode<[Params]> | undefined | null; private surfaceId_: string = ""; private renderType_: NodeRenderType = NodeRenderType.RENDER_TYPE_DISPLAY; private width_: number = 0; private height_: number = 0; setRenderOption(params: NodeControllerParams) { this.surfaceId_ = params.surfaceId; this.renderType_ = params.renderType; this.width_ = params.width; this.height_ = params.height; } makeNode(uiContext: UIContext): FrameNode | null { this.rootNode = new BuilderNode(uiContext, { surfaceId: this.surfaceId_, type: this.renderType_ }); this.rootNode.build(wrapBuilder(ButtonBuilder), { text: "myButton", width: this.width_, height: this.height_ }); return this.rootNode.getFrameNode(); } postEvent(event: TouchEvent | undefined): boolean { return this.rootNode?.postTouchEvent(event) as boolean; } } @Component struct ButtonComponent { @Prop params: Params; @State bkColor: Color = Color.Red; build() { Column() { Button(this.params.text) .height(50) .width(200) .border({ width: 2, color: Color.Red }) .backgroundColor(this.bkColor) } .width(this.params.width) .height(this.params.height) } } @Builder function ButtonBuilder(params: Params) { ButtonComponent({ params: params }) .backgroundColor(Color.Green) } @Entry @Component struct WebComponent { @State embedVisibility: string = ''; controller: webview.WebviewController = new webview.WebviewController(); private nodeController: MyNodeController = new MyNodeController(); build() { Column() { Stack() { NodeContainer(this.nodeController) Web({ src: $rawfile("index.html"), controller: this.controller }) .enableNativeEmbedMode(true) .onNativeEmbedLifecycleChange((embed) => { if (embed.status == NativeEmbedStatus.CREATE) { this.nodeController.setRenderOption({ surfaceId: embed.surfaceId as string, renderType: NodeRenderType.RENDER_TYPE_TEXTURE, width: px2vp(embed.info?.width), height: px2vp(embed.info?.height) }); this.nodeController.rebuild(); } }) .onNativeEmbedVisibilityChange((embed) => { if (embed.visibility) { this.embedVisibility = 'Visible'; } else { this.embedVisibility = 'Hidden'; } console.log("embedId = " + embed.embedId); console.log("visibility = " + embed.visibility); }) } } } } ``` 加载的html文件 ```html 同层渲染测试html
``` ## WebKeyboardCallback12+ type WebKeyboardCallback = (keyboardCallbackInfo: WebKeyboardCallbackInfo) => WebKeyboardOptions 拦截网页可编辑元素拉起软键盘的回调，一般在点击网页input标签时触发。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------- | ------ | ---- | ------------------ | | keyboardCallbackInfo | [WebKeyboardCallbackInfo](#webkeyboardcallbackinfo12) | 是 | 拦截网页拉起软键盘回调通知的入参，其中包括[WebKeyboardController](#webkeyboardcontroller12)、可编辑元素的属性。 | **返回值：** | 类型 | 说明 | | ------------------ | ------------------------------------------------------------ | | [WebKeyboardOptions](#webkeyboardoptions12) | 回调函数通过返回[WebKeyboardOptions](#webkeyboardoptions12)来决定ArkWeb内核拉起不同类型的软键盘。 | ## WebKeyboardCallbackInfo12+ 拦截网页可编辑元素拉起软键盘的回调入参，其中包括[WebKeyboardController](#webkeyboardcontroller12)、可编辑元素的属性。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 类型 | 必填 | 说明 | | -------------- | ------- | ---- | ---------------------------------------- | | controller | [WebKeyboardController](#webkeyboardcontroller12) | 是 | 提供控制自定义键盘的输入、删除、关闭等操作。 | | attributes | Record | 是 | 触发本次软键盘弹出的网页元素属性。 ## WebKeyboardOptions12+ 拦截网页可编辑元素拉起软键盘的回调返回值，可以指定使用的键盘类型，并返回给web内核，以控制拉起不同类型的软键盘； **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 类型 | 必填 | 说明 | | -------------- | ------- | ---- | ---------------------------------------- | | useSystemKeyboard | boolean | 是 | 是否使用系统默认软键盘。
true表示使用系统默认软键盘，false表示不使用系统默认软键盘。
默认值：true。 | | enterKeyType | number | 否 | 指定系统软键盘enter键的类型，取值范围见输入框架的定义[EnterKeyType](../apis-ime-kit/js-apis-inputmethod.md#enterkeytype10)，该参数为可选参数，当useSystemKeyboard为true，并且设置了有效的enterKeyType时候，才有效。| | customKeyboard | [CustomBuilder](../apis-arkui/arkui-ts/ts-types.md#custombuilder8) | 否 | 指定自定义键盘组件builder，可选参数，当useSystemKeyboard为false时，需要设置该参数，然后Web组件会拉起该自定义键盘。 ## WebKeyboardController12+ 控制自定义键盘的输入、删除、关闭等操作。示例代码参考[onInterceptKeyboardAttach](#oninterceptkeyboardattach12)。 ### constructor12+ constructor() WebKeyboardController的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### insertText12+ insertText(text: string): void 插入字符。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------- | ---- | --------------------- | | text | string | 是 | 向Web输入框插入字符。 | ### deleteForward12+ deleteForward(length: number): void 从后往前删除length参数指定长度的字符。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------- | ---- | ------------------------ | | length | number | 是 | 从后往前删除字符的长度。
参数无取值范围，当参数值大于字符长度时，默认删除光标前面所有字符；参数值为负数时，不执行删除操作。 | ### deleteBackward12+ deleteBackward(length: number): void 从前往后删除length参数指定长度的字符。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------- | ---- | ------------------------ | | length | number | 是 | 从前往后删除字符的长度。
参数无取值范围，当参数值大于字符长度时，默认删除光标后面所有字符；参数值为负数时，不执行删除操作。 | ### sendFunctionKey12+ sendFunctionKey(key: number): void 插入功能按键，目前仅支持enter键类型，取值见[EnterKeyType](../apis-ime-kit/js-apis-inputmethod.md#enterkeytype10)。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------- | ---- | ------------------------------------------ | | key | number | 是 | 向Web输入框传递功能键，目前仅支持enter键。 | ### close12+ close(): void 关闭自定义键盘。 **系统能力：** SystemCapability.Web.Webview.Core ## ConsoleMessage Web组件获取控制台信息对象。示例代码参考[onConsole事件](#onconsole)。 ### constructor constructor(message: string, sourceId: string, lineNumber: number, messageLevel: MessageLevel) ConsoleMessage的构造函数。 > **说明：** > > 从API version 8开始支持，从API version 9开始废弃。建议使用[constructor](#constructor9)代替。 **系统能力：** SystemCapability.Web.Webview.Core ### constructor9+ constructor() ConsoleMessage的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### getLineNumber getLineNumber(): number 获取ConsoleMessage的行数。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | -------------------- | | number | 返回ConsoleMessage的行数。 | ### getMessage getMessage(): string 获取ConsoleMessage的日志信息。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ---------------------- | | string | 返回ConsoleMessage的日志信息。 | ### getMessageLevel getMessageLevel(): MessageLevel 获取ConsoleMessage的信息级别。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | --------------------------------- | ---------------------- | | [MessageLevel](#messagelevel枚举说明) | 返回ConsoleMessage的信息级别。 | ### getSourceId getSourceId(): string 获取网页源文件路径和名字。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------- | | string | 返回网页源文件路径和名字。 | ## JsResult Web组件返回的弹窗确认或弹窗取消功能对象。示例代码参考[onAlert事件](#onalert)。 ### constructor constructor() JsResult的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### handleCancel handleCancel(): void 通知Web组件用户取消弹窗操作。 **系统能力：** SystemCapability.Web.Webview.Core ### handleConfirm handleConfirm(): void 通知Web组件用户确认弹窗操作。 **系统能力：** SystemCapability.Web.Webview.Core ### handlePromptConfirm9+ handlePromptConfirm(result: string): void 通知Web组件用户确认弹窗操作及对话框内容。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ----------- | | result | string | 是 | 用户输入的对话框内容。 | ## FullScreenExitHandler9+ 通知开发者Web组件退出全屏。示例代码参考[onFullScreenEnter事件](#onfullscreenenter9)。 ### constructor9+ constructor() FullScreenExitHandler的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### exitFullScreen9+ exitFullScreen(): void 通知开发者Web组件退出全屏。 **系统能力：** SystemCapability.Web.Webview.Core ## ControllerHandler9+ 设置用户新建Web组件的WebviewController对象。示例代码参考[onWindowNew事件](#onwindownew9)。 **系统能力：** SystemCapability.Web.Webview.Core ### constructor9+ constructor() ControllerHandler的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### setWebController9+ setWebController(controller: WebviewController): void 设置WebviewController对象，如果不需要打开新窗口请设置为null。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ---------------------------------------- | ---- | ---------------------------------------- | | controller | [WebviewController](js-apis-webview.md#webviewcontroller) | 是 | 新建Web组件的WebviewController对象，如果不需要打开新窗口请设置为null。 | ## WebResourceError Web组件资源管理错误信息对象。示例代码参考[onErrorReceive事件](#onerrorreceive)。 ### constructor constructor() WebResourceError的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### getErrorCode getErrorCode(): number 获取加载资源的错误码。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ----------- | | number | 返回加载资源的错误码。错误码的含义可以参考[WebNetErrorList](js-apis-netErrorList.md) | ### getErrorInfo getErrorInfo(): string 获取加载资源的错误信息。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------ | | string | 返回加载资源的错误信息。 | ## WebResourceRequest Web组件获取资源请求对象。示例代码参考[onErrorReceive事件](#onerrorreceive)。 ### constructor constructor() WebResourceRequest的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### getRequestHeader getRequestHeader(): Array\ 获取资源请求头信息。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | -------------------------- | ---------- | | Array\<[Header](#header)\> | 返回资源请求头信息。 | ### getRequestUrl getRequestUrl(): string 获取资源请求的URL信息。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------- | | string | 返回资源请求的URL信息。 | ### isMainFrame isMainFrame(): boolean 判断资源请求是否为主frame。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------- | ---------------- | | boolean | 返回资源请求是否为主frame。
true表示返回资源请求为主frame，false表示返回资源请求不为主frame。 | ### isRedirect isRedirect(): boolean 判断资源请求是否被服务端重定向。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------- | ---------------- | | boolean | 返回资源请求是否被服务端重定向。
true表示返回资源请求被服务端重定向，false表示返回资源请求未被服务端重定向。 | ### isRequestGesture isRequestGesture(): boolean 获取资源请求是否与手势（如点击）相关联。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------- | -------------------- | | boolean | 返回资源请求是否与手势（如点击）相关联。
true表示返回资源请求与手势（如点击）相关联，false表示返回资源请求与手势（如点击）不相关联。 | ### getRequestMethod9+ getRequestMethod(): string 获取请求方法。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------- | | string | 返回请求方法。 | ## Header Web组件返回的请求/响应头对象。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | ------------- | | headerKey | string | 是 | 请求/响应头的key。 | | headerValue | string | 是 | 请求/响应头的value。 | ## WebResourceResponse Web组件资源响应对象。示例代码参考[onHttpErrorReceive事件](#onhttperrorreceive)。 ### constructor constructor() WebResourceResponse的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### getReasonMessage getReasonMessage(): string 获取资源响应的状态码描述。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------- | | string | 返回资源响应的状态码描述。 | ### getResponseCode getResponseCode(): number 获取资源响应的状态码。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ----------- | | number | 返回资源响应的状态码。 | ### getResponseData getResponseData(): string 获取资源响应数据。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | --------- | | string | 返回资源响应数据。 | ### getResponseEncoding getResponseEncoding(): string 获取资源响应的编码。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ---------- | | string | 返回资源响应的编码。 | ### getResponseHeader getResponseHeader() : Array\ 获取资源响应头。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | -------------------------- | -------- | | Array\<[Header](#header)\> | 返回资源响应头。 | ### getResponseMimeType getResponseMimeType(): string 获取资源响应的媒体（MIME）类型。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------------ | | string | 返回资源响应的媒体（MIME）类型。 | ### getResponseDataEx13+ getResponseDataEx(): string | number | ArrayBuffer | Resource | undefined 获取资源响应数据，支持多种数据类型。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** |类型|说明| |---|---| |string|返回HTML格式的字符串。| |number|返回文件句柄。| |ArrayBuffer|返回二进制数据。| |[Resource](../apis-arkui/arkui-ts/ts-types.md)|返回`$rawfile`资源。| |undefined|如果没有可用数据，返回`undefined`。| ### getResponseIsReady13+ getResponseIsReady(): boolean 获取响应数据是否已准备就绪。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** |类型|说明| |---|---| |boolean|`true`表示响应数据已准备好，`false`表示未准备好。| ### setResponseData9+ setResponseData(data: string \| number \| Resource \| ArrayBuffer): void 设置资源响应数据。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ---------------------------------------- | ---- | ---------------------------------------- | | data | string \| number \| [Resource](../apis-arkui/arkui-ts/ts-types.md)10+ \| ArrayBuffer11+ | 是 | 要设置的资源响应数据。string表示HTML格式的字符串。number表示文件句柄, 此句柄由系统的Web组件负责关闭。 Resource表示应用rawfile目录下文件资源。 ArrayBuffer表示资源的原始二进制数据。 | ### setResponseEncoding9+ setResponseEncoding(encoding: string): void 设置资源响应的编码。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------ | ---- | ------------ | | encoding | string | 是 | 要设置的资源响应的编码。 | ### setResponseMimeType9+ setResponseMimeType(mimeType: string): void 设置资源响应的媒体（MIME）类型。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------ | ---- | -------------------- | | mimeType | string | 是 | 要设置的资源响应的媒体（MIME）类型。 | ### setReasonMessage9+ setReasonMessage(reason: string): void 设置资源响应的状态码描述。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------- | | reason | string | 是 | 要设置的资源响应的状态码描述。 | ### setResponseHeader9+ setResponseHeader(header: Array\): void 设置资源响应头。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------------------------- | ---- | ---------- | | header | Array\<[Header](#header)\> | 是 | 要设置的资源响应头。 | ### setResponseCode9+ setResponseCode(code: number): void 设置资源响应的状态码。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ------------- | | code | number | 是 | 要设置的资源响应的状态码。如果该资源以错误结束，请参考[@ohos.web.netErrorList](js-apis-netErrorList.md)设置相应错误码，避免设置错误码为 ERR_IO_PENDING，设置为该错误码可能会导致XMLHttpRequest同步请求阻塞。 | ### setResponseIsReady9+ setResponseIsReady(IsReady: boolean): void 设置资源响应数据是否已经就绪。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | ------------- | | IsReady | boolean | 是 | 资源响应数据是否已经就绪。
true表示资源响应数据已经就绪，false表示资源响应数据未就绪。默认值：true。 | ## FileSelectorResult9+ 通知Web组件的文件选择结果。示例代码参考[onShowFileSelector事件](#onshowfileselector9)。 ### constructor9+ constructor() FileSelectorResult的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### handleFileList9+ handleFileList(fileList: Array\): void 通知Web组件进行文件选择操作。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------- | ---- | ------------ | | fileList | Array\ | 是 | 需要进行操作的文件列表。 | ## FileSelectorParam9+ Web组件获取文件对象。示例代码参考[onShowFileSelector事件](#onshowfileselector9)。 ### constructor9+ constructor() FileSelectorParam的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### getTitle9+ getTitle(): string 获取文件选择器标题。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ---------- | | string | 返回文件选择器标题。 | ### getMode9+ getMode(): FileSelectorMode 获取文件选择器的模式。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ---------------------------------------- | ----------- | | [FileSelectorMode](#fileselectormode9枚举说明) | 返回文件选择器的模式。 | ### getAcceptType9+ getAcceptType(): Array\ 获取文件过滤类型。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | --------------- | --------- | | Array\ | 返回文件过滤类型。 | ### isCapture9+ isCapture(): boolean 获取是否调用多媒体能力。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------- | ------------ | | boolean | 返回是否调用多媒体能力。
true表示返回调用多媒体能力，false表示返回未调用多媒体能力。 | ### getMimeTypes18+ getMimeTypes(): Array\ 获取文件MIME类型。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | --------------- | --------- | | Array\ | 返回文件MIME类型。 | ## HttpAuthHandler9+ Web组件返回的http auth认证请求确认或取消和使用缓存密码认证功能对象。示例代码参考[onHttpAuthRequest事件](#onhttpauthrequest9)。 ### constructor9+ constructor() HttpAuthHandler的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### cancel9+ cancel(): void 通知Web组件用户取消HTTP认证操作。 **系统能力：** SystemCapability.Web.Webview.Core ### confirm9+ confirm(userName: string, password: string): boolean 使用用户名和密码进行HTTP认证操作。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------ | ---- | ---------- | | userName | string | 是 | HTTP认证用户名。 | | password | string | 是 | HTTP认证密码。 | **返回值：** | 类型 | 说明 | | ------- | --------------------- | | boolean | 认证成功返回true，失败返回false。 | ### isHttpAuthInfoSaved9+ isHttpAuthInfoSaved(): boolean 通知Web组件用户使用服务器缓存的账号密码认证。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------- | ------------------------- | | boolean | 存在密码认证成功返回true，其他返回false。 | ## SslErrorHandler9+ Web组件返回的SSL错误通知事件用户处理功能对象。示例代码参考[onSslErrorEventReceive事件](#onsslerroreventreceive9)。 ### constructor9+ constructor() SslErrorHandler的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### handleCancel9+ handleCancel(): void 通知Web组件取消此请求。 **系统能力：** SystemCapability.Web.Webview.Core ### handleConfirm9+ handleConfirm(): void 通知Web组件继续使用SSL证书。 **系统能力：** SystemCapability.Web.Webview.Core ## ClientAuthenticationHandler9+ Web组件返回的SSL客户端证书请求事件用户处理功能对象。示例代码参考[onClientAuthenticationRequest事件](#onclientauthenticationrequest9)。 ### constructor9+ constructor() ClientAuthenticationHandler的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### confirm9+ confirm(priKeyFile : string, certChainFile : string): void 通知Web组件使用指定的私钥和客户端证书链。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------- | ------ | ---- | ------------------ | | priKeyFile | string | 是 | 存放私钥文件的完整路径。 | | certChainFile | string | 是 | 存放证书链文件的完整路径。 | ### confirm10+ confirm(authUri : string): void 通知Web组件使用指定的凭据(从证书管理模块获得)。 > **说明：** > > 需要配置权限：ohos.permission.ACCESS_CERT_MANAGER。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | ------- | | authUri | string | 是 | 凭据的关键值。 | ### cancel9+ cancel(): void 通知Web组件取消相同host和port服务器发送的客户端证书请求事件。同时，相同host和port服务器的请求，不重复上报该事件。 **系统能力：** SystemCapability.Web.Webview.Core ### ignore9+ ignore(): void 通知Web组件忽略本次请求。 **系统能力：** SystemCapability.Web.Webview.Core ## PermissionRequest9+ Web组件返回授权或拒绝权限功能的对象。示例代码参考[onPermissionRequest事件](#onpermissionrequest9)。 ### constructor9+ constructor() PermissionRequest的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### deny9+ deny(): void 拒绝网页所请求的权限。 **系统能力：** SystemCapability.Web.Webview.Core ### getOrigin9+ getOrigin(): string 获取网页来源。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------ | | string | 当前请求权限网页的来源。 | ### getAccessibleResource9+ getAccessibleResource(): Array\ 获取网页所请求的权限资源列表，资源列表类型参考[ProtectedResourceType](#protectedresourcetype9枚举说明)。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | --------------- | ------------- | | Array\ | 网页所请求的权限资源列表。 | ### grant9+ grant(resources: Array\): void 对网页访问的给定权限进行授权。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | --------------- | ---- | --------------- | | resources | Array\ | 是 | 授予网页请求的权限的资源列表。 | ## ScreenCaptureHandler10+ Web组件返回授权或拒绝屏幕捕获功能的对象。示例代码参考[onScreenCaptureRequest事件](#onscreencapturerequest10)。 ### constructor10+ constructor() ScreenCaptureHandler的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### deny10+ deny(): void 拒绝网页所请求的屏幕捕获操作。 **系统能力：** SystemCapability.Web.Webview.Core ### getOrigin10+ getOrigin(): string 获取网页来源。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------ | | string | 当前请求权限网页的来源。 | ### grant10+ grant(config: ScreenCaptureConfig): void 对网页访问的屏幕捕获操作进行授权。 > **说明：** > > 需要配置权限：ohos.permission.MICROPHONE。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ---------------------------------------- | ---- | ------- | | config | [ScreenCaptureConfig](#screencaptureconfig10) | 是 | 屏幕捕获配置。 | ## EventResult12+ 通知Web组件事件消费结果，支持的事件参考[触摸事件的类型](../apis-arkui/arkui-ts/ts-appendix-enums.md#touchtype)。如果应用不消费该事件，则设置为false，事件被Web组件消费。应用消费了该事件，设置为true，Web组件不消费。示例代码参考[onNativeEmbedGestureEvent事件](#onnativeembedgestureevent11)。 ### constructor12+ constructor() EventResult的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### setGestureEventResult12+ setGestureEventResult(result: boolean): void 设置手势事件消费结果。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------------- | -------- | ---- |------- | | result | boolean | 是 | 是否消费该手势事件。
true表示消费该手势事件，false表示不消费该手势事件。默认值为true。 | **示例：** 请参考[onNativeEmbedGestureEvent事件](#onnativeembedgestureevent11)。 ### setGestureEventResult14+ setGestureEventResult(result: boolean, stopPropagation: boolean): void 设置手势事件消费结果。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------------- | -------- | ---- |------- | | result | boolean | 是 | 是否消费该手势事件。
true表示消费该手势事件，false表示不消费该手势事件。
默认值为true。 | | stopPropagation | boolean | 是 | 是否阻止冒泡，在result为true时生效。
true表示阻止冒泡，false表示不阻止冒泡。
默认值为true。 | **示例：** 请参考[onNativeEmbedGestureEvent事件](#onnativeembedgestureevent11)。 ## ContextMenuSourceType9+枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | --------- | -- |------------ | | None | 0 | 其他事件来源。 | | Mouse | 1 | 鼠标事件。 | | LongPress | 2 | 长按事件。 | ## ContextMenuMediaType9+枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ----- | -- | ------------- | | None | 0 | 非特殊媒体或其他媒体类型。 | | Image | 1 | 图片。 | ## ContextMenuInputFieldType9+枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | --------- | -- | --------------------------- | | None | 0 | 非输入框。 | | PlainText | 1 | 纯文本类型，包括text、search、email等。 | | Password | 2 | 密码类型。 | | Number | 3 | 数字类型。 | | Telephone | 4 | 电话号码类型。 | | Other | 5 | 其他类型。 | ## ContextMenuEditStateFlags9+枚举说明 支持以按位或的方式使用此枚举。例如，如果需要同时支持CAN_CUT、CAN_COPY和CAN_SELECT_ALL，可使用CAN_CUT | CAN_COPY | CAN_SELECT_ALL或11。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | -------------- | -- | -------- | | NONE | 0 | 不可编辑。 | | CAN_CUT | 1 << 0 | 支持剪切。 | | CAN_COPY | 1 << 1 | 支持拷贝。 | | CAN_PASTE | 1 << 2 | 支持粘贴。 | | CAN_SELECT_ALL | 1 << 3 | 支持全选。 | ## WebContextMenuParam9+ 实现长按页面元素或鼠标右键弹出来的菜单信息。示例代码参考[onContextMenuShow事件](#oncontextmenushow9)。 ### constructor9+ constructor() WebContextMenuParam的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### x9+ x(): number 弹出菜单的x坐标。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------------ | | number | 显示正常返回非负整数，否则返回-1。
单位：vp。 | ### y9+ y(): number 弹出菜单的y坐标。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------------ | | number | 显示正常返回非负整数，否则返回-1。
单位：vp。 | ### getLinkUrl9+ getLinkUrl(): string 获取链接地址。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------------------- | | string | 如果长按位置是链接，返回经过安全检查的url链接。 | ### getUnfilteredLinkUrl9+ getUnfilteredLinkUrl(): string 获取链接地址。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | --------------------- | | string | 如果长按位置是链接，返回原始的url链接。 | ### getSourceUrl9+ getSourceUrl(): string 获取sourceUrl链接。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ------------------------ | | string | 如果选中的元素有src属性，返回src的url。 | ### existsImageContents9+ existsImageContents(): boolean 是否存在图像内容。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------- | ------------------------- | | boolean | 长按位置中有图片返回true，否则返回false。 | ### getMediaType9+ getMediaType(): ContextMenuMediaType 获取网页元素媒体类型。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ---------------------------------------- | --------- | | [ContextMenuMediaType](#contextmenumediatype9枚举说明) | 网页元素媒体类型。 | ### getSelectionText9+ getSelectionText(): string 获取选中文本。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | -------------------- | | string | 菜单上下文选中文本内容，不存在则返回空。 | ### getSourceType9+ getSourceType(): ContextMenuSourceType 获取菜单事件来源。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | [ContextMenuSourceType](#contextmenusourcetype9枚举说明) | 菜单事件来源。 | ### getInputFieldType9+ getInputFieldType(): ContextMenuInputFieldType 获取网页元素输入框类型。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------ | | [ContextMenuInputFieldType](#contextmenuinputfieldtype9枚举说明) | 输入框类型。 | ### isEditable9+ isEditable(): boolean 获取网页元素是否可编辑标识。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------- | -------------------------- | | boolean | 网页元素可编辑返回true，不可编辑返回false。 | ### getEditStateFlags9+ getEditStateFlags(): number 获取网页元素可编辑标识。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ---------------------------------------- | | number | 网页元素可编辑标识，参照[ContextMenuEditStateFlags](#contextmenueditstateflags9枚举说明)。 | ### getPreviewWidth13+ getPreviewWidth(): number 获取预览图的宽。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ----------- | | number | 预览图的宽。
单位：vp。 | ### getPreviewHeight13+ getPreviewHeight(): number 获取预览图的高。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------ | ---------- | | number | 预览图的高。
单位：vp。 | ## WebContextMenuResult9+ 实现长按页面元素或鼠标右键弹出来的菜单所执行的响应事件。示例代码参考[onContextMenuShow事件](#oncontextmenushow9)。 ### constructor9+ constructor() WebContextMenuResult的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### closeContextMenu9+ closeContextMenu(): void 不执行WebContextMenuResult其他接口操作时，需要调用此接口关闭菜单。 **系统能力：** SystemCapability.Web.Webview.Core ### copyImage9+ copyImage(): void WebContextMenuParam有图片内容则复制图片。 **系统能力：** SystemCapability.Web.Webview.Core ### copy9+ copy(): void 执行与此上下文菜单相关的拷贝文本操作。 **系统能力：** SystemCapability.Web.Webview.Core ### paste9+ paste(): void 执行与此上下文菜单相关的粘贴操作。 > **说明：** > > 需要配置权限：ohos.permission.READ_PASTEBOARD。 **系统能力：** SystemCapability.Web.Webview.Core ### cut9+ cut(): void 执行与此上下文菜单相关的剪切操作。 **系统能力：** SystemCapability.Web.Webview.Core ### selectAll9+ selectAll(): void 执行与此上下文菜单相关的全选操作。 **系统能力：** SystemCapability.Web.Webview.Core ## JsGeolocation Web组件返回授权或拒绝权限功能的对象。示例代码参考[onGeolocationShow事件](#ongeolocationshow)。 ### constructor constructor() JsGeolocation的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### invoke invoke(origin: string, allow: boolean, retain: boolean): void 设置网页地理位置权限状态。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ---------------------------------------- | | origin | string | 是 | 指定源的字符串索引。 | | allow | boolean | 是 | 设置的地理位置权限状态。
true表示开启地理位置权限，false表示不开启地理位置权限。 | | retain | boolean | 是 | 是否允许将地理位置权限状态保存到系统中。可通过[GeolocationPermissions9+](js-apis-webview.md#geolocationpermissions)接口管理保存到系统的地理位置权限。
true表示允许，false表示不允许。 | ## MessageLevel枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ----- | -- | ---- | | Debug | 1 | 调试级别。 | | Error | 4 | 错误级别。 | | Info | 2 | 消息级别。 | | Log | 5 | 日志级别。 | | Warn | 3 | 警告级别。 | ## RenderExitReason9+枚举说明 onRenderExited接口返回的渲染进程退出的具体原因。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | -------------------------- | -- | ----------------- | | ProcessAbnormalTermination | 0 | 渲染进程异常退出。 | | ProcessWasKilled | 1 | 收到SIGKILL，或被手动终止。 | | ProcessCrashed | 2 | 渲染进程崩溃退出，如段错误。 | | ProcessOom | 3 | 程序内存不足。 | | ProcessExitUnknown | 4 | 其他原因。 | ## MixedMode枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ---------- | -- | ---------------------------------- | | All | 0 | 允许加载HTTP和HTTPS混合内容。所有不安全的内容都可以被加载。 | | Compatible | 1 | 混合内容兼容性模式，部分不安全的内容可能被加载。 | | None | 2 | 不允许加载HTTP和HTTPS混合内容。 | ## CacheMode枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ------- | -- | ------------------------------------ | | Default9+ | 0 | 优先使用未过期cache加载资源，无效或无cache时从网络获取。 | | None | 1 | 优先使用cache(含过期)加载资源，无cache时从网络获取。 | | Online | 2 | 强制从网络获取最新资源，不使用任何cache。 | | Only | 3 | 仅使用本地cache加载资源。 | ## FileSelectorMode9+枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | -------------------- | -- | ---------- | | FileOpenMode | 0 | 打开上传单个文件。 | | FileOpenMultipleMode | 1 | 打开上传多个文件。 | | FileOpenFolderMode | 2 | 打开上传文件夹模式。 | | FileSaveMode | 3 | 文件保存模式。 | ## HitTestType枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ------------- | -- | ------------------------ | | EditText | 0 | 可编辑的区域。 | | Email | 1 | 电子邮件地址。 | | HttpAnchor | 2 | 超链接，其src为http。 | | HttpAnchorImg | 3 | 带有超链接的图片，其中超链接的src为http。 | | Img | 4 | HTML::img标签。 | | Map | 5 | 地理地址。 | | Phone | 6 | 电话号码。 | | Unknown | 7 | 未知内容。 | ## OverScrollMode11+枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ------ | -- | ----------- | | NEVER | 0 | Web过滚动模式关闭。 | | ALWAYS | 1 | Web过滚动模式开启。 | ## OnContextMenuHideCallback11+ type OnContextMenuHideCallback = () => void 上下文菜单自定义隐藏的回调。 **系统能力：** SystemCapability.Web.Webview.Core ## SslError9+枚举说明 onSslErrorEventReceive接口返回的SSL错误的具体原因。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ------------ | -- | ----------- | | Invalid | 0 | 一般错误。 | | HostMismatch | 1 | 主机名不匹配。 | | DateInvalid | 2 | 证书日期无效。 | | Untrusted | 3 | 证书颁发机构不受信任。 | ## ProtectedResourceType9+枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | 备注 | | --------------------------- | --------------- | ------------- | -------------------------- | | MidiSysex | TYPE_MIDI_SYSEX | MIDI SYSEX资源。 | 目前仅支持权限事件上报，MIDI设备的使用还未支持。 | | VIDEO_CAPTURE10+ | TYPE_VIDEO_CAPTURE | 视频捕获资源，例如相机。 | | | AUDIO_CAPTURE10+ | TYPE_AUDIO_CAPTURE | 音频捕获资源，例如麦克风。 | | | SENSOR12+ | TYPE_SENSOR | 传感器资源，例如加速度传感器。 | | ## WebDarkMode9+枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ---- | -- | ------------ | | Off | 0 | Web深色模式关闭。 | | On | 1 | Web深色模式开启。 | | Auto | 2 | Web深色模式跟随系统。 | ## WebCaptureMode10+枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ----------- | -- | ------- | | HOME_SCREEN | 0 | 主屏捕获模式。 | ## WebMediaOptions10+ Web媒体策略的配置。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 类型 | 必填 | 说明 | | -------------- | ------- | ---- | ---------------------------------------- | | resumeInterval | number | 否 | 被暂停的Web音频能够自动续播的有效期，单位：秒。有效期范围0~60秒，如若超过60秒，按照60s处理，由于近似值原因，该有效期可能存在一秒内的误差。 | | audioExclusive | boolean | 否 | 应用内多个Web实例的音频是否独占。
true表示独占，false表示不独占。 | ## ScreenCaptureConfig10+ Web屏幕捕获的配置。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 类型 | 必填 | 说明 | | ----------- | --------------------------------------- | ---- | ---------- | | captureMode | [WebCaptureMode](#webcapturemode10枚举说明) | 是 | Web屏幕捕获模式。 | ## WebLayoutMode11+枚举说明 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ----------- | -- | ------------------ | | NONE | 0 | Web布局跟随系统。 | | FIT_CONTENT | 1 | Web基于页面大小的自适应网页布局。 | ## NestedScrollOptionsExt14+对象说明 通过NestedScrollOptionsExt可以设置上下左右四个方向的嵌套滚动规则。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 类型 | 必填 | 说明 | | -------------- | ---------------- | ---- | -------------------- | | scrollUp | [NestedScrollMode](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10) | 否 | 可滚动组件往上滚动时的嵌套滚动选项。 | | scrollDown | [NestedScrollMode](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10) | 否 | 可滚动组件往下滚动时的嵌套滚动选项。 | | scrollLeft | [NestedScrollMode](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10) | 否 | 可滚动组件往左滚动时的嵌套滚动选项。 | | scrollRight | [NestedScrollMode](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10) | 否 | 可滚动组件往右滚动时的嵌套滚动选项。 | ## DataResubmissionHandler9+ 通过DataResubmissionHandler可以重新提交表单数据或取消提交表单数据。 ### constructor9+ constructor() DataResubmissionHandler的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### resend9+ resend(): void 重新发送表单数据。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onDataResubmitted((event) => { console.log('onDataResubmitted'); event.handler.resend(); }) } } } ``` ### cancel9+ cancel(): void 取消重新发送表单数据。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) .onDataResubmitted((event) => { console.log('onDataResubmitted'); event.handler.cancel(); }) } } } ``` ## WebController 通过WebController可以控制Web组件各种行为。一个WebController对象只能控制一个Web组件，且必须在Web组件和WebController绑定后，才能调用WebController上的方法。 从API version 9开始不再维护，建议使用[WebviewController9+](js-apis-webview.md#webviewcontroller)代替。 ### 创建对象 ```ts let webController: WebController = new WebController() ``` ### constructor constructor() WebController的构造函数。 > **说明：** > > 从API version 8开始支持，从API version 9开始废弃。并且不再提供新的接口作为替代。 **系统能力：** SystemCapability.Web.Webview.Core ### getCookieManager(deprecated) getCookieManager(): WebCookie 获取Web组件cookie管理对象。 从API version 9开始不再维护，建议使用[getCookie](js-apis-webview.md#getcookiedeprecated)代替。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | --------- | ---------------------------------------- | | WebCookie | Web组件cookie管理对象，参考[WebCookie](#webcookie)定义。 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('getCookieManager') .onClick(() => { let cookieManager = this.controller.getCookieManager() }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### requestFocus(deprecated) requestFocus() 使当前web页面获取焦点。 从API version 9开始不再维护，建议使用[requestFocus9+](js-apis-webview.md#requestfocus)代替。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('requestFocus') .onClick(() => { this.controller.requestFocus() }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### accessBackward(deprecated) accessBackward(): boolean 当前页面是否可后退，即当前页面是否有返回历史记录。 从API version 9开始不再维护，建议使用[accessBackward9+](js-apis-webview.md#accessbackward)代替。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------- | --------------------- | | boolean | 可以后退返回true,否则返回false。 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('accessBackward') .onClick(() => { let result = this.controller.accessBackward() console.log('result:' + result) }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### accessForward(deprecated) accessForward(): boolean 当前页面是否可前进，即当前页面是否有前进历史记录。 从API version 9开始不再维护，建议使用[accessForward9+](js-apis-webview.md#accessforward)代替。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------- | --------------------- | | boolean | 可以前进返回true,否则返回false。 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('accessForward') .onClick(() => { let result = this.controller.accessForward() console.log('result:' + result) }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### accessStep(deprecated) accessStep(step: number): boolean 当前页面是否可前进或者后退给定的step步。 从API version 9开始不再维护，建议使用[accessStep9+](js-apis-webview.md#accessstep)代替。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | --------------------- | | step | number | 是 | 要跳转的步数，正数代表前进，负数代表后退。 | **返回值：** | 类型 | 说明 | | ------- | --------- | | boolean | 页面是否前进或后退 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() @State steps: number = 2 build() { Column() { Button('accessStep') .onClick(() => { let result = this.controller.accessStep(this.steps) console.log('result:' + result) }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### backward(deprecated) backward() 按照历史栈，后退一个页面。一般结合accessBackward一起使用。 从API version 9开始不再维护，建议使用[backward9+](js-apis-webview.md#backward)代替。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('backward') .onClick(() => { this.controller.backward() }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### forward(deprecated) forward() 按照历史栈，前进一个页面。一般结合accessForward一起使用。 从API version 9开始不再维护，建议使用[forward9+](js-apis-webview.md#forward)代替。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('forward') .onClick(() => { this.controller.forward() }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### deleteJavaScriptRegister(deprecated) deleteJavaScriptRegister(name: string) 删除通过registerJavaScriptProxy注册到window上的指定name的应用侧JavaScript对象。删除后立即生效，无须调用[refresh](#refreshdeprecated)接口。 从API version 9开始不再维护，建议使用[deleteJavaScriptRegister9+](js-apis-webview.md#deletejavascriptregister)代替。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------------------------- | | name | string | 是 | 注册对象的名称，可在网页侧JavaScript中通过此名称调用应用侧JavaScript对象。 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() @State name: string = 'Object' build() { Column() { Button('deleteJavaScriptRegister') .onClick(() => { this.controller.deleteJavaScriptRegister(this.name) }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### getHitTest(deprecated) getHitTest(): HitTestType 获取当前被点击区域的元素类型。 从API version 9开始不再维护，建议使用[getHitTest9+](js-apis-webview.md#gethittest)代替。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** | 类型 | 说明 | | ------------------------------- | ----------- | | [HitTestType](#hittesttype枚举说明) | 被点击区域的元素类型。 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('getHitTest') .onClick(() => { let hitType = this.controller.getHitTest() console.log("hitType: " + hitType) }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### loadData(deprecated) loadData(options: { data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string }) baseUrl为空时，通过”data“协议加载指定的一段字符串。 当baseUrl为”data“协议时，编码后的data字符串将被Web组件作为”data"协议加载。 当baseUrl为“http/https"协议时，编码后的data字符串将被Web组件以类似loadUrl的方式以非编码字符串处理。 从API version 9开始不再维护，建议使用[loadData9+](js-apis-webview.md#loaddata)代替。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------ | ---- | ---------------------------------------- | | data | string | 是 | 按照”Base64“或者”URL"编码后的一段字符串。 | | mimeType | string | 是 | 媒体类型（MIME）。 | | encoding | string | 是 | 编码类型，具体为“Base64"或者”URL编码。 | | baseUrl | string | 否 | 指定的一个URL路径（“http”/“https”/"data"协议），并由Web组件赋值给window.origin。 | | historyUrl | string | 否 | 历史记录URL。非空时，可被历史记录管理，实现前后后退功能。当baseUrl为空时，此属性无效。 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('loadData') .onClick(() => { this.controller.loadData({ data: "Source:
source
", mimeType: "text/html", encoding: "UTF-8" }) }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### loadUrl(deprecated) loadUrl(options: { url: string | Resource, headers?: Array\ }) 使用指定的http头加载指定的URL。 通过loadUrl注入的对象只在当前document有效，即通过loadUrl导航到新的页面会无效。 而通过registerJavaScriptProxy注入的对象，在loadUrl导航到新的页面也会有效。 从API version 9开始不再维护，建议使用[loadUrl9+](js-apis-webview.md#loadurl)代替。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | -------------------------- | ---- | -------------- | | url | string \| Resource | 是 | 需要加载的 URL。 | | headers | Array\<[Header](#header)\> | 否 | URL的附加HTTP请求头。默认值：[]。 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('loadUrl') .onClick(() => { this.controller.loadUrl({ url: 'www.example.com' }) }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### onActive(deprecated) onActive(): void 调用此接口通知Web组件进入前台激活状态。 从API version 9开始不再维护，建议使用[onActive9+](js-apis-webview.md#onactive)代替。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('onActive') .onClick(() => { this.controller.onActive() }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### onInactive(deprecated) onInactive(): void 调用此接口通知Web组件进入未激活状态。 从API version 9开始不再维护，建议使用[onInactive9+](js-apis-webview.md#oninactive)代替。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('onInactive') .onClick(() => { this.controller.onInactive() }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### zoom(deprecated) zoom(factor: number): void 调整当前网页的缩放比例。 从API version 9开始不再维护，建议使用[zoom9+](js-apis-webview.md#zoom)代替。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------------ | | factor | number | 是 | 基于当前网页所需调整的相对缩放比例，正值为放大，负值为缩小。 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() @State factor: number = 1 build() { Column() { Button('zoom') .onClick(() => { this.controller.zoom(this.factor) }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### refresh(deprecated) refresh() 调用此接口通知Web组件刷新网页。 从API version 9开始不再维护，建议使用[refresh9+](js-apis-webview.md#refresh)代替。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('refresh') .onClick(() => { this.controller.refresh() }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### registerJavaScriptProxy(deprecated) registerJavaScriptProxy(options: { object: object, name: string, methodList: Array\ }) 注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。注册后，须调用[refresh](#refreshdeprecated)接口生效。 从API version 9开始不再维护，建议使用[registerJavaScriptProxy9+](js-apis-webview.md#registerjavascriptproxy)代替。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | --------------- | ---- | ---------------------------------------- | | object | object | 是 | 参与注册的应用侧JavaScript对象。可以声明方法，也可以声明属性，但是不支持h5直接调用。其中方法的参数和返回类型只能为string，number，boolean | | name | string | 是 | 注册对象的名称，与window中调用的对象名一致。注册后window对象可以通过此名字访问应用侧JavaScript对象。 | | methodList | Array\ | 是 | 参与注册的应用侧JavaScript对象的方法。 | **示例：** ```ts // xxx.ets class TestObj { constructor() { } test(): string { return "ArkUI Web Component" } toString(): void { console.log('Web Component toString') } } @Entry @Component struct Index { controller: WebController = new WebController() testObj = new TestObj(); build() { Column() { Row() { Button('Register JavaScript To Window').onClick(() => { this.controller.registerJavaScriptProxy({ object: this.testObj, name: "objName", methodList: ["test", "toString"], }) }) } Web({ src: $rawfile('index.html'), controller: this.controller }) .javaScriptAccess(true) } } } ``` 加载的html文件。 ```html Hello world! ``` ### runJavaScript(deprecated) runJavaScript(options: { script: string, callback?: (result: string) => void }) 异步执行JavaScript脚本，并通过回调方式返回脚本执行的结果。runJavaScript需要在loadUrl完成后，比如onPageEnd中调用。 从API version 9开始不再维护，建议使用[runJavaScript9+](js-apis-webview.md#runjavascript)代替。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------ | ---- | ---------------------------------------- | | script | string | 是 | JavaScript脚本。 | | callback | (result: string) => void | 否 | 回调执行JavaScript脚本结果。JavaScript脚本若执行失败或无返回值时，返回null。 | **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() @State webResult: string = '' build() { Column() { Text(this.webResult).fontSize(20) Web({ src: $rawfile('index.html'), controller: this.controller }) .javaScriptAccess(true) .onPageEnd((event) => { this.controller.runJavaScript({ script: 'test()', callback: (result: string)=> { this.webResult = result console.info(`The test() return value is: ${result}`) }}) if (event) { console.info('url: ', event.url) } }) } } } ``` 加载的html文件。 ```html Hello world! ``` ### stop(deprecated) stop() 停止页面加载。 从API version 9开始不再维护，建议使用[stop9+](js-apis-webview.md#stop)代替。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('stop') .onClick(() => { this.controller.stop() }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ### clearHistory(deprecated) clearHistory(): void 删除所有前进后退记录。 从API version 9开始不再维护，建议使用[clearHistory9+](js-apis-webview.md#clearhistory)代替。 **系统能力：** SystemCapability.Web.Webview.Core **示例：** ```ts // xxx.ets @Entry @Component struct WebComponent { controller: WebController = new WebController() build() { Column() { Button('clearHistory') .onClick(() => { this.controller.clearHistory() }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ## WebCookie 通过WebCookie可以控制Web组件中的cookie的各种行为，其中每个应用中的所有Web组件共享一个WebCookie。通过controller方法中的getCookieManager方法可以获取WebCookie对象，进行后续的cookie管理操作。 ### constructor constructor() WebCookie的构造函数。 **系统能力：** SystemCapability.Web.Webview.Core ### setCookie(deprecated) setCookie() 设置cookie，该方法为同步方法。设置成功返回true，否则返回false。 从API version 9开始不再维护，建议使用[setCookie9+](js-apis-webview.md#setcookie)代替。 **系统能力：** SystemCapability.Web.Webview.Core ### saveCookie(deprecated) saveCookie() 将当前存在内存中的cookie同步到磁盘中，该方法为同步方法。 从API version 9开始不再维护，建议使用[saveCookieAsync9+](js-apis-webview.md#savecookieasync)代替。 **系统能力：** SystemCapability.Web.Webview.Core ## ScriptItem11+ 通过[javaScriptOnDocumentStart](#javascriptondocumentstart11)属性注入到Web组件的ScriptItem对象。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 类型 | 必填 | 说明 | | ----------- | -------------- | ---- | --------------------- | | script | string | 是 | 需要注入、执行的JavaScript脚本。 | | scriptRules | Array\ | 是 | 一组允许来源的匹配规则。
1.如果需要允许所有来源的网址，使用通配符“ * ”。
2.如果需要精确匹配，则描述网站地址，如"https:\//www\.example.com"。
3.如果模糊匹配网址，可以使用“ * ”通配符替代，如"https://*.example.com"。不允许使用"x. * .y.com"、" * foobar.com"等。
4.如果来源是ip地址，则使用规则2。
5.对于http/https以外的协议(自定义协议)，不支持使用精确匹配和模糊匹配，且必须以"://"结尾，例如"resource://"。
6.一组scriptRule中，如果其中一条不满足以上规则，则整组scriptRule都不生效。 | ## WebNavigationType11+ 定义navigation类型。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ----------------------------- | -- | ------------ | | UNKNOWN | 0 | 未知类型。 | | MAIN_FRAME_NEW_ENTRY | 1 | 主文档上产生的新的历史节点跳转。 | | MAIN_FRAME_EXISTING_ENTRY | 2 | 主文档上产生的到已有的历史节点的跳转。 | | NAVIGATION_TYPE_NEW_SUBFRAME | 4 | 子文档上产生的用户触发的跳转。 | | NAVIGATION_TYPE_AUTO_SUBFRAME | 5 | 子文档上产生的非用户触发的跳转。 | ## LoadCommittedDetails11+ 提供已提交跳转的网页的详细信息。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 类型 | 必填 | 说明 | | ----------- | ------------------------------------ | ---- | --------------------- | | isMainFrame | boolean | 是 | 是否是主文档。
true表示是主文档，false表示不是主文档。 | | isSameDocument | boolean | 是 | 是否在不更改文档的情况下进行的网页跳转。
true表示在不更改文档的情况下进行的网页跳转，false表示在更改文档的情况下进行的网页跳转。
在同文档跳转的示例：1.参考片段跳转；2.pushState或replaceState触发的跳转；3.同一页面历史跳转。 | | didReplaceEntry | boolean | 是 | 是否提交的新节点替换了已有的节点。
true表示提交的新节点替换了已有的节点，false表示提交的新节点未替换已有的节点。
另外在一些子文档跳转的场景，虽然没有实际替换已有节点，但是有一些属性发生了变更。 | | navigationType | [WebNavigationType](#webnavigationtype11) | 是 | 网页跳转的类型。 | | url | string | 是 | 当前跳转网页的URL。 | ## ThreatType11+ 定义网站风险类型。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 值 | 说明 | | ---------------- | -- | ----------------------| | THREAT_ILLEGAL | 0 | 非法网站。 | | THREAT_FRAUD | 1 | 欺诈网站。 | | THREAT_RISK | 2 | 存在安全风险的网站。 | | THREAT_WARNING | 3 | 涉嫌包含不健康内容的网站。 | ## OnNavigationEntryCommittedCallback11+ type OnNavigationEntryCommittedCallback = (loadCommittedDetails: [LoadCommittedDetails](#loadcommitteddetails11)) => void 导航条目提交时触发的回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | loadCommittedDetails | [LoadCommittedDetails](#loadcommitteddetails11) | 是 | 提供已提交跳转的网页的详细信息。 | ## OnSafeBrowsingCheckResultCallback11+ type OnSafeBrowsingCheckResultCallback = (threatType: ThreatType) => void 网站安全风险检查触发的回调。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------- | | threatType | [ThreatType](#threattype11) | 是 | 定义网站threat类型。 | ## FullScreenEnterEvent12+ Web组件进入全屏回调事件的详情。 **系统能力：** SystemCapability.Web.Webview.Core | 名称 | 类型 | 必填 | 说明 | | ----------- | ------------------------------------ | ---- | --------------------- | | handler | [FullScreenExitHandler](#fullscreenexithandler9) | 是 | 用于退出全屏模式的函数句柄。 | | videoWidth | number | 否 | 视频的宽度，单位：px。如果进入全屏的是 `