目录

Interfaces(其他)

  • 该组件从API version 8开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

  • 示例效果请以真机运行为准。

WebOptions

通过接口定义Web选项,包括网页资源地址、控制器、渲染方式等。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
src string | Resource 否 否

网页资源地址。如果访问本地资源文件,请使用resource协议或$rawfile资源引用。如果加载应用包外沙箱路径的本地资源文件(文件支持html和txt类型),请使用file://沙箱文件路径。

src不能通过状态变量(例如:@State)动态更改地址,如需更改,请通过loadUrl()重新加载。

controller WebController | WebviewController 否 否 控制器,通过controller可以控制Web组件各种行为,包括页面导航、生命周期状态、JavaScript交互等。从API version 9开始,WebController不再维护,建议使用WebviewController替代。
renderMode12+ RenderMode 否 是 表示当前Web组件的渲染方式,RenderMode.ASYNC_RENDER表示Web组件异步渲染,RenderMode.SYNC_RENDER表示Web组件同步渲染,默认值RenderMode.ASYNC_RENDER,该模式不支持动态调整。
incognitoMode11+ boolean 否 是

表示当前创建的Webview是否是隐私模式。true表示创建隐私模式,false表示创建正常模式。

默认值:false。

传入undefined或null时为false。

sharedRenderProcessToken12+ string 否 是

表示当前Web组件指定共享渲染进程的token,多渲染进程模式下,相同token的Web组件会优先尝试复用绑定的渲染进程。绑定发生在渲染进程的初始化阶段。当渲染进程没有关联的Web组件时,其绑定关系将被移除。

默认值: ""。

emulateTouchFromMouseEvent22+ boolean 否 是

设定鼠标事件是否被转换成触摸事件。

默认值:false。

WebMediaOptions10+

用于配置Web组件的媒体策略,包括音频续播有效期、音频独占模式等。适用于需要优化音频播放体验和多实例音频管理的场景,提升媒体播放的稳定性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
resumeInterval number 否 是

被其他应用暂停的Web音视频能够自动续播的有效期,单位:秒。取值范围:[-2147483648, 2147483647]。值为0时,不自动续播;大于0时,将在该时间内尝试续播;小于0时,将在无限时间内尝试续播。由于近似值原因,该有效期可能存在一秒内的误差。

说明:

HLS视频被打断后,回到前台将自动续播,不受该时间控制。

默认值:0。

audioExclusive boolean 否 是

应用内多个Web实例的音频是否独占。

true表示应用内多个Web实例的音频独占,false表示不独占。

默认值:true。

audioSessionType20+ AudioSessionType 否 是 应用中Web音频类型。默认值对应系统音频流类型StreamUsage中的STREAM_USAGE_MUSIC。用于改变组件音频类型与系统音频类型映射关系,影响ArkWeb音频焦点策略。

ScriptItem11+

通过javaScriptOnDocumentStart属性注入到Web组件的ScriptItem对象。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
script string 否 否 需要注入、执行的JavaScript脚本。
scriptRules Array<string> 否 否

一组允许来源的匹配规则。

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都不生效。

urlRegexRules23+ Array<UrlRegexRule> 否 是

一组允许来源的正则匹配规则。 当scriptRules设置为[]时,才使用urlRegexRules进行匹配。

模型约束: 此接口仅可在Stage模型下使用。

UrlRegexRule23+

定义Url正则表达式规则。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
secondLevelDomain string 否 否 二级域名的精确匹配。例如,https://www.example.com的二级域名为example.com;https://www.example.com.cn二级域名为example.com.cn。网址没有二级域名则为空。
rule string 否 否 url正则表达式。 在secondLevelDomain匹配成功后,才进行url正则匹配。

NestedScrollOptionsExt14+

用于设置Web组件嵌套滚动规则,支持上下左右四个方向的滚动选项。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
scrollUp NestedScrollMode 否 是

可滚动组件往上滚动时的嵌套滚动选项。

默认值:NestedScrollMode.SELF_FIRST。

scrollDown NestedScrollMode 否 是

可滚动组件往下滚动时的嵌套滚动选项。

默认值:NestedScrollMode.SELF_FIRST。

scrollLeft NestedScrollMode 否 是

可滚动组件往左滚动时的嵌套滚动选项。

默认值:NestedScrollMode.SELF_FIRST。

scrollRight NestedScrollMode 否 是

可滚动组件往右滚动时的嵌套滚动选项。

默认值:NestedScrollMode.SELF_FIRST。

NativeMediaPlayerConfig12+

