# Interfaces（其他） > phone | 2in1 | tablet | tv | wearable > 说明 > > * 该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 > > * 示例效果请以真机运行为准。 ## WebOptions > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 通过[接口](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web#接口)定义Web选项，包括网页资源地址、控制器、渲染方式等。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |src|string | [Resource](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#resource)|否|否|网页资源地址。如果访问本地资源文件，请使用resource协议或$rawfile资源引用。如果加载应用包外沙箱路径的本地资源文件（文件支持html和txt类型），请使用file://沙箱文件路径。 src不能通过状态变量（例如：@State）动态更改地址，如需更改，请通过[loadUrl()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-webview-webviewcontroller#loadurl)重新加载。| |controller|[WebController](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-webcontroller) | [WebviewController](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-webview-webviewcontroller)|否|否|控制器，通过controller可以控制Web组件各种行为，包括页面导航、生命周期状态、JavaScript交互等。从API version 9开始，WebController不再维护，建议使用[WebviewController](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-t#webviewcontroller9)替代。| |renderMode^12+^|[RenderMode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-e#rendermode12)|否|是|表示当前Web组件的渲染方式，RenderMode.ASYNC_RENDER表示Web组件异步渲染，RenderMode.SYNC_RENDER表示Web组件同步渲染，默认值RenderMode.ASYNC_RENDER，该模式不支持动态调整。| |incognitoMode^11+^|boolean|否|是|表示当前创建的Webview是否是隐私模式。true表示创建隐私模式，false表示创建正常模式。 默认值：false。 传入undefined或null时为false。| |sharedRenderProcessToken^12+^|string|否|是|表示当前Web组件指定共享渲染进程的token，多渲染进程模式下，相同token的Web组件会优先尝试复用绑定的渲染进程。绑定发生在渲染进程的初始化阶段。当渲染进程没有关联的Web组件时，其绑定关系将被移除。 默认值： ""。| |emulateTouchFromMouseEvent^22+^|boolean|否|是|设定鼠标事件是否被转换成触摸事件。 默认值：false。| ## WebMediaOptions^10+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 用于配置Web组件的媒体策略，包括音频续播有效期、音频独占模式等。适用于需要优化音频播放体验和多实例音频管理的场景，提升媒体播放的稳定性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:--------------------|:------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |resumeInterval|number|否|是|被其他应用暂停的Web音视频能够自动续播的有效期，单位：秒。取值范围：[-2147483648, 2147483647]。值为0时，不自动续播；大于0时，将在该时间内尝试续播；小于0时，将在无限时间内尝试续播。由于近似值原因，该有效期可能存在一秒内的误差。 **说明：** HLS视频被打断后，回到前台将自动续播，不受该时间控制。 默认值：0。| |audioExclusive|boolean|否|是|应用内多个Web实例的音频是否独占。 true表示应用内多个Web实例的音频独占，false表示不独占。 默认值：true。| |audioSessionType^20+^|[AudioSessionType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-e#audiosessiontype20)|否|是|应用中Web音频类型。默认值对应系统音频流类型[StreamUsage](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-e#streamusage)中的STREAM_USAGE_MUSIC。用于改变组件音频类型与系统音频类型映射关系，影响ArkWeb音频焦点策略。| ## ScriptItem^11+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 通过[javaScriptOnDocumentStart](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-attributes#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都不生效。| |urlRegexRules^23+^|Array<[UrlRegexRule](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-i#urlregexrule23)>|否|是|一组允许来源的正则匹配规则。 当scriptRules设置为[]时，才使用urlRegexRules进行匹配。 **模型约束：** 此接口仅可在Stage模型下使用。| ## UrlRegexRule^23+^ > phone 23+ | 2in1 23+ | tablet 23+ | tv 23+ | wearable 23+ 定义Url正则表达式规则。 **模型约束：** 此接口仅可在Stage模型下使用。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:----------------|:-----|:-|:-|:----------------------------------------------------------------------------------------------------------------------------------------------| |secondLevelDomain|string|否|否|二级域名的精确匹配。例如，"[https://www.example.com"的二级域名为example.com；"https://www.example.com.cn"二级域名为example.com.cn。网址没有二级域名则为空。](https://www.example.com)| |rule|string|否|否|url正则表达式。 在secondLevelDomain匹配成功后，才进行url正则匹配。| ## NestedScrollOptionsExt^14+^ > phone 14+ | 2in1 14+ | tablet 14+ | tv 19+ | wearable 18+ 用于设置Web组件嵌套滚动规则，支持上下左右四个方向的滚动选项。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:----------|:-------------------------------------------------------------------------------------------------------------------------|:-|:-|:--------------------------------------------------| |scrollUp|[NestedScrollMode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#nestedscrollmode10)|否|是|可滚动组件往上滚动时的嵌套滚动选项。 默认值：NestedScrollMode.SELF_FIRST。| |scrollDown|[NestedScrollMode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#nestedscrollmode10)|否|是|可滚动组件往下滚动时的嵌套滚动选项。 默认值：NestedScrollMode.SELF_FIRST。| |scrollLeft|[NestedScrollMode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#nestedscrollmode10)|否|是|可滚动组件往左滚动时的嵌套滚动选项。 默认值：NestedScrollMode.SELF_FIRST。| |scrollRight|[NestedScrollMode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#nestedscrollmode10)|否|是|可滚动组件往右滚动时的嵌套滚动选项。 默认值：NestedScrollMode.SELF_FIRST。| ## NativeMediaPlayerConfig^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 用于配置应用接管网页媒体播放功能接口[enableNativeMediaPlayer](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-attributes#enablenativemediaplayer12)的功能，支持是否开启及是否覆盖网页内容。适用于需要自定义媒体播放行为的场景，提升媒体播放的集成度和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------------|:------|:-|:-|:---------------------------------------------------------------------------------------------| |enable|boolean|否|否|是否开启应用接管网页媒体播放功能。 true表示开启应用接管网页媒体播放功能，false表示关闭该功能。 默认值：false。| |shouldOverlay|boolean|否|否|开启应用接管网页媒体播放功能后，应用接管网页视频的播放器画面是否覆盖网页内容。 true表示改变视频图层的层级，覆盖网页内容。false表示保持原层级，嵌入在网页中。 默认值：false。| ## ExpandedMenuItemOptions^(deprecated)^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 自定义菜单扩展项。 > 说明 > > 从API version 12开始支持，从API version 20开始废弃。建议使用[editMenuOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-attributes#editmenuoptions12)替代。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:--------|:----------------------------------------------------------------------------------------------------|:-|:-|:----------------------------------------------------------------| |content|[ResourceStr](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#resourcestr)|否|否|显示内容。| |startIcon|[ResourceStr](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#resourcestr)|否|是|显示图标。默认值为空，不显示图标。| |action|(selectedText: {plainText: string}) => void|否|否|回调函数，用于接收用户选择菜单扩展项后的操作。回调参数selectedText包含plainText字段，表示用户选中的文本内容。| ## AdsBlockedDetails^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ 发生广告拦截时，广告资源信息。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:---------|:------------|:-|:-|:-------------------------------------------| |url|string|否|否|发生广告过滤的页面url。| |adsBlocked|Array|否|否|被过滤的资源的url或dompath标识，被过滤的多个对象url相同则可能出现重复元素。| ## SelectionMenuOptionsExt^13+^ > phone 13+ | 2in1 13+ | tablet 13+ | tv 19+ | wearable 18+ 自定义菜单扩展项。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:----------------------|:----------------------------------------------------------------------------------------------------------|:-|:-|:-------------------------------------------------------------------------------------| |onAppear|Callback|否|是|自定义选择菜单弹出时回调。| |onDisappear|Callback|否|是|自定义选择菜单关闭时回调。| |preview|[CustomBuilder](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#custombuilder8)|否|是|自定义选择菜单的预览内容样式，未配置时无预览内容。| |menuType|[MenuType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-text-common#menutype13枚举说明)|否|是|自定义选择菜单类型。 默认值：MenuType.SELECTION_MENU。 从API version 20起，MenuType.PREVIEW_MENU支持超链接预览。| |previewMenuOptions^20+^|[PreviewMenuOptions](#previewmenuoptions20)|否|是|自定义选择预览菜单选项。| |onMenuShow^21+^|Callback|否|是|自定义选择菜单显示时回调。| |onMenuHide^21+^|Callback|否|是|自定义选择菜单隐藏时回调。| ## PreviewMenuOptions^20+^ > phone 20+ | 2in1 20+ | tablet 20+ | tv 20+ | wearable 20+ 用于配置预览菜单选项，支持设置菜单弹出时的振动效果。适用于需要增强菜单交互反馈的场景，提升用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-----------------|:----------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:---------------------------------------------------------------------------------| |hapticFeedbackMode|[HapticFeedbackMode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-menu#hapticfeedbackmode18)|否|是|菜单弹出时振动效果。需配置"ohos.permission.VIBRATE"权限 默认值：HapticFeedbackMode.DISABLED，菜单弹出时不振动。| ## EmbedOptions^16+^ > phone 16+ | 2in1 16+ | tablet 16+ | tv 19+ | wearable 18+ Web同层渲染的配置。用于配置Web同层渲染选项，包括支持固定大小和CSS显示属性。适用于需要优化同层元素渲染效果的场景，提升渲染的兼容性和灵活性。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:---------------------------|:------|:-|:-|:-----------------------------------------------------------------------------------------------------------------------------------------| |supportDefaultIntrinsicSize|boolean|否|是|设置同层渲染元素是否支持固定大小 300 * 150。 当H5侧CSS设置了大小时，同层渲染元素大小为CSS大小，否则为固定大小。 为true时，固定大小为 300 * 150。 为false时，若H5侧CSS未设置大小，则同层渲染元素不渲染。 默认值：false 单位：px| |supportCssDisplayChange^20+^|boolean|否|是|设置同层渲染可见性接口是否支持显示属性。 同层渲染可见性接口默认支持同层标签相对于视口的可见状态。 设置为true时，支持显示CSS属性，包括visibility、display和宽高。 设置为false时，不支持显示CSS属性，仅支持同层标签相对于视口的可见性。| ## OnAlertEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页触发 alert() 告警时的回调函数。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:----------------------------------------------------------------------------------------------------------------|:-|:-|:--------------| |url|string|否|否|当前显示弹窗的网页的URL。| |message|string|否|否|显示在弹窗中的信息。| |result|[JsResult](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-jsresult)|否|否|通知Web组件用户的操作结果。| ## OnBeforeUnloadEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义刷新或关闭场景下，在即将离开当前页面时触发此回调。适用于表单编辑等场景，允许开发者拦截离开动作并弹窗确认，从而避免用户未提交的数据意外丢失。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------------|:----------------------------------------------------------------------------------------------------------------|:-|:-|:-----------------------------------------------------------------------| |url|string|否|否|当前显示弹窗所在网页的URL。| |message|string|否|否|弹窗中显示的信息。| |result|[JsResult](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-jsresult)|否|否|通知Web组件用户操作行为。| |isReload^20+^|boolean|否|是|页面是否刷新。 当页面因刷新即将离开时，isReload为true；当页面因关闭即将离开时，isReload为false。 默认值：false。| ## OnConfirmEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页触发 confirm() 弹窗时的回调函数。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:----------------------------------------------------------------------------------------------------------------|:-|:-|:--------------| |url|string|否|否|当前显示弹窗的网页的URL。| |message|string|否|否|显示在弹窗中的信息。| |result|[JsResult](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-jsresult)|否|否|通知Web组件用户的操作结果。| ## OnPromptEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页触发 prompt() 弹窗时的回调函数。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:----------------------------------------------------------------------------------------------------------------|:-|:-|:--------------| |url|string|否|否|当前显示弹窗的网页的URL。| |message|string|否|否|显示在弹窗中的信息。| |value|string|否|否|对话框默认返回的信息。| |result|[JsResult](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-jsresult)|否|否|通知Web组件用户的操作结果。| ## OnConsoleEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义通知宿主应用JavaScript console消息。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:----------------------------------------------------------------------------------------------------------------------------|:-|:-|:--------| |message|[ConsoleMessage](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-consolemessage)|否|否|触发的控制台信息。| ## OnErrorReceiveEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页加载遇到错误时触发的回调信息，包括请求和错误详情。适用于需要监控和处理网页加载错误的场景，提升错误处理的及时性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-------------| |request|[WebResourceRequest](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-webresourcerequest)|否|否|网页请求的封装信息。| |error|[WebResourceError](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-webresourceerror)|否|否|网页加载资源错误的封装信息。| ## OnHttpErrorReceiveEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页收到资源加载HTTP错误时触发的回调信息，包括请求和响应详情。适用于需要监控和处理HTTP错误的场景，提升网络错误诊断的准确性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-------|:--------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:---------| |request|[WebResourceRequest](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-webresourcerequest)|否|否|网页请求的封装信息。| |response|[WebResourceResponse](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-webresourceresponse)|否|否|资源响应的封装信息。| ## OnDownloadStartEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义通知主应用开始下载文件的回调信息，包括URL、用户代理和文件详情。适用于需要监控和管理文件下载的场景，提升下载流程的可控性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-----------------|:-----|:-|:-|:--------------------------------------| |url|string|否|否|文件下载的URL。| |userAgent|string|否|否|用于下载的用户代理。| |contentDisposition|string|否|否|服务器返回的 Content-Disposition响应头，服务器可能返回空。| |mimetype|string|否|否|服务器返回内容媒体类型（MIME）信息。| |contentLength|number|否|否|服务器返回文件的长度。单位：字节。| ## OnRefreshAccessedHistoryEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义导航完成时触发的回调信息，包括URL和刷新状态。适用于需要监控页面导航历史的场景，提升导航行为跟踪的准确性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:---------------|:------|:-|:-|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------| |url|string|否|否|访问的url。| |isRefreshed|boolean|否|否|true表示该页面是被重新加载的（调用[refresh^9+^](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-webview-webviewcontroller#refresh)接口），false表示该页面是新加载的。| |isMainFrame^22+^|boolean|否|是|是否是主文档触发。 true表示是主文档触发，false表示不是主文档触发。| ## OnRenderExitedEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义渲染进程退出时触发。适用于需要监控渲染进程异常的场景，提升渲染稳定性和故障排查效率。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:---------------|:-----------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-------------| |renderExitReason|[RenderExitReason](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-e#renderexitreason9)|否|否|渲染进程异常退出的具体原因。| ## OnShowFileSelectorEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义文件选择器结果的回调信息，包括结果和参数详情。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-----------|:------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:----------------| |result|[FileSelectorResult](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-fileselectorresult)|否|否|用于通知Web组件文件选择的结果。| |fileSelector|[FileSelectorParam](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-fileselectorparam)|否|否|文件选择器的相关信息。| ## OnResourceLoadEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义加载URL时触发的回调信息，包括资源URL。适用于需要监控资源加载行为的场景，提升资源管理的可见性和性能优化。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:--|:-----|:-|:-|:-------------| |url|string|否|否|所加载的资源文件url信息。| ## OnScaleChangeEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义当前页面显示比例的变化时触发。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-------|:-----|:-|:-|:-----------| |oldScale|number|否|否|变化前的显示比例百分比。| |newScale|number|否|否|变化后的显示比例百分比。| ## OnHttpAuthRequestEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义收到HTTP认证请求时触发的回调信息，包括主机和域信息。适用于需要处理HTTP身份验证的场景，提升认证流程的灵活性和安全性。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:------------------------------------------------------------------------------------------------------------------------------|:-|:-|:---------------| |handler|[HttpAuthHandler](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-httpauthhandler)|否|否|通知Web组件用户操作行为。| |host|string|否|否|HTTP身份验证凭据应用的主机。| |realm|string|否|否|HTTP身份验证凭据应用的域。| ## OnInterceptRequestEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义Web组件加载URL之前触发的回调信息，包括请求详情。适用于需要拦截或修改网络请求的场景，提升请求控制的灵活性和安全性。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:----------| |request|[WebResourceRequest](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-webresourcerequest)|否|否|url请求的相关信息。| ## OnPermissionRequestEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义收到权限请求时触发的回调信息，包括请求详情。适用于需要处理权限授予的场景，提升权限管理的灵活性和安全性。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:----------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-------------| |request|[PermissionRequest](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-permissionrequest)|否|否|通知Web组件用户操作行为。| ## OnScreenCaptureRequestEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义收到屏幕捕获请求时触发的回调信息。适用于需要处理屏幕录制权限的场景，提升录屏流程的可控性和安全性。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:----------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-------------| |handler|[ScreenCaptureHandler](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-screencapturehandler)|否|否|通知Web组件用户操作行为。| ## OnContextMenuShowEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义调用时触发的回调信息，以允许自定义显示上下文菜单。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-----|:----------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:----------| |param|[WebContextMenuParam](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-webcontextmenuparam)|否|否|菜单相关参数。| |result|[WebContextMenuResult](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-webcontextmenuresult)|否|否|菜单相应事件传入内核。| ## OnSearchResultReceiveEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页页内查找结果的回调信息，包括匹配项序号和总数。适用于需要监控页内搜索行为的场景，提升搜索交互的可见性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-----------------|:------|:-|:-|:--------------------------------------------------------------------------| |activeMatchOrdinal|number|否|否|当前匹配的查找项的序号（从0开始）。| |numberOfMatches|number|否|否|所有匹配到的关键词的个数。| |isDoneCounting|boolean|否|否|当次页内查找操作是否结束。 true表示当次页内查找操作结束，false表示未结束。 该方法可能回调多次，直到isDoneCounting为true。| ## OnScrollEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义滚动条滑动到指定位置时触发的回调信息，包括水平和垂直偏移量。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:-----|:-|:-|:----------------------------| |xOffset|number|否|否|以网页最左端为基准，水平滚动条滚动所在位置。 单位：vp。| |yOffset|number|否|否|以网页最上端为基准，竖直滚动条滚动所在位置。 单位：vp。| ## OnSslErrorEventReceiveEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页收到SSL错误时触发的回调信息，包括错误码和证书链。适用于需要处理SSL错误的场景，提升安全异常的监控和处理能力。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-----------------|:------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-------------| |handler|[SslErrorHandler](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-sslerrorhandler)|否|否|通知Web组件用户操作行为。| |error|[SslError](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-e#sslerror9)|否|否|错误码。| |certChainData^15+^|Array|否|是|证书链数据。| ## SslErrorEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 用户加载资源时发生SSL错误时触发的回调详情，包括URL、错误类型和证书链。适用于需要详细分析SSL错误的场景，提升安全问题的诊断和排查效率。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-----------------|:------------------------------------------------------------------------------------------------------------------------------|:-|:-|:------------------------------------------------------------------------------------------| |handler|[SslErrorHandler](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-sslerrorhandler)|否|否|通知Web组件用户操作行为。| |error|[SslError](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-e#sslerror9)|否|否|错误码。| |url|string|否|否|url地址。| |originalUrl|string|否|否|请求的原始url地址。| |referrer|string|否|否|referrer url地址。| |isFatalError|boolean|否|否|是否是致命错误。致命错误会导致页面无法正常加载和渲染（如证书验证失败、协议错误），非致命错误只影响部分资源的加载（如图片加载失败）。 true表示致命错误，false表示非致命错误。| |isMainFrame|boolean|否|否|是否是主资源。 true表示主资源，false表示非主资源。| |certChainData^20+^|Array|否|是|证书链数据。| ## OnClientAuthenticationEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义需要提供SSL客户端证书时触发的回调信息，包括主机、端口和密钥类型。适用于需要处理客户端证书认证的场景，提升认证流程的灵活性和安全性。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-------|:------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:--------------------------| |handler|[ClientAuthenticationHandler](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-clientauthenticationhandler)|否|否|通知Web组件用户操作行为。| |host|string|否|否|请求证书服务器的主机名。| |port|number|否|否|请求证书服务器的端口号。取值范围通常为0-65535。| |keyTypes|Array|否|否|可接受的非对称密钥类型。| |issuers|Array|否|否|与私钥匹配的证书可接受颁发者。| ## VerifyPinEvent^22+^ > phone 22+ | 2in1 22+ | tablet 22+ | tv 22+ | wearable 22+ 定义当需要用户进行PIN码认证时触发回调。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-------|:--------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-------------| |handler|[VerifyPinHandler](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-verifypinhandler)|否|否|通知Web组件用户操作行为。| |identity|string|否|否|用于认证的证书凭据标识。| ## OnWindowNewEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页要求用户创建窗口时触发的回调信息。从API version 23开始，如需获取更多窗口信息，可使用[OnWindowNewExtEvent](#onwindownewextevent23)。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------------|:----------------------------------------------------------------------------------------------------------------------------------|:-|:-|:----------------------------| |isAlert|boolean|否|否|true代表请求创建对话框，false代表新标签页。| |isUserTrigger|boolean|否|否|true代表用户触发，false代表非用户触发。| |targetUrl|string|否|否|目标url。| |handler|[ControllerHandler](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-controllerhandler)|否|否|用于设置新建窗口的WebviewController实例。| ## WindowFeatures^23+^ > phone 23+ | 2in1 23+ | tablet 23+ | tv 23+ | wearable 23+ 提供网页请求创建的新窗口特征信息，包括大小和位置。适用于需要精确控制新窗口属性的场景，提升窗口布局的准确性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-----|:-----|:-|:-|:----------------| |x|number|否|否|新窗口左上角横坐标（单位：像素）。| |y|number|否|否|新窗口左上角纵坐标（单位：像素）。| |width|number|否|否|新窗口宽度（单位：像素）。| |height|number|否|否|新窗口高度（单位：像素）。| ## OnWindowNewExtEvent^23+^ > phone 23+ | 2in1 23+ | tablet 23+ | tv 23+ | wearable 23+ 定义网页请求创建窗口时触发的回调信息，包括窗口特征信息和窗口打开方式。适用于需要精细控制新窗口行为的场景，提升窗口管理的定制性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:---------------|:------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-----------------------------| |isAlert|boolean|否|否|true代表请求创建对话框，false代表请求创建新标签页。| |isUserTrigger|boolean|否|否|true代表用户触发，false代表非用户触发。| |targetUrl|string|否|否|请求的新窗口中需要打开的url。| |handler|[ControllerHandler](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-controllerhandler)|否|否|用于设置新建窗口的WebviewController实例。| |windowFeatures|[WindowFeatures](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-i#windowfeatures23)|否|否|网页请求创建的新窗口特征信息。| |navigationPolicy|[NavigationPolicy](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-e#navigationpolicy23)|否|否|网页请求用户创建新窗口时的窗口打开方式。| ## OnTouchIconUrlReceivedEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义接收到apple-touch-icon URL时触发的回调信息，包括URL和预合成状态。适用于需要获取网页图标的场景，提升图标管理的灵活性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:----------|:------|:-|:-|:-------------------------------------------------------------------------------------| |url|string|否|否|接收到的apple-touch-icon url地址。| |precomposed|boolean|否|否|对应apple-touch-icon是否为预合成。 true表示对应apple-touch-icon为预合成，false表示对应apple-touch-icon不是预合成。| ## OnFaviconReceivedEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义应用接收到新favicon时触发的回调信息，包括图标PixelMap对象。适用于需要获取网页favicon的场景，提升图标管理的灵活性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:------------------------------------------------------------------------------------------------------|:-|:-|:------------------------| |favicon|[PixelMap](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-image-pixelmap)|否|否|接收到的favicon图标的PixelMap对象。| ## OnPageVisibleEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义旧页面不再呈现，新页面即将可见时触发的回调函数。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:--|:-----|:-|:-|:---------| |url|string|否|否|新页面的URL地址。| ## OnDataResubmittedEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页表单可以重新提交时触发的回调信息，包括提交句柄。适用于需要处理表单重试提交的场景，提升表单交互的可靠性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:----------------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:----------| |handler|[DataResubmissionHandler](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-dataresubmissionhandler)|否|否|表单数据重新提交句柄。| ## OnAudioStateChangedEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页音频播放状态改变时触发的回调信息，包括播放状态。适用于需要监控音频播放行为的场景，提升音频管理的可见性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:------|:-|:-|:---------------------------------| |playing|boolean|否|否|当前页面的音频播放状态，true表示正在播放，false表示未播放。| ## OnFirstContentfulPaintEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页首次内容绘制的回调信息，包括加载时间和绘制时间。适用于需要监控页面渲染性能的场景，提升性能优化的准确性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:---------------------|:-----|:-|:-|:-----------------------------| |navigationStartTick|number|否|否|启动页面加载开始的时间，单位以微秒表示。| |firstContentfulPaintMs|number|否|否|从启动页面加载开始到第一次绘制内容的时间，单位是以毫秒表示。| ## OnLoadInterceptEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义截获资源加载时触发的回调信息，包括请求详情。适用于需要拦截或处理资源加载的场景，提升资源控制的灵活性和安全性。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:---|:------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:----------| |data|[WebResourceRequest](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-webresourcerequest)|否|否|url请求的相关信息。| ## OnOverScrollEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页过度滚动时触发的回调信息，包括水平和垂直偏移量。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:-----|:-|:-|:---------------------------| |xOffset|number|否|否|以网页最左端为基准，水平过度滚动的偏移量。 单位：vp。| |yOffset|number|否|否|以网页最上端为基准，竖直过度滚动的偏移量。 单位：vp。| ## JavaScriptProxy^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义要注入的JavaScript对象，包括对象名、方法列表和权限配置。适用于需要实现JavaScript与原生交互的场景，提升跨语言调用的灵活性和安全性。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:-------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |object|object|否|否|参与注册的对象。只能声明方法，不能声明属性。方法必须是函数类型。| |name|string|否|否|注册对象的名称，与window中调用的对象名一致。| |methodList|Array|否|否|参与注册的应用侧JavaScript对象的同步方法。| |controller|[WebController](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-webcontroller) | [WebviewController](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-webview-webviewcontroller)|否|否|控制器。从API version 9开始，WebController不再维护，建议使用WebviewController替代。| |asyncMethodList^12+^|Array|否|是|参与注册的应用侧JavaScript对象的异步方法。异步方法无法获取返回值。| |permission^12+^|string|否|是|json字符串，默认为空，通过该字符串配置JSBridge的权限管控，可以定义object、method一级的url白名单。 JavaScriptProxy的permission参数支持resource/http/https协议，不支持file协议。 示例请参考[前端页面调用应用侧函数](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-in-page-app-function-invoking)。| ## OnPageEndEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页加载结束时触发的回调信息，包括页面URL。适用于需要监控页面加载完成的场景，提升页面生命周期的管理能力。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:--|:-----|:-|:-|:---------------| |url|string|否|否|网页加载完成后的页面URL地址。| ## OnPageBeginEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页加载开始时触发的回调信息，包括页面URL。适用于需要监控页面加载开始的场景，提升页面生命周期的管理能力。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:--|:-----|:-|:-|:-------------------| |url|string|否|否|网页加载开始时即将加载的页面URL地址。| ## OnProgressChangeEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页加载进度变化时触发的回调信息，包括新的进度值。适用于需要监控页面加载进度的场景，提升加载过程的可见性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:----------|:-----|:-|:-|:-----------------------| |newProgress|number|否|否|新的加载进度，取值范围为[0, 100]的整数。| ## OnTitleReceiveEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义网页标题更改时触发的回调信息，包括标题内容和来源。适用于需要监控页面标题变化的场景，提升页面信息的实时性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:---------------|:------|:-|:-|:-----------------------------------------------------------------| |title|string|否|否|document标题内容。| |isRealTitle^20+^|boolean|否|是|document标题来源，true表示来自网页的title标签，false表示该title是根据url自动生成。 默认值：false| ## OnGeolocationShowEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 定义收到地理位置获取请求时触发的回调信息，包括源信息和地理对象。适用于需要处理地理位置权限的场景。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:----------|:--------------------------------------------------------------------------------------------------------------------------|:-|:-|:--------------------------------| |origin|string|否|否|发起地理位置权限请求的网页源，用于标识特定网站的地理位置请求来源。| |geolocation|[JsGeolocation](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-jsgeolocation)|否|否|通知Web组件用户操作行为。| ## NativeEmbedVisibilityInfo^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 提供同层标签的可见性信息，包括可见状态和标签ID。适用于需要监控同层元素可见性的场景，提升渲染状态管理的准确性和用户体验。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:---------|:------|:-|:-|:------------------------| |visibility|boolean|否|否|可见性。 true表示可见，false表示不可见。| |embedId|string|否|否|同层渲染标签的唯一id。| ## RenderProcessNotRespondingData^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 提供渲染进程无响应的详细信息。适用于需要诊断渲染进程异常的场景，提升故障排查的准确性和效率。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:------------------| |jsStack|string|否|否|网页的JavaScript调用栈信息。| |pid|number|否|否|网页的进程id。| |reason|[RenderProcessNotRespondingReason](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-e#renderprocessnotrespondingreason12)|否|否|触发渲染进程无响应回调的原因。| ## FullScreenEnterEvent^12+^ > phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+ 提供Web组件进入全屏的回调信息，包括视频尺寸和退出句柄。适用于需要处理全屏视频的场景，提升视频播放的沉浸式体验和可控性。 **系统能力：** SystemCapability.Web.Webview.Core |名称|类型|只读|可选|说明| |:----------|:------------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-------------------------------------------------------------------------------------| |handler|[FullScreenExitHandler](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-fullscreenexithandler)|否|否|用于退出全屏模式的函数句柄。| |videoWidth|number|否|是|视频的宽度，单位：px。如果进入全屏的是