@ohos.web.webview (Webview)
@ohos.web.webview提供web控制能力，Web组件提供网页显示的能力。
说明：
本模块接口从API version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
示例效果请以真机运行为准，当前DevEco Studio预览器不支持。
静态方法必须在用户界面（UI）线程上使用。
需要权限
访问在线网页时需添加网络权限：ohos.permission.INTERNET，具体申请方式请参考声明权限。
导入模块
import { webview } from '@kit.ArkWeb';
webview.once
once(type: string, callback: Callback<void>): void
订阅一次指定类型Web事件的回调，Web事件的类型目前仅支持"webInited"，在Web引擎初始化完成时触发。
当应用中开始加载第一个Web组件时，Web引擎初始化，且后续再在同一应用中继续加载其他Web组件时不会再触发once接口。当应用销毁最后一个Web组件时，若再加载第一个Web组件，应用重新进入Web引擎初始化流程。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | Web事件的类型，目前支持："webInited"（Web初始化完成）。 |
| callback | Callback<void> | 是 | 所订阅的回调函数。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
webview.once("webInited", () => {
console.log("configCookieSync");
webview.WebCookieManager.configCookieSync("https://www.example.com", "a=b");
})
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
JsMessageExt10+
runJavaScriptExt接口执行脚本返回的数据对象。
getType10+
getType(): JsMessageType
获取数据对象的类型。完整示例代码参考runJavaScriptExt。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| JsMessageType | runJavaScriptExt接口脚本执行后返回的结果的类型。 |
getString10+
getString(): string
获取数据对象的字符串类型数据。完整示例代码参考runJavaScriptExt。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 返回字符串类型的数据。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 17100014 | The type and value of the message do not match. |
getNumber10+
getNumber(): number
获取数据对象的数值类型数据。完整示例代码参考runJavaScriptExt。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| number | 返回数值类型的数据。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 17100014 | The type and value of the message do not match. |
getBoolean10+
getBoolean(): boolean
获取数据对象的布尔类型数据。完整示例代码参考runJavaScriptExt。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| boolean | 返回布尔类型的数据。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 17100014 | The type and value of the message do not match. |
getArrayBuffer10+
getArrayBuffer(): ArrayBuffer
获取数据对象的原始二进制数据。完整示例代码参考runJavaScriptExt。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| ArrayBuffer | 返回原始二进制数据。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 17100014 | The type and value of the message do not match. |
getArray10+
getArray(): Array<string | number | boolean>
获取数据对象的数组类型数据。完整示例代码参考runJavaScriptExt。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| Array<string | number | boolean> | 返回数组类型的数据。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 17100014 | The type and value of the message do not match. |
HistoryItem
页面历史记录项。
系统能力： SystemCapability.Web.Webview.Core
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| icon | image.PixelMap | 是 | 否 | 历史页面图标的PixelMap对象。 |
| historyUrl | string | 否 | 否 | 历史记录项的url地址。 |
| historyRawUrl | string | 否 | 否 | 历史记录项的原始url地址。 |
| title | string | 否 | 否 | 历史记录项的标题。 |
WebDownloadItem11+
表示下载任务，您可以使用此对象来操作相应的下载任务。
说明：
在下载过程中，下载的进程会通过WebDownloadDelegate通知给使用者，使用者可以通过参数WebDownloadItem来操作下载任务。
getGuid11+
getGuid(): string
获取下载任务的唯一ID。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 下载任务的唯一ID。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getCurrentSpeed11+
getCurrentSpeed(): number
获取下载的速度，单位：字节每秒。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| number | 下载的速度（字节每秒）。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update current speed: " + webDownloadItem.getCurrentSpeed());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getPercentComplete11+
getPercentComplete(): number
获取下载的进度，100代表下载完成。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| number | 下载完成的进度，100代表下载完成。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getTotalBytes11+
getTotalBytes(): number
获取待下载文件的总长度。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| number | 待下载文件的总长度。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update total bytes: " + webDownloadItem.getTotalBytes());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getState11+
getState(): WebDownloadState
获取下载的状态。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| WebDownloadState | 下载的状态。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update download state: " + webDownloadItem.getState());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getLastErrorCode11+
getLastErrorCode(): WebDownloadErrorCode
获取下载的错误码。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| WebDownloadErrorCode | 下载发生错误的时候的错误码。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
console.log("download error code: " + webDownloadItem.getLastErrorCode());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getMethod11+
getMethod(): string
获取下载任务的请求方式。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 下载的请求方式。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download， method:" + webDownloadItem.getMethod());
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getMimeType11+
getMimeType(): string
获取下载的媒体类型（例如，一个声音文件可能被标记为 audio/ogg ，一个图像文件可能是 image/png）。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 下载的媒体类型（例如，一个声音文件可能被标记为 audio/ogg ，一个图像文件可能是 image/png）。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download， mime type:" + webDownloadItem.getMimeType());
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getUrl11+
getUrl(): string
获取下载的请求地址。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 下载的请求地址。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download, url:" + webDownloadItem.getUrl());
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getSuggestedFileName11+
getSuggestedFileName(): string
获取下载的建议文件名。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 下载的建议文件名。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download, suggest name:" + webDownloadItem.getSuggestedFileName());
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getReceivedBytes11+
getReceivedBytes(): number
获取已经接收的字节数。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| number | 已经接收的字节数。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
console.log("download update received bytes: " + webDownloadItem.getReceivedBytes());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
getFullPath11+
getFullPath(): string
获取下载文件在磁盘上的全路径。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 下载文件在磁盘上的全路径。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
console.log("download finish full path: " + webDownloadItem.getFullPath());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
serialize11+
serialize(): Uint8Array
将失败的下载序列化到一个字节数组。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| Uint8Array | 失败的下载序列化后的字节数组。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
deserialize11+
static deserialize(serializedData: Uint8Array): WebDownloadItem
将序列化后的字节数组反序列化为一个WebDownloadItem对象。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| serializedData | Uint8Array | 是 | 序列化后的下载。 |
返回值：
| 类型 | 说明 |
|---|---|
| WebDownloadItem | 从字节数组反序列化为一个WebDownloadItem对象。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
start11+
start(downloadPath: string): void
开始下载到指定目录，参数为下载文件的磁盘存储路径(包含文件名)。
说明：
该接口应在WebDownloadDelegate的onBeforeDownload回调中使用。若在WebDownloadDelegate的onBeforeDownload中未调用start('xxx')，则下载任务将保持在PENDING状态。处于PENDING状态的下载会将文件下载到临时目录，临时文件会在WebDownloadItem.start指定目标路径后被重命名为目标路径，未下载完成的部分会在WebDownloadItem.start指定目标路径后直接下载到目标路径。如果在调用WebDownloadItem.start之前不希望下载到临时文件路径，可以先通过WebDownloadItem.cancel取消当前下载任务，随后通过WebDownloadManager.resumeDownload恢复被取消的下载任务。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| downloadPath | string | 是 | 下载文件的路径(包含文件名)，路径长度与文件管理中长度一致，最长255字符。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
cancel11+
cancel(): void
取消一个正在下载的下载任务。
系统能力： SystemCapability.Web.Webview.Core
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
download: webview.WebDownloadItem = new webview.WebDownloadItem();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
this.download = webDownloadItem;
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('cancel')
.onClick(() => {
try {
this.download.cancel();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
pause11+
pause(): void
暂停一个正在下载的下载任务。
系统能力： SystemCapability.Web.Webview.Core
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 17100019 | The download task is not started yet. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
download: webview.WebDownloadItem = new webview.WebDownloadItem();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
this.download = webDownloadItem;
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('cancel')
.onClick(() => {
try {
this.download.cancel();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('pause')
.onClick(() => {
try {
this.download.pause();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
resume11+
resume(): void
恢复一个暂停的下载任务。
系统能力： SystemCapability.Web.Webview.Core
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 17100016 | The download task is not paused. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
download: webview.WebDownloadItem = new webview.WebDownloadItem();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
this.download = webDownloadItem;
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('cancel')
.onClick(() => {
try {
this.download.cancel();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('pause')
.onClick(() => {
try {
this.download.pause();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resume')
.onClick(() => {
try {
this.download.resume();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
WebDownloadDelegate11+
下载任务的状态会通过该类的回调接口通知给用户。
onBeforeDownload11+
onBeforeDownload(callback: Callback<WebDownloadItem>): void
下载开始前通知给用户，用户需要在此接口中调用WebDownloadItem.start("xxx")并提供下载路径，否则下载会一直处于PENDING状态。
说明：
处于PENDING状态的下载任务会首先将文件保存至临时目录。在调用WebDownloadItem.start并指定目标路径后，临时文件将被重命名为目标文件名，未完成下载的部分会在调用WebDownloadItem.start并指定目标路径后直接下载到目标路径。若希望避免在调用WebDownloadItem.start前生成临时文件，可先通过WebDownloadItem.cancel来取消当前的下载任务，之后再使用WebDownloadManager.resumeDownload来恢复被取消的下载任务。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | Callback<WebDownloadItem> | 是 | 触发下载的回调。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
download: webview.WebDownloadItem = new webview.WebDownloadItem();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
this.download = webDownloadItem;
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('cancel')
.onClick(() => {
try {
this.download.cancel();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('pause')
.onClick(() => {
try {
this.download.pause();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resume')
.onClick(() => {
try {
this.download.resume();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
onDownloadUpdated11+
onDownloadUpdated(callback: Callback<WebDownloadItem>): void
下载过程中的回调，通过该回调的参数可以了解下载进度等信息。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | Callback<WebDownloadItem> | 是 | 下载的回调已更新。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
download: webview.WebDownloadItem = new webview.WebDownloadItem();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
this.download = webDownloadItem;
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('cancel')
.onClick(() => {
try {
this.download.cancel();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('pause')
.onClick(() => {
try {
this.download.pause();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resume')
.onClick(() => {
try {
this.download.resume();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
onDownloadFinish11+
onDownloadFinish(callback: Callback<WebDownloadItem>): void
下载完成的通知。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | Callback<WebDownloadItem> | 是 | 下载的回调已完成。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
download: webview.WebDownloadItem = new webview.WebDownloadItem();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
this.download = webDownloadItem;
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('cancel')
.onClick(() => {
try {
this.download.cancel();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('pause')
.onClick(() => {
try {
this.download.pause();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resume')
.onClick(() => {
try {
this.download.resume();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
onDownloadFailed11+
onDownloadFailed(callback: Callback<WebDownloadItem>): void
下载失败的通知。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | Callback<WebDownloadItem> | 是 | 下载回调失败。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
download: webview.WebDownloadItem = new webview.WebDownloadItem();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
this.download = webDownloadItem;
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('cancel')
.onClick(() => {
try {
this.download.cancel();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('pause')
.onClick(() => {
try {
this.download.pause();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resume')
.onClick(() => {
try {
this.download.resume();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
WebDownloadManager11+
可以通过该类提供的接口来恢复失败的下载任务。
setDownloadDelegate11+
static setDownloadDelegate(delegate: WebDownloadDelegate): void
设置用于接收从WebDownloadManager触发的下载进度的委托。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| delegate | WebDownloadDelegate | 是 | 用来接收下载进回调的委托。 |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
download: webview.WebDownloadItem = new webview.WebDownloadItem();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
this.download = webDownloadItem;
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
webview.WebDownloadManager.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('cancel')
.onClick(() => {
try {
this.download.cancel();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('pause')
.onClick(() => {
try {
this.download.pause();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resume')
.onClick(() => {
try {
this.download.resume();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
resumeDownload11+
static resumeDownload(webDownloadItem: WebDownloadItem): void
恢复一个失败的下载任务。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| webDownloadItem | WebDownloadItem | 是 | 待恢复的下载任务。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 17100018 | No WebDownloadDelegate has been set yet. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
download: webview.WebDownloadItem = new webview.WebDownloadItem();
failedData: Uint8Array = new Uint8Array();
build() {
Column() {
Button('setDownloadDelegate')
.onClick(() => {
try {
this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
console.log("will start a download.");
// 传入一个下载路径，并开始下载。
webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
})
this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
this.download = webDownloadItem;
})
this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
console.log("download failed guid: " + webDownloadItem.getGuid());
// 序列化失败的下载到一个字节数组。
this.failedData = webDownloadItem.serialize();
})
this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
console.log("download finish guid: " + webDownloadItem.getGuid());
})
this.controller.setDownloadDelegate(this.delegate);
webview.WebDownloadManager.setDownloadDelegate(this.delegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('startDownload')
.onClick(() => {
try {
this.controller.startDownload('https://www.example.com');
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resumeDownload')
.onClick(() => {
try {
webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('cancel')
.onClick(() => {
try {
this.download.cancel();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('pause')
.onClick(() => {
try {
this.download.pause();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button('resume')
.onClick(() => {
try {
this.download.resume();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
ProxyConfig15+
可以通过该类提供的接口对代理进行配置。
insertProxyRule15+
insertProxyRule(proxyRule: string, schemeFilter?: ProxySchemeFilter): void
插入一条代理规则，与schemeFilter匹配的URL都会使用指定代理。如果schemeFilter为空，所有URL都将使用指定代理。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| proxyRule | string | 是 | URL要使用的代理。 |
| schemeFilter | ProxySchemeFilter | 否 | 与schemeFilter匹配的URL会使用代理。 默认值：MATCH_ALL_SCHEMES。 |
错误码：
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例：
完整示例代码参考removeProxyOverride。
insertDirectRule15+
insertDirectRule(schemeFilter?: ProxySchemeFilter): void
插入一条代理规则，指明符合schemeFilter条件的URL将直接连接到服务器。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| schemeFilter | ProxySchemeFilter | 否 | 与schemeFilter匹配的URL会直接与服务器相连。 默认值：MATCH_ALL_SCHEMES |
错误码：
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例：
完整示例代码参考removeProxyOverride。
insertBypassRule15+
insertBypassRule(bypassRule: string): void
插入一条bypass规则，指明哪些URL应该绕过代理并直接连接到服务器。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| bypassRule | string | 是 | 与bypassRule匹配的URL会绕过代理。 |
错误码：
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例：
完整示例代码参考removeProxyOverride。
bypassHostnamesWithoutPeriod15+
bypassHostnamesWithoutPeriod(): void
没有点字符的域名将跳过代理并直接连接到服务器。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考removeProxyOverride。
clearImplicitRules15+
clearImplicitRules(): void
默认情况下，如果某些主机名是本地IP地址或localhost地址，它们会绕过代理。调用此函数以覆盖默认行为，并强制将localhost或本地IP地址通过代理发送。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考removeProxyOverride。
enableReverseBypass15+
enableReverseBypass(reverse: boolean): void
反转bypass规则。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reverse | boolean | 是 | 参数值默认是false，表示与insertBypassRule中的bypassRule匹配的URL会绕过代理，参数值为true时，表示与insertBypassRule中的bypassRule匹配的URL会使用代理。 |
错误码：
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例：
完整示例代码参考removeProxyOverride。
getBypassRules15+
getBypassRules(): Array<string>
获取不使用代理的URL列表。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| Array<string> | 不使用代理的URL列表。 |
示例：
完整示例代码参考removeProxyOverride。
getProxyRules15+
getProxyRules(): Array<ProxyRule>
获取代理规则。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| Array<ProxyRule> | 代理规则。 |
示例：
完整示例代码参考removeProxyOverride。
isReverseBypassEnabled15+
isReverseBypassEnabled(): boolean
获取enableReverseBypass的参数值，详见enableReverseBypass。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| boolean | enableReverseBypass的参数值。参数值为false，表示与insertBypassRule中的bypassRule匹配的URL会绕过代理，参数值为true时，表示与insertBypassRule中的bypassRule匹配的URL会使用代理。 |
示例：
完整示例代码参考removeProxyOverride。
ProxyRule15+
insertProxyRule中使用的代理规则。
getSchemeFilter15+
getSchemeFilter(): ProxySchemeFilter
获取代理规则中的ProxySchemeFilter信息。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| ProxySchemeFilter | 代理规则中的ProxySchemeFilter信息。 |
示例：
完整示例代码参考removeProxyOverride。
getUrl15+
getUrl(): string
获取代理规则中的代理的URL信息。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 代理规则中的代理的Url信息。 |
示例：
完整示例代码参考removeProxyOverride。
OnProxyConfigChangeCallback15+
type OnProxyConfigChangeCallback = () => void
回调函数，回调成功表示代理设置成功。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考removeProxyOverride。
ProxyController15+
此类用于为应用程序设置代理。
applyProxyOverride15+
static applyProxyOverride(proxyConfig: ProxyConfig, callback: OnProxyConfigChangeCallback): void
设置应用中所有Web使用的代理配置，与insertBypassRule中插入的bypass规则匹配的URL将不会使用代理，而是直接向URL指定的源地址发起请求。代理设置成功后，不保证网络连接后会立即使用新的代理设置，在加载页面之前请等待监听器触发，这个监听器将在UI线程上被调用。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| proxyConfig | ProxyConfig | 是 | 对代理的配置。 |
| callback | OnProxyConfigChangeCallback | 是 | 代理设置成功的回调。 |
错误码：
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例：
完整示例代码参考removeProxyOverride。
removeProxyOverride15+
static removeProxyOverride(callback: OnProxyConfigChangeCallback): void
移除代理配置。移除代理配置后，不保证网络连接后会立即使用新的代理设置，在加载页面之前等待监听器，这个监听器将在UI线程上被调用。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | OnProxyConfigChangeCallback | 是 | 代理设置成功的回调。 |
错误码：
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
proxyRules: webview.ProxyRule[] = [];
build() {
Row() {
Column() {
Button("applyProxyOverride").onClick(()=>{
let proxyConfig:webview.ProxyConfig = new webview.ProxyConfig();
//优先使用第一个代理配置https://proxy.XXX.com
//代理失败后会回落到直连服务器insertDirectRule
try {
proxyConfig.insertProxyRule("https://proxy.XXX.com", webview.ProxySchemeFilter.MATCH_ALL_SCHEMES);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
try {
proxyConfig.insertDirectRule(webview.ProxySchemeFilter.MATCH_HTTP);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
try {
proxyConfig.insertBypassRule("*.example.com");
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
proxyConfig.clearImplicitRules();
proxyConfig.bypassHostnamesWithoutPeriod();
try {
proxyConfig.enableReverseBypass(true);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
let bypassRules = proxyConfig.getBypassRules();
for (let i = 0; i < bypassRules.length; i++) {
console.log("bypassRules: " + bypassRules[i]);
}
this.proxyRules = proxyConfig.getProxyRules();
for (let i = 0; i < this.proxyRules.length; i++) {
console.log("SchemeFiletr: " + this.proxyRules[i].getSchemeFilter());
console.log("Url: " + this.proxyRules[i].getUrl());
}
let isReverseBypassRule = proxyConfig.isReverseBypassEnabled();
console.log("isReverseBypassRules: " + isReverseBypassRule);
try {
webview.ProxyController.applyProxyOverride(proxyConfig, () => {
console.log("PROXYCONTROLLER proxy changed");
});
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Button("loadUrl-https").onClick(()=>{
this.controller.loadUrl("https://www.example.com")
})
Button("loadUrl-http").onClick(()=>{
this.controller.loadUrl("http://www.example.com")
})
Button("removeProxyOverride").onClick(()=>{
try {
webview.ProxyController.removeProxyOverride(() => {
console.log("PROXYCONTROLLER proxy changed");
});
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller})
}
.width('100%')
}
.height('100%')
}
}
WebHttpBodyStream12+
POST、PUT请求的数据体，支持BYTES、FILE、BLOB、CHUNKED类型的数据。注意本类中其他接口需要在initialize成功后才能调用。
initialize12+
initialize(): Promise<void>
初始化WebHttpBodyStream。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| Promise<void> | Promise实例，用于获取WebHttpBodyStream是否初始化成功。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 17100022 | Failed to initialize the HTTP body stream. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { buffer } from '@kit.ArkTS';
import { WebNetErrorList } from '@ohos.web.netErrorList'
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
schemeHandler: webview.WebSchemeHandler = new webview.WebSchemeHandler();
htmlData: string = "<html><body bgcolor=\"white\">Source:<pre>source</pre></body></html>";
build() {
Column() {
Button('postUrl')
.onClick(() => {
try {
let postData = buffer.from(this.htmlData);
this.controller.postUrl('https://www.example.com', postData.buffer);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'https://www.example.com', controller: this.controller })
.onControllerAttached(() => {
try {
this.schemeHandler.onRequestStart((request: webview.WebSchemeHandlerRequest, resourceHandler: webview.WebResourceHandler) => {
console.log("[schemeHandler] onRequestStart");
try {
let stream = request.getHttpBodyStream();
if (stream) {
stream.initialize().then(() => {
if (!stream) {
return;
}
console.log("[schemeHandler] onRequestStart postDataStream size:" + stream.getSize());
console.log("[schemeHandler] onRequestStart postDataStream position:" + stream.getPosition());
console.log("[schemeHandler] onRequestStart postDataStream isChunked:" + stream.isChunked());
console.log("[schemeHandler] onRequestStart postDataStream isEof:" + stream.isEof());
console.log("[schemeHandler] onRequestStart postDataStream isInMemory:" + stream.isInMemory());
stream.read(stream.getSize()).then((buffer) => {
if (!stream) {
return;
}
console.log("[schemeHandler] onRequestStart postDataStream readlength:" + buffer.byteLength);
console.log("[schemeHandler] onRequestStart postDataStream isEof:" + stream.isEof());
console.log("[schemeHandler] onRequestStart postDataStream position:" + stream.getPosition());
}).catch((error: BusinessError) => {
console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
})
}).catch((error: BusinessError) => {
console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
})
} else {
console.log("[schemeHandler] onRequestStart has no http body stream");
}
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
return false;
})
this.schemeHandler.onRequestStop((request: webview.WebSchemeHandlerRequest) => {
console.log("[schemeHandler] onRequestStop");
});
this.controller.setWebSchemeHandler('https', this.schemeHandler);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
.javaScriptAccess(true)
.domStorageAccess(true)
}
}
}
read12+
read(size: number): Promise<ArrayBuffer>
读取WebHttpBodyStream中的数据。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| size | number | 是 | 读取WebHttpBodyStream中的字节数。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<ArrayBuffer> | Promise实例，用于获取WebHttpBodyStream中读取的数据。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. |
示例：
完整示例代码参考initialize。
getSize12+
getSize(): number
获取WebHttpBodyStream中的数据大小，分块传输时总是返回零。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| number | 获取WebHttpBodyStream中的数据大小。 |
示例：
完整示例代码参考initialize。
getPosition12+
getPosition(): number
读取WebHttpBodyStream中当前的读取位置。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| number | WebHttpBodyStream中当前的读取位置。 |
示例：
完整示例代码参考initialize。
isChunked12+
isChunked(): boolean
WebHttpBodyStream是否采用分块传输。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| boolean | WebHttpBodyStream是否采用分块传输，如果采用分块传输则返回true，否则返回false。 |
示例：
完整示例代码参考initialize。
isEof12+
isEof(): boolean
判断WebHttpBodyStream中的所有数据是否都已被读取。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| boolean | WebHttpBodyStream中的所有数据是否都已被读取。 如果所有数据都已被读取，则返回true。对于分块传输类型的WebHttpBodyStream，在第一次读取尝试之前返回false。 |
示例：
完整示例代码参考initialize。
isInMemory12+
isInMemory(): boolean
判断WebHttpBodyStream中的上传数据是否在内存中。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| boolean | WebHttpBodyStream中的上传数据是否在内存中。 如果WebHttpBodyStream中的上传数据完全在内存中，并且所有读取请求都将同步成功，则返回true。对于分块传输类型的数据，预期返回false。 |
示例：
完整示例代码参考initialize。
WebSchemeHandlerRequest12+
通过WebSchemeHandler拦截到的请求。
getHeader12+
getHeader(): Array<WebHeader>
获取资源请求头信息。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| Array<WebHeader> | 返回资源请求头信息。 |
示例：
完整示例代码参考onRequestStart。
getRequestUrl12+
getRequestUrl(): string
获取资源请求的URL信息。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 返回资源请求的URL信息。 |
示例：
完整示例代码参考onRequestStart。
getRequestMethod12+
getRequestMethod(): string
获取请求方法。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 返回请求方法。 |
示例：
完整示例代码参考onRequestStart。
getReferrer12+
getReferrer(): string
获取referrer。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 获取到的referrer。 |
示例：
完整示例代码参考onRequestStart。
isMainFrame12+
isMainFrame(): boolean
判断资源请求是否为主frame。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| boolean | 判断资源请求是否为主frame，如果资源请求是主frame则返回true，否则返回false。 |
示例：
完整示例代码参考onRequestStart。
hasGesture12+
hasGesture(): boolean
获取资源请求是否与手势（如点击）相关联。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| boolean | 返回资源请求是否与手势（如点击）相关联，如果返回资源请求与手势相关联则返回true，否则返回false。 |
示例：
完整示例代码参考onRequestStart。
getHttpBodyStream12+
getHttpBodyStream(): WebHttpBodyStream | null
获取资源请求中的WebHttpBodyStream。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| WebHttpBodyStream | null | 返回资源请求中的WebHttpBodyStream，如果没有则返回null。 |
示例：
完整示例代码参考onRequestStart。
getRequestResourceType12+
getRequestResourceType(): WebResourceType
获取资源请求的资源类型。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| WebResourceType | 返回资源请求的资源类型。 |
示例：
完整示例代码参考onRequestStart。
getFrameUrl12+
getFrameUrl(): string
获取触发此请求的Frame的URL。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 返回触发此请求的Frame的URL。 |
示例：
完整示例代码参考onRequestStart。
WebSchemeHandlerResponse12+
请求的响应，可以为被拦截的请求创建一个Response并填充自定义的内容返回给Web组件。
constructor12+
constructor()
Response的构造函数。
系统能力： SystemCapability.Web.Webview.Core
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { WebNetErrorList } from '@ohos.web.netErrorList';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
schemeHandler: webview.WebSchemeHandler = new webview.WebSchemeHandler();
build() {
Column() {
Button('response').onClick(() => {
let response = new webview.WebSchemeHandlerResponse();
try {
response.setUrl("http://www.example.com")
response.setStatus(200)
response.setStatusText("OK")
response.setMimeType("text/html")
response.setEncoding("utf-8")
response.setHeaderByName("header1", "value1", false)
response.setNetErrorCode(WebNetErrorList.NET_OK)
console.log("[schemeHandler] getUrl:" + response.getUrl())
console.log("[schemeHandler] getStatus:" + response.getStatus())
console.log("[schemeHandler] getStatusText:" + response.getStatusText())
console.log("[schemeHandler] getMimeType:" + response.getMimeType())
console.log("[schemeHandler] getEncoding:" + response.getEncoding())
console.log("[schemeHandler] getHeaderByValue:" + response.getHeaderByName("header1"))
console.log("[schemeHandler] getNetErrorCode:" + response.getNetErrorCode())
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'https://www.example.com', controller: this.controller })
}
}
}
setUrl12+
setUrl(url: string): void
给当前的Response设置重定向或因HSTS而更改后的URL，设置了url后会触发请求的跳转。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 即将要跳转的URL。 |
示例：
完整示例代码参考constructor。
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. |
setNetErrorCode12+
setNetErrorCode(code: WebNetErrorList): void
给当前的Response设置网络错误码。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | WebNetErrorList | 是 | 网络错误码。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例：
完整示例代码参考constructor。
setStatus12+
setStatus(code: number): void
给当前的Response设置HTTP状态码。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | number | 是 | Http状态码。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. |
示例：
完整示例代码参考constructor。
setStatusText12+
setStatusText(text: string): void
给当前的Response设置状态文本。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| text | string | 是 | 状态文本。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. |
示例：
完整示例代码参考constructor。
setMimeType12+
setMimeType(type: string): void
给当前的Response设置媒体类型。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 媒体类型。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. |
示例：
完整示例代码参考constructor。
setEncoding12+
setEncoding(encoding: string): void
给当前的Response设置字符集。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| encoding | string | 是 | 字符集。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. |
示例：
完整示例代码参考constructor。
setHeaderByName12+
setHeaderByName(name: string, value: string, overwrite: boolean): void
给当前的Response设置头信息。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 头部（header）的名称。 |
| value | string | 是 | 头部（header）的值。 |
| overwrite | boolean | 是 | 如果为true，将覆盖现有的头部，否则不覆盖。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例：
完整示例代码参考constructor。
getUrl12+
getUrl(): string
获取重定向或由于HSTS而更改后的URL。 风险提示：如果想获取url来做JavascriptProxy通信接口认证，请使用getLastJavascriptProxyCallingFrameUrl12+
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 获取经过重定向或由于HSTS而更改后的URL。 |
示例：
完整示例代码参考constructor。
getNetErrorCode12+
getNetErrorCode(): WebNetErrorList
获取Response的网络错误码。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| WebNetErrorList | 获取Response的网络错误码。 |
示例：
完整示例代码参考constructor。
getStatus12+
getStatus(): number
获取Response的Http状态码。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| number | 获取Response的Http状态码。 |
示例：
完整示例代码参考constructor。
getStatusText12+
getStatusText(): string
获取Response的状态文本。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 状态文本。 |
示例：
完整示例代码参考constructor。
getMimeType12+
getMimeType(): string
获取Response的媒体类型。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 媒体类型。 |
示例：
完整示例代码参考constructor。
getEncoding12+
getEncoding(): string
获取Response的字符集。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| string | 字符集。 |
示例：
完整示例代码参考constructor。
getHeaderByName12+
getHeaderByName(name: string): string
获取Response的字符集。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 头部（header）的名称。 |
返回值：
| 类型 | 说明 |
|---|---|
| string | 头部（header）的值。 |
示例：
完整示例代码参考constructor。
WebResourceHandler12+
通过WebResourceHandler，可以提供自定义的返回头以及返回体给Web组件。
didReceiveResponse12+
didReceiveResponse(response: WebSchemeHandlerResponse): void
将构造的响应头传递给被拦截的请求。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| response | WebSchemeHandlerResponse | 是 | 该拦截请求的响应。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. |
| 17100021 | The resource handler is invalid. |
示例：
示例请参考OnRequestStart。
didReceiveResponseBody12+
didReceiveResponseBody(data: ArrayBuffer): void
将构造的响应体传递给被拦截的请求。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| data | ArrayBuffer | 是 | 响应体数据。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. |
| 17100021 | The resource handler is invalid. |
示例：
示例请参考OnRequestStart。
didFinish12+
didFinish(): void
通知Web组件被拦截的请求已经完成，并且没有更多的数据可用，调用前需要优先调用didReceiveResponse将构造的响应头传递给被拦截的请求。
系统能力： SystemCapability.Web.Webview.Core
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 17100021 | The resource handler is invalid. |
示例：
示例请参考OnRequestStart。
didFail12+
didFail(code: WebNetErrorList): void
通知ArkWeb内核被拦截请求应该返回失败，调用前需要优先调用didReceiveResponse将构造的响应头传递给被拦截的请求。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | WebNetErrorList | 是 | 网络错误码。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. |
| 17100021 | The resource handler is invalid. |
系统能力： SystemCapability.Web.Webview.Core
示例：
示例请参考OnRequestStart。
WebSchemeHandler12+
用于拦截指定scheme的请求的拦截器。
onRequestStart12+
onRequestStart(callback: (request: WebSchemeHandlerRequest, handler: WebResourceHandler) => boolean): void
当请求开始时的回调，在该回调函数中可以决定是否拦截该请求。当回调返回false是表示不拦截此请求，此时handler失效；当回调返回true，表示拦截此请求。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | (request: WebSchemeHandlerRequest, handler: WebResourceHandler) => boolean | 是 | 拦截对应scheme请求开始时触发的回调。request为请求，handler用于提供自定义的返回头以及返回体给Web组件，返回值表示该请求是否拦截。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { buffer } from '@kit.ArkTS';
import { WebNetErrorList } from '@ohos.web.netErrorList';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
schemeHandler: webview.WebSchemeHandler = new webview.WebSchemeHandler();
htmlData: string = "<html><body bgcolor=\"white\">Source:<pre>source</pre></body></html>";
build() {
Column() {
Web({ src: 'https://www.example.com', controller: this.controller })
.onControllerAttached(() => {
try {
this.schemeHandler.onRequestStart((request: webview.WebSchemeHandlerRequest, resourceHandler: webview.WebResourceHandler) => {
console.log("[schemeHandler] onRequestStart");
try {
console.log("[schemeHandler] onRequestStart url:" + request.getRequestUrl());
console.log("[schemeHandler] onRequestStart method:" + request.getRequestMethod());
console.log("[schemeHandler] onRequestStart referrer:" + request.getReferrer());
console.log("[schemeHandler] onRequestStart isMainFrame:" + request.isMainFrame());
console.log("[schemeHandler] onRequestStart hasGesture:" + request.hasGesture());
console.log("[schemeHandler] onRequestStart header size:" + request.getHeader().length);
console.log("[schemeHandler] onRequestStart resource type:" + request.getRequestResourceType());
console.log("[schemeHandler] onRequestStart frame url:" + request.getFrameUrl());
let header = request.getHeader();
for (let i = 0; i < header.length; i++) {
console.log("[schemeHandler] onRequestStart header:" + header[i].headerKey + " " + header[i].headerValue);
}
let stream = request.getHttpBodyStream();
if (stream) {
console.log("[schemeHandler] onRequestStart has http body stream");
} else {
console.log("[schemeHandler] onRequestStart has no http body stream");
}
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
if (request.getRequestUrl().endsWith("example.com")) {
return false;
}
let response = new webview.WebSchemeHandlerResponse();
try {
response.setNetErrorCode(WebNetErrorList.NET_OK);
response.setStatus(200);
response.setStatusText("OK");
response.setMimeType("text/html");
response.setEncoding("utf-8");
response.setHeaderByName("header1", "value1", false);
} catch (error) {
console.error(`[schemeHandler] ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
// 调用 didFinish/didFail 前需要优先调用 didReceiveResponse 将构造的响应头传递给被拦截的请求。
let buf = buffer.from(this.htmlData)
try {
if (buf.length == 0) {
console.log("[schemeHandler] length 0");
resourceHandler.didReceiveResponse(response);
// 如果认为buf.length为0是正常情况，则调用resourceHandler.didFinish，否则调用resourceHandler.didFail
resourceHandler.didFail(WebNetErrorList.ERR_FAILED);
} else {
console.log("[schemeHandler] length 1");
resourceHandler.didReceiveResponse(response);
resourceHandler.didReceiveResponseBody(buf.buffer);
resourceHandler.didFinish();
}
} catch (error) {
console.error(`[schemeHandler] ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
return true;
})
this.schemeHandler.onRequestStop((request: webview.WebSchemeHandlerRequest) => {
console.log("[schemeHandler] onRequestStop");
});
this.controller.setWebSchemeHandler('https', this.schemeHandler);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
.javaScriptAccess(true)
.domStorageAccess(true)
}
}
}
onRequestStop12+
onRequestStop(callback: Callback<WebSchemeHandlerRequest>): void
当请求完成时的回调，仅当前面onRequestStart中回调决定拦截此请求中触发。触发的时机有以下两点：
1.WebResourceHandler调用didFail或者didFinish。
2.此请求因为其他原因中断。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | Callback<WebSchemeHandlerRequest> | 是 | 对应请求结束的回调函数。 |
错误码：
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Invalid input parameter. |
示例：
完整示例代码参考onRequestStart。
NativeMediaPlayerHandler12+
CreateNativeMediaPlayerCallback 回调函数的参数。 应用通过该对象，将播放器的状态报告给ArkWeb内核。
handleStatusChanged12+
handleStatusChanged(status: PlaybackStatus): void
当播放器的播放状态发生变化时，调用该方法将播放状态通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| status | PlaybackStatus | 是 | 播放器的播放状态。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleVolumeChanged12+
handleVolumeChanged(volume: number): void
当播放器的音量发生变化时，调用该方法将音量通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| volume | number | 是 | 播放器的音量。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleMutedChanged12+
handleMutedChanged(muted: boolean): void
当播放器的静音状态发生变化时，调用该方法将静音状态通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| muted | boolean | 是 | 当前播放器是否静音。 true表示当前播放器静音，false表示当前播放器未静音。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handlePlaybackRateChanged12+
handlePlaybackRateChanged(playbackRate: number): void
当播放器的播放速度发生变化时，调用该方法将播放速度通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| playbackRate | number | 是 | 播放速率。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleDurationChanged12+
handleDurationChanged(duration: number): void
当播放器解析出媒体的总时长时，调用该方法将媒体的总时长通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| duration | number | 是 | 媒体的总时长。 单位：秒。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleTimeUpdate12+
handleTimeUpdate(currentPlayTime: number): void
当媒体的播放进度发生变化时，调用该方法将媒体的播放进度通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| currentPlayTime | number | 是 | 当前播放时间。单位： 秒。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleBufferedEndTimeChanged12+
handleBufferedEndTimeChanged(bufferedEndTime: number): void
当媒体的缓冲时长发生变化时，调用该方法将媒体的缓冲时长通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| bufferedEndTime | number | 是 | 媒体缓冲的时长。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleEnded12+
handleEnded(): void
当媒体播放结束时，调用该方法通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleNetworkStateChanged12+
handleNetworkStateChanged(state: NetworkState): void
当播放器的网络状态发生变化时，调用该方法将播放器的网络状态通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| state | NetworkState | 是 | 播放器的网络状态。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleReadyStateChanged12+
handleReadyStateChanged(state: ReadyState): void
当播放器的缓存状态发生变化时，调用该方法将播放器的缓存状态通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| state | ReadyState | 是 | 播放器的缓存状态。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleFullscreenChanged12+
handleFullscreenChanged(fullscreen: boolean): void
当播放器的全屏状态发生变化时，调用该方法将播放器的全屏状态通知给 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fullscreen | boolean | 是 | 是否全屏。 true表示全屏，false表示未全屏。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleSeeking12+
handleSeeking(): void
当播放器进入seek 状态时，调用该方法通知 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleSeekFinished12+
handleSeekFinished(): void
当播放器 seek 完成后，调用该方法通知 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleError12+
handleError(error: MediaError, errorMessage: string): void
当播放器发生错误时， 调用该方法通知 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| error | MediaError | 是 | 错误类型。 |
| errorMessage | string | 是 | 错误的详细描述。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
handleVideoSizeChanged12+
handleVideoSizeChanged(width: number, height: number): void
当播放器解析出视频的尺寸时， 调用该方法通知 ArkWeb 内核。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| width | number | 是 | 视频的宽。 |
| height | number | 是 | 视频的高。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
NativeMediaPlayerBridge12+
CreateNativeMediaPlayerCallback 回调函数的返回值类型。 接管网页媒体的播放器和 ArkWeb 内核之间的一个接口类。 ArkWeb 内核通过该接口类的实例对象来控制应用创建的用来接管网页媒体的播放器。
updateRect12+
updateRect(x: number, y: number, width: number, height: number): void
更新 surface 位置信息。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| x | number | 是 | surface 相对于 Web 组件的 x 坐标信息。 |
| y | number | 是 | surface 相对于 Web 组件的 y 坐标信息。 |
| width | number | 是 | surface 的宽度。 |
| height | number | 是 | surface 的高度。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
play12+
play(): void
播放视频。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考onCreateNativeMediaPlayer。
pause12+
pause(): void
暂停播放。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考onCreateNativeMediaPlayer。
seek12+
seek(targetTime: number): void
播放跳转到某个时间点。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| targetTime | number | 是 | 播放跳转到的时间点。 单位：秒。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
setVolume12+
setVolume(volume: number): void
设置播放器音量值。
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| volume | number | 是 | 播放器的音量。 取值范围:[0, 1.0]，其中0表示静音，1.0表示最大音量。 |
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考onCreateNativeMediaPlayer。
setMuted12+
setMuted(muted: boolean): void
设置静音状态。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| muted | boolean | 是 | 是否静音。 true表示静音，false表示未静音。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
setPlaybackRate12+
setPlaybackRate(playbackRate: number): void
设置播放速度。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| playbackRate | number | 是 | 播放倍率。 取值范围: [0, 10.0]，其中1表示原速播放。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
release12+
release(): void
销毁播放器。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考onCreateNativeMediaPlayer。
enterFullscreen12+
enterFullscreen(): void
播放器进入全屏。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考onCreateNativeMediaPlayer。
exitFullscreen12+
exitFullscreen(): void
播放器退出全屏。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考onCreateNativeMediaPlayer。
resumePlayer12+
resumePlayer?(): void
通知应用重建应用内播放器，并恢复应用内播放器的状态信息。
系统能力： SystemCapability.Web.Webview.Core
示例：
完整示例代码参考onCreateNativeMediaPlayer。
suspendPlayer12+
suspendPlayer?(type: SuspendType): void
通知应用销毁应用内播放器，并保存应用内播放器的状态信息。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | SuspendType | 是 | 播放器挂起类型。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
MediaSourceInfo12+
表示媒体源的信息。
系统能力： SystemCapability.Web.Webview.Core
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | SourceType | 是 | 媒体源的类型。 |
| source | string | 是 | 媒体源地址。 |
| format | string | 是 | 媒体源格式， 可能为空， 需要使用者自己去判断格式。 |
NativeMediaPlayerSurfaceInfo12+
应用接管网页媒体播放功能中用于同层渲染的 surface 信息。
系统能力： SystemCapability.Web.Webview.Core
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | surface的id，用于同层渲染的NativeImage的psurfaceid。 详见NativeEmbedDataInfo。 |
| rect | RectEvent | 是 | surface的位置信息。 |
MediaInfo12+
CreateNativeMediaPlayerCallback回调函数的一个参数。 包含了网页中媒体的信息。应用可以根据这些信息来创建接管网页媒体播放的播放器。
系统能力： SystemCapability.Web.Webview.Core
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| embedID | string | 是 | 网页中的 <video> 或 <audio> 的 ID 。 |
| mediaType | MediaType | 是 | 媒体的类型。 |
| mediaSrcList | MediaSourceInfo[] | 是 | 媒体的源。可能有多个源，应用需要选择一个支持的源来播放。 |
| surfaceInfo | NativeMediaPlayerSurfaceInfo | 是 | 用于同层渲染的 surface 信息。 |
| controlsShown | boolean | 是 | <video> 或 <audio> 中是否有 controls属性。true表示有，false表示没有。 |
| controlList | string[] | 是 | <video> 或 <audio> 中的 controlslist 属性的值。 |
| muted | boolean | 是 | 是否要求静音播放。 true表示静音播放，false表示未静音播放。 |
| posterUrl | string | 是 | 海报的地址。 |
| preload | Preload | 是 | 是否需要预加载。 |
| headers | Record<string, string> | 是 | 播放器请求媒体资源时，需要携带的 HTTP 头。 |
| attributes | Record<string, string> | 是 | <video> 或 <audio> 标签中的属性。 |
CreateNativeMediaPlayerCallback12+
type CreateNativeMediaPlayerCallback = (handler: NativeMediaPlayerHandler, mediaInfo: MediaInfo) => NativeMediaPlayerBridge
onCreateNativeMediaPlayer方法的参数。 一个回调函数，创建一个播放器，用于接管网页中的媒体播放。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| handler | NativeMediaPlayerHandler | 是 | 通过该对象，将播放器的状态报告给 ArkWeb 内核。 |
| mediaInfo | MediaInfo | 是 | 网页媒体的信息。 |
返回值：
| 类型 | 说明 |
|---|---|
| NativeMediaPlayerBridge | 接管网页媒体的播放器和 ArkWeb 内核之间的一个接口类。 应用需要实现该接口类。 ArkWeb 内核通过该接口类的对象来控制应用创建的用来接管网页媒体的播放器。 如果应用返回了 null ， 则表示应用不接管这个媒体，由 ArkWeb 内核来播放该媒体。 |
示例：
完整示例代码参考onCreateNativeMediaPlayer。
RectEvent12+
矩形定义。
系统能力： SystemCapability.Web.Webview.Core
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| x | number | 否 | 否 | 矩形区域左上角x坐标。 |
| y | number | 否 | 否 | 矩形区域左上角y坐标。 |
| width | number | 否 | 否 | 矩形的宽度。 |
| height | number | 否 | 否 | 矩形的高度。 |
BackForwardCacheSupportedFeatures12+
选择性允许使用以下特性的页面进入前进后退缓存。完整示例代码参考enableBackForwardCache。
系统能力： SystemCapability.Web.Webview.Core
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| nativeEmbed | boolean | 是 | 是否允许使用同层渲染的页面进入前进后退缓存。 如果设置为允许，需要维护为同层渲染元素创建的系统控件的生命周期，避免造成泄漏。 true：允许使用同层渲染的页面进入前进后退缓存，false：不允许使用同层渲染的页面进入前进后退缓存。 默认值：false。 |
| mediaTakeOver | boolean | 是 | 是否允许使用视频托管的页面进入前进后退缓存。 如果设置为允许，需要维护为视频元素创建的系统控件的生命周期，避免造成泄漏。 true：允许使用视频托管的页面进入前进后退缓存，false：不允许使用视频托管的页面进入前进后退缓存。 默认值：false。 |
constructor12+
constructor()
BackForwardCacheSupportedFeatures的构造函数。
系统能力： SystemCapability.Web.Webview.Core
BackForwardCacheOptions12+
前进后退缓存相关设置对象，用来控制Web组件前进后退缓存相关选项。
系统能力： SystemCapability.Web.Webview.Core
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| size | number | 是 | 设置每个Web组件允许缓存的最大页面个数。 默认为1，最大可设置为50。 设置为0或负数时，前进后退缓存功能不生效。 Web会根据内存压力对缓存进行回收。 |
| timeToLive | number | 是 | 设置每个Web组件允许页面在前进后退缓存中停留的时间。 设置为0或负数时，前进后退缓存功能不生效。 默认值：600。 单位：秒。 |
constructor12+
constructor()
BackForwardCacheOptions的构造函数。
系统能力： SystemCapability.Web.Webview.Core
AdsBlockManager12+
通过AdsBlockManager可以向Web组件中设置自定义的广告过滤配置、关闭特定网站的广告过滤功能，其中每个应用中的所有Web组件都共享一个AdsBlockManager实例。
说明：
本模块接口从API version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
示例效果请以真机运行为准，当前DevEco Studio预览器不支持。
静态方法必须在用户界面（UI）线程上使用。
setAdsBlockRules12+
static setAdsBlockRules(rulesFile: string, replace: boolean): void
向Web组件中设置自定义的符合通用easylist语法规则的广告过滤配置文件。
说明：
此接口设置的广告过滤规则，内部解析成功后会持久化存储，应用重启后不需要重复设置。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| rulesFile | string | 是 | 指定了符合 easylist 通用语法的规则文件路径，应用需要有此文件的读权限。 |
| replace | boolean | 是 | true表示强制替换掉内置的默认规则，false表示设置的自定义规则将与内置规则共同工作。 |
错误码：
说明：
从API version 18开始，在不支持广告过滤功能的设备上调用该API会抛出801异常。
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { picker, fileUri } from '@kit.CoreFileKit';
// 演示点击按钮，通过filepicker打开一个easylist规则文件并设置到Web组件中
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Row() {
Flex() {
Button({ type: ButtonType.Capsule }) {
Text("setAdsBlockRules")
}
.onClick(() => {
try {
let documentSelectionOptions: ESObject = new picker.DocumentSelectOptions();
let documentPicker: ESObject = new picker.DocumentViewPicker();
documentPicker.select(documentSelectionOptions).then((documentSelectResult: ESObject) => {
if (documentSelectResult && documentSelectResult.length > 0) {
let fileRealPath = new fileUri.FileUri(documentSelectResult[0]);
console.info('DocumentViewPicker.select successfully, uri: ' + fileRealPath);
webview.AdsBlockManager.setAdsBlockRules(fileRealPath.path, true);
}
})
} catch (err) {
console.error('DocumentViewPicker.select failed with err:' + err);
}
})
}
}
}
}
addAdsBlockDisallowedList12+
static addAdsBlockDisallowedList(domainSuffixes: Array<string>): void
向AdsBlockManager的DisallowedList中添加一组域名。广告过滤功能开启时，将禁用这些网站的广告过滤功能。
说明：
此接口设置的域名不会持久化，应用重启需要重新设置。
广告过滤特性会使用后缀匹配的方式判断domainSuffix和当前站点的url是否能匹配，例如，当前Web组件打开的网站是https://www.example.com，设置的DisallowList中有'example.com'或者'www.example.com'，后缀匹配成功，此网站将禁用广告过滤，访问'https://m.example.com'也将禁用广告过滤。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| domainSuffixes | Array<string> | 是 | 一组域名列表，例如['example.com', 'abcd.efg.com'] |
错误码：
说明：
从API version 18开始，在不支持广告过滤功能的设备上调用该API会抛出801异常。
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
// 演示通过一个按钮的点击向Web组件设置广告过滤的域名策略
@Entry
@Component
struct WebComponent {
main_url: string = 'https://www.example.com';
text_input_controller: TextInputController = new TextInputController();
controller: webview.WebviewController = new webview.WebviewController();
@State input_text: string = 'https://www.example.com';
build() {
Column() {
Row() {
Flex() {
TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller})
.id("input_url")
.height(40)
.margin(5)
.borderColor(Color.Blue)
.onChange((value: string) => {
this.input_text = value;
})
Button({type: ButtonType.Capsule}) { Text("Go") }
.onClick(() => {
this.controller.loadUrl(this.input_text);
})
Button({type: ButtonType.Capsule}) { Text("addAdsBlockDisallowedList") }
.onClick(() => {
let arrDomainSuffixes = new Array<string>();
arrDomainSuffixes.push('example.com');
arrDomainSuffixes.push('abcdefg.cn');
webview.AdsBlockManager.addAdsBlockDisallowedList(arrDomainSuffixes);
})
}
}
Web({ src: this.main_url, controller: this.controller })
.onControllerAttached(()=>{
this.controller.enableAdsBlock(true);
})
}
}
}
removeAdsBlockDisallowedList12+
static removeAdsBlockDisallowedList(domainSuffixes: Array<string>): void
从AdsBlockManager的DisallowedList中删除一组域名。
说明：
AdsBlockManager的DisallowedList不会持久化，应用重启需要重新设置。删除不存在的条目不会触发异常。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| domainSuffixes | Array<string> | 是 | 一组域名列表，例如['example.com', 'abcd.efg.com'] |
错误码：
说明：
从API version 18开始，在不支持广告过滤功能的设备上调用该API会抛出801异常。
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
// 演示通过一个按钮的点击从AdsBlockManager的DisallowedList中删除域名元素
@Entry
@Component
struct WebComponent {
main_url: string = 'https://www.example.com';
text_input_controller: TextInputController = new TextInputController();
controller: webview.WebviewController = new webview.WebviewController();
@State input_text: string = 'https://www.example.com';
build() {
Column() {
Row() {
Flex() {
TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller})
.id("input_url")
.height(40)
.margin(5)
.borderColor(Color.Blue)
.onChange((value: string) => {
this.input_text = value;
})
Button({type: ButtonType.Capsule}) { Text("Go") }
.onClick(() => {
this.controller.loadUrl(this.input_text);
})
Button({type: ButtonType.Capsule}) { Text("removeAdsBlockDisallowedList") }
.onClick(() => {
let arrDomainSuffixes = new Array<string>();
arrDomainSuffixes.push('example.com');
arrDomainSuffixes.push('abcdefg.cn');
webview.AdsBlockManager.removeAdsBlockDisallowedList(arrDomainSuffixes);
})
}
}
Web({ src: this.main_url, controller: this.controller })
.onControllerAttached(()=>{
this.controller.enableAdsBlock(true);
})
}
}
}
clearAdsBlockDisallowedList12+
static clearAdsBlockDisallowedList(): void
清空AdsBlockManager的DisallowedList。
系统能力： SystemCapability.Web.Webview.Core
错误码：
说明：
从API version 18开始，在不支持广告过滤功能的设备上调用该API会抛出801异常。
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 801 | Capability not supported. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
main_url: string = 'https://www.example.com';
text_input_controller: TextInputController = new TextInputController();
controller: webview.WebviewController = new webview.WebviewController();
@State input_text: string = 'https://www.example.com';
build() {
Column() {
Row() {
Flex() {
TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller})
.id("input_url")
.height(40)
.margin(5)
.borderColor(Color.Blue)
.onChange((value: string) => {
this.input_text = value;
})
Button({type: ButtonType.Capsule}) { Text("Go") }
.onClick(() => {
this.controller.loadUrl(this.input_text);
})
Button({type: ButtonType.Capsule}) { Text("clearAdsBlockDisallowedList") }
.onClick(() => {
webview.AdsBlockManager.clearAdsBlockDisallowedList();
})
}
}
Web({ src: this.main_url, controller: this.controller })
.onControllerAttached(()=>{
this.controller.enableAdsBlock(true);
})
}
}
}
addAdsBlockAllowedList12+
static addAdsBlockAllowedList(domainSuffixes: Array<string>): void
向AdsBlockManager的AllowedList中添加一组域名，主要用于重新开启DisallowList中的部分网站的广告过滤。
说明：
此接口设置的域名不会持久化，应用重启需要重新设置。
AllowedList的优先级比DisAllowList高，例如，DisallowList中配置了['example.com']，禁用了所有example.com域名下的网页，此时如果需要开启'news.example.com'下的广告过滤，可以使用addAdsBlockAllowedList(['news.example.com'])。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| domainSuffixes | Array<string> | 是 | 一组域名列表，例如['example.com', 'abcd.efg.com'] |
错误码：
说明：
从API version 18开始，在不支持广告过滤功能的设备上调用该API会抛出801异常。
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
// 演示通过一个按钮的点击向Web组件设置广告过滤的域名策略
@Entry
@Component
struct WebComponent {
main_url: string = 'https://www.example.com';
text_input_controller: TextInputController = new TextInputController();
controller: webview.WebviewController = new webview.WebviewController();
@State input_text: string = 'https://www.example.com';
build() {
Column() {
Row() {
Flex() {
TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller})
.id("input_url")
.height(40)
.margin(5)
.borderColor(Color.Blue)
.onChange((value: string) => {
this.input_text = value;
})
Button({type: ButtonType.Capsule}) { Text("Go") }
.onClick(() => {
this.controller.loadUrl(this.input_text);
})
Button({type: ButtonType.Capsule}) { Text("addAdsBlockAllowedList") }
.onClick(() => {
let arrDisallowDomainSuffixes = new Array<string>();
arrDisallowDomainSuffixes.push('example.com');
webview.AdsBlockManager.addAdsBlockDisallowedList(arrDisallowDomainSuffixes);
let arrAllowedDomainSuffixes = new Array<string>();
arrAllowedDomainSuffixes.push('news.example.com');
webview.AdsBlockManager.addAdsBlockAllowedList(arrAllowedDomainSuffixes);
})
}
}
Web({ src: this.main_url, controller: this.controller })
.onControllerAttached(()=>{
this.controller.enableAdsBlock(true)
})
}
}
}
removeAdsBlockAllowedList12+
static removeAdsBlockAllowedList(domainSuffixes: Array<string>): void
从AdsBlockManager的AllowedList中删除一组域名。
说明：
AdsBlockManager的AllowedList不会持久化，应用重启需要重新设置。删除不存在的条目不会触发异常。
系统能力： SystemCapability.Web.Webview.Core
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| domainSuffixes | Array<string> | 是 | 一组域名列表，例如['example.com', 'abcd.efg.com'] |
错误码：
说明：
从API version 18开始，在不支持广告过滤功能的设备上调用该API会抛出801异常。
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
// 演示通过一个按钮的点击从AdsBlockManager的DisallowedList中删除域名元素
@Entry
@Component
struct WebComponent {
main_url: string = 'https://www.example.com';
text_input_controller: TextInputController = new TextInputController();
controller: webview.WebviewController = new webview.WebviewController();
@State input_text: string = 'https://www.example.com';
build() {
Column() {
Row() {
Flex() {
TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller})
.id("input_url")
.height(40)
.margin(5)
.borderColor(Color.Blue)
.onChange((value: string) => {
this.input_text = value;
})
Button({type: ButtonType.Capsule}) { Text("Go") }
.onClick(() => {
this.controller.loadUrl(this.input_text);
})
Button({type: ButtonType.Capsule}) { Text("removeAdsBlockAllowedList") }
.onClick(() => {
let arrDomainSuffixes = new Array<string>();
arrDomainSuffixes.push('example.com');
arrDomainSuffixes.push('abcdefg.cn');
webview.AdsBlockManager.removeAdsBlockAllowedList(arrDomainSuffixes);
})
}
}
Web({ src: this.main_url, controller: this.controller })
.onControllerAttached(()=>{
this.controller.enableAdsBlock(true);
})
}
}
}
clearAdsBlockAllowedList12+
static clearAdsBlockAllowedList(): void
清空AdsBlockManager的AllowedList。
系统能力： SystemCapability.Web.Webview.Core
错误码：
说明：
从API version 18开始，在不支持广告过滤功能的设备上调用该API会抛出801异常。
以下错误码的详细介绍请参见webview错误码。
| 错误码ID | 错误信息 |
|---|---|
| 801 | Capability not supported. |
示例：
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
main_url: string = 'https://www.example.com';
text_input_controller: TextInputController = new TextInputController();
controller: webview.WebviewController = new webview.WebviewController();
@State input_text: string = 'https://www.example.com';
build() {
Column() {
Row() {
Flex() {
TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller})
.id("input_url")
.height(40)
.margin(5)
.borderColor(Color.Blue)
.onChange((value: string) => {
this.input_text = value;
})
Button({type: ButtonType.Capsule}) { Text("Go") }
.onClick(() => {
this.controller.loadUrl(this.input_text);
})
Button({type: ButtonType.Capsule}) { Text("clearAdsBlockAllowedList") }
.onClick(() => {
webview.AdsBlockManager.clearAdsBlockAllowedList();
})
}
}
Web({ src: this.main_url, controller: this.controller })
.onControllerAttached(()=>{
this.controller.enableAdsBlock(true);
})
}
}
}
PdfData14+
createPdf函数输出数据流类。
说明：
在网页生成PDF过程中，返回的是数据流，由PdfData类封装。
pdfArrayBuffer14+
pdfArrayBuffer(): Uint8Array
获取网页生成的数据流。完整示例代码参考createPdf。
系统能力： SystemCapability.Web.Webview.Core
返回值：
| 类型 | 说明 |
|---|---|
| Uint8Array | 数据流。 |