用于配置应用接管网页媒体播放功能接口enableNativeMediaPlayer的功能,支持是否开启及是否覆盖网页内容。适用于需要自定义媒体播放行为的场景,提升媒体播放的集成度和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
enable boolean 否 否

是否开启应用接管网页媒体播放功能。

true表示开启应用接管网页媒体播放功能,false表示关闭该功能。

默认值:false。

shouldOverlay boolean 否 否

开启应用接管网页媒体播放功能后,应用接管网页视频的播放器画面是否覆盖网页内容。

true表示改变视频图层的层级,覆盖网页内容。false表示保持原层级,嵌入在网页中。

默认值:false。

ExpandedMenuItemOptions(deprecated)

自定义菜单扩展项。

从API version 12开始支持,从API version 20开始废弃。建议使用editMenuOptions替代。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
content ResourceStr 否 否 显示内容。
startIcon ResourceStr 否 是 显示图标。默认值为空,不显示图标。
action (selectedText: {plainText: string}) => void 否 否 回调函数,用于接收用户选择菜单扩展项后的操作。回调参数selectedText包含plainText字段,表示用户选中的文本内容。

AdsBlockedDetails12+

发生广告拦截时,广告资源信息。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 发生广告过滤的页面url。
adsBlocked Array<string> 否 否 被过滤的资源的url或dompath标识,被过滤的多个对象url相同则可能出现重复元素。

SelectionMenuOptionsExt13+

自定义菜单扩展项。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
onAppear Callback<void> 否 是 自定义选择菜单弹出时回调。
onDisappear Callback<void> 否 是 自定义选择菜单关闭时回调。
preview CustomBuilder 否 是 自定义选择菜单的预览内容样式,未配置时无预览内容。
menuType MenuType 否 是

自定义选择菜单类型。

默认值:MenuType.SELECTION_MENU。

从API version 20起,MenuType.PREVIEW_MENU支持超链接预览。

previewMenuOptions20+ PreviewMenuOptions 否 是 自定义选择预览菜单选项。
onMenuShow21+ Callback<void> 否 是 自定义选择菜单显示时回调。
onMenuHide21+ Callback<void> 否 是 自定义选择菜单隐藏时回调。

PreviewMenuOptions20+

用于配置预览菜单选项,支持设置菜单弹出时的振动效果。适用于需要增强菜单交互反馈的场景,提升用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
hapticFeedbackMode HapticFeedbackMode 否 是

菜单弹出时振动效果。需配置"ohos.permission.VIBRATE"权限

默认值:HapticFeedbackMode.DISABLED,菜单弹出时不振动。

EmbedOptions16+

Web同层渲染的配置。用于配置Web同层渲染选项,包括支持固定大小和CSS显示属性。适用于需要优化同层元素渲染效果的场景,提升渲染的兼容性和灵活性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
supportDefaultIntrinsicSize boolean 否 是

设置同层渲染元素是否支持固定大小 300 * 150。

当H5侧CSS设置了大小时,同层渲染元素大小为CSS大小,否则为固定大小。

为true时,固定大小为 300 * 150。

为false时,若H5侧CSS未设置大小,则同层渲染元素不渲染。

默认值:false

单位:px

supportCssDisplayChange20+ boolean 否 是

设置同层渲染可见性接口是否支持显示属性。

同层渲染可见性接口默认支持同层标签相对于视口的可见状态。

设置为true时,支持显示CSS属性,包括visibility、display和宽高。

设置为false时,不支持显示CSS属性,仅支持同层标签相对于视口的可见性。

OnAlertEvent12+

定义网页触发 alert() 告警时的回调函数。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 当前显示弹窗的网页的URL。
message string 否 否 显示在弹窗中的信息。
result JsResult 否 否 通知Web组件用户的操作结果。

OnBeforeUnloadEvent12+

定义刷新或关闭场景下,在即将离开当前页面时触发此回调。适用于表单编辑等场景,允许开发者拦截离开动作并弹窗确认,从而避免用户未提交的数据意外丢失。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 当前显示弹窗所在网页的URL。
message string 否 否 弹窗中显示的信息。
result JsResult 否 否 通知Web组件用户操作行为。
isReload20+ boolean 否 是

页面是否刷新。

当页面因刷新即将离开时,isReload为true;当页面因关闭即将离开时,isReload为false。

默认值:false。

OnConfirmEvent12+

定义网页触发 confirm() 弹窗时的回调函数。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 当前显示弹窗的网页的URL。
message string 否 否 显示在弹窗中的信息。
result JsResult 否 否 通知Web组件用户的操作结果。

OnPromptEvent12+

定义网页触发 prompt() 弹窗时的回调函数。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 当前显示弹窗的网页的URL。
message string 否 否 显示在弹窗中的信息。
value string 否 否 对话框默认返回的信息。
result JsResult 否 否 通知Web组件用户的操作结果。

OnConsoleEvent12+

定义通知宿主应用JavaScript console消息。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
message ConsoleMessage 否 否 触发的控制台信息。

OnErrorReceiveEvent12+

定义网页加载遇到错误时触发的回调信息,包括请求和错误详情。适用于需要监控和处理网页加载错误的场景,提升错误处理的及时性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
request WebResourceRequest 否 否 网页请求的封装信息。
error WebResourceError 否 否 网页加载资源错误的封装信息。

OnHttpErrorReceiveEvent12+

定义网页收到资源加载HTTP错误时触发的回调信息,包括请求和响应详情。适用于需要监控和处理HTTP错误的场景,提升网络错误诊断的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
request WebResourceRequest 否 否 网页请求的封装信息。
response WebResourceResponse 否 否 资源响应的封装信息。

OnDownloadStartEvent12+

定义通知主应用开始下载文件的回调信息,包括URL、用户代理和文件详情。适用于需要监控和管理文件下载的场景,提升下载流程的可控性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 文件下载的URL。
userAgent string 否 否 用于下载的用户代理。
contentDisposition string 否 否 服务器返回的 Content-Disposition响应头,服务器可能返回空。
mimetype string 否 否 服务器返回内容媒体类型(MIME)信息。
contentLength number 否 否 服务器返回文件的长度。单位:字节。

OnRefreshAccessedHistoryEvent12+

定义导航完成时触发的回调信息,包括URL和刷新状态。适用于需要监控页面导航历史的场景,提升导航行为跟踪的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 访问的url。
isRefreshed boolean 否 否 true表示该页面是被重新加载的(调用refresh9+接口),false表示该页面是新加载的。
isMainFrame22+ boolean 否 是

是否是主文档触发。

true表示是主文档触发,false表示不是主文档触发。

OnRenderExitedEvent12+

定义渲染进程退出时触发。适用于需要监控渲染进程异常的场景,提升渲染稳定性和故障排查效率。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
renderExitReason RenderExitReason 否 否 渲染进程异常退出的具体原因。

OnShowFileSelectorEvent12+

定义文件选择器结果的回调信息,包括结果和参数详情。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
result FileSelectorResult 否 否 用于通知Web组件文件选择的结果。
fileSelector FileSelectorParam 否 否 文件选择器的相关信息。

OnResourceLoadEvent12+

定义加载URL时触发的回调信息,包括资源URL。适用于需要监控资源加载行为的场景,提升资源管理的可见性和性能优化。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 所加载的资源文件url信息。

OnScaleChangeEvent12+

定义当前页面显示比例的变化时触发。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
oldScale number 否 否 变化前的显示比例百分比。
newScale number 否 否 变化后的显示比例百分比。

OnHttpAuthRequestEvent12+

定义收到HTTP认证请求时触发的回调信息,包括主机和域信息。适用于需要处理HTTP身份验证的场景,提升认证流程的灵活性和安全性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
handler HttpAuthHandler 否 否 通知Web组件用户操作行为。
host string 否 否 HTTP身份验证凭据应用的主机。
realm string 否 否 HTTP身份验证凭据应用的域。

OnInterceptRequestEvent12+

定义Web组件加载URL之前触发的回调信息,包括请求详情。适用于需要拦截或修改网络请求的场景,提升请求控制的灵活性和安全性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
request WebResourceRequest 否 否 url请求的相关信息。

OnPermissionRequestEvent12+

定义收到权限请求时触发的回调信息,包括请求详情。适用于需要处理权限授予的场景,提升权限管理的灵活性和安全性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
request PermissionRequest 否 否 通知Web组件用户操作行为。

OnScreenCaptureRequestEvent12+

定义收到屏幕捕获请求时触发的回调信息。适用于需要处理屏幕录制权限的场景,提升录屏流程的可控性和安全性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
handler ScreenCaptureHandler 否 否 通知Web组件用户操作行为。

OnContextMenuShowEvent12+

定义调用时触发的回调信息,以允许自定义显示上下文菜单。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
param WebContextMenuParam 否 否 菜单相关参数。
result WebContextMenuResult 否 否 菜单相应事件传入内核。

OnSearchResultReceiveEvent12+

定义网页页内查找结果的回调信息,包括匹配项序号和总数。适用于需要监控页内搜索行为的场景,提升搜索交互的可见性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
activeMatchOrdinal number 否 否 当前匹配的查找项的序号(从0开始)。
numberOfMatches number 否 否 所有匹配到的关键词的个数。
isDoneCounting boolean 否 否

当次页内查找操作是否结束。

true表示当次页内查找操作结束,false表示未结束。

该方法可能回调多次,直到isDoneCounting为true。

OnScrollEvent12+

定义滚动条滑动到指定位置时触发的回调信息,包括水平和垂直偏移量。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
xOffset number 否 否

以网页最左端为基准,水平滚动条滚动所在位置。

单位:vp。

yOffset number 否 否

以网页最上端为基准,竖直滚动条滚动所在位置。

单位:vp。

OnSslErrorEventReceiveEvent12+

定义网页收到SSL错误时触发的回调信息,包括错误码和证书链。适用于需要处理SSL错误的场景,提升安全异常的监控和处理能力。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
handler SslErrorHandler 否 否 通知Web组件用户操作行为。
error SslError 否 否 错误码。
certChainData15+ Array<Uint8Array> 否 是 证书链数据。

SslErrorEvent12+

用户加载资源时发生SSL错误时触发的回调详情,包括URL、错误类型和证书链。适用于需要详细分析SSL错误的场景,提升安全问题的诊断和排查效率。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
handler SslErrorHandler 否 否 通知Web组件用户操作行为。
error SslError 否 否 错误码。
url string 否 否 url地址。
originalUrl string 否 否 请求的原始url地址。
referrer string 否 否 referrer url地址。
isFatalError boolean 否 否

是否是致命错误。致命错误会导致页面无法正常加载和渲染(如证书验证失败、协议错误),非致命错误只影响部分资源的加载(如图片加载失败)。

true表示致命错误,false表示非致命错误。

isMainFrame boolean 否 否

是否是主资源。

true表示主资源,false表示非主资源。

certChainData20+ Array<Uint8Array> 否 是 证书链数据。

OnClientAuthenticationEvent12+

定义需要提供SSL客户端证书时触发的回调信息,包括主机、端口和密钥类型。适用于需要处理客户端证书认证的场景,提升认证流程的灵活性和安全性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
handler ClientAuthenticationHandler 否 否 通知Web组件用户操作行为。
host string 否 否 请求证书服务器的主机名。
port number 否 否 请求证书服务器的端口号。取值范围通常为0-65535。
keyTypes Array<string> 否 否 可接受的非对称密钥类型。
issuers Array<string> 否 否 与私钥匹配的证书可接受颁发者。

VerifyPinEvent22+

定义当需要用户进行PIN码认证时触发回调。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
handler VerifyPinHandler 否 否 通知Web组件用户操作行为。
identity string 否 否 用于认证的证书凭据标识。

OnWindowNewEvent12+

定义网页要求用户创建窗口时触发的回调信息。从API version 23开始,如需获取更多窗口信息,可使用OnWindowNewExtEvent。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
isAlert boolean 否 否 true代表请求创建对话框,false代表新标签页。
isUserTrigger boolean 否 否 true代表用户触发,false代表非用户触发。
targetUrl string 否 否 目标url。
handler ControllerHandler 否 否 用于设置新建窗口的WebviewController实例。

WindowFeatures23+

提供网页请求创建的新窗口特征信息,包括大小和位置。适用于需要精确控制新窗口属性的场景,提升窗口布局的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
x number 否 否 新窗口左上角横坐标(单位:像素)。
y number 否 否 新窗口左上角纵坐标(单位:像素)。
width number 否 否 新窗口宽度(单位:像素)。
height number 否 否 新窗口高度(单位:像素)。

OnWindowNewExtEvent23+

定义网页请求创建窗口时触发的回调信息,包括窗口特征信息和窗口打开方式。适用于需要精细控制新窗口行为的场景,提升窗口管理的定制性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
isAlert boolean 否 否 true代表请求创建对话框,false代表请求创建新标签页。
isUserTrigger boolean 否 否 true代表用户触发,false代表非用户触发。
targetUrl string 否 否 请求的新窗口中需要打开的url。
handler ControllerHandler 否 否 用于设置新建窗口的WebviewController实例。
windowFeatures WindowFeatures 否 否 网页请求创建的新窗口特征信息。
navigationPolicy NavigationPolicy 否 否 网页请求用户创建新窗口时的窗口打开方式。

OnTouchIconUrlReceivedEvent12+

定义接收到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不是预合成。

OnFaviconReceivedEvent12+

定义应用接收到新favicon时触发的回调信息,包括图标PixelMap对象。适用于需要获取网页favicon的场景,提升图标管理的灵活性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
favicon PixelMap 否 否 接收到的favicon图标的PixelMap对象。

OnPageVisibleEvent12+

定义旧页面不再呈现,新页面即将可见时触发的回调函数。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 新页面的URL地址。

OnDataResubmittedEvent12+

定义网页表单可以重新提交时触发的回调信息,包括提交句柄。适用于需要处理表单重试提交的场景,提升表单交互的可靠性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
handler DataResubmissionHandler 否 否 表单数据重新提交句柄。

OnAudioStateChangedEvent12+

定义网页音频播放状态改变时触发的回调信息,包括播放状态。适用于需要监控音频播放行为的场景,提升音频管理的可见性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
playing boolean 否 否 当前页面的音频播放状态,true表示正在播放,false表示未播放。

OnFirstContentfulPaintEvent12+

定义网页首次内容绘制的回调信息,包括加载时间和绘制时间。适用于需要监控页面渲染性能的场景,提升性能优化的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
navigationStartTick number 否 否 启动页面加载开始的时间,单位以微秒表示。
firstContentfulPaintMs number 否 否 从启动页面加载开始到第一次绘制内容的时间,单位是以毫秒表示。

OnLoadInterceptEvent12+

定义截获资源加载时触发的回调信息,包括请求详情。适用于需要拦截或处理资源加载的场景,提升资源控制的灵活性和安全性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
data WebResourceRequest 否 否 url请求的相关信息。

OnOverScrollEvent12+

定义网页过度滚动时触发的回调信息,包括水平和垂直偏移量。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
xOffset number 否 否

以网页最左端为基准,水平过度滚动的偏移量。

单位:vp。

yOffset number 否 否

以网页最上端为基准,竖直过度滚动的偏移量。

单位:vp。

JavaScriptProxy12+

定义要注入的JavaScript对象,包括对象名、方法列表和权限配置。适用于需要实现JavaScript与原生交互的场景,提升跨语言调用的灵活性和安全性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
object object 否 否 参与注册的对象。只能声明方法,不能声明属性。方法必须是函数类型。
name string 否 否 注册对象的名称,与window中调用的对象名一致。
methodList Array<string> 否 否 参与注册的应用侧JavaScript对象的同步方法。
controller WebController | WebviewController 否 否 控制器。从API version 9开始,WebController不再维护,建议使用WebviewController替代。
asyncMethodList12+ Array<string> 否 是 参与注册的应用侧JavaScript对象的异步方法。异步方法无法获取返回值。
permission12+ string 否 是

json字符串,默认为空,通过该字符串配置JSBridge的权限管控,可以定义object、method一级的url白名单。

JavaScriptProxy的permission参数支持resource/http/https协议,不支持file协议。

示例请参考前端页面调用应用侧函数。

OnPageEndEvent12+

定义网页加载结束时触发的回调信息,包括页面URL。适用于需要监控页面加载完成的场景,提升页面生命周期的管理能力。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 网页加载完成后的页面URL地址。

OnPageBeginEvent12+

定义网页加载开始时触发的回调信息,包括页面URL。适用于需要监控页面加载开始的场景,提升页面生命周期的管理能力。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 网页加载开始时即将加载的页面URL地址。

OnProgressChangeEvent12+

定义网页加载进度变化时触发的回调信息,包括新的进度值。适用于需要监控页面加载进度的场景,提升加载过程的可见性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
newProgress number 否 否 新的加载进度,取值范围为[0, 100]的整数。

OnTitleReceiveEvent12+

定义网页标题更改时触发的回调信息,包括标题内容和来源。适用于需要监控页面标题变化的场景,提升页面信息的实时性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
title string 否 否 document标题内容。
isRealTitle20+ boolean 否 是

document标题来源,true表示来自网页的title标签,false表示该title是根据url自动生成。

默认值:false

OnGeolocationShowEvent12+

定义收到地理位置获取请求时触发的回调信息,包括源信息和地理对象。适用于需要处理地理位置权限的场景。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
origin string 否 否 发起地理位置权限请求的网页源,用于标识特定网站的地理位置请求来源。
geolocation JsGeolocation 否 否 通知Web组件用户操作行为。

NativeEmbedVisibilityInfo12+

提供同层标签的可见性信息,包括可见状态和标签ID。适用于需要监控同层元素可见性的场景,提升渲染状态管理的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
visibility boolean 否 否

可见性。

true表示可见,false表示不可见。

embedId string 否 否 同层渲染标签的唯一id。

RenderProcessNotRespondingData12+

提供渲染进程无响应的详细信息。适用于需要诊断渲染进程异常的场景,提升故障排查的准确性和效率。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
jsStack string 否 否 网页的JavaScript调用栈信息。
pid number 否 否 网页的进程id。
reason RenderProcessNotRespondingReason 否 否 触发渲染进程无响应回调的原因。

FullScreenEnterEvent12+

提供Web组件进入全屏的回调信息,包括视频尺寸和退出句柄。适用于需要处理全屏视频的场景,提升视频播放的沉浸式体验和可控性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
handler FullScreenExitHandler 否 否 用于退出全屏模式的函数句柄。
videoWidth number 否 是 视频的宽度,单位:px。如果进入全屏的是 <video> 元素,表示其宽度;如果进入全屏的子元素中包含 <video> 元素,表示第一个子视频元素的宽度;其他情况下,为0。
videoHeight number 否 是 视频的高度,单位:px。如果进入全屏的是 <video> 元素,表示其高度;如果进入全屏的子元素中包含 <video> 元素,表示第一个子视频元素的高度;其他情况下,为0。

LoadCommittedDetails11+

提供已提交跳转的网页详细信息,包括是否主文档、导航类型等。适用于需要监控页面导航行为的场景,提升导航状态管理的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
isMainFrame boolean 否 否

是否是主文档。

true表示主文档,false表示非主文档。

isSameDocument boolean 否 否

是否在不更改文档的情况下进行的网页跳转。

true表示在不更改文档的情况下进行的网页跳转,false表示在更改文档的情况下进行的网页跳转。

同文档跳转示例:1.参考片段跳转;2.pushState或replaceState触发的跳转;3.同一页面历史跳转。

didReplaceEntry boolean 否 否

是否提交的新节点替换了已有的节点。

true表示提交的新节点替换了已有的节点,false表示提交的新节点未替换已有的节点。

另外在一些子文档跳转的场景,虽然没有实际替换已有节点,但是有一些属性发生了变更。

navigationType WebNavigationType 否 否 网页跳转的类型。
url string 否 否 跳转到的网页的URL。

NativeEmbedInfo11+

提供同层标签的详细信息,包括ID、类型、尺寸和位置等。适用于需要获取同层元素属性的场景,提升同层渲染的定制性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
id string 否 是 同层标签的id信息。
type string 否 是 同层标签的type信息,统一为小写字符。
src string 否 是 同层标签的src信息。
width number 否 是 同层标签的宽,单位为px。
height number 否 是 同层标签的高,单位为px。
url string 否 是 同层标签的url信息。
tag12+ string 否 是 标签名,统一为大写字符。
params12+ Map<string, string> 否 是 object标签包含的params标签键值对列表,请使用Object提供的方法操作该对象,即embed.info?.params?.["name"]。
position12+ Position 否 是 同层标签相对于Web组件左上角为坐标原点的位置信息,此处区别于标准Position,单位为px。

NativeEmbedParamItem21+

提供同层渲染object标签内嵌param元素的详细信息,包括状态和参数。适用于需要监控param元素变化的场景,提升同层元素管理的灵活性和准确性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
status NativeEmbedParamStatus 否 否 param元素的状态变化类型。
id string 否 否 param元素的id信息。
name string 否 是 param元素的参数名称。
value string 否 是 param元素的参数值。

IntelligentTrackingPreventionDetails12+

提供智能防跟踪拦截的详细信息,包括网站域名和追踪者域名。适用于需要监控广告拦截行为的场景,提升隐私保护的透明度和可控性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
host string 否 否 网站域名。
trackerHost string 否 否 追踪者域名。

WebKeyboardCallbackInfo12+

拦截网页可编辑元素拉起软键盘的回调入参,包括WebKeyboardController和可编辑元素的属性。适用于需要自定义键盘交互的场景,提升输入体验的定制性和灵活性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
controller WebKeyboardController 否 否 提供控制自定义键盘的输入、删除、关闭等操作。
attributes Record<string, string> 否 否 触发本次软键盘弹出的网页元素属性。

WebKeyboardOptions12+

拦截网页可编辑元素拉起软键盘的回调返回值,包括键盘类型和自定义键盘。适用于需要控制软键盘行为的场景。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
useSystemKeyboard boolean 否 否

是否使用系统默认软键盘。

true表示使用系统默认软键盘,false表示不使用系统默认软键盘。

默认值:true。

enterKeyType number 否 是 指定系统软键盘enter键的类型,取值范围见输入框架的定义EnterKeyType,该参数为可选参数,默认值为UNSPECIFIED。当useSystemKeyboard为true,并且设置了有效的enterKeyType时候,才有效。
customKeyboard CustomBuilder 否 是 指定自定义键盘组件builder,可选参数,当useSystemKeyboard为false时,需要设置该参数,然后Web组件会拉起该自定义键盘。

FirstMeaningfulPaint12+

提供网页绘制页面主要内容的详细信息,包括导航时间和绘制时间。适用于需要监控页面渲染性能的场景,提升性能优化的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
navigationStartTime number 否 是 导航开始时间,单位以微秒表示。
firstMeaningfulPaintTime number 否 是 绘制页面主要内容时间,单位以毫秒表示。

LargestContentfulPaint12+

提供网页绘制页面最大内容的详细信息,包括导航时间和各类绘制时间。适用于需要监控页面渲染性能的场景,提升性能优化的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
navigationStartTime number 否 是 导航开始时间,单位以微秒表示。
largestImagePaintTime number 否 是 最大图片加载的时间,单位是以毫秒表示。
largestTextPaintTime number 否 是 最大文本加载时间,单位是以毫秒表示。
largestImageLoadStartTime number 否 是 最大图片开始加载时间,单位是以毫秒表示。
largestImageLoadEndTime number 否 是 最大图片结束加载时间,单位是以毫秒表示。
imageBPP number 否 是 最大图片像素位数。

NativeEmbedDataInfo11+

提供同层标签生命周期变化的详细信息,包括状态和标签信息。适用于需要监控同层元素生命周期的场景,提升渲染状态管理的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
status NativeEmbedStatus 否 是 同层标签生命周期状态。
surfaceId string 否 是 NativeImage的surfaceId。
embedId string 否 是 同层标签的唯一id。
info NativeEmbedInfo 否 是 同层标签的详细信息。

NativeEmbedTouchInfo11+

提供手指触摸同层标签的详细信息,包括标签ID和触摸事件。适用于需要处理同层元素触摸交互的场景,提升触摸体验的定制性和灵活性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
embedId string 否 是 同层标签的唯一id。
touchEvent TouchEvent 否 是 手指触摸动作信息。
result12+ EventResult 否 是 通知Web组件手势事件的消费结果。

NativeEmbedMouseInfo20+

提供鼠标/触摸板在同层标签上点击或长按的详细信息,包括标签ID和鼠标事件。适用于需要处理同层元素鼠标交互的场景,提升鼠标体验的定制性和灵活性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
embedId string 否 是 同层标签的唯一id。
mouseEvent MouseEvent 否 是 鼠标/触摸板点击/长按信息。
result EventResult 否 是 通知Web组件鼠标事件的消费结果。

NativeEmbedParamDataInfo21+

提供同层渲染object标签内嵌param元素变化时同层标签的详细信息,包括标签ID和参数项。适用于需要监控param元素变化的场景,提升同层元素管理的灵活性和准确性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
embedId string 否 否 同层标签的唯一id。
objectAttributeId string 否 是 同层标签的id信息。
paramItems Array<NativeEmbedParamItem> 否 是 发生变化的param元素的详细信息,包括每一个param元素的状态变化类型、id、参数名称和参数值。

OnLoadStartedEvent20+

定义网页加载开始时触发的回调信息,包括页面URL。适用于需要监控页面加载开始的场景,提升页面生命周期的管理能力。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 页面的URL地址。

OnLoadFinishedEvent20+

定义网页加载结束时触发的回调信息,包括页面URL。适用于需要监控页面加载完成的场景,提升页面生命周期的管理能力。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 页面的URL地址。

OnPdfLoadEvent20+

定义PDF加载成功或失败时触发的函数。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 页面的URL地址。
result PdfLoadResult 否 否 PDF页面加载结果。

OnPdfScrollEvent20+

定义PDF页面滚动到底时触发的回调函数。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 页面的URL地址。

ScreenCaptureConfig10+

提供Web屏幕捕获的配置选项,包括捕获模式。适用于需要自定义网页录屏行为的场景,提升录屏功能的灵活性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
captureMode WebCaptureMode 否 否 Web屏幕捕获模式。

BlankScreenDetectionEventInfo22+

提供检测到白屏时的事件信息,包括URL、原因和细节。适用于需要监控页面白屏问题的场景,提升白屏诊断的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 检测到白屏时,页面的url。
blankScreenReason DetectedBlankScreenReason 否 否 本次检测到白屏时,具体原因与检测的方法相关。
blankScreenDetails BlankScreenDetails 否 是 本次检测白屏的结果的细节。当使用检测有内容的节点检测策略,且检测到的有内容节点数量未超过阈值时,此参数包含当前命中了多少有内容节点等详细信息;未使用该策略或节点数量超过阈值时,此参数为空。

BlankScreenDetails22+

提供检测到白屏时的结果细节,包括有内容节点数量。适用于需要分析白屏原因的场景,提升白屏诊断的详细性和准确性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
detectedContentfulNodesCount number 否 是

在使用到检测有内容的节点检测策略时,且开发者自己设置了检测到节点数量阈值时,可能包含该属性。否则没有该属性。

表示当前命中了多少有内容的节点。

BlankScreenDetectionConfig22+

提供白屏检测的策略配置选项,包括检测时机、方法和阈值。适用于需要自定义白屏检测行为的场景,提升白屏监控的灵活性和准确性。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
enable boolean 否 否 是否启用白屏策略功能。true表示启用,false表示不启用。
detectionTiming number[] 否 是

用以设置需要在加载后多少秒的时机来检测是否白屏。

单位:秒。

注:

1.重复值会忽略。

2.需大于0,小于0的值会被忽略。

默认值:[1.0,3.0,5.0]。

detectionMethods BlankScreenDetectionMethod[] 否 是

使用检测策略的方法,是一个数组。

注:

1.重复值会忽略。

默认值:[BlankScreenDetectionMethod.DETECTION_CONTENTFUL_NODES_SEVENTEEN]。

contentfulNodesCountThreshold number 否 是

在使用到检测有内容的节点检测策略时,才会生效。

可以设置0-${检测策略最大节点},如果小于等于阈值则会触发近似白屏。

默认值:0。

注:检测策略最大节点依赖于所选择的检测策略。

MonitoredBlankScreenEventInfo

白屏检测归因信息,包括页面URL、白屏根因、归因详情。

起始版本: 26.0.1

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 页面URL。
reason BlankScreenReason 否 否 白屏的具体原因。
extraMsg string 否 否 归因详情,JSON格式的字符串。

CameraCaptureStateChangeInfo23+

提供摄像头触发回调时的状态变化信息,包括改变前的状态和新状态。适用于需要监控摄像头状态变化的场景,提升摄像头管理的可见性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
originalState CameraCaptureState 否 否 改变前的状态
newState CameraCaptureState 否 否 改变后的状态

MicrophoneCaptureStateChangeInfo23+

提供麦克风触发回调时的状态变化信息,包括改变前的状态和改变后的状态。适用于需要监控麦克风状态变化的场景,提升麦克风管理的可见性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
originalState MicrophoneCaptureState 否 否 改变前的状态。
newState MicrophoneCaptureState 否 否 改变后的状态。

AcceptableFileType23+

提供文件选择器推荐的文件类型信息,包括MIME类型和类型数组。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
mimeType string 否 否 文件MIME类型。
acceptableType Array<string> 否 否 文件类型数组,包含若干可供选择的文件类型。

FirstScreenPaint23+

提供首屏渲染事件的信息,包括URL和绘制时间。适用于需要监控页面首屏渲染性能的场景,提升性能优化的准确性和用户体验。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
url string 否 否 本次首屏渲染统计所对应的url。
navigationStartTime number 否 否

url所指页面开始导航的时刻。

单位:毫秒。

firstScreenPaintTime number 否 否

url所指页面首屏绘制完成的时刻。

单位:毫秒。

AISessionEvent

自定义AI会话配置对象,用于定义AI会话的生命周期回调,包括创建、执行和销毁。

起始版本: 26.0.0

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Web.Webview.Core

名称 类型 只读 可选 说明
aiSessionType AISessionType 否 否 AI会话类型。
onCreateAISession OnCreateAISession 否 否 AI会话创建时触发的回调函数。返回true跳过系统默认行为,返回false继续执行系统默认逻辑。
onExecuteAIAction OnExecuteAIAction 否 否 AI会话执行操作时触发的回调函数。
onDestroyAISession OnDestroyAISession 否 否 AI会话销毁时触发的回调函数,用于清理与自定义AI模型关联的资源。