1# @ohos.web.webview (Webview) 2 3@ohos.web.webview提供web控制能力，[Web](ts-basic-components-web.md)组件提供网页显示的能力。 4 5> **说明：** 6> 7> - 本模块接口从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> - 示例效果请以真机运行为准，当前IDE预览器不支持。 10 11## 需要权限 12 13访问在线网页时需添加网络权限：ohos.permission.INTERNET，具体申请方式请参考[声明权限](../../security/AccessToken/declare-permissions.md)。 14 15## 导入模块 16 17```ts 18import { webview } from '@kit.ArkWeb'; 19``` 20 21## webview.once 22 23once(type: string, callback: Callback\<void\>): void 24 25订阅一次指定类型Web事件的回调，Web事件的类型目前仅支持"webInited"，在Web引擎初始化完成时触发。 26 27当应用中开始加载第一个Web组件时，Web引擎初始化，且后续再在同一应用中继续加载其他Web组件时不会再触发once接口。当应用销毁最后一个Web组件时，若再加载第一个Web组件，应用重新进入Web引擎初始化流程。 28 29**系统能力：** SystemCapability.Web.Webview.Core 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| ------- | ---------------- | ---- | -------------------- | 35| type | string | 是 | Web事件的类型，目前支持："webInited"（Web初始化完成）。 | 36| callback | Callback\<void\> | 是 | 所订阅的回调函数。 | 37 38**错误码：** 39 40以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 41 42| 错误码ID | 错误信息 | 43| -------- | ----------------------- | 44| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 45 46**示例：** 47 48```ts 49// xxx.ets 50import { webview } from '@kit.ArkWeb'; 51 52webview.once("webInited", () => { 53 console.log("configCookieSync"); 54 webview.WebCookieManager.configCookieSync("https://www.example.com", "a=b"); 55}) 56 57@Entry 58@Component 59struct WebComponent { 60 controller: webview.WebviewController = new webview.WebviewController(); 61 62 build() { 63 Column() { 64 Web({ src: 'www.example.com', controller: this.controller }) 65 } 66 } 67} 68``` 69 70## WebMessagePort 71 72通过WebMessagePort可以进行消息的发送以及接收，发送[WebMessageType](#webmessagetype10)/[WebMessage](#webmessage)类型消息给HTML5侧。 73 74### 属性 75 76**系统能力：** SystemCapability.Web.Webview.Core 77 78| 名称 | 类型 | 可读 | 可写 | 说明 | 79| ------------ | ------ | ---- | ---- | ------------------------------------------------| 80| isExtentionType<sup>10+</sup> | boolean | 是 | 是 | 创建WebMessagePort时是否指定使用扩展增强接口，[postMessageEventExt](#postmessageeventext10)、[onMessageEventExt](#onmessageeventext10)，默认false不使用。 | 81 82### postMessageEvent 83 84postMessageEvent(message: WebMessage): void 85 86发送[WebMessage](#webmessage)类型消息给HTML5侧，必须先调用[onMessageEvent](#onmessageevent)，否则会发送失败。完整示例代码参考[postMessage](#postmessage)。 87 88**系统能力：** SystemCapability.Web.Webview.Core 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| ------- | ------ | ---- | :------------- | 94| message | [WebMessage](#webmessage) | 是 | 要发送的消息。 | 95 96**错误码：** 97 98以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 99 100| 错误码ID | 错误信息 | 101| -------- | ------------------------------------- | 102| 17100010 | Failed to post messages through the port. | 103| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 104 105**示例：** 106 107```ts 108// xxx.ets 109import { webview } from '@kit.ArkWeb'; 110import { BusinessError } from '@kit.BasicServicesKit'; 111 112@Entry 113@Component 114struct WebComponent { 115 controller: webview.WebviewController = new webview.WebviewController(); 116 ports: webview.WebMessagePort[] = []; 117 118 build() { 119 Column() { 120 Button('postMessageEvent') 121 .onClick(() => { 122 try { 123 this.ports = this.controller.createWebMessagePorts(); 124 this.controller.postMessage('__init_port__', [this.ports[0]], '*'); 125 this.ports[1].postMessageEvent("post message from ets to html5"); 126 } catch (error) { 127 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 128 } 129 }) 130 Web({ src: 'www.example.com', controller: this.controller }) 131 } 132 } 133} 134``` 135 136### onMessageEvent 137 138onMessageEvent(callback: (result: WebMessage) => void): void 139 140在应用侧的消息端口上注册回调函数，接收HTML5侧发送过来的[WebMessage](#webmessage)类型消息。完整示例代码参考[postMessage](#postmessage)。 141 142**系统能力：** SystemCapability.Web.Webview.Core 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 说明 | 147| -------- | -------- | ---- | :------------------- | 148| callback | (result: [WebMessage](#webmessage)) => void | 是 | 接收到的消息。 | 149 150**错误码：** 151 152以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 153 154| 错误码ID | 错误信息 | 155| -------- | ----------------------------------------------- | 156| 17100006 | Failed to register a message event for the port.| 157| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.| 158 159**示例：** 160 161```ts 162// xxx.ets 163import { webview } from '@kit.ArkWeb'; 164import { BusinessError } from '@kit.BasicServicesKit'; 165 166@Entry 167@Component 168struct WebComponent { 169 controller: webview.WebviewController = new webview.WebviewController(); 170 ports: webview.WebMessagePort[] = []; 171 172 build() { 173 Column() { 174 Button('onMessageEvent') 175 .onClick(() => { 176 try { 177 this.ports = this.controller.createWebMessagePorts(); 178 this.ports[1].onMessageEvent((msg) => { 179 if (typeof (msg) == "string") { 180 console.log("received string message from html5, string is:" + msg); 181 } else if (typeof (msg) == "object") { 182 if (msg instanceof ArrayBuffer) { 183 console.log("received arraybuffer from html5, length is:" + msg.byteLength); 184 } else { 185 console.log("not support"); 186 } 187 } else { 188 console.log("not support"); 189 } 190 }) 191 } catch (error) { 192 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 193 } 194 }) 195 Web({ src: 'www.example.com', controller: this.controller }) 196 } 197 } 198} 199``` 200 201### postMessageEventExt<sup>10+</sup> 202 203postMessageEventExt(message: WebMessageExt): void 204 205发送[WebMessageType](#webmessagetype10)类型消息给HTML5侧，必须先调用[onMessageEventExt](#onmessageeventext10)，否则会发送失败。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 206 207**系统能力：** SystemCapability.Web.Webview.Core 208 209**参数：** 210 211| 参数名 | 类型 | 必填 | 说明 | 212| ------- | ------ | ---- | :------------- | 213| message | [WebMessageExt](#webmessageext10) | 是 | 要发送的消息。 | 214 215**错误码：** 216 217以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 218 219| 错误码ID | 错误信息 | 220| -------- | ------------------------------------- | 221| 17100010 | Failed to post messages through the port. | 222| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 223 224### onMessageEventExt<sup>10+</sup> 225 226onMessageEventExt(callback: (result: WebMessageExt) => void): void 227 228在应用侧的消息端口上注册回调函数，接收HTML5侧发送过来的[WebMessageType](#webmessagetype10)类型消息。 229 230**系统能力：** SystemCapability.Web.Webview.Core 231 232**参数：** 233 234| 参数名 | 类型 | 必填 | 说明 | 235| -------- | -------- | ---- | :------------------- | 236| callback | (result: [WebMessageExt](#webmessageext10)) => void | 是 | 接收到的消息。 | 237 238**错误码：** 239 240以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 241 242| 错误码ID | 错误信息 | 243| -------- | ----------------------------------------------- | 244| 17100006 | Failed to register a message event for the port. | 245| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 246 247**示例：** 248 249```ts 250// xxx.ets 251import { webview } from '@kit.ArkWeb'; 252import { BusinessError } from '@kit.BasicServicesKit'; 253 254class TestObj { 255 test(str: string): ArrayBuffer { 256 let buf = new ArrayBuffer(str.length); 257 let buff = new Uint8Array(buf); 258 259 for (let i = 0; i < str.length; i++) { 260 buff[i] = str.charCodeAt(i); 261 } 262 return buf; 263 } 264} 265 266// 应用与网页互发消息的示例：使用"init_web_messageport"的通道，通过端口0在应用侧接受网页发送的消息，通过端口1在网页侧接受应用发送的消息。 267@Entry 268@Component 269struct WebComponent { 270 controller: webview.WebviewController = new webview.WebviewController(); 271 ports: webview.WebMessagePort[] = []; 272 nativePort: webview.WebMessagePort | null = null; 273 @State msg1: string = ""; 274 @State msg2: string = ""; 275 message: webview.WebMessageExt = new webview.WebMessageExt(); 276 @State testObjtest: TestObj = new TestObj(); 277 278 build() { 279 Column() { 280 Text(this.msg1).fontSize(16) 281 Text(this.msg2).fontSize(16) 282 Button('SendToH5 setString').margin({ 283 right: 800, 284 }) 285 .onClick(() => { 286 // 使用本侧端口发送消息给HTML5 287 try { 288 console.log("In ArkTS side send true start"); 289 if (this.nativePort) { 290 this.message.setType(1); 291 this.message.setString("helloFromEts"); 292 this.nativePort.postMessageEventExt(this.message); 293 } 294 } 295 catch (error) { 296 console.error(`In ArkTS side send message catch error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 297 } 298 }) 299 Button('SendToH5 setNumber').margin({ 300 top: 10, 301 right: 800, 302 }) 303 .onClick(() => { 304 // 使用本侧端口发送消息给HTML5 305 try { 306 console.log("In ArkTS side send true start"); 307 if (this.nativePort) { 308 this.message.setType(2); 309 this.message.setNumber(12345); 310 this.nativePort.postMessageEventExt(this.message); 311 } 312 } 313 catch (error) { 314 console.error(`In ArkTS side send message catch error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 315 } 316 }) 317 Button('SendToH5 setBoolean').margin({ 318 top: -90, 319 }) 320 .onClick(() => { 321 // 使用本侧端口发送消息给HTML5 322 try { 323 console.log("In ArkTS side send true start"); 324 if (this.nativePort) { 325 this.message.setType(3); 326 this.message.setBoolean(true); 327 this.nativePort.postMessageEventExt(this.message); 328 } 329 } 330 catch (error) { 331 console.error(`In ArkTS side send message catch error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 332 } 333 }) 334 Button('SendToH5 setArrayBuffer').margin({ 335 top: 10, 336 }) 337 .onClick(() => { 338 // 使用本侧端口发送消息给HTML5 339 try { 340 console.log("In ArkTS side send true start"); 341 if (this.nativePort) { 342 this.message.setType(4); 343 this.message.setArrayBuffer(this.testObjtest.test("Name=test&Password=test")); 344 this.nativePort.postMessageEventExt(this.message); 345 } 346 } 347 catch (error) { 348 console.error(`In ArkTS side send message catch error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 349 } 350 }) 351 Button('SendToH5 setArray').margin({ 352 top: -90, 353 left: 800, 354 }) 355 .onClick(() => { 356 // 使用本侧端口发送消息给HTML5 357 try { 358 console.log("In ArkTS side send true start"); 359 if (this.nativePort) { 360 this.message.setType(5); 361 this.message.setArray([1, 2, 3]); 362 this.nativePort.postMessageEventExt(this.message); 363 } 364 } 365 catch (error) { 366 console.error(`In ArkTS side send message catch error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 367 } 368 }) 369 Button('SendToH5 setError').margin({ 370 top: 10, 371 left: 800, 372 }) 373 .onClick(() => { 374 // 使用本侧端口发送消息给HTML5 375 try { 376 console.log("In ArkTS side send true start"); 377 throw new ReferenceError("ReferenceError"); 378 } 379 catch (error) { 380 if (this.nativePort) { 381 this.message.setType(6); 382 this.message.setError(error); 383 this.nativePort.postMessageEventExt(this.message); 384 } 385 console.error(`In ArkTS side send message catch error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 386 } 387 }) 388 389 Web({ src: $rawfile('index.html'), controller: this.controller }) 390 .onPageEnd(() => { 391 console.log("In ArkTS side message onPageEnd init message channel"); 392 // 1. 创建消息端口 393 this.ports = this.controller.createWebMessagePorts(true); 394 // 2. 发送端口1到HTML5 395 this.controller.postMessage("init_web_messageport", [this.ports[1]], "*"); 396 // 3. 保存端口0到本地 397 this.nativePort = this.ports[0]; 398 // 4. 设置回调函数 399 this.nativePort.onMessageEventExt((result) => { 400 console.log("In ArkTS side got message"); 401 try { 402 let type = result.getType(); 403 console.log("In ArkTS side getType:" + type); 404 switch (type) { 405 case webview.WebMessageType.STRING: { 406 this.msg1 = "result type:" + typeof (result.getString()); 407 this.msg2 = "result getString:" + ((result.getString())); 408 break; 409 } 410 case webview.WebMessageType.NUMBER: { 411 this.msg1 = "result type:" + typeof (result.getNumber()); 412 this.msg2 = "result getNumber:" + ((result.getNumber())); 413 break; 414 } 415 case webview.WebMessageType.BOOLEAN: { 416 this.msg1 = "result type:" + typeof (result.getBoolean()); 417 this.msg2 = "result getBoolean:" + ((result.getBoolean())); 418 break; 419 } 420 case webview.WebMessageType.ARRAY_BUFFER: { 421 this.msg1 = "result type:" + typeof (result.getArrayBuffer()); 422 this.msg2 = "result getArrayBuffer byteLength:" + ((result.getArrayBuffer().byteLength)); 423 break; 424 } 425 case webview.WebMessageType.ARRAY: { 426 this.msg1 = "result type:" + typeof (result.getArray()); 427 this.msg2 = "result getArray:" + result.getArray(); 428 break; 429 } 430 case webview.WebMessageType.ERROR: { 431 this.msg1 = "result type:" + typeof (result.getError()); 432 this.msg2 = "result getError:" + result.getError(); 433 break; 434 } 435 default: { 436 this.msg1 = "default break, type:" + type; 437 break; 438 } 439 } 440 } 441 catch (error) { 442 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 443 } 444 }); 445 }) 446 } 447 } 448} 449``` 450 451加载的html文件。 452```html 453<!--index.html--> 454<!DOCTYPE html> 455<html lang="en-gb"> 456<head> 457 <title>WebView MessagePort Demo</title> 458</head> 459 460<body> 461<h1>Html5 Send and Receive Message</h1> 462<h3 id="msg">Receive string:</h3> 463<h3 id="msg2">Receive arraybuffer:</h3> 464<div style="font-size: 10pt; text-align: center;"> 465 <input type="button" value="Send String" onclick="postStringToApp();" /><br/> 466</div> 467</body> 468<script src="index.js"></script> 469</html> 470``` 471 472```js 473//index.js 474var h5Port; 475window.addEventListener('message', function(event) { 476 if (event.data == 'init_web_messageport') { 477 if(event.ports[0] != null) { 478 h5Port = event.ports[0]; // 1. 保存从ets侧发送过来的端口 479 h5Port.onmessage = function(event) { 480 console.log("hwd In html got message"); 481 // 2. 接收ets侧发送过来的消息. 482 var result = event.data; 483 console.log("In html got message, typeof: ", typeof(result)); 484 console.log("In html got message, result: ", (result)); 485 if (typeof(result) == "string") { 486 console.log("In html got message, String: ", result); 487 document.getElementById("msg").innerHTML = "String:" + result; 488 } else if (typeof(result) == "number") { 489 console.log("In html side got message, number: ", result); 490 document.getElementById("msg").innerHTML = "Number:" + result; 491 } else if (typeof(result) == "boolean") { 492 console.log("In html side got message, boolean: ", result); 493 document.getElementById("msg").innerHTML = "Boolean:" + result; 494 } else if (typeof(result) == "object") { 495 if (result instanceof ArrayBuffer) { 496 document.getElementById("msg2").innerHTML = "ArrayBuffer:" + result.byteLength; 497 console.log("In html got message, byteLength: ", result.byteLength); 498 } else if (result instanceof Error) { 499 console.log("In html error message, err:" + (result)); 500 console.log("In html error message, typeof err:" + typeof(result)); 501 document.getElementById("msg2").innerHTML = "Error:" + result.name + ", msg:" + result.message; 502 } else if (result instanceof Array) { 503 console.log("In html got message, Array"); 504 console.log("In html got message, Array length:" + result.length); 505 console.log("In html got message, Array[0]:" + (result[0])); 506 console.log("In html got message, typeof Array[0]:" + typeof(result[0])); 507 document.getElementById("msg2").innerHTML = "Array len:" + result.length + ", value:" + result; 508 } else { 509 console.log("In html got message, not any instance of support type"); 510 document.getElementById("msg").innerHTML = "not any instance of support type"; 511 } 512 } else { 513 console.log("In html got message, not support type"); 514 document.getElementById("msg").innerHTML = "not support type"; 515 } 516 } 517 h5Port.onmessageerror = (event) => { 518 console.error(`hwd In html Error receiving message: ${event}`); 519 }; 520 } 521 } 522}) 523 524// 使用h5Port往ets侧发送String类型的消息. 525function postStringToApp() { 526 if (h5Port) { 527 console.log("In html send string message"); 528 h5Port.postMessage("hello"); 529 console.log("In html send string message end"); 530 } else { 531 console.error("In html h5port is null, please init first"); 532 } 533} 534``` 535 536### close 537 538close(): void 539 540不需要发送消息时关闭该消息端口。在使用close前，请先使用[createWebMessagePorts](#createwebmessageports)创建消息端口。 541 542**系统能力：** SystemCapability.Web.Webview.Core 543 544**示例：** 545 546```ts 547// xxx.ets 548import { webview } from '@kit.ArkWeb'; 549import { BusinessError } from '@kit.BasicServicesKit'; 550 551@Entry 552@Component 553struct WebComponent { 554 controller: webview.WebviewController = new webview.WebviewController(); 555 msgPort: webview.WebMessagePort[] = []; 556 557 build() { 558 Column() { 559 // 先使用createWebMessagePorts创建端口。 560 Button('createWebMessagePorts') 561 .onClick(() => { 562 try { 563 this.msgPort = this.controller.createWebMessagePorts(); 564 console.log("createWebMessagePorts size:" + this.msgPort.length) 565 } catch (error) { 566 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 567 } 568 }) 569 Button('close') 570 .onClick(() => { 571 try { 572 if (this.msgPort && this.msgPort.length == 2) { 573 this.msgPort[1].close(); 574 } else { 575 console.error("msgPort is null, Please initialize first"); 576 } 577 } catch (error) { 578 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 579 } 580 }) 581 Web({ src: 'www.example.com', controller: this.controller }) 582 } 583 } 584} 585``` 586 587## WebviewController 588 589通过WebviewController可以控制Web组件各种行为。一个WebviewController对象只能控制一个Web组件，且必须在Web组件和WebviewController绑定后，才能调用WebviewController上的方法（静态方法除外）。 590 591### constructor<sup>11+</sup> 592 593constructor(webTag?: string) 594 595用于创建 WebviewController 对象的构造函数。 596 597> **说明：** 598> 599> 不传参：new webview.WebviewController()表示构造函数为空，不使用C API时不需要传参。 600> 601> 传参且参数是合法字符串：new webview.WebviewController("xxx")，用于开发者区分多实例，并调用对应实例下的方法。 602> 603> 传入参数为空：new webview.WebviewController("")或new webview.WebviewController(undefined)，该场景下参数无意义，无法区分多个实例，直接返回undefined，需要开发者判断返回值是否正常。 604 605**系统能力：** SystemCapability.Web.Webview.Core 606 607**参数：** 608 609| 参数名 | 类型 | 必填 | 说明 | 610| ---------- | ------ | ---- | -------------------------------- | 611| webTag | string | 否 | 指定了 Web 组件的名称。 | 612 613**示例：** 614 615```ts 616// xxx.ets 617import { webview } from '@kit.ArkWeb'; 618import { BusinessError } from '@kit.BasicServicesKit'; 619 620class WebObj { 621 constructor() { 622 } 623 624 webTest(): string { 625 console.log('Web test'); 626 return "Web test"; 627 } 628 629 webString(): void { 630 console.log('Web test toString'); 631 } 632} 633 634@Entry 635@Component 636struct WebComponent { 637 controller: webview.WebviewController = new webview.WebviewController() 638 @State webTestObj: WebObj = new WebObj(); 639 640 build() { 641 Column() { 642 Button('refresh') 643 .onClick(() => { 644 try { 645 this.controller.refresh(); 646 } catch (error) { 647 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 648 } 649 }) 650 Button('deleteJavaScriptRegister') 651 .onClick(() => { 652 try { 653 this.controller.deleteJavaScriptRegister("objTestName"); 654 } catch (error) { 655 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 656 } 657 }) 658 Web({ src: '', controller: this.controller }) 659 .javaScriptAccess(true) 660 .onControllerAttached(() => { 661 this.controller.loadUrl($rawfile("index.html")); 662 this.controller.registerJavaScriptProxy(this.webTestObj, "objTestName", ["webTest", "webString"]); 663 }) 664 } 665 } 666} 667``` 668 669加载的html文件。 670```html 671<!-- index.html --> 672<!DOCTYPE html> 673<html> 674 <meta charset="utf-8"> 675 <body> 676 <button type="button" onclick="htmlTest()">Click Me!</button> 677 <p id="demo"></p> 678 <p id="webDemo"></p> 679 </body> 680 <script type="text/javascript"> 681 function htmlTest() { 682 // This function call expects to return "Web test" 683 let webStr = objTestName.webTest(); 684 document.getElementById("webDemo").innerHTML=webStr; 685 console.log('objTestName.webTest result:'+ webStr) 686 } 687</script> 688</html> 689``` 690 691### initializeWebEngine 692 693static initializeWebEngine(): void 694 695在 Web 组件初始化之前，通过此接口加载 Web 引擎的动态库文件，以提高启动性能。自动预连接历史访问过的高频网站。 696 697> **说明：** 698> 699> - initializeWebEngine不支持在异步线程中调用，否则会造成崩溃。 700> - initializeWebEngine全局生效，在整个APP生命周期中调用一次即可，不需要重复调用。 701 702**系统能力：** SystemCapability.Web.Webview.Core 703 704**示例：** 705 706本示例以EntryAbility为例，描述了在 Ability 创建阶段完成 Web 组件动态库加载的功能。 707 708```ts 709// xxx.ets 710import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 711import { webview } from '@kit.ArkWeb'; 712 713export default class EntryAbility extends UIAbility { 714 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 715 console.log("EntryAbility onCreate") 716 webview.WebviewController.initializeWebEngine() 717 console.log("EntryAbility onCreate done") 718 } 719} 720``` 721 722### setHttpDns<sup>10+</sup> 723 724static setHttpDns(secureDnsMode:SecureDnsMode, secureDnsConfig:string): void 725 726设置Web组件是否使用HTTPDNS解析dns。 727 728**系统能力：** SystemCapability.Web.Webview.Core 729 730**参数：** 731 732| 参数名 | 类型 | 必填 | 说明 | 733| ------------------ | ------- | ---- | ------------- | 734| secureDnsMode | [SecureDnsMode](#securednsmode10) | 是 | 使用HTTPDNS的模式。| 735| secureDnsConfig | string | 是 | HTTPDNS server的配置，必须是https协议并且只允许配置一个server。 | 736 737**错误码：** 738 739以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 740 741| 错误码ID | 错误信息 | 742| -------- | ----------------------- | 743| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 744 745**示例：** 746 747```ts 748// xxx.ets 749import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 750import { webview } from '@kit.ArkWeb'; 751import { BusinessError } from '@kit.BasicServicesKit'; 752 753export default class EntryAbility extends UIAbility { 754 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 755 console.log("EntryAbility onCreate") 756 try { 757 webview.WebviewController.setHttpDns(webview.SecureDnsMode.AUTO, "https://example1.test") 758 } catch (error) { 759 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 760 } 761 762 AppStorage.setOrCreate("abilityWant", want); 763 console.log("EntryAbility onCreate done") 764 } 765} 766``` 767 768### setWebDebuggingAccess 769 770static setWebDebuggingAccess(webDebuggingAccess: boolean): void 771 772设置是否启用网页调试功能，默认不开启。详情请参考[DevTools工具](../../web/web-debugging-with-devtools.md)。 773 774安全提示：启用网页调试功能可以让用户检查修改Web页面内部状态，存在安全隐患，不建议在应用正式发布版本中启用。 775 776**系统能力：** SystemCapability.Web.Webview.Core 777 778**参数：** 779 780| 参数名 | 类型 | 必填 | 说明 | 781| ------------------ | ------- | ---- | ------------- | 782| webDebuggingAccess | boolean | 是 | 设置是否启用网页调试功能。| 783 784**错误码：** 785 786以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 787 788| 错误码ID | 错误信息 | 789| -------- | ------------------------------------------------------------ | 790| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 791 792**示例：** 793 794```ts 795// xxx.ets 796import { webview } from '@kit.ArkWeb'; 797import { BusinessError } from '@kit.BasicServicesKit'; 798 799@Entry 800@Component 801struct WebComponent { 802 controller: webview.WebviewController = new webview.WebviewController(); 803 804 aboutToAppear(): void { 805 try { 806 webview.WebviewController.setWebDebuggingAccess(true); 807 } catch (error) { 808 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 809 } 810 } 811 812 build() { 813 Column() { 814 Web({ src: 'www.example.com', controller: this.controller }) 815 } 816 } 817} 818``` 819 820### loadUrl 821 822loadUrl(url: string | Resource, headers?: Array\<WebHeader>): void 823 824加载指定的URL。 825 826**系统能力：** SystemCapability.Web.Webview.Core 827 828**参数：** 829 830| 参数名 | 类型 | 必填 | 说明 | 831| ------- | ---------------- | ---- | :-------------------- | 832| url | string \| Resource | 是 | 需要加载的 URL。 | 833| headers | Array\<[WebHeader](#webheader)> | 否 | URL的附加HTTP请求头。 | 834 835**错误码：** 836 837以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 838 839| 错误码ID | 错误信息 | 840| -------- | ------------------------------------------------------------ | 841| 17100001 | Init error. The WebviewController must be associated with a Web component. | 842| 17100002 | Invalid url. | 843| 17100003 | Invalid resource path or file type. | 844| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 845 846**示例：** 847 848```ts 849// xxx.ets 850import { webview } from '@kit.ArkWeb'; 851import { BusinessError } from '@kit.BasicServicesKit'; 852 853@Entry 854@Component 855struct WebComponent { 856 controller: webview.WebviewController = new webview.WebviewController(); 857 858 build() { 859 Column() { 860 Button('loadUrl') 861 .onClick(() => { 862 try { 863 // 需要加载的URL是string类型。 864 this.controller.loadUrl('www.example.com'); 865 } catch (error) { 866 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 867 } 868 }) 869 Web({ src: 'www.example.com', controller: this.controller }) 870 } 871 } 872} 873``` 874 875```ts 876// xxx.ets 877import { webview } from '@kit.ArkWeb'; 878import { BusinessError } from '@kit.BasicServicesKit'; 879 880@Entry 881@Component 882struct WebComponent { 883 controller: webview.WebviewController = new webview.WebviewController(); 884 885 build() { 886 Column() { 887 Button('loadUrl') 888 .onClick(() => { 889 try { 890 // 带参数headers。 891 this.controller.loadUrl('www.example.com', [{ headerKey: "headerKey", headerValue: "headerValue" }]); 892 } catch (error) { 893 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 894 } 895 }) 896 Web({ src: 'www.example.com', controller: this.controller }) 897 } 898 } 899} 900``` 901 902加载本地网页，加载本地资源文件有三种方式。 903 9041.$rawfile方式。 905```ts 906// xxx.ets 907import { webview } from '@kit.ArkWeb'; 908import { BusinessError } from '@kit.BasicServicesKit'; 909 910@Entry 911@Component 912struct WebComponent { 913 controller: webview.WebviewController = new webview.WebviewController(); 914 915 build() { 916 Column() { 917 Button('loadUrl') 918 .onClick(() => { 919 try { 920 // 通过$rawfile加载本地资源文件。 921 this.controller.loadUrl($rawfile('index.html')); 922 } catch (error) { 923 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 924 } 925 }) 926 Web({ src: 'www.example.com', controller: this.controller }) 927 } 928 } 929} 930``` 931 9322.resources协议，适用Webview加载带有"#"路由的链接。 933```ts 934// xxx.ets 935import { webview } from '@kit.ArkWeb'; 936import { BusinessError } from '@kit.BasicServicesKit'; 937 938@Entry 939@Component 940struct WebComponent { 941 controller: webview.WebviewController = new webview.WebviewController(); 942 943 build() { 944 Column() { 945 Button('loadUrl') 946 .onClick(() => { 947 try { 948 // 通过resource协议加载本地资源文件。 949 this.controller.loadUrl("resource://rawfile/index.html"); 950 } catch (error) { 951 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 952 } 953 }) 954 Web({ src: 'www.example.com', controller: this.controller }) 955 } 956 } 957} 958``` 959 9603.通过沙箱路径加载本地文件，可以参考[web](ts-basic-components-web.md#web)加载沙箱路径的示例代码。 961 962加载的html文件。 963```html 964<!-- index.html --> 965<!DOCTYPE html> 966<html> 967 <body> 968 <p>Hello World</p> 969 </body> 970</html> 971``` 972 973### loadData 974 975loadData(data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string): void 976 977加载指定的数据。 978 979baseUrl与historyUrl同时为空的情况下： 980 981encoding如果为非base64（包括空值），则假定数据对安全URL字符范围内的八位字节使用ASCII编码，对该范围外的八位字节使用URL的标准%xx十六进制编码。 982 983data数据必须使用base64编码或将内容中的任何#字符编码为%23。否则#将被视为内容的结尾而剩余的文本将被用作文档片段标识符。 984 985**系统能力：** SystemCapability.Web.Webview.Core 986 987**参数：** 988 989| 参数名 | 类型 | 必填 | 说明 | 990| ---------- | ------ | ---- | ------------------------------------------------------------ | 991| data | string | 是 | 按照"base64"或者"URL"编码后的一段字符串。 | 992| mimeType | string | 是 | 媒体类型（MIME）。 | 993| encoding | string | 是 | 编码类型，具体为"base64"或者"URL"编码。 | 994| baseUrl | string | 否 | 指定的一个URL路径（"http"/"https"/"data"协议），并由Web组件赋值给window.origin。当加载大量html文件时，需设置为"data"。 | 995| historyUrl | string | 否 | 用作历史记录所使用的URL。非空时，历史记录以此URL进行管理。当baseUrl为空时，此属性无效。 | 996 997> **说明：** 998> 999> 若加载本地图片，可以给baseUrl或historyUrl任一参数赋值空格，详情请参考示例代码。 1000> 加载本地图片场景，baseUrl和historyUrl不能同时为空，否则图片无法成功加载。 1001> 若html中的富文本中带有注入#等特殊字符，建议将baseUrl和historyUrl两个参数的值设置为"空格"。 1002 1003**错误码：** 1004 1005以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1006 1007| 错误码ID | 错误信息 | 1008| -------- | ------------------------------------------------------------ | 1009| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1010| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1011 1012**示例：** 1013 1014baseUrl与historyUrl同时为空。 1015```ts 1016// xxx.ets 1017import { webview } from '@kit.ArkWeb'; 1018import { BusinessError } from '@kit.BasicServicesKit'; 1019 1020@Entry 1021@Component 1022struct WebComponent { 1023 controller: webview.WebviewController = new webview.WebviewController(); 1024 1025 build() { 1026 Column() { 1027 Button('loadData') 1028 .onClick(() => { 1029 try { 1030 this.controller.loadData( 1031 "<html><body bgcolor=\"white\">Source:<pre>source</pre></body></html>", 1032 "text/html", 1033 // UTF-8为charset。 1034 "UTF-8" 1035 ); 1036 } catch (error) { 1037 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1038 } 1039 }) 1040 Web({ src: 'www.example.com', controller: this.controller }) 1041 } 1042 } 1043} 1044``` 1045 1046```ts 1047// xxx.ets 1048import { webview } from '@kit.ArkWeb'; 1049import { BusinessError } from '@kit.BasicServicesKit'; 1050 1051@Entry 1052@Component 1053struct WebComponent { 1054 controller: webview.WebviewController = new webview.WebviewController(); 1055 1056 build() { 1057 Column() { 1058 Button('loadData') 1059 .onClick(() => { 1060 try { 1061 this.controller.loadData( 1062 // Coding tests通过base64编码后的字符串。 1063 "Q29kaW5nIHRlc3Rz", 1064 "text/html", 1065 "base64" 1066 ); 1067 } catch (error) { 1068 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1069 } 1070 }) 1071 Web({ src: 'www.example.com', controller: this.controller }) 1072 } 1073 } 1074} 1075``` 1076 1077加载本地资源 1078```ts 1079// xxx.ets 1080import { webview } from '@kit.ArkWeb'; 1081import { BusinessError } from '@kit.BasicServicesKit'; 1082 1083@Entry 1084@Component 1085struct WebComponent { 1086 controller: webview.WebviewController = new webview.WebviewController(); 1087 updataContent: string = '<body><div><image src=resource://rawfile/xxx.png alt="image -- end" width="500" height="250"></image></div></body>' 1088 1089 build() { 1090 Column() { 1091 Button('loadData') 1092 .onClick(() => { 1093 try { 1094 // UTF-8为charset。 1095 this.controller.loadData(this.updataContent, "text/html", "UTF-8", " ", " "); 1096 } catch (error) { 1097 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1098 } 1099 }) 1100 Web({ src: 'www.example.com', controller: this.controller }) 1101 } 1102 } 1103} 1104``` 1105 1106### accessForward 1107 1108accessForward(): boolean 1109 1110当前页面是否可前进，即当前页面是否有前进历史记录。 1111 1112可以结合使用[getBackForwardEntries](#getbackforwardentries)来获取当前WebView的历史信息列表，以及使用[accessStep](#accessstep)来判断是否可以按照给定的步数前进或后退。 1113 1114**系统能力：** SystemCapability.Web.Webview.Core 1115 1116**返回值：** 1117 1118| 类型 | 说明 | 1119| ------- | --------------------------------- | 1120| boolean | 可以前进返回true，否则返回false。 | 1121 1122**错误码：** 1123 1124以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1125 1126| 错误码ID | 错误信息 | 1127| -------- | ------------------------------------------------------------ | 1128| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1129 1130**示例：** 1131 1132```ts 1133// xxx.ets 1134import { webview } from '@kit.ArkWeb'; 1135import { BusinessError } from '@kit.BasicServicesKit'; 1136 1137@Entry 1138@Component 1139struct WebComponent { 1140 controller: webview.WebviewController = new webview.WebviewController(); 1141 1142 build() { 1143 Column() { 1144 Button('accessForward') 1145 .onClick(() => { 1146 try { 1147 let result = this.controller.accessForward(); 1148 console.log('result:' + result); 1149 } catch (error) { 1150 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1151 } 1152 }) 1153 Web({ src: 'www.example.com', controller: this.controller }) 1154 } 1155 } 1156} 1157``` 1158 1159### forward 1160 1161forward(): void 1162 1163按照历史栈，前进一个页面。一般结合accessForward一起使用。 1164 1165**系统能力：** SystemCapability.Web.Webview.Core 1166 1167**错误码：** 1168 1169以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1170 1171| 错误码ID | 错误信息 | 1172| -------- | ------------------------------------------------------------ | 1173| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1174 1175**示例：** 1176 1177```ts 1178// xxx.ets 1179import { webview } from '@kit.ArkWeb'; 1180import { BusinessError } from '@kit.BasicServicesKit'; 1181 1182@Entry 1183@Component 1184struct WebComponent { 1185 controller: webview.WebviewController = new webview.WebviewController(); 1186 1187 build() { 1188 Column() { 1189 Button('forward') 1190 .onClick(() => { 1191 try { 1192 this.controller.forward(); 1193 } catch (error) { 1194 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1195 } 1196 }) 1197 Web({ src: 'www.example.com', controller: this.controller }) 1198 } 1199 } 1200} 1201``` 1202 1203### accessBackward 1204 1205accessBackward(): boolean 1206 1207当前页面是否可后退，即当前页面是否有返回历史记录。 1208 1209可以结合使用[getBackForwardEntries](#getbackforwardentries)来获取当前WebView的历史信息列表，以及使用[accessStep](#accessstep)来判断是否可以按照给定的步数前进或后退。 1210 1211> **说明：** 1212> 1213> 在Web组件首次加载过程中调用[setCustomUserAgent](#setcustomuseragent10)，可能会导致在当前存在多个历史节点的情况下，获取的accessBackForward实际为false，即没有后退节点。建议先调用setCustomUserAgent方法设置UserAgent，再通过loadUrl加载具体页面。 1214> 1215> 该现象是由于在Web组件首次加载时，调用[setCustomUserAgent](#setcustomuseragent10)会导致组件重新加载并保持初始历史节点的状态。随后新增的节点将替换初始历史节点，不会生成新的历史节点，导致accessBackward为false。 1216 1217**系统能力：** SystemCapability.Web.Webview.Core 1218 1219**返回值：** 1220 1221| 类型 | 说明 | 1222| ------- | -------------------------------- | 1223| boolean | 可以后退返回true,否则返回false。 | 1224 1225**错误码：** 1226 1227以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1228 1229| 错误码ID | 错误信息 | 1230| -------- | ------------------------------------------------------------ | 1231| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1232 1233**示例：** 1234 1235```ts 1236// xxx.ets 1237import { webview } from '@kit.ArkWeb'; 1238import { BusinessError } from '@kit.BasicServicesKit'; 1239 1240@Entry 1241@Component 1242struct WebComponent { 1243 controller: webview.WebviewController = new webview.WebviewController(); 1244 1245 build() { 1246 Column() { 1247 Button('accessBackward') 1248 .onClick(() => { 1249 try { 1250 let result = this.controller.accessBackward(); 1251 console.log('result:' + result); 1252 } catch (error) { 1253 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1254 } 1255 }) 1256 Web({ src: 'www.example.com', controller: this.controller }) 1257 } 1258 } 1259} 1260``` 1261 1262### backward 1263 1264backward(): void 1265 1266按照历史栈，后退一个页面。一般结合accessBackward一起使用。 1267 1268**系统能力：** SystemCapability.Web.Webview.Core 1269 1270**错误码：** 1271 1272以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1273 1274| 错误码ID | 错误信息 | 1275| -------- | ------------------------------------------------------------ | 1276| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1277 1278**示例：** 1279 1280```ts 1281// xxx.ets 1282import { webview } from '@kit.ArkWeb'; 1283import { BusinessError } from '@kit.BasicServicesKit'; 1284 1285@Entry 1286@Component 1287struct WebComponent { 1288 controller: webview.WebviewController = new webview.WebviewController(); 1289 1290 build() { 1291 Column() { 1292 Button('backward') 1293 .onClick(() => { 1294 try { 1295 this.controller.backward(); 1296 } catch (error) { 1297 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1298 } 1299 }) 1300 Web({ src: 'www.example.com', controller: this.controller }) 1301 } 1302 } 1303} 1304``` 1305 1306### onActive 1307 1308onActive(): void 1309 1310调用此接口通知Web组件进入前台激活状态。 1311<br />激活状态是应用与用户互动的状态。应用会保持这种状态，直到发生某些事件（例如收到来电或设备屏幕关闭）时将焦点从应用移开。 1312 1313**系统能力：** SystemCapability.Web.Webview.Core 1314 1315**错误码：** 1316 1317以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1318 1319| 错误码ID | 错误信息 | 1320| -------- | ------------------------------------------------------------ | 1321| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1322 1323**示例：** 1324 1325```ts 1326// xxx.ets 1327import { webview } from '@kit.ArkWeb'; 1328import { BusinessError } from '@kit.BasicServicesKit'; 1329 1330@Entry 1331@Component 1332struct WebComponent { 1333 controller: webview.WebviewController = new webview.WebviewController(); 1334 1335 build() { 1336 Column() { 1337 Button('onActive') 1338 .onClick(() => { 1339 try { 1340 this.controller.onActive(); 1341 } catch (error) { 1342 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1343 } 1344 }) 1345 Web({ src: 'www.example.com', controller: this.controller }) 1346 } 1347 } 1348} 1349``` 1350 1351### onInactive 1352 1353onInactive(): void 1354 1355调用此接口通知Web组件进入未激活状态。开发者可以在此回调中实现应用失去焦点时应表现的恰当行为。 1356 1357此状态下会尽可能的暂停任何可以安全暂停的内容，例如动画和地理位置。但不会暂停JavaScript，要全局暂停JavaScript，请使用[pauseAllTimers](#pausealltimers12)。要重新激活Web组件，请调用[onActive](#onactive)。 1358 1359**系统能力：** SystemCapability.Web.Webview.Core 1360 1361**错误码：** 1362 1363以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1364 1365| 错误码ID | 错误信息 | 1366| -------- | ------------------------------------------------------------ | 1367| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1368 1369**示例：** 1370 1371```ts 1372// xxx.ets 1373import { webview } from '@kit.ArkWeb'; 1374import { BusinessError } from '@kit.BasicServicesKit'; 1375 1376@Entry 1377@Component 1378struct WebComponent { 1379 controller: webview.WebviewController = new webview.WebviewController(); 1380 1381 build() { 1382 Column() { 1383 Button('onInactive') 1384 .onClick(() => { 1385 try { 1386 this.controller.onInactive(); 1387 } catch (error) { 1388 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1389 } 1390 }) 1391 Web({ src: 'www.example.com', controller: this.controller }) 1392 } 1393 } 1394} 1395``` 1396 1397### refresh 1398refresh(): void 1399 1400调用此接口通知Web组件刷新网页。 1401 1402**系统能力：** SystemCapability.Web.Webview.Core 1403 1404**错误码：** 1405 1406以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1407 1408| 错误码ID | 错误信息 | 1409| -------- | ------------------------------------------------------------ | 1410| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1411 1412**示例：** 1413 1414```ts 1415// xxx.ets 1416import { webview } from '@kit.ArkWeb'; 1417import { BusinessError } from '@kit.BasicServicesKit'; 1418 1419@Entry 1420@Component 1421struct WebComponent { 1422 controller: webview.WebviewController = new webview.WebviewController(); 1423 1424 build() { 1425 Column() { 1426 Button('refresh') 1427 .onClick(() => { 1428 try { 1429 this.controller.refresh(); 1430 } catch (error) { 1431 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1432 } 1433 }) 1434 Web({ src: 'www.example.com', controller: this.controller }) 1435 } 1436 } 1437} 1438``` 1439 1440### accessStep 1441 1442accessStep(step: number): boolean 1443 1444当前页面是否可前进或者后退给定的step步。 1445 1446**系统能力：** SystemCapability.Web.Webview.Core 1447 1448**参数：** 1449 1450| 参数名 | 类型 | 必填 | 说明 | 1451| ------ | -------- | ---- | ------------------------------------------ | 1452| step | number | 是 | 要跳转的步数，正数代表前进，负数代表后退。 | 1453 1454**返回值：** 1455 1456| 类型 | 说明 | 1457| ------- | ------------------ | 1458| boolean | 页面是否前进或后退 | 1459 1460**错误码：** 1461 1462以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1463 1464| 错误码ID | 错误信息 | 1465| -------- | ------------------------------------------------------------ | 1466| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1467| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1468 1469**示例：** 1470 1471```ts 1472// xxx.ets 1473import { webview } from '@kit.ArkWeb'; 1474import { BusinessError } from '@kit.BasicServicesKit'; 1475 1476@Entry 1477@Component 1478struct WebComponent { 1479 controller: webview.WebviewController = new webview.WebviewController(); 1480 @State steps: number = 2; 1481 1482 build() { 1483 Column() { 1484 Button('accessStep') 1485 .onClick(() => { 1486 try { 1487 let result = this.controller.accessStep(this.steps); 1488 console.log('result:' + result); 1489 } catch (error) { 1490 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1491 } 1492 }) 1493 Web({ src: 'www.example.com', controller: this.controller }) 1494 } 1495 } 1496} 1497``` 1498 1499### clearHistory 1500 1501clearHistory(): void 1502 1503删除所有前进后退记录，不建议在onErrorReceive与onPageBegin中调用clearHistory，会造成异常退出。 1504 1505**系统能力：** SystemCapability.Web.Webview.Core 1506 1507**错误码：** 1508 1509以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1510 1511| 错误码ID | 错误信息 | 1512| -------- | ------------------------------------------------------------ | 1513| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1514 1515**示例：** 1516 1517```ts 1518// xxx.ets 1519import { webview } from '@kit.ArkWeb'; 1520import { BusinessError } from '@kit.BasicServicesKit'; 1521 1522@Entry 1523@Component 1524struct WebComponent { 1525 controller: webview.WebviewController = new webview.WebviewController(); 1526 1527 build() { 1528 Column() { 1529 Button('clearHistory') 1530 .onClick(() => { 1531 try { 1532 this.controller.clearHistory(); 1533 } catch (error) { 1534 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1535 } 1536 }) 1537 Web({ src: 'www.example.com', controller: this.controller }) 1538 } 1539 } 1540} 1541``` 1542 1543### getHitTest 1544 1545getHitTest(): WebHitTestType 1546 1547获取当前被点击区域的元素类型。 1548 1549**系统能力：** SystemCapability.Web.Webview.Core 1550 1551**返回值：** 1552 1553| 类型 | 说明 | 1554| ------------------------------------------------------------ | ---------------------- | 1555| [WebHitTestType](#webhittesttype)| 被点击区域的元素类型。 | 1556 1557**错误码：** 1558 1559以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1560 1561| 错误码ID | 错误信息 | 1562| -------- | ------------------------------------------------------------ | 1563| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1564 1565**示例：** 1566 1567```ts 1568// xxx.ets 1569import { webview } from '@kit.ArkWeb'; 1570import { BusinessError } from '@kit.BasicServicesKit'; 1571 1572@Entry 1573@Component 1574struct WebComponent { 1575 controller: webview.WebviewController = new webview.WebviewController(); 1576 1577 build() { 1578 Column() { 1579 Button('getHitTest') 1580 .onClick(() => { 1581 try { 1582 let hitTestType = this.controller.getHitTest(); 1583 console.log("hitTestType: " + hitTestType); 1584 } catch (error) { 1585 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1586 } 1587 }) 1588 Web({ src: 'www.example.com', controller: this.controller }) 1589 } 1590 } 1591} 1592``` 1593 1594### registerJavaScriptProxy 1595 1596registerJavaScriptProxy(object: object, name: string, methodList: Array\<string>, asyncMethodList?: Array\<string>, permission?: string): void 1597 1598registerJavaScriptProxy提供了应用与Web组件加载的网页之间强大的交互能力。 1599<br>注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。注册后，须调用[refresh](#refresh)接口生效。 1600 1601> **说明：** 1602> 1603> - registerJavaScriptProxy需要和deleteJavaScriptRegister接口配合使用，防止内存泄漏。 1604> - 请尽可能只在可信的URL及安全通信HTTPS场景下进行registerJavaScriptProxy注册。在非可信的Web组件中注入JavaScript对象，可能会导致应用被恶意攻击。 1605> - 在注册registerJavaScriptProxy后，应用会将JavaScript对象暴露给所有的页面frames。 1606> - 同一方法在同步与异步列表中重复注册，将默认异步调用。 1607> - 同步函数列表和异步函数列表不可同时为空，否则此次调用接口注册失败。 1608 1609**系统能力：** SystemCapability.Web.Webview.Core 1610 1611**参数：** 1612 1613| 参数名 | 类型 | 必填 | 说明 | 1614| ---------- | -------------- | ---- | ------------------------------------------------------------ | 1615| object | object | 是 | 参与注册的应用侧JavaScript对象。可以单独声明方法和属性，但无法同时进行注册与使用。对象只包含属性时，H5可以访问对象中的属性。对象只包含方法时，H5可以访问对象中的方法。<br>方法的参数和返回类型可以为string，number，boolean。<br>方法的参数和返回类型支持Dictionary，Array，最多嵌套10层，每层1w个数据。<br>方法的参数和返回类型支持Object，需要在Object里添加属性methodNameListForJsProxy:[fun1, fun2]，fun1和fun2为可被调用的方法。<br>方法的参数支持Function，Promise，它们的Callback不能有返回值。<br>方法的返回类型支持Promise，Promise的Callback不能有返回值。<br>示例请参考[前端页面调用应用侧函数](../../web/web-in-page-app-function-invoking.md)。 | 1616| name | string | 是 | 注册对象的名称，与window中调用的对象名一致。注册后window对象可以通过此名字访问应用侧JavaScript对象。 | 1617| methodList | Array\<string> | 是 | 参与注册的应用侧JavaScript对象的同步方法。 | 1618| asyncMethodList<sup>12+</sup> | Array\<string> | 否 | 参与注册的应用侧JavaScript对象的异步方法，默认为空。异步方法无法获取返回值。 | 1619| permission<sup>12+</sup> | string | 否 | json字符串，默认为空，通过该字符串配置JSBridge的权限管控，可以定义object、method一级的url白名单。<br>示例请参考[前端页面调用应用侧函数](../../web/web-in-page-app-function-invoking.md)。| 1620 1621**错误码：** 1622 1623以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1624 1625| 错误码ID | 错误信息 | 1626| -------- | ------------------------------------------------------------ | 1627| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1628| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1629 1630**示例：** 1631 1632```ts 1633// xxx.ets 1634import { webview } from '@kit.ArkWeb'; 1635import { BusinessError } from '@kit.BasicServicesKit'; 1636 1637class TestObj { 1638 constructor() { 1639 } 1640 1641 test(testStr: string): string { 1642 console.log('Web Component str' + testStr); 1643 return testStr; 1644 } 1645 1646 toString(): void { 1647 console.log('Web Component toString'); 1648 } 1649 1650 testNumber(testNum: number): number { 1651 console.log('Web Component number' + testNum); 1652 return testNum; 1653 } 1654 1655 asyncTestBool(testBol: boolean): void { 1656 console.log('Web Component boolean' + testBol); 1657 } 1658} 1659 1660class WebObj { 1661 constructor() { 1662 } 1663 1664 webTest(): string { 1665 console.log('Web test'); 1666 return "Web test"; 1667 } 1668 1669 webString(): void { 1670 console.log('Web test toString'); 1671 } 1672} 1673 1674class AsyncObj { 1675 constructor() { 1676 } 1677 1678 asyncTest(): void { 1679 console.log('Async test'); 1680 } 1681 1682 asyncString(testStr:string): void { 1683 console.log('Web async string' + testStr); 1684 } 1685} 1686 1687@Entry 1688@Component 1689struct Index { 1690 controller: webview.WebviewController = new webview.WebviewController(); 1691 @State testObjtest: TestObj = new TestObj(); 1692 @State webTestObj: WebObj = new WebObj(); 1693 @State asyncTestObj: AsyncObj = new AsyncObj(); 1694 1695 build() { 1696 Column() { 1697 Button('refresh') 1698 .onClick(() => { 1699 try { 1700 this.controller.refresh(); 1701 } catch (error) { 1702 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1703 } 1704 }) 1705 Button('Register JavaScript To Window') 1706 .onClick(() => { 1707 try { 1708 // 同时注册同步和异步函数 1709 this.controller.registerJavaScriptProxy(this.testObjtest, "objName", ["test", "toString", "testNumber"], ["asyncTestBool"]); 1710 // 仅注册同步函数 1711 this.controller.registerJavaScriptProxy(this.webTestObj, "objTestName", ["webTest", "webString"]); 1712 // 仅注册异步函数 1713 this.controller.registerJavaScriptProxy(this.asyncTestObj, "objAsyncName", [], ["asyncTest", "asyncString"]); 1714 } catch (error) { 1715 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1716 } 1717 }) 1718 Button('deleteJavaScriptRegister') 1719 .onClick(() => { 1720 try { 1721 this.controller.deleteJavaScriptRegister("objName"); 1722 this.controller.deleteJavaScriptRegister("objTestName"); 1723 this.controller.deleteJavaScriptRegister("objAsyncName"); 1724 } catch (error) { 1725 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1726 } 1727 }) 1728 Web({ src: $rawfile('index.html'), controller: this.controller }) 1729 .javaScriptAccess(true) 1730 } 1731 } 1732} 1733``` 1734 1735加载的html文件。 1736```html 1737<!-- index.html --> 1738<!DOCTYPE html> 1739<html> 1740 <meta charset="utf-8"> 1741 <body> 1742 <button type="button" onclick="htmlTest()">Click Me!</button> 1743 <p id="demo"></p> 1744 <p id="webDemo"></p> 1745 <p id="asyncDemo"></p> 1746 </body> 1747 <script type="text/javascript"> 1748 function htmlTest() { 1749 // This function call expects to return "ArkUI Web Component" 1750 let str=objName.test("webtest data"); 1751 objName.testNumber(1); 1752 objName.asyncTestBool(true); 1753 document.getElementById("demo").innerHTML=str; 1754 console.log('objName.test result:'+ str) 1755 1756 // This function call expects to return "Web test" 1757 let webStr = objTestName.webTest(); 1758 document.getElementById("webDemo").innerHTML=webStr; 1759 console.log('objTestName.webTest result:'+ webStr) 1760 1761 objAsyncName.asyncTest(); 1762 objAsyncName.asyncString("async test data"); 1763 } 1764</script> 1765</html> 1766``` 1767更多示例，请参考[前端页面调用应用侧函数](../../web/web-in-page-app-function-invoking.md)。 1768 1769### runJavaScript 1770 1771runJavaScript(script: string, callback : AsyncCallback\<string>): void 1772 1773异步执行JavaScript脚本，并通过回调方式返回脚本执行的结果。runJavaScript需要在loadUrl完成后，比如onPageEnd中调用。 1774 1775> **说明：** 1776> 1777> 离屏组件不会触发runJavaScript接口。 1778 1779**系统能力：** SystemCapability.Web.Webview.Core 1780 1781**参数：** 1782 1783| 参数名 | 类型 | 必填 | 说明 | 1784| -------- | -------------------- | ---- | ---------------------------- | 1785| script | string | 是 | JavaScript脚本。 | 1786| callback | AsyncCallback\<string> | 是 | 回调执行JavaScript脚本结果。JavaScript脚本若执行失败或无返回值时，返回null。 | 1787 1788**错误码：** 1789 1790以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1791 1792| 错误码ID | 错误信息 | 1793| -------- | ------------------------------------------------------------ | 1794| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1795| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1796 1797**示例：** 1798 1799```ts 1800import { webview } from '@kit.ArkWeb'; 1801import { BusinessError } from '@kit.BasicServicesKit'; 1802 1803@Entry 1804@Component 1805struct WebComponent { 1806 controller: webview.WebviewController = new webview.WebviewController(); 1807 @State webResult: string = ''; 1808 1809 build() { 1810 Column() { 1811 Text(this.webResult).fontSize(20) 1812 Web({ src: $rawfile('index.html'), controller: this.controller }) 1813 .javaScriptAccess(true) 1814 .onPageEnd(e => { 1815 try { 1816 this.controller.runJavaScript( 1817 'test()', 1818 (error, result) => { 1819 if (error) { 1820 console.error(`run JavaScript error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1821 return; 1822 } 1823 if (result) { 1824 this.webResult = result; 1825 console.info(`The test() return value is: ${result}`); 1826 } 1827 }); 1828 if (e) { 1829 console.info('url: ', e.url); 1830 } 1831 } catch (error) { 1832 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1833 } 1834 }) 1835 } 1836 } 1837} 1838``` 1839 1840加载的html文件。 1841```html 1842<!-- index.html --> 1843<!DOCTYPE html> 1844<html> 1845 <meta charset="utf-8"> 1846 <body> 1847 Hello world! 1848 </body> 1849 <script type="text/javascript"> 1850 function test() { 1851 console.log('Ark WebComponent') 1852 return "This value is from index.html" 1853 } 1854 </script> 1855</html> 1856``` 1857 1858### runJavaScript 1859 1860runJavaScript(script: string): Promise\<string> 1861 1862异步执行JavaScript脚本，并通过Promise方式返回脚本执行的结果。runJavaScript需要在loadUrl完成后，比如onPageEnd中调用。 1863 1864**系统能力：** SystemCapability.Web.Webview.Core 1865 1866**参数：** 1867 1868| 参数名 | 类型 | 必填 | 说明 | 1869| ------ | -------- | ---- | ---------------- | 1870| script | string | 是 | JavaScript脚本。 | 1871 1872**返回值：** 1873 1874| 类型 | 说明 | 1875| --------------- | --------------------------------------------------- | 1876| Promise\<string> | Promise实例，返回脚本执行的结果，执行失败返回null。 | 1877 1878**错误码：** 1879 1880以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1881 1882| 错误码ID | 错误信息 | 1883| -------- | ------------------------------------------------------------ | 1884| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1885| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1886 1887**示例：** 1888 1889```ts 1890// xxx.ets 1891import { webview } from '@kit.ArkWeb'; 1892import { BusinessError } from '@kit.BasicServicesKit'; 1893 1894@Entry 1895@Component 1896struct WebComponent { 1897 controller: webview.WebviewController = new webview.WebviewController(); 1898 1899 build() { 1900 Column() { 1901 Web({ src: $rawfile('index.html'), controller: this.controller }) 1902 .javaScriptAccess(true) 1903 .onPageEnd(e => { 1904 try { 1905 this.controller.runJavaScript('test()') 1906 .then((result) => { 1907 console.log('result: ' + result); 1908 }) 1909 .catch((error: BusinessError) => { 1910 console.error("error: " + error); 1911 }) 1912 if (e) { 1913 console.info('url: ', e.url); 1914 } 1915 } catch (error) { 1916 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 1917 } 1918 }) 1919 } 1920 } 1921} 1922``` 1923 1924加载的html文件。 1925```html 1926<!-- index.html --> 1927<!DOCTYPE html> 1928<html> 1929 <meta charset="utf-8"> 1930 <body> 1931 Hello world! 1932 </body> 1933 <script type="text/javascript"> 1934 function test() { 1935 console.log('Ark WebComponent') 1936 return "This value is from index.html" 1937 } 1938 </script> 1939</html> 1940``` 1941 1942### runJavaScriptExt<sup>10+</sup> 1943 1944runJavaScriptExt(script: string | ArrayBuffer, callback : AsyncCallback\<JsMessageExt>): void 1945 1946异步执行JavaScript脚本，并通过回调方式返回脚本执行的结果。runJavaScriptExt需要在loadUrl完成后，比如onPageEnd中调用。 1947 1948**系统能力：** SystemCapability.Web.Webview.Core 1949 1950**参数：** 1951 1952| 参数名 | 类型 | 必填 | 说明 | 1953| -------- | -------------------- | ---- | ---------------------------- | 1954| script | string \| ArrayBuffer<sup>12+</sup> | 是 | JavaScript脚本。 | 1955| callback | AsyncCallback\<[JsMessageExt](#jsmessageext10)\> | 是 | 回调执行JavaScript脚本结果。 | 1956 1957**错误码：** 1958 1959以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 1960 1961| 错误码ID | 错误信息 | 1962| -------- | ------------------------------------------------------------ | 1963| 17100001 | Init error. The WebviewController must be associated with a Web component. | 1964| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1965 1966**示例：** 1967 1968```ts 1969import { webview } from '@kit.ArkWeb'; 1970import { BusinessError } from '@kit.BasicServicesKit'; 1971 1972@Entry 1973@Component 1974struct WebComponent { 1975 controller: webview.WebviewController = new webview.WebviewController(); 1976 @State msg1: string = ''; 1977 @State msg2: string = ''; 1978 1979 build() { 1980 Column() { 1981 Text(this.msg1).fontSize(20) 1982 Text(this.msg2).fontSize(20) 1983 Web({ src: $rawfile('index.html'), controller: this.controller }) 1984 .javaScriptAccess(true) 1985 .onPageEnd(e => { 1986 try { 1987 this.controller.runJavaScriptExt( 1988 'test()', 1989 (error, result) => { 1990 if (error) { 1991 console.error(`run JavaScript error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`) 1992 return; 1993 } 1994 if (result) { 1995 try { 1996 let type = result.getType(); 1997 switch (type) { 1998 case webview.JsMessageType.STRING: { 1999 this.msg1 = "result type:" + typeof (result.getString()); 2000 this.msg2 = "result getString:" + ((result.getString())); 2001 break; 2002 } 2003 case webview.JsMessageType.NUMBER: { 2004 this.msg1 = "result type:" + typeof (result.getNumber()); 2005 this.msg2 = "result getNumber:" + ((result.getNumber())); 2006 break; 2007 } 2008 case webview.JsMessageType.BOOLEAN: { 2009 this.msg1 = "result type:" + typeof (result.getBoolean()); 2010 this.msg2 = "result getBoolean:" + ((result.getBoolean())); 2011 break; 2012 } 2013 case webview.JsMessageType.ARRAY_BUFFER: { 2014 this.msg1 = "result type:" + typeof (result.getArrayBuffer()); 2015 this.msg2 = "result getArrayBuffer byteLength:" + ((result.getArrayBuffer().byteLength)); 2016 break; 2017 } 2018 case webview.JsMessageType.ARRAY: { 2019 this.msg1 = "result type:" + typeof (result.getArray()); 2020 this.msg2 = "result getArray:" + result.getArray(); 2021 break; 2022 } 2023 default: { 2024 this.msg1 = "default break, type:" + type; 2025 break; 2026 } 2027 } 2028 } 2029 catch (resError) { 2030 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2031 } 2032 } 2033 }); 2034 if (e) { 2035 console.info('url: ', e.url); 2036 } 2037 } catch (error) { 2038 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2039 } 2040 }) 2041 } 2042 } 2043} 2044``` 2045 2046```ts 2047// 使用ArrayBuffer入参，从文件中获取JavaScript脚本数据 2048import { webview } from '@kit.ArkWeb'; 2049import { BusinessError } from '@kit.BasicServicesKit'; 2050import { fileIo } from '@kit.CoreFileKit'; 2051import { common } from '@kit.AbilityKit'; 2052 2053@Entry 2054@Component 2055struct WebComponent { 2056 controller: webview.WebviewController = new webview.WebviewController(); 2057 @State msg1: string = '' 2058 @State msg2: string = '' 2059 2060 build() { 2061 Column() { 2062 Text(this.msg1).fontSize(20) 2063 Text(this.msg2).fontSize(20) 2064 Button('runJavaScriptExt') 2065 .onClick(() => { 2066 try { 2067 let context = getContext(this) as common.UIAbilityContext; 2068 let filePath = context.filesDir + 'test.txt'; 2069 // 新建并打开文件 2070 let file = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE); 2071 // 写入一段内容至文件 2072 fileIo.writeSync(file.fd, "test()"); 2073 // 从文件中读取内容 2074 let arrayBuffer: ArrayBuffer = new ArrayBuffer(6); 2075 fileIo.readSync(file.fd, arrayBuffer, { offset: 0, length: arrayBuffer.byteLength }); 2076 // 关闭文件 2077 fileIo.closeSync(file); 2078 this.controller.runJavaScriptExt( 2079 arrayBuffer, 2080 (error, result) => { 2081 if (error) { 2082 console.error(`run JavaScript error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`) 2083 return; 2084 } 2085 if (result) { 2086 try { 2087 let type = result.getType(); 2088 switch (type) { 2089 case webview.JsMessageType.STRING: { 2090 this.msg1 = "result type:" + typeof (result.getString()); 2091 this.msg2 = "result getString:" + ((result.getString())); 2092 break; 2093 } 2094 case webview.JsMessageType.NUMBER: { 2095 this.msg1 = "result type:" + typeof (result.getNumber()); 2096 this.msg2 = "result getNumber:" + ((result.getNumber())); 2097 break; 2098 } 2099 case webview.JsMessageType.BOOLEAN: { 2100 this.msg1 = "result type:" + typeof (result.getBoolean()); 2101 this.msg2 = "result getBoolean:" + ((result.getBoolean())); 2102 break; 2103 } 2104 case webview.JsMessageType.ARRAY_BUFFER: { 2105 this.msg1 = "result type:" + typeof (result.getArrayBuffer()); 2106 this.msg2 = "result getArrayBuffer byteLength:" + ((result.getArrayBuffer().byteLength)); 2107 break; 2108 } 2109 case webview.JsMessageType.ARRAY: { 2110 this.msg1 = "result type:" + typeof (result.getArray()); 2111 this.msg2 = "result getArray:" + result.getArray(); 2112 break; 2113 } 2114 default: { 2115 this.msg1 = "default break, type:" + type; 2116 break; 2117 } 2118 } 2119 } 2120 catch (resError) { 2121 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2122 } 2123 } 2124 }); 2125 } catch (error) { 2126 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2127 } 2128 }) 2129 Web({ src: $rawfile('index.html'), controller: this.controller }) 2130 .javaScriptAccess(true) 2131 } 2132 } 2133} 2134``` 2135 2136加载的html文件。 2137```html 2138<!-- index.html --> 2139<!DOCTYPE html> 2140<html lang="en-gb"> 2141<body> 2142<h1>run JavaScript Ext demo</h1> 2143</body> 2144<script type="text/javascript"> 2145function test() { 2146 return "hello, world"; 2147} 2148</script> 2149</html> 2150``` 2151 2152### runJavaScriptExt<sup>10+</sup> 2153 2154runJavaScriptExt(script: string | ArrayBuffer): Promise\<JsMessageExt> 2155 2156异步执行JavaScript脚本，并通过Promise方式返回脚本执行的结果。runJavaScriptExt需要在loadUrl完成后，比如onPageEnd中调用。 2157 2158**系统能力：** SystemCapability.Web.Webview.Core 2159 2160**参数：** 2161 2162| 参数名 | 类型 | 必填 | 说明 | 2163| ------ | -------- | ---- | ---------------- | 2164| script | string \| ArrayBuffer<sup>12+</sup> | 是 | JavaScript脚本。 | 2165 2166**返回值：** 2167 2168| 类型 | 说明 | 2169| --------------- | --------------------------------------------------- | 2170| Promise\<[JsMessageExt](#jsmessageext10)> | Promise实例，返回脚本执行的结果。 | 2171 2172**错误码：** 2173 2174以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2175 2176| 错误码ID | 错误信息 | 2177| -------- | ------------------------------------------------------------ | 2178| 17100001 | Init error. The WebviewController must be associated with a Web component. | 2179| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2180 2181**示例：** 2182 2183```ts 2184// xxx.ets 2185import { webview } from '@kit.ArkWeb'; 2186import { BusinessError } from '@kit.BasicServicesKit'; 2187 2188@Entry 2189@Component 2190struct WebComponent { 2191 controller: webview.WebviewController = new webview.WebviewController(); 2192 @State webResult: string = ''; 2193 @State msg1: string = ''; 2194 @State msg2: string = ''; 2195 2196 build() { 2197 Column() { 2198 Text(this.webResult).fontSize(20) 2199 Text(this.msg1).fontSize(20) 2200 Text(this.msg2).fontSize(20) 2201 Web({ src: $rawfile('index.html'), controller: this.controller }) 2202 .javaScriptAccess(true) 2203 .onPageEnd(() => { 2204 this.controller.runJavaScriptExt('test()') 2205 .then((result) => { 2206 try { 2207 let type = result.getType(); 2208 switch (type) { 2209 case webview.JsMessageType.STRING: { 2210 this.msg1 = "result type:" + typeof (result.getString()); 2211 this.msg2 = "result getString:" + ((result.getString())); 2212 break; 2213 } 2214 case webview.JsMessageType.NUMBER: { 2215 this.msg1 = "result type:" + typeof (result.getNumber()); 2216 this.msg2 = "result getNumber:" + ((result.getNumber())); 2217 break; 2218 } 2219 case webview.JsMessageType.BOOLEAN: { 2220 this.msg1 = "result type:" + typeof (result.getBoolean()); 2221 this.msg2 = "result getBoolean:" + ((result.getBoolean())); 2222 break; 2223 } 2224 case webview.JsMessageType.ARRAY_BUFFER: { 2225 this.msg1 = "result type:" + typeof (result.getArrayBuffer()); 2226 this.msg2 = "result getArrayBuffer byteLength:" + ((result.getArrayBuffer().byteLength)); 2227 break; 2228 } 2229 case webview.JsMessageType.ARRAY: { 2230 this.msg1 = "result type:" + typeof (result.getArray()); 2231 this.msg2 = "result getArray:" + result.getArray(); 2232 break; 2233 } 2234 default: { 2235 this.msg1 = "default break, type:" + type; 2236 break; 2237 } 2238 } 2239 } 2240 catch (resError) { 2241 console.error(`ErrorCode: ${(resError as BusinessError).code}, Message: ${(resError as BusinessError).message}`); 2242 } 2243 }).catch((error: BusinessError) => { 2244 console.error("error: " + error); 2245 }) 2246 }) 2247 } 2248 } 2249} 2250``` 2251 2252```ts 2253// 使用ArrayBuffer入参，从文件中获取JavaScript脚本数据 2254import { webview } from '@kit.ArkWeb'; 2255import { BusinessError } from '@kit.BasicServicesKit'; 2256import { fileIo } from '@kit.CoreFileKit'; 2257import { common } from '@kit.AbilityKit'; 2258 2259@Entry 2260@Component 2261struct WebComponent { 2262 controller: webview.WebviewController = new webview.WebviewController(); 2263 @State msg1: string = ''; 2264 @State msg2: string = ''; 2265 2266 build() { 2267 Column() { 2268 Text(this.msg1).fontSize(20) 2269 Text(this.msg2).fontSize(20) 2270 Button('runJavaScriptExt') 2271 .onClick(() => { 2272 try { 2273 let context = getContext(this) as common.UIAbilityContext; 2274 let filePath = context.filesDir + 'test.txt'; 2275 // 新建并打开文件 2276 let file = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE); 2277 // 写入一段内容至文件 2278 fileIo.writeSync(file.fd, "test()"); 2279 // 从文件中读取内容 2280 let arrayBuffer: ArrayBuffer = new ArrayBuffer(6); 2281 fileIo.readSync(file.fd, arrayBuffer, { offset: 0, length: arrayBuffer.byteLength }); 2282 // 关闭文件 2283 fileIo.closeSync(file); 2284 this.controller.runJavaScriptExt(arrayBuffer) 2285 .then((result) => { 2286 try { 2287 let type = result.getType(); 2288 switch (type) { 2289 case webview.JsMessageType.STRING: { 2290 this.msg1 = "result type:" + typeof (result.getString()); 2291 this.msg2 = "result getString:" + ((result.getString())); 2292 break; 2293 } 2294 case webview.JsMessageType.NUMBER: { 2295 this.msg1 = "result type:" + typeof (result.getNumber()); 2296 this.msg2 = "result getNumber:" + ((result.getNumber())); 2297 break; 2298 } 2299 case webview.JsMessageType.BOOLEAN: { 2300 this.msg1 = "result type:" + typeof (result.getBoolean()); 2301 this.msg2 = "result getBoolean:" + ((result.getBoolean())); 2302 break; 2303 } 2304 case webview.JsMessageType.ARRAY_BUFFER: { 2305 this.msg1 = "result type:" + typeof (result.getArrayBuffer()); 2306 this.msg2 = "result getArrayBuffer byteLength:" + ((result.getArrayBuffer().byteLength)); 2307 break; 2308 } 2309 case webview.JsMessageType.ARRAY: { 2310 this.msg1 = "result type:" + typeof (result.getArray()); 2311 this.msg2 = "result getArray:" + result.getArray(); 2312 break; 2313 } 2314 default: { 2315 this.msg1 = "default break, type:" + type; 2316 break; 2317 } 2318 } 2319 } 2320 catch (resError) { 2321 console.error(`ErrorCode: ${(resError as BusinessError).code}, Message: ${(resError as BusinessError).message}`); 2322 } 2323 }) 2324 .catch((error: BusinessError) => { 2325 console.error("error: " + error); 2326 }) 2327 } catch (error) { 2328 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2329 } 2330 }) 2331 Web({ src: $rawfile('index.html'), controller: this.controller }) 2332 .javaScriptAccess(true) 2333 } 2334 } 2335} 2336``` 2337 2338加载的html文件。 2339```html 2340<!-- index.html --> 2341<!DOCTYPE html> 2342<html lang="en-gb"> 2343<body> 2344<h1>run JavaScript Ext demo</h1> 2345</body> 2346<script type="text/javascript"> 2347function test() { 2348 return "hello, world"; 2349} 2350</script> 2351</html> 2352``` 2353 2354### deleteJavaScriptRegister 2355 2356deleteJavaScriptRegister(name: string): void 2357 2358删除通过registerJavaScriptProxy注册到window上的指定name的应用侧JavaScript对象。删除后，须调用[refresh](#refresh)接口。 2359 2360**系统能力：** SystemCapability.Web.Webview.Core 2361 2362**参数：** 2363 2364| 参数名 | 类型 | 必填 | 说明 | 2365| ------ | -------- | ---- | ---- | 2366| name | string | 是 | 注册对象的名称，可在网页侧JavaScript中通过此名称调用应用侧JavaScript对象。 | 2367 2368**错误码：** 2369 2370以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2371 2372| 错误码ID | 错误信息 | 2373| -------- | ------------------------------------------------------------ | 2374| 17100001 | Init error. The WebviewController must be associated with a Web component. | 2375| 17100008 | Failed to delete JavaScriptProxy because it does not exist. | 2376| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2377 2378**示例：** 2379 2380```ts 2381// xxx.ets 2382import { webview } from '@kit.ArkWeb'; 2383import { BusinessError } from '@kit.BasicServicesKit'; 2384 2385class TestObj { 2386 constructor() { 2387 } 2388 2389 test(): string { 2390 return "ArkUI Web Component"; 2391 } 2392 2393 toString(): void { 2394 console.log('Web Component toString'); 2395 } 2396} 2397 2398@Entry 2399@Component 2400struct WebComponent { 2401 controller: webview.WebviewController = new webview.WebviewController(); 2402 @State testObjtest: TestObj = new TestObj(); 2403 @State name: string = 'objName'; 2404 build() { 2405 Column() { 2406 Button('refresh') 2407 .onClick(() => { 2408 try { 2409 this.controller.refresh(); 2410 } catch (error) { 2411 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2412 } 2413 }) 2414 Button('Register JavaScript To Window') 2415 .onClick(() => { 2416 try { 2417 this.controller.registerJavaScriptProxy(this.testObjtest, this.name, ["test", "toString"]); 2418 } catch (error) { 2419 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2420 } 2421 }) 2422 Button('deleteJavaScriptRegister') 2423 .onClick(() => { 2424 try { 2425 this.controller.deleteJavaScriptRegister(this.name); 2426 } catch (error) { 2427 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2428 } 2429 }) 2430 Web({ src: $rawfile('index.html'), controller: this.controller }) 2431 .javaScriptAccess(true) 2432 } 2433 } 2434} 2435``` 2436 2437加载的html文件。 2438```html 2439<!-- index.html --> 2440<!DOCTYPE html> 2441<html> 2442 <meta charset="utf-8"> 2443 <body> 2444 <button type="button" onclick="htmlTest()">Click Me!</button> 2445 <p id="demo"></p> 2446 </body> 2447 <script type="text/javascript"> 2448 function htmlTest() { 2449 let str=objName.test(); 2450 document.getElementById("demo").innerHTML=str; 2451 console.log('objName.test result:'+ str) 2452 } 2453</script> 2454</html> 2455``` 2456 2457### zoom 2458 2459zoom(factor: number): void 2460 2461调整当前网页的缩放比例，[zoomAccess](ts-basic-components-web.md#zoomaccess)需为true。 2462 2463**系统能力：** SystemCapability.Web.Webview.Core 2464 2465**参数：** 2466 2467| 参数名 | 类型 | 必填 | 说明 | 2468| ------ | -------- | ---- | ------------------------------------------------------------ | 2469| factor | number | 是 | 基于当前网页所需调整的相对缩放比例，入参要求大于0，当入参为1时为默认加载网页的缩放比例，入参小于1为缩小，入参大于1为放大。 | 2470 2471**错误码：** 2472 2473以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2474 2475| 错误码ID | 错误信息 | 2476| -------- | ------------------------------------------------------------ | 2477| 17100001 | Init error. The WebviewController must be associated with a Web component. | 2478| 17100004 | Function not enabled. | 2479| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2480 2481**示例：** 2482 2483```ts 2484// xxx.ets 2485import { webview } from '@kit.ArkWeb'; 2486import { BusinessError } from '@kit.BasicServicesKit'; 2487 2488@Entry 2489@Component 2490struct WebComponent { 2491 controller: webview.WebviewController = new webview.WebviewController(); 2492 @State factor: number = 1; 2493 2494 build() { 2495 Column() { 2496 Button('zoom') 2497 .onClick(() => { 2498 try { 2499 this.controller.zoom(this.factor); 2500 } catch (error) { 2501 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2502 } 2503 }) 2504 Web({ src: 'www.example.com', controller: this.controller }) 2505 .zoomAccess(true) 2506 } 2507 } 2508} 2509``` 2510 2511### searchAllAsync 2512 2513searchAllAsync(searchString: string): void 2514 2515异步查找网页中所有匹配关键字'searchString'的内容并高亮，结果通过[onSearchResultReceive](ts-basic-components-web.md#onsearchresultreceive9)异步返回。 2516 2517**系统能力：** SystemCapability.Web.Webview.Core 2518 2519**参数：** 2520 2521| 参数名 | 类型 | 必填 | 说明 | 2522| ------------ | -------- | ---- | -------------- | 2523| searchString | string | 是 | 查找的关键字。 | 2524 2525**错误码：** 2526 2527以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2528 2529| 错误码ID | 错误信息 | 2530| -------- | ------------------------------------------------------------ | 2531| 17100001 | Init error. The WebviewController must be associated with a Web component. | 2532| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2533 2534**示例：** 2535 2536```ts 2537// xxx.ets 2538import { webview } from '@kit.ArkWeb'; 2539import { BusinessError } from '@kit.BasicServicesKit'; 2540 2541@Entry 2542@Component 2543struct WebComponent { 2544 controller: webview.WebviewController = new webview.WebviewController(); 2545 @State searchString: string = "Hello World"; 2546 2547 build() { 2548 Column() { 2549 Button('searchString') 2550 .onClick(() => { 2551 try { 2552 this.controller.searchAllAsync(this.searchString); 2553 } catch (error) { 2554 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2555 } 2556 }) 2557 Web({ src: $rawfile('index.html'), controller: this.controller }) 2558 .onSearchResultReceive(ret => { 2559 if (ret) { 2560 console.log("on search result receive:" + "[cur]" + ret.activeMatchOrdinal + 2561 "[total]" + ret.numberOfMatches + "[isDone]" + ret.isDoneCounting); 2562 } 2563 }) 2564 } 2565 } 2566} 2567``` 2568 2569加载的html文件。 2570```html 2571<!-- index.html --> 2572<!DOCTYPE html> 2573<html> 2574 <body> 2575 <p>Hello World Highlight Hello World</p> 2576 </body> 2577</html> 2578``` 2579 2580### clearMatches 2581 2582clearMatches(): void 2583 2584清除所有通过[searchAllAsync](#searchallasync)匹配到的高亮字符查找结果。 2585 2586**系统能力：** SystemCapability.Web.Webview.Core 2587 2588**错误码：** 2589 2590以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2591 2592| 错误码ID | 错误信息 | 2593| -------- | ------------------------------------------------------------ | 2594| 17100001 | Init error. The WebviewController must be associated with a Web component. | 2595 2596**示例：** 2597 2598```ts 2599// xxx.ets 2600import { webview } from '@kit.ArkWeb'; 2601import { BusinessError } from '@kit.BasicServicesKit'; 2602 2603@Entry 2604@Component 2605struct WebComponent { 2606 controller: webview.WebviewController = new webview.WebviewController(); 2607 2608 build() { 2609 Column() { 2610 Button('clearMatches') 2611 .onClick(() => { 2612 try { 2613 this.controller.clearMatches(); 2614 } catch (error) { 2615 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2616 } 2617 }) 2618 Web({ src: $rawfile('index.html'), controller: this.controller }) 2619 } 2620 } 2621} 2622``` 2623 2624加载的html文件，请参考[searchAllAsync](#searchallasync)接口下加载的html文件。 2625 2626### searchNext 2627 2628searchNext(forward: boolean): void 2629 2630滚动到下一个匹配的查找结果并高亮。 2631 2632**系统能力：** SystemCapability.Web.Webview.Core 2633 2634**参数：** 2635 2636| 参数名 | 类型 | 必填 | 说明 | 2637| ------- | -------- | ---- | ---------------------- | 2638| forward | boolean | 是 | 从前向后或者逆向查找。 | 2639 2640**错误码：** 2641 2642以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2643 2644| 错误码ID | 错误信息 | 2645| -------- | ------------------------------------------------------------ | 2646| 17100001 | Init error. The WebviewController must be associated with a Web component. | 2647| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2648 2649**示例：** 2650 2651```ts 2652// xxx.ets 2653import { webview } from '@kit.ArkWeb'; 2654import { BusinessError } from '@kit.BasicServicesKit'; 2655 2656@Entry 2657@Component 2658struct WebComponent { 2659 controller: webview.WebviewController = new webview.WebviewController(); 2660 2661 build() { 2662 Column() { 2663 Button('searchNext') 2664 .onClick(() => { 2665 try { 2666 this.controller.searchNext(true); 2667 } catch (error) { 2668 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2669 } 2670 }) 2671 Web({ src: $rawfile('index.html'), controller: this.controller }) 2672 } 2673 } 2674} 2675``` 2676 2677加载的html文件，请参考[searchAllAsync](#searchallasync)接口下加载的html文件。 2678 2679### clearSslCache 2680 2681clearSslCache(): void 2682 2683清除Web组件记录的SSL证书错误事件对应的用户操作行为。 2684 2685**系统能力：** SystemCapability.Web.Webview.Core 2686 2687**错误码：** 2688 2689以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2690 2691| 错误码ID | 错误信息 | 2692| -------- | ------------------------------------------------------------ | 2693| 17100001 | Init error. The WebviewController must be associated with a Web component. | 2694 2695**示例：** 2696 2697```ts 2698// xxx.ets 2699import { webview } from '@kit.ArkWeb'; 2700import { BusinessError } from '@kit.BasicServicesKit'; 2701 2702@Entry 2703@Component 2704struct WebComponent { 2705 controller: webview.WebviewController = new webview.WebviewController(); 2706 2707 build() { 2708 Column() { 2709 Button('clearSslCache') 2710 .onClick(() => { 2711 try { 2712 this.controller.clearSslCache(); 2713 } catch (error) { 2714 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2715 } 2716 }) 2717 Web({ src: 'www.example.com', controller: this.controller }) 2718 } 2719 } 2720} 2721``` 2722 2723### clearClientAuthenticationCache 2724 2725clearClientAuthenticationCache(): void 2726 2727清除Web组件记录的客户端证书请求事件对应的用户操作行为。 2728 2729**系统能力：** SystemCapability.Web.Webview.Core 2730 2731**错误码：** 2732 2733以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2734 2735| 错误码ID | 错误信息 | 2736| -------- | ------------------------------------------------------------ | 2737| 17100001 | Init error. The WebviewController must be associated with a Web component. | 2738 2739**示例：** 2740 2741```ts 2742// xxx.ets 2743import { webview } from '@kit.ArkWeb'; 2744import { BusinessError } from '@kit.BasicServicesKit'; 2745 2746@Entry 2747@Component 2748struct WebComponent { 2749 controller: webview.WebviewController = new webview.WebviewController(); 2750 2751 build() { 2752 Column() { 2753 Button('clearClientAuthenticationCache') 2754 .onClick(() => { 2755 try { 2756 this.controller.clearClientAuthenticationCache(); 2757 } catch (error) { 2758 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2759 } 2760 }) 2761 Web({ src: 'www.example.com', controller: this.controller }) 2762 } 2763 } 2764} 2765``` 2766 2767### createWebMessagePorts 2768 2769createWebMessagePorts(isExtentionType?: boolean): Array\<WebMessagePort> 2770 2771创建Web消息端口。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 2772 2773**系统能力：** SystemCapability.Web.Webview.Core 2774 2775**参数：** 2776 2777| 参数名 | 类型 | 必填 | 说明 | 2778| ------ | ---------------------- | ---- | :------------------------------| 2779| isExtentionType<sup>10+</sup> | boolean | 否 | 是否使用扩展增强接口，默认false不使用。 | 2780 2781**返回值：** 2782 2783| 类型 | 说明 | 2784| ---------------------- | ----------------- | 2785| Array\<[WebMessagePort](#webmessageport)> | web消息端口列表。 | 2786 2787**错误码：** 2788 2789以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2790 2791| 错误码ID | 错误信息 | 2792| -------- | ------------------------------------------------------------ | 2793| 17100001 | Init error. The WebviewController must be associated with a Web component. | 2794| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2795 2796**示例：** 2797 2798```ts 2799// xxx.ets 2800import { webview } from '@kit.ArkWeb'; 2801import { BusinessError } from '@kit.BasicServicesKit'; 2802 2803@Entry 2804@Component 2805struct WebComponent { 2806 controller: webview.WebviewController = new webview.WebviewController(); 2807 ports: webview.WebMessagePort[] = []; 2808 2809 build() { 2810 Column() { 2811 Button('createWebMessagePorts') 2812 .onClick(() => { 2813 try { 2814 this.ports = this.controller.createWebMessagePorts(); 2815 console.log("createWebMessagePorts size:" + this.ports.length); 2816 } catch (error) { 2817 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2818 } 2819 }) 2820 Web({ src: 'www.example.com', controller: this.controller }) 2821 } 2822 } 2823} 2824``` 2825 2826### postMessage 2827 2828postMessage(name: string, ports: Array\<WebMessagePort>, uri: string): void 2829 2830发送Web消息端口到HTML。 2831 2832**系统能力：** SystemCapability.Web.Webview.Core 2833 2834**参数：** 2835 2836| 参数名 | 类型 | 必填 | 说明 | 2837| ------ | ---------------------- | ---- | :------------------------------- | 2838| name | string | 是 | 要发送的消息名称。 | 2839| ports | Array\<[WebMessagePort](#webmessageport)> | 是 | 要发送的消息端口。 | 2840| uri | string | 是 | 接收该消息的URI。 | 2841 2842**错误码：** 2843 2844以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2845 2846| 错误码ID | 错误信息 | 2847| -------- | ------------------------------------------------------------ | 2848| 17100001 | Init error. The WebviewController must be associated with a Web component. | 2849| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2850 2851**示例：** 2852 2853```ts 2854// xxx.ets 2855import { webview } from '@kit.ArkWeb'; 2856import { BusinessError } from '@kit.BasicServicesKit'; 2857 2858@Entry 2859@Component 2860struct WebComponent { 2861 controller: webview.WebviewController = new webview.WebviewController(); 2862 ports: webview.WebMessagePort[] = []; 2863 @State sendFromEts: string = 'Send this message from ets to HTML'; 2864 @State receivedFromHtml: string = 'Display received message send from HTML'; 2865 2866 build() { 2867 Column() { 2868 // 展示接收到的来自HTML的内容 2869 Text(this.receivedFromHtml) 2870 // 输入框的内容发送到html 2871 TextInput({ placeholder: 'Send this message from ets to HTML' }) 2872 .onChange((value: string) => { 2873 this.sendFromEts = value; 2874 }) 2875 2876 Button('postMessage') 2877 .onClick(() => { 2878 try { 2879 // 1、创建两个消息端口。 2880 this.ports = this.controller.createWebMessagePorts(); 2881 // 2、在应用侧的消息端口(如端口1)上注册回调事件。 2882 this.ports[1].onMessageEvent((result: webview.WebMessage) => { 2883 let msg = 'Got msg from HTML:'; 2884 if (typeof (result) == "string") { 2885 console.log("received string message from html5, string is:" + result); 2886 msg = msg + result; 2887 } else if (typeof (result) == "object") { 2888 if (result instanceof ArrayBuffer) { 2889 console.log("received arraybuffer from html5, length is:" + result.byteLength); 2890 msg = msg + "length is " + result.byteLength; 2891 } else { 2892 console.log("not support"); 2893 } 2894 } else { 2895 console.log("not support"); 2896 } 2897 this.receivedFromHtml = msg; 2898 }) 2899 // 3、将另一个消息端口(如端口0)发送到HTML侧，由HTML侧保存并使用。 2900 this.controller.postMessage('__init_port__', [this.ports[0]], '*'); 2901 } catch (error) { 2902 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2903 } 2904 }) 2905 2906 // 4、使用应用侧的端口给另一个已经发送到html的端口发送消息。 2907 Button('SendDataToHTML') 2908 .onClick(() => { 2909 try { 2910 if (this.ports && this.ports[1]) { 2911 this.ports[1].postMessageEvent(this.sendFromEts); 2912 } else { 2913 console.error(`ports is null, Please initialize first`); 2914 } 2915 } catch (error) { 2916 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 2917 } 2918 }) 2919 Web({ src: $rawfile('index.html'), controller: this.controller }) 2920 } 2921 } 2922} 2923``` 2924 2925加载的html文件。 2926```html 2927<!--index.html--> 2928<!DOCTYPE html> 2929<html> 2930<head> 2931 <meta name="viewport" content="width=device-width, initial-scale=1.0"> 2932 <title>WebView Message Port Demo</title> 2933</head> 2934 2935 <body> 2936 <h1>WebView Message Port Demo</h1> 2937 <div> 2938 <input type="button" value="SendToEts" onclick="PostMsgToEts(msgFromJS.value);"/><br/> 2939 <input id="msgFromJS" type="text" value="send this message from HTML to ets"/><br/> 2940 </div> 2941 <p class="output">display received message send from ets</p> 2942 </body> 2943 <script src="xxx.js"></script> 2944</html> 2945``` 2946 2947```js 2948//xxx.js 2949var h5Port; 2950var output = document.querySelector('.output'); 2951window.addEventListener('message', function (event) { 2952 if (event.data == '__init_port__') { 2953 if (event.ports[0] != null) { 2954 h5Port = event.ports[0]; // 1. 保存从ets侧发送过来的端口 2955 h5Port.onmessage = function (event) { 2956 // 2. 接收ets侧发送过来的消息. 2957 var msg = 'Got message from ets:'; 2958 var result = event.data; 2959 if (typeof(result) == "string") { 2960 console.log("received string message from html5, string is:" + result); 2961 msg = msg + result; 2962 } else if (typeof(result) == "object") { 2963 if (result instanceof ArrayBuffer) { 2964 console.log("received arraybuffer from html5, length is:" + result.byteLength); 2965 msg = msg + "length is " + result.byteLength; 2966 } else { 2967 console.log("not support"); 2968 } 2969 } else { 2970 console.log("not support"); 2971 } 2972 output.innerHTML = msg; 2973 } 2974 } 2975 } 2976}) 2977 2978// 3. 使用h5Port往ets侧发送消息. 2979function PostMsgToEts(data) { 2980 if (h5Port) { 2981 h5Port.postMessage(data); 2982 } else { 2983 console.error("h5Port is null, Please initialize first"); 2984 } 2985} 2986``` 2987 2988### requestFocus 2989 2990requestFocus(): void 2991 2992使当前web页面获取焦点。 2993 2994**系统能力：** SystemCapability.Web.Webview.Core 2995 2996**错误码：** 2997 2998以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 2999 3000| 错误码ID | 错误信息 | 3001| -------- | ------------------------------------------------------------ | 3002| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3003 3004**示例：** 3005 3006```ts 3007// xxx.ets 3008import { webview } from '@kit.ArkWeb'; 3009import { BusinessError } from '@kit.BasicServicesKit'; 3010 3011@Entry 3012@Component 3013struct WebComponent { 3014 controller: webview.WebviewController = new webview.WebviewController(); 3015 3016 build() { 3017 Column() { 3018 Button('requestFocus') 3019 .onClick(() => { 3020 try { 3021 this.controller.requestFocus(); 3022 } catch (error) { 3023 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3024 } 3025 }); 3026 Web({ src: 'www.example.com', controller: this.controller }) 3027 } 3028 } 3029} 3030``` 3031 3032### zoomIn 3033 3034zoomIn(): void 3035 3036调用此接口将当前网页进行放大，比例为20%。 3037 3038**系统能力：** SystemCapability.Web.Webview.Core 3039 3040**错误码：** 3041 3042以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3043 3044| 错误码ID | 错误信息 | 3045| -------- | ------------------------------------------------------------ | 3046| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3047| 17100004 | Function not enabled. | 3048 3049**示例：** 3050 3051```ts 3052// xxx.ets 3053import { webview } from '@kit.ArkWeb'; 3054import { BusinessError } from '@kit.BasicServicesKit'; 3055 3056@Entry 3057@Component 3058struct WebComponent { 3059 controller: webview.WebviewController = new webview.WebviewController(); 3060 3061 build() { 3062 Column() { 3063 Button('zoomIn') 3064 .onClick(() => { 3065 try { 3066 this.controller.zoomIn(); 3067 } catch (error) { 3068 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3069 } 3070 }) 3071 Web({ src: 'www.example.com', controller: this.controller }) 3072 } 3073 } 3074} 3075``` 3076 3077### zoomOut 3078 3079zoomOut(): void 3080 3081调用此接口将当前网页进行缩小，比例为20%。 3082 3083**系统能力：** SystemCapability.Web.Webview.Core 3084 3085**错误码：** 3086 3087以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3088 3089| 错误码ID | 错误信息 | 3090| -------- | ------------------------------------------------------------ | 3091| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3092| 17100004 | Function not enabled. | 3093 3094**示例：** 3095 3096```ts 3097// xxx.ets 3098import { webview } from '@kit.ArkWeb'; 3099import { BusinessError } from '@kit.BasicServicesKit'; 3100 3101@Entry 3102@Component 3103struct WebComponent { 3104 controller: webview.WebviewController = new webview.WebviewController(); 3105 3106 build() { 3107 Column() { 3108 Button('zoomOut') 3109 .onClick(() => { 3110 try { 3111 this.controller.zoomOut(); 3112 } catch (error) { 3113 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3114 } 3115 }) 3116 Web({ src: 'www.example.com', controller: this.controller }) 3117 } 3118 } 3119} 3120``` 3121 3122### getHitTestValue 3123 3124getHitTestValue(): HitTestValue 3125 3126获取当前被点击区域的元素信息。 3127 3128**系统能力：** SystemCapability.Web.Webview.Core 3129 3130**返回值：** 3131 3132| 类型 | 说明 | 3133| ------------ | -------------------- | 3134| [HitTestValue](#hittestvalue) | 点击区域的元素信息。 | 3135 3136**错误码：** 3137 3138以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3139 3140| 错误码ID | 错误信息 | 3141| -------- | ------------------------------------------------------------ | 3142| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3143 3144**示例：** 3145 3146```ts 3147// xxx.ets 3148import { webview } from '@kit.ArkWeb'; 3149import { BusinessError } from '@kit.BasicServicesKit'; 3150 3151@Entry 3152@Component 3153struct WebComponent { 3154 controller: webview.WebviewController = new webview.WebviewController(); 3155 3156 build() { 3157 Column() { 3158 Button('getHitTestValue') 3159 .onClick(() => { 3160 try { 3161 let hitValue = this.controller.getHitTestValue(); 3162 console.log("hitType: " + hitValue.type); 3163 console.log("extra: " + hitValue.extra); 3164 } catch (error) { 3165 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3166 } 3167 }) 3168 Web({ src: 'www.example.com', controller: this.controller }) 3169 } 3170 } 3171} 3172``` 3173 3174### getWebId 3175 3176getWebId(): number 3177 3178获取当前Web组件的索引值，用于多个Web组件的管理。 3179 3180**系统能力：** SystemCapability.Web.Webview.Core 3181 3182**返回值：** 3183 3184| 类型 | 说明 | 3185| ------ | --------------------- | 3186| number | 当前Web组件的索引值。 | 3187 3188**错误码：** 3189 3190以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3191 3192| 错误码ID | 错误信息 | 3193| -------- | ------------------------------------------------------------ | 3194| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3195 3196**示例：** 3197 3198```ts 3199// xxx.ets 3200import { webview } from '@kit.ArkWeb'; 3201import { BusinessError } from '@kit.BasicServicesKit'; 3202 3203@Entry 3204@Component 3205struct WebComponent { 3206 controller: webview.WebviewController = new webview.WebviewController(); 3207 3208 build() { 3209 Column() { 3210 Button('getWebId') 3211 .onClick(() => { 3212 try { 3213 let id = this.controller.getWebId(); 3214 console.log("id: " + id); 3215 } catch (error) { 3216 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3217 } 3218 }) 3219 Web({ src: 'www.example.com', controller: this.controller }) 3220 } 3221 } 3222} 3223``` 3224 3225### getUserAgent 3226 3227getUserAgent(): string 3228 3229获取当前默认用户代理。 3230 3231默认UserAgent定义与使用场景请参考[UserAgent详情参考](../../web/web-default-userAgent.md) 3232 3233**系统能力：** SystemCapability.Web.Webview.Core 3234 3235**返回值：** 3236 3237| 类型 | 说明 | 3238| ------ | -------------- | 3239| string | 默认用户代理。 | 3240 3241**错误码：** 3242 3243以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3244 3245| 错误码ID | 错误信息 | 3246| -------- | ------------------------------------------------------------ | 3247| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3248 3249**示例：** 3250 3251```ts 3252// xxx.ets 3253import { webview } from '@kit.ArkWeb'; 3254import { BusinessError } from '@kit.BasicServicesKit'; 3255 3256@Entry 3257@Component 3258struct WebComponent { 3259 controller: webview.WebviewController = new webview.WebviewController(); 3260 3261 build() { 3262 Column() { 3263 Button('getUserAgent') 3264 .onClick(() => { 3265 try { 3266 let userAgent = this.controller.getUserAgent(); 3267 console.log("userAgent: " + userAgent); 3268 } catch (error) { 3269 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3270 } 3271 }) 3272 Web({ src: 'www.example.com', controller: this.controller }) 3273 } 3274 } 3275} 3276``` 3277 3278支持开发者基于默认的UserAgent去定制UserAgent。 3279```ts 3280// xxx.ets 3281import { webview } from '@kit.ArkWeb'; 3282import { BusinessError } from '@kit.BasicServicesKit'; 3283 3284@Entry 3285@Component 3286struct WebComponent { 3287 controller: webview.WebviewController = new webview.WebviewController(); 3288 @State ua: string = ""; 3289 3290 aboutToAppear(): void { 3291 webview.once('webInited', () => { 3292 try { 3293 // 应用侧用法示例，定制UserAgent。 3294 this.ua = this.controller.getUserAgent() + 'xxx'; 3295 this.controller.setCustomUserAgent(this.ua); 3296 } catch (error) { 3297 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3298 } 3299 }) 3300 } 3301 3302 build() { 3303 Column() { 3304 Web({ src: 'www.example.com', controller: this.controller }) 3305 } 3306 } 3307} 3308``` 3309 3310### getTitle 3311 3312getTitle(): string 3313 3314获取当前网页的标题。 3315 3316**系统能力：** SystemCapability.Web.Webview.Core 3317 3318**返回值：** 3319 3320| 类型 | 说明 | 3321| ------ | -------------------- | 3322| string | 当前网页的标题。 | 3323 3324**错误码：** 3325 3326以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3327 3328| 错误码ID | 错误信息 | 3329| -------- | ------------------------------------------------------------ | 3330| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3331 3332**示例:** 3333 3334```ts 3335// xxx.ets 3336import { webview } from '@kit.ArkWeb'; 3337import { BusinessError } from '@kit.BasicServicesKit'; 3338 3339@Entry 3340@Component 3341struct WebComponent { 3342 controller: webview.WebviewController = new webview.WebviewController(); 3343 3344 build() { 3345 Column() { 3346 Button('getTitle') 3347 .onClick(() => { 3348 try { 3349 let title = this.controller.getTitle(); 3350 console.log("title: " + title); 3351 } catch (error) { 3352 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3353 } 3354 }) 3355 Web({ src: 'www.example.com', controller: this.controller }) 3356 } 3357 } 3358} 3359``` 3360 3361### getPageHeight 3362 3363getPageHeight(): number 3364 3365获取当前网页的页面高度。 3366 3367**系统能力：** SystemCapability.Web.Webview.Core 3368 3369**返回值：** 3370 3371| 类型 | 说明 | 3372| ------ | -------------------- | 3373| number | 当前网页的页面高度。单位：vp。 | 3374 3375**错误码：** 3376 3377以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3378 3379| 错误码ID | 错误信息 | 3380| -------- | ------------------------------------------------------------ | 3381| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3382 3383**示例:** 3384 3385```ts 3386// xxx.ets 3387import { webview } from '@kit.ArkWeb'; 3388import { BusinessError } from '@kit.BasicServicesKit'; 3389 3390@Entry 3391@Component 3392struct WebComponent { 3393 controller: webview.WebviewController = new webview.WebviewController(); 3394 3395 build() { 3396 Column() { 3397 Button('getPageHeight') 3398 .onClick(() => { 3399 try { 3400 let pageHeight = this.controller.getPageHeight(); 3401 console.log("pageHeight : " + pageHeight); 3402 } catch (error) { 3403 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3404 } 3405 }) 3406 Web({ src: 'www.example.com', controller: this.controller }) 3407 } 3408 } 3409} 3410``` 3411 3412### storeWebArchive 3413 3414storeWebArchive(baseName: string, autoName: boolean, callback: AsyncCallback\<string>): void 3415 3416以回调方式异步保存当前页面。 3417 3418**系统能力：** SystemCapability.Web.Webview.Core 3419 3420**参数：** 3421 3422| 参数名 | 类型 | 必填 | 说明 | 3423| -------- | --------------------- | ---- | ------------------------------------------------------------ | 3424| baseName | string | 是 | 生成的离线网页存储位置，该值不能为空。 | 3425| autoName | boolean | 是 | 决定是否自动生成文件名。如果为false，则按baseName的文件名存储；如果为true，则根据当前Url自动生成文件名，并按baseName的文件目录存储。 | 3426| callback | AsyncCallback\<string> | 是 | 返回文件存储路径，保存网页失败会返回null。 | 3427 3428**错误码：** 3429 3430以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3431 3432| 错误码ID | 错误信息 | 3433| -------- | ------------------------------------------------------------ | 3434| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3435| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3436| 17100003 | Invalid resource path or file type. | 3437 3438**示例：** 3439 3440```ts 3441// xxx.ets 3442import { webview } from '@kit.ArkWeb'; 3443import { BusinessError } from '@kit.BasicServicesKit'; 3444 3445@Entry 3446@Component 3447struct WebComponent { 3448 controller: webview.WebviewController = new webview.WebviewController(); 3449 3450 build() { 3451 Column() { 3452 Button('storeWebArchive') 3453 .onClick(() => { 3454 try { 3455 this.controller.storeWebArchive("/data/storage/el2/base/", true, (error, filename) => { 3456 if (error) { 3457 console.error(`save web archive error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3458 return; 3459 } 3460 if (filename != null) { 3461 console.info(`save web archive success: ${filename}`); 3462 } 3463 }); 3464 } catch (error) { 3465 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3466 } 3467 }) 3468 Web({ src: 'www.example.com', controller: this.controller }) 3469 } 3470 } 3471} 3472``` 3473 3474### storeWebArchive 3475 3476storeWebArchive(baseName: string, autoName: boolean): Promise\<string> 3477 3478以Promise方式异步保存当前页面。 3479 3480**系统能力：** SystemCapability.Web.Webview.Core 3481 3482**参数：** 3483 3484| 参数名 | 类型 | 必填 | 说明 | 3485| -------- | -------- | ---- | ------------------------------------------------------------ | 3486| baseName | string | 是 | 生成的离线网页存储位置，该值不能为空。 | 3487| autoName | boolean | 是 | 决定是否自动生成文件名。如果为false，则按baseName的文件名存储；如果为true，则根据当前Url自动生成文件名，并按baseName的文件目录存储。 | 3488 3489**返回值：** 3490 3491| 类型 | 说明 | 3492| --------------- | ----------------------------------------------------- | 3493| Promise\<string> | Promise实例，保存成功返回文件路径，保存失败返回null。 | 3494 3495**错误码：** 3496 3497以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3498 3499| 错误码ID | 错误信息 | 3500| -------- | ------------------------------------------------------------ | 3501| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3502| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3503| 17100003 | Invalid resource path or file type. | 3504 3505**示例：** 3506 3507```ts 3508// xxx.ets 3509import { webview } from '@kit.ArkWeb'; 3510import { BusinessError } from '@kit.BasicServicesKit'; 3511 3512@Entry 3513@Component 3514struct WebComponent { 3515 controller: webview.WebviewController = new webview.WebviewController(); 3516 3517 build() { 3518 Column() { 3519 Button('storeWebArchive') 3520 .onClick(() => { 3521 try { 3522 this.controller.storeWebArchive("/data/storage/el2/base/", true) 3523 .then(filename => { 3524 if (filename != null) { 3525 console.info(`save web archive success: ${filename}`) 3526 } 3527 }) 3528 .catch((error: BusinessError) => { 3529 console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); 3530 }) 3531 } catch (error) { 3532 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3533 } 3534 }) 3535 Web({ src: 'www.example.com', controller: this.controller }) 3536 } 3537 } 3538} 3539``` 3540 3541### getUrl 3542 3543getUrl(): string 3544 3545获取当前页面的url地址。 3546 3547**系统能力：** SystemCapability.Web.Webview.Core 3548 3549**返回值：** 3550 3551| 类型 | 说明 | 3552| ------ | ------------------- | 3553| string | 当前页面的url地址。 | 3554 3555**错误码：** 3556 3557以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3558 3559| 错误码ID | 错误信息 | 3560| -------- | ------------------------------------------------------------ | 3561| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3562 3563**示例：** 3564 3565```ts 3566// xxx.ets 3567import { webview } from '@kit.ArkWeb'; 3568import { BusinessError } from '@kit.BasicServicesKit'; 3569 3570@Entry 3571@Component 3572struct WebComponent { 3573 controller: webview.WebviewController = new webview.WebviewController(); 3574 3575 build() { 3576 Column() { 3577 Button('getUrl') 3578 .onClick(() => { 3579 try { 3580 let url = this.controller.getUrl(); 3581 console.log("url: " + url); 3582 } catch (error) { 3583 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3584 } 3585 }) 3586 Web({ src: 'www.example.com', controller: this.controller }) 3587 } 3588 } 3589} 3590``` 3591 3592### stop 3593 3594stop(): void 3595 3596停止页面加载。 3597 3598**系统能力：** SystemCapability.Web.Webview.Core 3599 3600**错误码：** 3601 3602以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3603 3604| 错误码ID | 错误信息 | 3605| -------- | ------------------------------------------------------------ | 3606| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3607 3608**示例：** 3609 3610```ts 3611// xxx.ets 3612import { webview } from '@kit.ArkWeb'; 3613import { BusinessError } from '@kit.BasicServicesKit'; 3614 3615@Entry 3616@Component 3617struct WebComponent { 3618 controller: webview.WebviewController = new webview.WebviewController(); 3619 3620 build() { 3621 Column() { 3622 Button('stop') 3623 .onClick(() => { 3624 try { 3625 this.controller.stop(); 3626 } catch (error) { 3627 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3628 } 3629 }); 3630 Web({ src: 'www.example.com', controller: this.controller }) 3631 } 3632 } 3633} 3634``` 3635 3636### backOrForward 3637 3638backOrForward(step: number): void 3639 3640按照历史栈，前进或者后退指定步长的页面，当历史栈中不存在对应步长的页面时，不会进行页面跳转。 3641 3642前进或者后退页面时，直接使用已加载过的网页，无需重新加载网页。 3643 3644**系统能力：** SystemCapability.Web.Webview.Core 3645 3646**参数：** 3647 3648| 参数名 | 类型 | 必填 | 说明 | 3649| ------ | -------- | ---- | ---------------------- | 3650| step | number | 是 | 需要前进或后退的步长。 | 3651 3652**错误码：** 3653 3654以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3655 3656| 错误码ID | 错误信息 | 3657| -------- | ------------------------------------------------------------ | 3658| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3659| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3660 3661**示例：** 3662 3663```ts 3664// xxx.ets 3665import { webview } from '@kit.ArkWeb'; 3666import { BusinessError } from '@kit.BasicServicesKit'; 3667 3668@Entry 3669@Component 3670struct WebComponent { 3671 controller: webview.WebviewController = new webview.WebviewController(); 3672 @State step: number = -2; 3673 3674 build() { 3675 Column() { 3676 Button('backOrForward') 3677 .onClick(() => { 3678 try { 3679 this.controller.backOrForward(this.step); 3680 } catch (error) { 3681 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3682 } 3683 }) 3684 Web({ src: 'www.example.com', controller: this.controller }) 3685 } 3686 } 3687} 3688``` 3689 3690### scrollTo 3691 3692scrollTo(x:number, y:number, duration?:number): void 3693 3694在指定时间内，将页面滚动到指定的绝对位置。 3695 3696**系统能力：** SystemCapability.Web.Webview.Core 3697 3698**参数：** 3699 3700| 参数名 | 类型 | 必填 | 说明 | 3701| ------ | -------- | ---- | ---------------------- | 3702| x | number | 是 | 绝对位置的水平坐标，当传入数值为负数时，按照传入0处理。单位：vp。 | 3703| y | number | 是 | 绝对位置的垂直坐标，当传入数值为负数时，按照传入0处理。单位：vp。| 3704| duration<sup>14+</sup> | number | 否 | 滚动动画时间。<br>单位：ms。<br>不传入为无动画，当传入数值为负数或传入0时，按照不传入处理。 | 3705 3706**错误码：** 3707 3708以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3709 3710| 错误码ID | 错误信息 | 3711| -------- | ------------------------------------------------------------ | 3712| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3713| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3714 3715**示例：** 3716 3717```ts 3718// xxx.ets 3719import { webview } from '@kit.ArkWeb'; 3720import { BusinessError } from '@kit.BasicServicesKit'; 3721 3722@Entry 3723@Component 3724struct WebComponent { 3725 controller: webview.WebviewController = new webview.WebviewController(); 3726 3727 build() { 3728 Column() { 3729 Button('scrollTo') 3730 .onClick(() => { 3731 try { 3732 this.controller.scrollTo(50, 50, 500); 3733 } catch (error) { 3734 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3735 } 3736 }) 3737 Button('stopScroll') 3738 .onClick(() => { 3739 try { 3740 this.controller.scrollBy(0, 0, 1); //如果想停止当前scroll产生的动画，可再次生成一个1ms的动画去打断该动画。 3741 } catch (error) { 3742 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3743 } 3744 }) 3745 Web({ src: $rawfile('index.html'), controller: this.controller }) 3746 } 3747 } 3748} 3749``` 3750 3751加载的html文件。 3752```html 3753<!--index.html--> 3754<!DOCTYPE html> 3755<html> 3756<head> 3757 <title>Demo</title> 3758 <style> 3759 body { 3760 width:2000px; 3761 height:2000px; 3762 padding-right:170px; 3763 padding-left:170px; 3764 border:5px solid blueviolet 3765 } 3766 </style> 3767</head> 3768<body> 3769Scroll Test 3770</body> 3771</html> 3772``` 3773 3774### scrollBy 3775 3776scrollBy(deltaX:number, deltaY:number,duration?:number): void 3777 3778在指定时间内将页面滚动指定的偏移量。 3779 3780**系统能力：** SystemCapability.Web.Webview.Core 3781 3782**参数：** 3783 3784| 参数名 | 类型 | 必填 | 说明 | 3785| ------ | -------- | ---- | ---------------------- | 3786| deltaX | number | 是 | 水平偏移量，其中水平向右为正方向。单位：vp。 | 3787| deltaY | number | 是 | 垂直偏移量，其中垂直向下为正方向。单位：vp。 | 3788| duration<sup>14+</sup> | number | 否 | 滚动动画时间。<br>单位：ms。<br>不传入为无动画，当传入数值为负数或传入0时，按照不传入处理。 | 3789 3790**错误码：** 3791 3792以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3793 3794| 错误码ID | 错误信息 | 3795| -------- | ------------------------------------------------------------ | 3796| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3797| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3798 3799> **说明：** 3800> 3801> 嵌套滚动场景中，调用scrollBy不会触发父组件的嵌套滚动。 3802 3803**示例：** 3804 3805```ts 3806// xxx.ets 3807import { webview } from '@kit.ArkWeb'; 3808import { BusinessError } from '@kit.BasicServicesKit'; 3809 3810@Entry 3811@Component 3812struct WebComponent { 3813 controller: webview.WebviewController = new webview.WebviewController(); 3814 3815 build() { 3816 Column() { 3817 Button('scrollBy') 3818 .onClick(() => { 3819 try { 3820 this.controller.scrollBy(50, 50, 500); 3821 } catch (error) { 3822 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3823 } 3824 }) 3825 Button('stopScroll') 3826 .onClick(() => { 3827 try { 3828 this.controller.scrollBy(0, 0, 1); //如果想停止当前scroll产生的动画，可再次生成一个1ms的动画去打断该动画。 3829 } catch (error) { 3830 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3831 } 3832 }) 3833 Web({ src: $rawfile('index.html'), controller: this.controller }) 3834 } 3835 } 3836} 3837``` 3838 3839加载的html文件。 3840```html 3841<!--index.html--> 3842<!DOCTYPE html> 3843<html> 3844<head> 3845 <title>Demo</title> 3846 <style> 3847 body { 3848 width:2000px; 3849 height:2000px; 3850 padding-right:170px; 3851 padding-left:170px; 3852 border:5px solid blueviolet 3853 } 3854 </style> 3855</head> 3856<body> 3857Scroll Test 3858</body> 3859</html> 3860``` 3861### scrollByWithResult<sup>12+</sup> 3862 3863scrollByWithResult(deltaX: number, deltaY: number): boolean 3864 3865将页面滚动指定的偏移量，返回值表示此次滚动是否执行成功。 3866 3867**系统能力：** SystemCapability.Web.Webview.Core 3868 3869**参数：** 3870 3871| 参数名 | 类型 | 必填 | 说明 | 3872| ------ | -------- | ---- | ---------------------- | 3873| deltaX | number | 是 | 水平偏移量，其中水平向右为正方向。 | 3874| deltaY | number | 是 | 垂直偏移量，其中垂直向下为正方向。 | 3875 3876**返回值：** 3877 3878| 类型 | 说明 | 3879| ------- | --------------------------------------- | 3880| boolean | 当前网页是否可以滑动，默认为false。| 3881 3882**错误码：** 3883 3884以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3885 3886| 错误码ID | 错误信息 | 3887| -------- | ------------------------------------------------------------ | 3888| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3889| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3890 3891> **说明：** 3892> 3893> - 返回值场景：Web页面处于触摸中状态时，返回false，否则返回true。 3894> - 同层渲染场景中，Web的同层渲染区域处于触摸中状态时，返回值为true。 3895> - 嵌套滚动场景中，调用scrollByWithResult不会触发父组件的嵌套滚动。 3896> - 此接口不保证滑动帧率性能。 3897 3898**示例：** 3899 3900```ts 3901// xxx.ets 3902import { webview } from '@kit.ArkWeb'; 3903import { BusinessError } from '@kit.BasicServicesKit'; 3904 3905@Entry 3906@Component 3907struct WebComponent { 3908 controller: webview.WebviewController = new webview.WebviewController(); 3909 3910 build() { 3911 Column() { 3912 Button('scrollByWithResult') 3913 .onClick(() => { 3914 try { 3915 let result = this.controller.scrollByWithResult(50, 50); 3916 console.log("original result: " + result); 3917 } catch (error) { 3918 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3919 } 3920 }) 3921 Web({ src: $rawfile('index.html'), controller: this.controller }) 3922 } 3923 } 3924} 3925``` 3926 3927加载的html文件。 3928```html 3929<!--index.html--> 3930<!DOCTYPE html> 3931<html> 3932<head> 3933 <title>Demo</title> 3934 <style> 3935 body { 3936 width:2000px; 3937 height:2000px; 3938 padding-right:170px; 3939 padding-left:170px; 3940 border:5px solid blueviolet 3941 } 3942 </style> 3943</head> 3944<body> 3945Scroll Test 3946</body> 3947</html> 3948``` 3949### slideScroll 3950 3951slideScroll(vx:number, vy:number): void 3952 3953按照指定速度模拟对页面的轻扫滚动动作。 3954 3955**系统能力：** SystemCapability.Web.Webview.Core 3956 3957**参数：** 3958 3959| 参数名 | 类型 | 必填 | 说明 | 3960| ------ | -------- | ---- | ---------------------- | 3961| vx | number | 是 | 轻扫滚动的水平速度分量，其中水平向右为速度正方向。单位：vp/ms。 | 3962| vy | number | 是 | 轻扫滚动的垂直速度分量，其中垂直向下为速度正方向。单位：vp/ms。 | 3963 3964**错误码：** 3965 3966以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 3967 3968| 错误码ID | 错误信息 | 3969| -------- | ------------------------------------------------------------ | 3970| 17100001 | Init error. The WebviewController must be associated with a Web component. | 3971| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3972 3973**示例：** 3974 3975```ts 3976// xxx.ets 3977import { webview } from '@kit.ArkWeb'; 3978import { BusinessError } from '@kit.BasicServicesKit'; 3979 3980@Entry 3981@Component 3982struct WebComponent { 3983 controller: webview.WebviewController = new webview.WebviewController(); 3984 3985 build() { 3986 Column() { 3987 Button('slideScroll') 3988 .onClick(() => { 3989 try { 3990 this.controller.slideScroll(500, 500); 3991 } catch (error) { 3992 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 3993 } 3994 }) 3995 Web({ src: $rawfile('index.html'), controller: this.controller }) 3996 } 3997 } 3998} 3999``` 4000 4001加载的html文件。 4002```html 4003<!--index.html--> 4004<!DOCTYPE html> 4005<html> 4006<head> 4007 <title>Demo</title> 4008 <style> 4009 body { 4010 width:3000px; 4011 height:3000px; 4012 padding-right:170px; 4013 padding-left:170px; 4014 border:5px solid blueviolet 4015 } 4016 </style> 4017</head> 4018<body> 4019Scroll Test 4020</body> 4021</html> 4022``` 4023 4024### getOriginalUrl 4025 4026getOriginalUrl(): string 4027 4028获取当前页面的原始url地址。 4029风险提示：如果想获取url来做JavascriptProxy通信接口认证，请使用[getLastJavascriptProxyCallingFrameUrl<sup>12+</sup>](#getlastjavascriptproxycallingframeurl12) 4030 4031**系统能力：** SystemCapability.Web.Webview.Core 4032 4033**返回值：** 4034 4035| 类型 | 说明 | 4036| ------ | ----------------------- | 4037| string | 当前页面的原始url地址。 | 4038 4039**错误码：** 4040 4041以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4042 4043| 错误码ID | 错误信息 | 4044| -------- | ------------------------------------------------------------ | 4045| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4046 4047**示例：** 4048 4049```ts 4050// xxx.ets 4051import { webview } from '@kit.ArkWeb'; 4052import { BusinessError } from '@kit.BasicServicesKit'; 4053 4054@Entry 4055@Component 4056struct WebComponent { 4057 controller: webview.WebviewController = new webview.WebviewController(); 4058 4059 build() { 4060 Column() { 4061 Button('getOrgUrl') 4062 .onClick(() => { 4063 try { 4064 let url = this.controller.getOriginalUrl(); 4065 console.log("original url: " + url); 4066 } catch (error) { 4067 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4068 } 4069 }) 4070 Web({ src: 'www.example.com', controller: this.controller }) 4071 } 4072 } 4073} 4074``` 4075 4076### getFavicon 4077 4078getFavicon(): image.PixelMap 4079 4080获取页面的favicon图标。 4081 4082**系统能力：** SystemCapability.Web.Webview.Core 4083 4084**返回值：** 4085 4086| 类型 | 说明 | 4087| -------------------------------------- | ------------------------------- | 4088| [PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | 页面favicon图标的PixelMap对象。 | 4089 4090**错误码：** 4091 4092以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4093 4094| 错误码ID | 错误信息 | 4095| -------- | ------------------------------------------------------------ | 4096| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4097 4098**示例：** 4099 4100```ts 4101// xxx.ets 4102import { webview } from '@kit.ArkWeb'; 4103import { BusinessError } from '@kit.BasicServicesKit'; 4104import { image } from '@kit.ImageKit'; 4105 4106@Entry 4107@Component 4108struct WebComponent { 4109 controller: webview.WebviewController = new webview.WebviewController(); 4110 @State pixelmap: image.PixelMap | undefined = undefined; 4111 4112 build() { 4113 Column() { 4114 Button('getFavicon') 4115 .onClick(() => { 4116 try { 4117 this.pixelmap = this.controller.getFavicon(); 4118 } catch (error) { 4119 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4120 } 4121 }) 4122 Web({ src: 'www.example.com', controller: this.controller }) 4123 } 4124 } 4125} 4126``` 4127 4128### setNetworkAvailable 4129 4130setNetworkAvailable(enable: boolean): void 4131 4132设置JavaScript中的window.navigator.onLine属性。 4133 4134**系统能力：** SystemCapability.Web.Webview.Core 4135 4136**参数：** 4137 4138| 参数名 | 类型 | 必填 | 说明 | 4139| ------ | ------- | ---- | --------------------------------- | 4140| enable | boolean | 是 | 是否使能window.navigator.onLine。 | 4141 4142**错误码：** 4143 4144以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4145 4146| 错误码ID | 错误信息 | 4147| -------- | ------------------------------------------------------------ | 4148| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4149| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 4150 4151**示例：** 4152 4153```ts 4154// xxx.ets 4155import { webview } from '@kit.ArkWeb'; 4156import { BusinessError } from '@kit.BasicServicesKit'; 4157 4158@Entry 4159@Component 4160struct WebComponent { 4161 controller: webview.WebviewController = new webview.WebviewController(); 4162 4163 build() { 4164 Column() { 4165 Button('setNetworkAvailable') 4166 .onClick(() => { 4167 try { 4168 this.controller.setNetworkAvailable(true); 4169 } catch (error) { 4170 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4171 } 4172 }) 4173 Web({ src: $rawfile('index.html'), controller: this.controller }) 4174 } 4175 } 4176} 4177``` 4178 4179加载的html文件。 4180```html 4181<!-- index.html --> 4182<!DOCTYPE html> 4183<html> 4184<body> 4185<h1>online 属性</h1> 4186<p id="demo"></p> 4187<button onclick="func()">click</button> 4188<script> 4189 let online = navigator.onLine; 4190 document.getElementById("demo").innerHTML = "浏览器在线：" + online; 4191 4192 function func(){ 4193 var online = navigator.onLine; 4194 document.getElementById("demo").innerHTML = "浏览器在线：" + online; 4195 } 4196</script> 4197</body> 4198</html> 4199``` 4200 4201### hasImage 4202 4203hasImage(callback: AsyncCallback\<boolean>): void 4204 4205通过Callback方式异步查找当前页面是否存在图像。 4206 4207**系统能力：** SystemCapability.Web.Webview.Core 4208 4209**参数：** 4210 4211| 参数名 | 类型 | 必填 | 说明 | 4212| -------- | ----------------------- | ---- | -------------------------- | 4213| callback | AsyncCallback\<boolean> | 是 | 返回查找页面是否存在图像。 | 4214 4215**错误码：** 4216 4217以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4218 4219| 错误码ID | 错误信息 | 4220| -------- | ------------------------------------------------------------ | 4221| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4222| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 4223 4224**示例：** 4225 4226```ts 4227// xxx.ets 4228import { webview } from '@kit.ArkWeb'; 4229import { BusinessError } from '@kit.BasicServicesKit'; 4230 4231@Entry 4232@Component 4233struct WebComponent { 4234 controller: webview.WebviewController = new webview.WebviewController(); 4235 4236 build() { 4237 Column() { 4238 Button('hasImageCb') 4239 .onClick(() => { 4240 try { 4241 this.controller.hasImage((error, data) => { 4242 if (error) { 4243 console.error(`hasImage error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4244 return; 4245 } 4246 console.info("hasImage: " + data); 4247 }); 4248 } catch (error) { 4249 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4250 } 4251 }) 4252 Web({ src: 'www.example.com', controller: this.controller }) 4253 } 4254 } 4255} 4256``` 4257 4258### hasImage 4259 4260hasImage(): Promise\<boolean> 4261 4262通过Promise方式异步查找当前页面是否存在图像。 4263 4264**系统能力：** SystemCapability.Web.Webview.Core 4265 4266**返回值：** 4267 4268| 类型 | 说明 | 4269| ----------------- | --------------------------------------- | 4270| Promise\<boolean> | Promise实例，返回查找页面是否存在图像。 | 4271 4272**错误码：** 4273 4274以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4275 4276| 错误码ID | 错误信息 | 4277| -------- | ------------------------------------------------------------ | 4278| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4279| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 4280 4281**示例：** 4282 4283```ts 4284// xxx.ets 4285import { webview } from '@kit.ArkWeb'; 4286import { BusinessError } from '@kit.BasicServicesKit'; 4287 4288@Entry 4289@Component 4290struct WebComponent { 4291 controller: webview.WebviewController = new webview.WebviewController(); 4292 4293 build() { 4294 Column() { 4295 Button('hasImagePm') 4296 .onClick(() => { 4297 try { 4298 this.controller.hasImage().then((data) => { 4299 console.info('hasImage: ' + data); 4300 }).catch((error: BusinessError) => { 4301 console.error("error: " + error); 4302 }) 4303 } catch (error) { 4304 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4305 } 4306 }) 4307 Web({ src: 'www.example.com', controller: this.controller }) 4308 } 4309 } 4310} 4311``` 4312 4313### removeCache 4314 4315removeCache(clearRom: boolean): void 4316 4317清除应用中的资源缓存文件，此方法将会清除同一应用中所有webview的缓存文件。 4318 4319> **说明：** 4320> 4321> 可以通过在data/storage/el2/base/cache/web/Cache目录下查看Webview的缓存。 4322 4323**系统能力：** SystemCapability.Web.Webview.Core 4324 4325**参数：** 4326 4327| 参数名 | 类型 | 必填 | 说明 | 4328| -------- | ------- | ---- | -------------------------------------------------------- | 4329| clearRom | boolean | 是 | 设置为true时同时清除rom和ram中的缓存，设置为false时只清除ram中的缓存。 | 4330 4331**错误码：** 4332 4333以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4334 4335| 错误码ID | 错误信息 | 4336| -------- | ------------------------------------------------------------ | 4337| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4338| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 4339 4340**示例：** 4341 4342```ts 4343// xxx.ets 4344import { webview } from '@kit.ArkWeb'; 4345import { BusinessError } from '@kit.BasicServicesKit'; 4346 4347@Entry 4348@Component 4349struct WebComponent { 4350 controller: webview.WebviewController = new webview.WebviewController(); 4351 4352 build() { 4353 Column() { 4354 Button('removeCache') 4355 .onClick(() => { 4356 try { 4357 this.controller.removeCache(false); 4358 } catch (error) { 4359 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4360 } 4361 }) 4362 Web({ src: 'www.example.com', controller: this.controller }) 4363 } 4364 } 4365} 4366``` 4367 4368### pageUp 4369 4370pageUp(top: boolean): void 4371 4372将Webview的内容向上滚动半个视框大小或者跳转到页面最顶部，通过top入参控制。 4373 4374**系统能力：** SystemCapability.Web.Webview.Core 4375 4376**参数：** 4377 4378| 参数名 | 类型 | 必填 | 说明 | 4379| ------ | ------- | ---- | ------------------------------------------------------------ | 4380| top | boolean | 是 | 是否跳转到页面最顶部，设置为false时将页面内容向上滚动半个视框大小，设置为true时跳转到页面最顶部。 | 4381 4382**错误码：** 4383 4384以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4385 4386| 错误码ID | 错误信息 | 4387| -------- | ------------------------------------------------------------ | 4388| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4389| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 4390 4391**示例：** 4392 4393```ts 4394// xxx.ets 4395import { webview } from '@kit.ArkWeb'; 4396import { BusinessError } from '@kit.BasicServicesKit'; 4397 4398@Entry 4399@Component 4400struct WebComponent { 4401 controller: webview.WebviewController = new webview.WebviewController(); 4402 4403 build() { 4404 Column() { 4405 Button('pageUp') 4406 .onClick(() => { 4407 try { 4408 this.controller.pageUp(false); 4409 } catch (error) { 4410 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4411 } 4412 }) 4413 Web({ src: 'www.example.com', controller: this.controller }) 4414 } 4415 } 4416} 4417``` 4418 4419### pageDown 4420 4421pageDown(bottom: boolean): void 4422 4423将Webview的内容向下滚动半个视框大小或者跳转到页面最底部，通过bottom入参控制。 4424 4425**系统能力：** SystemCapability.Web.Webview.Core 4426 4427**参数：** 4428 4429| 参数名 | 类型 | 必填 | 说明 | 4430| ------ | ------- | ---- | ------------------------------------------------------------ | 4431| bottom | boolean | 是 | 是否跳转到页面最底部，设置为false时将页面内容向下滚动半个视框大小，设置为true时跳转到页面最底部。 | 4432 4433**错误码：** 4434 4435以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4436 4437| 错误码ID | 错误信息 | 4438| -------- | ------------------------------------------------------------ | 4439| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4440| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 4441 4442**示例：** 4443 4444```ts 4445// xxx.ets 4446import { webview } from '@kit.ArkWeb'; 4447import { BusinessError } from '@kit.BasicServicesKit'; 4448 4449@Entry 4450@Component 4451struct WebComponent { 4452 controller: webview.WebviewController = new webview.WebviewController(); 4453 4454 build() { 4455 Column() { 4456 Button('pageDown') 4457 .onClick(() => { 4458 try { 4459 this.controller.pageDown(false); 4460 } catch (error) { 4461 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4462 } 4463 }) 4464 Web({ src: 'www.example.com', controller: this.controller }) 4465 } 4466 } 4467} 4468``` 4469 4470### getBackForwardEntries 4471 4472getBackForwardEntries(): BackForwardList 4473 4474获取当前Webview的历史信息列表。 4475 4476**系统能力：** SystemCapability.Web.Webview.Core 4477 4478**返回值：** 4479 4480| 类型 | 说明 | 4481| ----------------------------------- | --------------------------- | 4482| [BackForwardList](#backforwardlist) | 当前Webview的历史信息列表。 | 4483 4484**错误码：** 4485 4486以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4487 4488| 错误码ID | 错误信息 | 4489| -------- | ------------------------------------------------------------ | 4490| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4491 4492**示例：** 4493 4494```ts 4495// xxx.ets 4496import { webview } from '@kit.ArkWeb'; 4497import { BusinessError } from '@kit.BasicServicesKit'; 4498 4499@Entry 4500@Component 4501struct WebComponent { 4502 controller: webview.WebviewController = new webview.WebviewController(); 4503 4504 build() { 4505 Column() { 4506 Button('getBackForwardEntries') 4507 .onClick(() => { 4508 try { 4509 let list = this.controller.getBackForwardEntries() 4510 } catch (error) { 4511 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4512 } 4513 }) 4514 Web({ src: 'www.example.com', controller: this.controller }) 4515 } 4516 } 4517} 4518``` 4519 4520### serializeWebState 4521 4522serializeWebState(): Uint8Array 4523 4524将当前Webview的页面状态历史记录信息序列化。 4525 4526**系统能力：** SystemCapability.Web.Webview.Core 4527 4528**返回值：** 4529 4530| 类型 | 说明 | 4531| ---------- | --------------------------------------------- | 4532| Uint8Array | 当前Webview的页面状态历史记录序列化后的数据。 | 4533 4534**错误码：** 4535 4536以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4537 4538| 错误码ID | 错误信息 | 4539| -------- | ------------------------------------------------------------ | 4540| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4541 4542**示例：** 4543 45441.对文件的操作需要导入文件管理模块，详情请参考[文件管理](../apis-core-file-kit/js-apis-file-fs.md)。 4545```ts 4546// xxx.ets 4547import { webview } from '@kit.ArkWeb'; 4548import { BusinessError } from '@kit.BasicServicesKit'; 4549import { fileIo } from '@kit.CoreFileKit'; 4550 4551@Entry 4552@Component 4553struct WebComponent { 4554 controller: webview.WebviewController = new webview.WebviewController(); 4555 4556 build() { 4557 Column() { 4558 Button('serializeWebState') 4559 .onClick(() => { 4560 try { 4561 let state = this.controller.serializeWebState(); 4562 let path:string | undefined = AppStorage.get("cacheDir"); 4563 if (path) { 4564 path += '/WebState'; 4565 // 以同步方法打开文件。 4566 let file = fileIo.openSync(path, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE); 4567 fileIo.writeSync(file.fd, state.buffer); 4568 fileIo.closeSync(file.fd); 4569 } 4570 } catch (error) { 4571 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4572 } 4573 }) 4574 Web({ src: 'www.example.com', controller: this.controller }) 4575 } 4576 } 4577} 4578``` 4579 45802.修改EntryAbility.ets。 4581获取应用缓存文件路径。 4582```ts 4583// xxx.ets 4584import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 4585 4586export default class EntryAbility extends UIAbility { 4587 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 4588 // 通过在AppStorage对象上绑定cacheDir，可以实现UIAbility组件与Page之间的数据同步。 4589 AppStorage.setOrCreate("cacheDir", this.context.cacheDir); 4590 } 4591} 4592``` 4593 4594### restoreWebState 4595 4596restoreWebState(state: Uint8Array): void 4597 4598当前Webview从序列化数据中恢复页面状态历史记录。 4599 4600如果state过大，可能会导致异常。建议state大于512k时，放弃恢复页面状态历史记录。 4601 4602**系统能力：** SystemCapability.Web.Webview.Core 4603 4604**参数：** 4605 4606| 参数名 | 类型 | 必填 | 说明 | 4607| ------ | ---------- | ---- | ---------------------------- | 4608| state | Uint8Array | 是 | 页面状态历史记录序列化数据。 | 4609 4610**错误码：** 4611 4612以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4613 4614| 错误码ID | 错误信息 | 4615| -------- | ------------------------------------------------------------ | 4616| 17100001 | Init error. The WebviewController must be associated with a Web component. | 4617| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 4618 4619**示例：** 4620 46211.对文件的操作需要导入文件管理模块，详情请参考[文件管理](../apis-core-file-kit/js-apis-file-fs.md)。 4622```ts 4623// xxx.ets 4624import { webview } from '@kit.ArkWeb'; 4625import { BusinessError } from '@kit.BasicServicesKit'; 4626import { fileIo } from '@kit.CoreFileKit'; 4627 4628@Entry 4629@Component 4630struct WebComponent { 4631 controller: webview.WebviewController = new webview.WebviewController(); 4632 4633 build() { 4634 Column() { 4635 Button('RestoreWebState') 4636 .onClick(() => { 4637 try { 4638 let path: string | undefined = AppStorage.get("cacheDir"); 4639 if (path) { 4640 path += '/WebState'; 4641 // 以同步方法打开文件。 4642 let file = fileIo.openSync(path, fileIo.OpenMode.READ_WRITE); 4643 let stat = fileIo.statSync(path); 4644 let size = stat.size; 4645 let buf = new ArrayBuffer(size); 4646 fileIo.read(file.fd, buf, (err, readLen) => { 4647 if (err) { 4648 console.info("mkdir failed with error message: " + err.message + ", error code: " + err.code); 4649 } else { 4650 console.info("read file data succeed"); 4651 this.controller.restoreWebState(new Uint8Array(buf.slice(0, readLen))); 4652 fileIo.closeSync(file); 4653 } 4654 }); 4655 } 4656 } catch (error) { 4657 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4658 } 4659 }) 4660 Web({ src: 'www.example.com', controller: this.controller }) 4661 } 4662 } 4663} 4664``` 4665 46662.修改EntryAbility.ets。 4667获取应用缓存文件路径。 4668```ts 4669// xxx.ets 4670import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 4671 4672export default class EntryAbility extends UIAbility { 4673 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 4674 // 通过在AppStorage对象上绑定cacheDir，可以实现UIAbility组件与Page之间的数据同步。 4675 AppStorage.setOrCreate("cacheDir", this.context.cacheDir); 4676 } 4677} 4678``` 4679 4680### customizeSchemes 4681 4682static customizeSchemes(schemes: Array\<WebCustomScheme\>): void 4683 4684对Web内核赋予自定义协议url的跨域请求与fetch请求的权限。当Web在跨域fetch自定义协议url时，该fetch请求可被onInterceptRequest事件接口所拦截，从而开发者可以进一步处理该请求。建议在任何Web组件初始化之前调用该接口。 4685 4686**系统能力：** SystemCapability.Web.Webview.Core 4687 4688**参数：** 4689 4690| 参数名 | 类型 | 必填 | 说明 | 4691| -------- | ------- | ---- | -------------------------------------- | 4692| schemes | Array\<[WebCustomScheme](#webcustomscheme)\> | 是 | 自定义协议配置，最多支持同时配置10个自定义协议。 | 4693 4694**错误码：** 4695 4696以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4697 4698| 错误码ID | 错误信息 | 4699| -------- | ------------------------------------------------------------ | 4700| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 4701| 17100020 | Failed to register custom schemes. | 4702 4703**示例：** 4704 4705```ts 4706// xxx.ets 4707import { webview } from '@kit.ArkWeb'; 4708import { BusinessError } from '@kit.BasicServicesKit'; 4709 4710@Entry 4711@Component 4712struct WebComponent { 4713 controller: webview.WebviewController = new webview.WebviewController(); 4714 responseWeb: WebResourceResponse = new WebResourceResponse(); 4715 scheme1: webview.WebCustomScheme = { schemeName: "name1", isSupportCORS: true, isSupportFetch: true }; 4716 scheme2: webview.WebCustomScheme = { schemeName: "name2", isSupportCORS: true, isSupportFetch: true }; 4717 scheme3: webview.WebCustomScheme = { schemeName: "name3", isSupportCORS: true, isSupportFetch: true }; 4718 4719 aboutToAppear(): void { 4720 try { 4721 webview.WebviewController.customizeSchemes([this.scheme1, this.scheme2, this.scheme3]); 4722 } catch (error) { 4723 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 4724 } 4725 } 4726 4727 build() { 4728 Column() { 4729 Web({ src: 'www.example.com', controller: this.controller }) 4730 .onInterceptRequest((event) => { 4731 if (event) { 4732 console.log('url:' + event.request.getRequestUrl()); 4733 } 4734 return this.responseWeb; 4735 }) 4736 } 4737 } 4738} 4739``` 4740 4741### getCertificate<sup>10+</sup> 4742 4743getCertificate(): Promise<Array<cert.X509Cert>> 4744 4745获取当前网站的证书信息。使用Web组件加载https网站，会进行SSL证书校验，该接口会通过Promise异步返回当前网站的X509格式证书（X509Cert证书类型定义见[X509Cert](../apis-device-certificate-kit/js-apis-cert.md#x509cert)定义），便于开发者展示网站证书信息。 4746 4747**系统能力：** SystemCapability.Web.Webview.Core 4748 4749**返回值：** 4750 4751| 类型 | 说明 | 4752| ---------- | --------------------------------------------- | 4753| Promise<Array<cert.X509Cert>> | Promise实例，用于获取当前加载的https网站的X509格式证书数组。 | 4754 4755**错误码：** 4756 4757以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4758 4759| 错误码ID | 错误信息 | 4760| -------- | ------------------------------------------------------------ | 4761| 17100001 | Init error. The WebviewController must be associated with a web component. | 4762 4763**示例：** 4764 4765```ts 4766// xxx.ets 4767import { webview } from '@kit.ArkWeb'; 4768import { BusinessError } from '@kit.BasicServicesKit'; 4769import { cert } from '@kit.DeviceCertificateKit'; 4770 4771function Uint8ArrayToString(dataArray: Uint8Array) { 4772 let dataString = ''; 4773 for (let i = 0; i < dataArray.length; i++) { 4774 dataString += String.fromCharCode(dataArray[i]); 4775 } 4776 return dataString; 4777} 4778 4779function ParseX509CertInfo(x509CertArray: Array<cert.X509Cert>) { 4780 let res: string = 'getCertificate success: len = ' + x509CertArray.length; 4781 for (let i = 0; i < x509CertArray.length; i++) { 4782 res += ', index = ' + i + ', issuer name = ' 4783 + Uint8ArrayToString(x509CertArray[i].getIssuerName().data) + ', subject name = ' 4784 + Uint8ArrayToString(x509CertArray[i].getSubjectName().data) + ', valid start = ' 4785 + x509CertArray[i].getNotBeforeTime() 4786 + ', valid end = ' + x509CertArray[i].getNotAfterTime(); 4787 } 4788 return res; 4789} 4790 4791@Entry 4792@Component 4793struct Index { 4794 // outputStr在UI界面显示调试信息 4795 @State outputStr: string = ''; 4796 webviewCtl: webview.WebviewController = new webview.WebviewController(); 4797 4798 build() { 4799 Row() { 4800 Column() { 4801 List({ space: 20, initialIndex: 0 }) { 4802 ListItem() { 4803 Button() { 4804 Text('load bad ssl') 4805 .fontSize(10) 4806 .fontWeight(FontWeight.Bold) 4807 } 4808 .type(ButtonType.Capsule) 4809 .onClick(() => { 4810 // 加载一个过期的证书网站，查看获取到的证书信息 4811 this.webviewCtl.loadUrl('https://expired.badssl.com'); 4812 }) 4813 .height(50) 4814 } 4815 4816 ListItem() { 4817 Button() { 4818 Text('load example') 4819 .fontSize(10) 4820 .fontWeight(FontWeight.Bold) 4821 } 4822 .type(ButtonType.Capsule) 4823 .onClick(() => { 4824 // 加载一个https网站，查看网站的证书信息 4825 this.webviewCtl.loadUrl('https://www.example.com'); 4826 }) 4827 .height(50) 4828 } 4829 4830 ListItem() { 4831 Button() { 4832 Text('getCertificate Promise') 4833 .fontSize(10) 4834 .fontWeight(FontWeight.Bold) 4835 } 4836 .type(ButtonType.Capsule) 4837 .onClick(() => { 4838 try { 4839 this.webviewCtl.getCertificate().then((x509CertArray: Array<cert.X509Cert>) => { 4840 this.outputStr = ParseX509CertInfo(x509CertArray); 4841 }) 4842 } catch (error) { 4843 this.outputStr = 'getCertificate failed: ' + (error as BusinessError).code + ", errMsg: " + (error as BusinessError).message; 4844 } 4845 }) 4846 .height(50) 4847 } 4848 4849 ListItem() { 4850 Button() { 4851 Text('getCertificate AsyncCallback') 4852 .fontSize(10) 4853 .fontWeight(FontWeight.Bold) 4854 } 4855 .type(ButtonType.Capsule) 4856 .onClick(() => { 4857 try { 4858 this.webviewCtl.getCertificate((error: BusinessError, x509CertArray: Array<cert.X509Cert>) => { 4859 if (error) { 4860 this.outputStr = 'getCertificate failed: ' + error.code + ", errMsg: " + error.message; 4861 } else { 4862 this.outputStr = ParseX509CertInfo(x509CertArray); 4863 } 4864 }) 4865 } catch (error) { 4866 this.outputStr = 'getCertificate failed: ' + (error as BusinessError).code + ", errMsg: " + (error as BusinessError).message; 4867 } 4868 }) 4869 .height(50) 4870 } 4871 } 4872 .listDirection(Axis.Horizontal) 4873 .height('10%') 4874 4875 Text(this.outputStr) 4876 .width('100%') 4877 .fontSize(10) 4878 4879 Web({ src: 'https://www.example.com', controller: this.webviewCtl }) 4880 .fileAccess(true) 4881 .javaScriptAccess(true) 4882 .domStorageAccess(true) 4883 .onlineImageAccess(true) 4884 .onPageEnd((e) => { 4885 if (e) { 4886 this.outputStr = 'onPageEnd : url = ' + e.url; 4887 } 4888 }) 4889 .onSslErrorEventReceive((e) => { 4890 // 忽略ssl证书错误，便于测试一些证书过期的网站，如：https://expired.badssl.com 4891 e.handler.handleConfirm(); 4892 }) 4893 .width('100%') 4894 .height('70%') 4895 } 4896 .height('100%') 4897 } 4898 } 4899} 4900``` 4901 4902### getCertificate<sup>10+</sup> 4903 4904getCertificate(callback: AsyncCallback<Array<cert.X509Cert>>): void 4905 4906获取当前网站的证书信息。使用Web组件加载https网站，会进行SSL证书校验，该接口会通过AsyncCallback异步返回当前网站的X509格式证书（X509Cert证书类型定义见[X509Cert定义](../apis-device-certificate-kit/js-apis-cert.md)），便于开发者展示网站证书信息。 4907 4908**系统能力：** SystemCapability.Web.Webview.Core 4909 4910**参数：** 4911 4912| 参数名 | 类型 | 必填 | 说明 | 4913| -------- | ---------------------------- | ---- | ---------------------------------------- | 4914| callback | AsyncCallback<Array<cert.X509Cert>> | 是 | 通过AsyncCallback异步返回当前网站的X509格式证书。 | 4915 4916**错误码：** 4917 4918以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 4919 4920| 错误码ID | 错误信息 | 4921| -------- | ------------------------------------------------------------ | 4922| 17100001 | Init error. The WebviewController must be associated with a web component. | 4923| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 4924 4925**示例：** 4926 4927```ts 4928// xxx.ets 4929import { webview } from '@kit.ArkWeb'; 4930import { BusinessError } from '@kit.BasicServicesKit'; 4931import { cert } from '@kit.DeviceCertificateKit'; 4932 4933function Uint8ArrayToString(dataArray: Uint8Array) { 4934 let dataString = ''; 4935 for (let i = 0; i < dataArray.length; i++) { 4936 dataString += String.fromCharCode(dataArray[i]); 4937 } 4938 return dataString; 4939} 4940 4941function ParseX509CertInfo(x509CertArray: Array<cert.X509Cert>) { 4942 let res: string = 'getCertificate success: len = ' + x509CertArray.length; 4943 for (let i = 0; i < x509CertArray.length; i++) { 4944 res += ', index = ' + i + ', issuer name = ' 4945 + Uint8ArrayToString(x509CertArray[i].getIssuerName().data) + ', subject name = ' 4946 + Uint8ArrayToString(x509CertArray[i].getSubjectName().data) + ', valid start = ' 4947 + x509CertArray[i].getNotBeforeTime() 4948 + ', valid end = ' + x509CertArray[i].getNotAfterTime(); 4949 } 4950 return res; 4951} 4952 4953@Entry 4954@Component 4955struct Index { 4956 // outputStr在UI界面显示调试信息 4957 @State outputStr: string = ''; 4958 webviewCtl: webview.WebviewController = new webview.WebviewController(); 4959 4960 build() { 4961 Row() { 4962 Column() { 4963 List({ space: 20, initialIndex: 0 }) { 4964 ListItem() { 4965 Button() { 4966 Text('load bad ssl') 4967 .fontSize(10) 4968 .fontWeight(FontWeight.Bold) 4969 } 4970 .type(ButtonType.Capsule) 4971 .onClick(() => { 4972 // 加载一个过期的证书网站，查看获取到的证书信息 4973 this.webviewCtl.loadUrl('https://expired.badssl.com'); 4974 }) 4975 .height(50) 4976 } 4977 4978 ListItem() { 4979 Button() { 4980 Text('load example') 4981 .fontSize(10) 4982 .fontWeight(FontWeight.Bold) 4983 } 4984 .type(ButtonType.Capsule) 4985 .onClick(() => { 4986 // 加载一个https网站，查看网站的证书信息 4987 this.webviewCtl.loadUrl('https://www.example.com'); 4988 }) 4989 .height(50) 4990 } 4991 4992 ListItem() { 4993 Button() { 4994 Text('getCertificate Promise') 4995 .fontSize(10) 4996 .fontWeight(FontWeight.Bold) 4997 } 4998 .type(ButtonType.Capsule) 4999 .onClick(() => { 5000 try { 5001 this.webviewCtl.getCertificate().then((x509CertArray: Array<cert.X509Cert>) => { 5002 this.outputStr = ParseX509CertInfo(x509CertArray); 5003 }) 5004 } catch (error) { 5005 this.outputStr = 'getCertificate failed: ' + (error as BusinessError).code + ", errMsg: " + (error as BusinessError).message; 5006 } 5007 }) 5008 .height(50) 5009 } 5010 5011 ListItem() { 5012 Button() { 5013 Text('getCertificate AsyncCallback') 5014 .fontSize(10) 5015 .fontWeight(FontWeight.Bold) 5016 } 5017 .type(ButtonType.Capsule) 5018 .onClick(() => { 5019 try { 5020 this.webviewCtl.getCertificate((error: BusinessError, x509CertArray: Array<cert.X509Cert>) => { 5021 if (error) { 5022 this.outputStr = 'getCertificate failed: ' + error.code + ", errMsg: " + error.message; 5023 } else { 5024 this.outputStr = ParseX509CertInfo(x509CertArray); 5025 } 5026 }) 5027 } catch (error) { 5028 this.outputStr = 'getCertificate failed: ' + (error as BusinessError).code + ", errMsg: " + (error as BusinessError).message; 5029 } 5030 }) 5031 .height(50) 5032 } 5033 } 5034 .listDirection(Axis.Horizontal) 5035 .height('10%') 5036 5037 Text(this.outputStr) 5038 .width('100%') 5039 .fontSize(10) 5040 5041 Web({ src: 'https://www.example.com', controller: this.webviewCtl }) 5042 .fileAccess(true) 5043 .javaScriptAccess(true) 5044 .domStorageAccess(true) 5045 .onlineImageAccess(true) 5046 .onPageEnd((e) => { 5047 if (e) { 5048 this.outputStr = 'onPageEnd : url = ' + e.url; 5049 } 5050 }) 5051 .onSslErrorEventReceive((e) => { 5052 // 忽略ssl证书错误，便于测试一些证书过期的网站，如：https://expired.badssl.com 5053 e.handler.handleConfirm(); 5054 }) 5055 .width('100%') 5056 .height('70%') 5057 } 5058 .height('100%') 5059 } 5060 } 5061} 5062``` 5063 5064### setAudioMuted<sup>10+</sup> 5065 5066setAudioMuted(mute: boolean): void 5067 5068设置网页静音。 5069 5070**系统能力：** SystemCapability.Web.Webview.Core 5071 5072**参数：** 5073 5074| 参数名 | 类型 | 必填 | 说明 | 5075| -------- | ------- | ---- | -------------------------------------- | 5076| mute | boolean | 是 | 表示是否将网页设置为静音状态，true表示设置为静音状态，false表示取消静音状态。 | 5077 5078**错误码：** 5079 5080以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5081 5082| 错误码ID | 错误信息 | 5083| -------- | ------------------------------------------------------------ | 5084| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 5085| 17100001 | Init error. The WebviewController must be associated with a Web component. | 5086 5087**示例：** 5088 5089```ts 5090// xxx.ets 5091import { webview } from '@kit.ArkWeb'; 5092 5093@Entry 5094@Component 5095struct WebComponent { 5096 controller: webview.WebviewController = new webview.WebviewController(); 5097 @State muted: boolean = false; 5098 5099 build() { 5100 Column() { 5101 Button("Toggle Mute") 5102 .onClick(event => { 5103 if (event) { 5104 this.muted = !this.muted; 5105 this.controller.setAudioMuted(this.muted); 5106 } 5107 }) 5108 Web({ src: 'www.example.com', controller: this.controller }) 5109 } 5110 } 5111} 5112``` 5113 5114### prefetchPage<sup>10+</sup> 5115 5116prefetchPage(url: string, additionalHeaders?: Array\<WebHeader>): void 5117 5118在预测到将要加载的页面之前调用，提前下载页面所需的资源，包括主资源子资源，但不会执行网页JavaScript代码或呈现网页，以加快加载速度。 5119 5120> **说明：** 5121> 5122> 下载的页面资源，会缓存五分钟左右，超过这段时间Web组件会自动释放。 5123 5124**系统能力：** SystemCapability.Web.Webview.Core 5125 5126**参数：** 5127 5128| 参数名 | 类型 | 必填 | 说明 | 5129| ------------------| --------------------------------| ---- | ------------- | 5130| url | string | 是 | 预加载的url。| 5131| additionalHeaders | Array\<[WebHeader](#webheader)> | 否 | url的附加HTTP请求头。| 5132 5133**错误码：** 5134 5135以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5136 5137| 错误码ID | 错误信息 | 5138| -------- | ------------------------------------------------------------ | 5139| 17100001 | Init error. The WebviewController must be associated with a Web component. | 5140| 17100002 | Invalid url. | 5141 5142**示例：** 5143 5144```ts 5145// xxx.ets 5146import { webview } from '@kit.ArkWeb'; 5147import { BusinessError } from '@kit.BasicServicesKit'; 5148 5149@Entry 5150@Component 5151struct WebComponent { 5152 controller: webview.WebviewController = new webview.WebviewController(); 5153 5154 build() { 5155 Column() { 5156 Button('prefetchPopularPage') 5157 .onClick(() => { 5158 try { 5159 // 预加载时，需要将'https://www.example.com'替换成一个真实的网站地址。 5160 this.controller.prefetchPage('https://www.example.com'); 5161 } catch (error) { 5162 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5163 } 5164 }) 5165 // 需要将'www.example1.com'替换成一个真实的网站地址。 5166 Web({ src: 'www.example1.com', controller: this.controller }) 5167 } 5168 } 5169} 5170``` 5171 5172### prefetchResource<sup>12+</sup> 5173 5174static prefetchResource(request: RequestInfo, additionalHeaders?: Array\<WebHeader>, cacheKey?: string, cacheValidTime?: number): void 5175 5176根据指定的请求信息和附加的http请求头去预获取资源请求，存入内存缓存，并指定其缓存key和有效期，以加快加载速度。目前仅支持Content-Type为application/x-www-form-urlencoded的post请求。最多可以预获取6个post请求。如果要预获取第7个，请通过[clearPrefetchedResource](#clearprefetchedresource12)清除不需要的post请求缓存，否则会自动清除最早预获取的post缓存。如果要使用预获取的资源缓存，开发者需要在正式发起的post请求的请求头中增加键值“ArkWebPostCacheKey”，其内容为对应缓存的cacheKey。 5177 5178**系统能力：** SystemCapability.Web.Webview.Core 5179 5180**参数：** 5181 5182| 参数名 | 类型 | 必填 | 说明 | 5183| ------------------| ------------------------------- | ---- | ------------------------------------------------------------------ | 5184| request | [RequestInfo](#requestinfo12) | 是 | 预获取请求的信息。 | 5185| additionalHeaders | Array\<[WebHeader](#webheader)> | 否 | 预获取请求的附加HTTP请求头。 | 5186| cacheKey | string | 否 | 用于后续查询预获取资源缓存的key。仅支持字母和数字，未传入或传入空则取默认值url作为key。 | 5187| cacheValidTime | number | 否 | 预获取资源缓存的有效期。取值范围：(0, 2147483647]。单位：秒。默认值：300秒。 | 5188 5189**错误码：** 5190 5191以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5192 5193| 错误码ID | 错误信息 | 5194| -------- | ------------------------------------------------------------ | 5195| 401 | Invalid input parameter.Possible causes: 1. Mandatory parameters are left unspecified.2. Incorrect parameter types.3. Parameter verification failed. | 5196| 17100002 | Invalid url. | 5197 5198**示例：** 5199 5200```ts 5201// xxx.ets 5202import { webview } from '@kit.ArkWeb'; 5203import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 5204 5205export default class EntryAbility extends UIAbility { 5206 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 5207 console.log("EntryAbility onCreate"); 5208 webview.WebviewController.initializeWebEngine(); 5209 // 预获取时，需要將"https://www.example1.com/post?e=f&g=h"替换成真实要访问的网站地址。 5210 webview.WebviewController.prefetchResource( 5211 { 5212 url: "https://www.example1.com/post?e=f&g=h", 5213 method: "POST", 5214 formData: "a=x&b=y", 5215 }, 5216 [{ 5217 headerKey: "c", 5218 headerValue: "z", 5219 },], 5220 "KeyX", 500); 5221 AppStorage.setOrCreate("abilityWant", want); 5222 console.log("EntryAbility onCreate done"); 5223 } 5224} 5225``` 5226 5227### clearPrefetchedResource<sup>12+</sup> 5228 5229static clearPrefetchedResource(cacheKeyList: Array\<string>): void 5230 5231根据指定的缓存key列表清除对应的预获取资源缓存。入参中的缓存key必须是[prefetchResource](#prefetchresource12)指定预获取到的资源缓存key。 5232 5233**系统能力：** SystemCapability.Web.Webview.Core 5234 5235**参数：** 5236 5237| 参数名 | 类型 | 必填 | 说明 | 5238| ------------------| ----------- | ---- | ------------------------------------------------------------------------- | 5239| cacheKeyList | Array\<string> | 是 | 用于后续查询预获取资源缓存的key。仅支持字母和数字，未传入或传入空则取默认值url作为key。 | 5240 5241**示例：** 5242 5243```ts 5244// xxx.ets 5245import { webview } from '@kit.ArkWeb'; 5246 5247@Entry 5248@Component 5249struct WebComponent { 5250 controller: webview.WebviewController = new webview.WebviewController(); 5251 5252 build() { 5253 Column() { 5254 Web({ src: "https://www.example.com/", controller: this.controller }) 5255 .onAppear(() => { 5256 // 预获取时，需要將"https://www.example1.com/post?e=f&g=h"替换成真实要访问的网站地址。 5257 webview.WebviewController.prefetchResource( 5258 { 5259 url: "https://www.example1.com/post?e=f&g=h", 5260 method: "POST", 5261 formData: "a=x&b=y", 5262 }, 5263 [{ 5264 headerKey: "c", 5265 headerValue: "z", 5266 },], 5267 "KeyX", 500); 5268 }) 5269 .onPageEnd(() => { 5270 // 清除后续不再使用的预获取缓存。 5271 webview.WebviewController.clearPrefetchedResource(["KeyX",]); 5272 }) 5273 } 5274 } 5275} 5276``` 5277 5278### prepareForPageLoad<sup>10+</sup> 5279 5280static prepareForPageLoad(url: string, preconnectable: boolean, numSockets: number): void 5281 5282预连接url，在加载url之前调用此API，对url只进行dns解析，socket建链操作，并不获取主资源子资源。 5283 5284**系统能力：** SystemCapability.Web.Webview.Core 5285 5286**参数：** 5287 5288| 参数名 | 类型 | 必填 | 说明 | 5289| ---------------| ------- | ---- | ------------- | 5290| url | string | 是 | 预连接的url。| 5291| preconnectable | boolean | 是 | 是否进行预连接。如果preconnectable为true，则对url进行dns解析，socket建链预连接；如果preconnectable为false，则不做任何预连接操作。| 5292| numSockets | number | 是 | 要预连接的socket数。socket数目连接需要大于0，最多允许6个连接。| 5293 5294**错误码：** 5295 5296以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5297 5298| 错误码ID | 错误信息 | 5299| -------- | ------------------------------------------------------------ | 5300| 17100002 | Invalid url. | 5301| 171000013| The number of preconnect sockets is invalid. | 5302 5303**示例：** 5304 5305```ts 5306// xxx.ets 5307import { webview } from '@kit.ArkWeb'; 5308import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 5309 5310export default class EntryAbility extends UIAbility { 5311 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 5312 console.log("EntryAbility onCreate"); 5313 webview.WebviewController.initializeWebEngine(); 5314 // 预连接时，需要將'https://www.example.com'替换成一个真实的网站地址。 5315 webview.WebviewController.prepareForPageLoad("https://www.example.com", true, 2); 5316 AppStorage.setOrCreate("abilityWant", want); 5317 console.log("EntryAbility onCreate done"); 5318 } 5319} 5320``` 5321 5322### setCustomUserAgent<sup>10+</sup> 5323 5324setCustomUserAgent(userAgent: string): void 5325 5326设置自定义用户代理，会覆盖系统的用户代理。 5327 5328当Web组件src设置了url时，建议在onControllerAttached回调事件中设置UserAgent，设置方式请参考示例。不建议将UserAgent设置在onLoadIntercept回调事件中，会概率性出现设置失败。 5329 5330当Web组件src设置为空字符串时，建议先调用setCustomUserAgent方法设置UserAgent，再通过loadUrl加载具体页面。 5331 5332默认UserAgent定义与使用场景请参考[UserAgent详情参考](../../web/web-default-userAgent.md) 5333 5334> **说明：** 5335> 5336>当Web组件src设置了url，且未在onControllerAttached回调事件中设置UserAgent。再调用setCustomUserAgent方法时，可能会出现加载的页面与实际设置UserAgent不符的异常现象。 5337 5338**系统能力：** SystemCapability.Web.Webview.Core 5339 5340**参数：** 5341 5342| 参数名 | 类型 | 必填 | 说明 | 5343| ---------------| ------- | ---- | ------------- | 5344| userAgent | string | 是 | 用户自定义代理信息。建议先使用[getUserAgent](#getuseragent)获取当前默认用户代理，在此基础上追加自定义用户代理信息。 | 5345 5346**错误码：** 5347 5348以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5349 5350| 错误码ID | 错误信息 | 5351| -------- | ------------------------------------------------------------ | 5352| 17100001 | Init error. The WebviewController must be associated with a Web component. | 5353| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 5354 5355**示例：** 5356 5357```ts 5358// xxx.ets 5359import { webview } from '@kit.ArkWeb'; 5360import { BusinessError } from '@kit.BasicServicesKit'; 5361 5362@Entry 5363@Component 5364struct WebComponent { 5365 controller: webview.WebviewController = new webview.WebviewController(); 5366 @State customUserAgent: string = ' DemoApp'; 5367 5368 build() { 5369 Column() { 5370 Web({ src: 'www.example.com', controller: this.controller }) 5371 .onControllerAttached(() => { 5372 console.log("onControllerAttached"); 5373 try { 5374 let userAgent = this.controller.getUserAgent() + this.customUserAgent; 5375 this.controller.setCustomUserAgent(userAgent); 5376 } catch (error) { 5377 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5378 } 5379 }) 5380 } 5381 } 5382} 5383``` 5384 5385### setDownloadDelegate<sup>11+</sup> 5386 5387setDownloadDelegate(delegate: WebDownloadDelegate): void 5388 5389为当前的Web组件设置一个WebDownloadDelegate，该delegate用来接收页面内触发的下载与下载的进展。 5390 5391**系统能力：** SystemCapability.Web.Webview.Core 5392 5393**参数：** 5394 5395| 参数名 | 类型 | 必填 | 说明 | 5396| ---------------| ------- | ---- | ------------- | 5397| delegate | [WebDownloadDelegate](#webdownloaddelegate11) | 是 | 用来接收下载进回调的委托。 | 5398 5399**错误码：** 5400 5401以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5402 5403| 错误码ID | 错误信息 | 5404| -------- | ------------------------------------------------------------ | 5405| 17100001 | Init error. The WebviewController must be associated with a Web component. | 5406 5407**示例：** 5408 5409```ts 5410// xxx.ets 5411import { webview } from '@kit.ArkWeb'; 5412import { BusinessError } from '@kit.BasicServicesKit'; 5413 5414@Entry 5415@Component 5416struct WebComponent { 5417 controller: webview.WebviewController = new webview.WebviewController(); 5418 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 5419 5420 build() { 5421 Column() { 5422 Button('setDownloadDelegate') 5423 .onClick(() => { 5424 try { 5425 this.controller.setDownloadDelegate(this.delegate); 5426 } catch (error) { 5427 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5428 } 5429 }) 5430 Web({ src: 'www.example.com', controller: this.controller }) 5431 } 5432 } 5433} 5434``` 5435 5436### startDownload<sup>11+</sup> 5437 5438startDownload(url: string): void 5439 5440使用Web组件的下载能力来下载指定的url, 比如下载网页中指定的图片。 5441 5442**系统能力：** SystemCapability.Web.Webview.Core 5443 5444**参数：** 5445 5446| 参数名 | 类型 | 必填 | 说明 | 5447| ---------------| ------- | ---- | ------------- | 5448| url | string | 是 | 下载地址。 | 5449 5450**错误码：** 5451 5452以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5453 5454| 错误码ID | 错误信息 | 5455| -------- | ------------------------------------------------------------ | 5456| 17100001 | Init error. The WebviewController must be associated with a Web component. | 5457| 17100002 | Invalid url. | 5458 5459**示例：** 5460 5461```ts 5462// xxx.ets 5463import { webview } from '@kit.ArkWeb'; 5464import { BusinessError } from '@kit.BasicServicesKit'; 5465 5466@Entry 5467@Component 5468struct WebComponent { 5469 controller: webview.WebviewController = new webview.WebviewController(); 5470 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 5471 5472 build() { 5473 Column() { 5474 Button('setDownloadDelegate') 5475 .onClick(() => { 5476 try { 5477 this.controller.setDownloadDelegate(this.delegate); 5478 } catch (error) { 5479 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5480 } 5481 }) 5482 Button('startDownload') 5483 .onClick(() => { 5484 try { 5485 this.controller.startDownload('https://www.example.com'); 5486 } catch (error) { 5487 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5488 } 5489 }) 5490 Web({ src: 'www.example.com', controller: this.controller }) 5491 } 5492 } 5493} 5494``` 5495 5496### getCustomUserAgent<sup>10+</sup> 5497 5498getCustomUserAgent(): string 5499 5500获取自定义用户代理。 5501 5502默认UserAgent定义与使用场景请参考[UserAgent详情参考](../../web/web-default-userAgent.md) 5503 5504**系统能力：** SystemCapability.Web.Webview.Core 5505 5506**返回值：** 5507 5508| 类型 | 说明 | 5509| ------ | ------------------------- | 5510| string | 用户自定义代理信息。 | 5511 5512**错误码：** 5513 5514以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5515 5516| 错误码ID | 错误信息 | 5517| -------- | ------------------------------------------------------------ | 5518| 17100001 | Init error. The WebviewController must be associated with a Web component. | 5519 5520**示例：** 5521 5522```ts 5523// xxx.ets 5524import { webview } from '@kit.ArkWeb'; 5525import { BusinessError } from '@kit.BasicServicesKit'; 5526 5527@Entry 5528@Component 5529struct WebComponent { 5530 controller: webview.WebviewController = new webview.WebviewController(); 5531 @State userAgent: string = ''; 5532 5533 build() { 5534 Column() { 5535 Button('getCustomUserAgent') 5536 .onClick(() => { 5537 try { 5538 this.userAgent = this.controller.getCustomUserAgent(); 5539 console.log("userAgent: " + this.userAgent); 5540 } catch (error) { 5541 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5542 } 5543 }) 5544 Web({ src: 'www.example.com', controller: this.controller }) 5545 } 5546 } 5547} 5548``` 5549 5550### setConnectionTimeout<sup>11+</sup> 5551 5552static setConnectionTimeout(timeout: number): void 5553 5554设置网络连接超时时间，使用者可通过Web组件中的onErrorReceive方法获取超时错误码。 5555 5556**系统能力：** SystemCapability.Web.Webview.Core 5557 5558**参数：** 5559 5560| 参数名 | 类型 | 必填 | 说明 | 5561| ---------------| ------- | ---- | ------------- | 5562| timeout | number | 是 | socket连接超时时间，以秒为单位，socket必须为大于0的整数。 | 5563 5564**错误码：** 5565 5566以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5567 5568| 错误码ID | 错误信息 | 5569| -------- | ------------------------------------------------------------ | 5570| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 5571 5572**示例：** 5573 5574```ts 5575// xxx.ets 5576import { webview } from '@kit.ArkWeb'; 5577import { BusinessError } from '@kit.BasicServicesKit'; 5578 5579@Entry 5580@Component 5581struct WebComponent { 5582 controller: webview.WebviewController = new webview.WebviewController(); 5583 5584 build() { 5585 Column() { 5586 Button('setConnectionTimeout') 5587 .onClick(() => { 5588 try { 5589 webview.WebviewController.setConnectionTimeout(5); 5590 console.log("setConnectionTimeout: 5s"); 5591 } catch (error) { 5592 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5593 } 5594 }) 5595 Web({ src: 'www.example.com', controller: this.controller }) 5596 .onErrorReceive((event) => { 5597 if (event) { 5598 console.log('getErrorInfo:' + event.error.getErrorInfo()); 5599 console.log('getErrorCode:' + event.error.getErrorCode()); 5600 } 5601 }) 5602 } 5603 } 5604} 5605``` 5606 5607### warmupServiceWorker<sup>12+</sup> 5608 5609static warmupServiceWorker(url: string): void 5610 5611预热ServiceWorker，以提升首屏页面的加载速度（仅限于会使用ServiceWorker的页面）。在加载url之前调用此API。 5612 5613**系统能力：** SystemCapability.Web.Webview.Core 5614 5615**参数：** 5616 5617| 参数名 | 类型 | 必填 | 说明 | 5618| ---------------| ------- | ---- | ------------- | 5619| url | string | 是 | 需要预热ServiceWorker的url。| 5620 5621**错误码：** 5622 5623以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5624 5625| 错误码ID | 错误信息 | 5626| -------- | ------------------------------------------------------------ | 5627| 17100002 | Invalid url. | 5628 5629**示例：** 5630 5631```ts 5632// xxx.ts 5633import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 5634import { hilog } from '@kit.PerformanceAnalysisKit'; 5635import { window } from '@kit.ArkUI'; 5636import { webview } from '@kit.ArkWeb'; 5637 5638export default class EntryAbility extends UIAbility { 5639 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 5640 console.log("EntryAbility onCreate"); 5641 webview.WebviewController.initializeWebEngine(); 5642 webview.WebviewController.warmupServiceWorker("https://www.example.com"); 5643 AppStorage.setOrCreate("abilityWant", want); 5644 } 5645} 5646``` 5647 5648### enableSafeBrowsing<sup>11+</sup> 5649 5650enableSafeBrowsing(enable: boolean): void 5651 5652<!--RP1-->启用检查网站安全风险的功能，非法和欺诈网站是强制启用的，不能通过此功能禁用。 5653本功能默认不生效，OpenHarmony只提供恶意网址拦截页WebUI，网址风险检测以及显示WebUI的功能由Vendor实现。推荐在WebContentsObserver中监听跳转[DidStartNavigation](https://gitee.com/openharmony-tpc/chromium_src/blob/master/content/public/browser/web_contents_observer.h#:~:text=virtual%20void-,DidStartNavigation)、[DidRedirectNavigation](https://gitee.com/openharmony-tpc/chromium_src/blob/master/content/public/browser/web_contents_observer.h#:~:text=virtual%20void-,DidRedirectNavigation)进行检测。 5654<!--RP1End--> 5655 5656**系统能力：** SystemCapability.Web.Webview.Core 5657 5658**参数：** 5659 5660| 参数名 | 类型 | 必填 | 说明 | 5661| --------| ------- | ---- | ---------------------------| 5662| enable | boolean | 是 | 是否启用检查网站安全风险的功能。 | 5663 5664**错误码：** 5665 5666以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5667 5668| 错误码ID | 错误信息 | 5669| -------- | ----------------------- | 5670| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 5671 5672**示例：** 5673 5674```ts 5675// xxx.ets 5676import { webview } from '@kit.ArkWeb'; 5677import { BusinessError } from '@kit.BasicServicesKit'; 5678 5679@Entry 5680@Component 5681struct WebComponent { 5682 controller: webview.WebviewController = new webview.WebviewController(); 5683 5684 build() { 5685 Column() { 5686 Button('enableSafeBrowsing') 5687 .onClick(() => { 5688 try { 5689 this.controller.enableSafeBrowsing(true); 5690 console.log("enableSafeBrowsing: true"); 5691 } catch (error) { 5692 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5693 } 5694 }) 5695 Web({ src: 'www.example.com', controller: this.controller }) 5696 } 5697 } 5698} 5699``` 5700 5701### isSafeBrowsingEnabled<sup>11+</sup> 5702 5703isSafeBrowsingEnabled(): boolean 5704 5705获取当前网页是否启用了检查网站安全风险。 5706 5707**系统能力：** SystemCapability.Web.Webview.Core 5708 5709**返回值：** 5710 5711| 类型 | 说明 | 5712| ------- | --------------------------------------- | 5713| boolean | 当前网页是否启用了检查网站安全风险的功能，默认为false。| 5714 5715**示例：** 5716 5717```ts 5718// xxx.ets 5719import { webview } from '@kit.ArkWeb'; 5720 5721@Entry 5722@Component 5723struct WebComponent { 5724 controller: webview.WebviewController = new webview.WebviewController(); 5725 5726 build() { 5727 Column() { 5728 Button('isSafeBrowsingEnabled') 5729 .onClick(() => { 5730 let result = this.controller.isSafeBrowsingEnabled(); 5731 console.log("result: " + result); 5732 }) 5733 Web({ src: 'www.example.com', controller: this.controller }) 5734 } 5735 } 5736} 5737``` 5738 5739### enableIntelligentTrackingPrevention<sup>12+</sup> 5740 5741enableIntelligentTrackingPrevention(enable: boolean): void 5742 5743启用智能防跟踪功能，默认该功能未启用。 5744 5745**系统能力：** SystemCapability.Web.Webview.Core 5746 5747**参数：** 5748 5749| 参数名 | 类型 | 必填 | 说明 | 5750| --------| ------- | ---- | ---------------------------| 5751| enable | boolean | 是 | 是否启用智能防跟踪功能。 | 5752 5753**错误码：** 5754 5755以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5756 5757| 错误码ID | 错误信息 | 5758| -------- | ----------------------- | 5759| 17100001 | Init error. The WebviewController must be associated with a Web component. | 5760| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 5761 5762**示例：** 5763 5764```ts 5765// xxx.ets 5766import { webview } from '@kit.ArkWeb'; 5767import { BusinessError } from '@kit.BasicServicesKit'; 5768 5769@Entry 5770@Component 5771struct WebComponent { 5772 controller: webview.WebviewController = new webview.WebviewController(); 5773 5774 build() { 5775 Column() { 5776 Button('enableIntelligentTrackingPrevention') 5777 .onClick(() => { 5778 try { 5779 this.controller.enableIntelligentTrackingPrevention(true); 5780 console.log("enableIntelligentTrackingPrevention: true"); 5781 } catch (error) { 5782 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5783 } 5784 }) 5785 Web({ src: 'www.example.com', controller: this.controller }) 5786 } 5787 } 5788} 5789``` 5790 5791### isIntelligentTrackingPreventionEnabled<sup>12+</sup> 5792 5793isIntelligentTrackingPreventionEnabled(): boolean 5794 5795获取当前Web是否启用了智能防跟踪功能。 5796 5797**系统能力：** SystemCapability.Web.Webview.Core 5798 5799**返回值：** 5800 5801| 类型 | 说明 | 5802| ------- | --------------------------------------- | 5803| boolean | 当前Web是否启用了智能防跟踪功能，默认为false。| 5804 5805**错误码：** 5806 5807以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5808 5809| 错误码ID | 错误信息 | 5810| -------- | ----------------------- | 5811| 17100001 | Init error. The WebviewController must be associated with a Web component. | 5812 5813**示例：** 5814 5815```ts 5816// xxx.ets 5817import { webview } from '@kit.ArkWeb'; 5818import { BusinessError } from '@kit.BasicServicesKit'; 5819 5820@Entry 5821@Component 5822struct WebComponent { 5823 controller: webview.WebviewController = new webview.WebviewController(); 5824 5825 build() { 5826 Column() { 5827 Button('isIntelligentTrackingPreventionEnabled') 5828 .onClick(() => { 5829 try { 5830 let result = this.controller.isIntelligentTrackingPreventionEnabled(); 5831 console.log("result: " + result); 5832 } catch (error) { 5833 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5834 } 5835 }) 5836 Web({ src: 'www.example.com', controller: this.controller }) 5837 } 5838 } 5839} 5840``` 5841 5842### addIntelligentTrackingPreventionBypassingList<sup>12+</sup> 5843 5844static addIntelligentTrackingPreventionBypassingList(hostList: Array\<string>): void 5845 5846添加智能防跟踪功能绕过的域名列表。 5847 5848**系统能力：** SystemCapability.Web.Webview.Core 5849 5850**参数：** 5851 5852| 参数名 | 类型 | 必填 | 说明 | 5853| ----------- | ------------- | ---- | ------------------------ | 5854| hostList | Array\<string> | 是 | 绕过智能防跟踪功能的域名列表。 | 5855 5856**错误码：** 5857 5858以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5859 5860| 错误码ID | 错误信息 | 5861| -------- | ------------------------ | 5862| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 5863 5864**示例：** 5865 5866```ts 5867// xxx.ets 5868import { webview } from '@kit.ArkWeb'; 5869import { BusinessError } from '@kit.BasicServicesKit'; 5870 5871@Entry 5872@Component 5873struct WebComponent { 5874 controller: webview.WebviewController = new webview.WebviewController(); 5875 5876 build() { 5877 Column() { 5878 Button('addIntelligentTrackingPreventionBypassingList') 5879 .onClick(() => { 5880 try { 5881 let hostList = ["www.test1.com", "www.test2.com", "www.test3.com"]; 5882 webview.WebviewController.addIntelligentTrackingPreventionBypassingList(hostList); 5883 } catch (error) { 5884 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5885 } 5886 }) 5887 Web({ src: 'www.example.com', controller: this.controller }) 5888 } 5889 } 5890} 5891``` 5892 5893### removeIntelligentTrackingPreventionBypassingList<sup>12+</sup> 5894 5895static removeIntelligentTrackingPreventionBypassingList(hostList: Array\<string>): void 5896 5897删除通过addIntelligentTrackingPreventionBypassingList接口添加的部分域名列表。 5898 5899**系统能力：** SystemCapability.Web.Webview.Core 5900 5901**参数：** 5902 5903| 参数名 | 类型 | 必填 | 说明 | 5904| ----------- | ------------- | ---- | ------------------------ | 5905| hostList | Array\<string> | 是 | 绕过智能防跟踪功能的域名列表。 | 5906 5907**错误码：** 5908 5909以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 5910 5911| 错误码ID | 错误信息 | 5912| -------- | ------------------------ | 5913| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 5914 5915**示例：** 5916 5917```ts 5918// xxx.ets 5919import { webview } from '@kit.ArkWeb'; 5920import { BusinessError } from '@kit.BasicServicesKit'; 5921 5922@Entry 5923@Component 5924struct WebComponent { 5925 controller: webview.WebviewController = new webview.WebviewController(); 5926 5927 build() { 5928 Column() { 5929 Button('removeIntelligentTrackingPreventionBypassingList') 5930 .onClick(() => { 5931 try { 5932 let hostList = ["www.test1.com", "www.test2.com"]; 5933 webview.WebviewController.removeIntelligentTrackingPreventionBypassingList(hostList); 5934 } catch (error) { 5935 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5936 } 5937 }) 5938 Web({ src: 'www.example.com', controller: this.controller }) 5939 } 5940 } 5941} 5942``` 5943 5944### clearIntelligentTrackingPreventionBypassingList<sup>12+</sup> 5945 5946static clearIntelligentTrackingPreventionBypassingList(): void 5947 5948删除通过addIntelligentTrackingPreventionBypassingList接口添加的所有域名。 5949 5950**系统能力：** SystemCapability.Web.Webview.Core 5951 5952**示例：** 5953 5954```ts 5955// xxx.ets 5956import { webview } from '@kit.ArkWeb'; 5957 5958@Entry 5959@Component 5960struct WebComponent { 5961 controller: webview.WebviewController = new webview.WebviewController(); 5962 5963 build() { 5964 Column() { 5965 Button('clearIntelligentTrackingPreventionBypassingList') 5966 .onClick(() => { 5967 webview.WebviewController.clearIntelligentTrackingPreventionBypassingList(); 5968 }) 5969 Web({ src: 'www.example.com', controller: this.controller }) 5970 } 5971 } 5972} 5973``` 5974 5975### getDefaultUserAgent<sup>14+</sup> 5976 5977static getDefaultUserAgent(): string 5978 5979获取默认用户代理。 5980 5981此接口只允许在UI线程调用。 5982 5983**系统能力：** SystemCapability.Web.Webview.Core 5984 5985**示例：** 5986 5987```ts 5988// xxx.ets 5989import { webview } from '@kit.ArkWeb'; 5990import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 5991 5992export default class EntryAbility extends UIAbility { 5993 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 5994 console.log("EntryAbility onCreate"); 5995 webview.WebviewController.initializeWebEngine(); 5996 let defaultUserAgent = webview.WebviewController.getDefaultUserAgent(); 5997 console.log("defaultUserAgent: " + defaultUserAgent); 5998 } 5999} 6000``` 6001 6002### enableAdsBlock<sup>12+</sup> 6003 6004enableAdsBlock(enable: boolean): void 6005 6006启用广告过滤功能，默认该功能未启用。 6007 6008**系统能力：** SystemCapability.Web.Webview.Core 6009 6010**参数：** 6011 6012| 参数名 | 类型 | 必填 | 说明 | 6013| --------| ------- | ---- | ---------------------------| 6014| enable | boolean | 是 | 是否启用广告过滤功能。 | 6015 6016**错误码：** 6017 6018以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6019 6020| 错误码ID | 错误信息 | 6021| -------- | ----------------------- | 6022| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6023| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Parameter string is too long. 3.Parameter verification failed. | 6024 6025**示例：** 6026 6027```ts 6028// xxx.ets 6029import { webview } from '@kit.ArkWeb'; 6030import { BusinessError } from '@kit.BasicServicesKit'; 6031 6032@Entry 6033@Component 6034struct WebComponent { 6035 controller: webview.WebviewController = new webview.WebviewController(); 6036 6037 build() { 6038 Column() { 6039 Button('enableAdsBlock') 6040 .onClick(() => { 6041 try { 6042 this.controller.enableAdsBlock(true); 6043 console.log("enableAdsBlock: true") 6044 } catch (error) { 6045 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6046 } 6047 }) 6048 Web({ src: 'www.example.com', controller: this.controller }) 6049 } 6050 } 6051} 6052``` 6053 6054### isAdsBlockEnabled<sup>12+</sup> 6055 6056isAdsBlockEnabled() : boolean 6057 6058查询广告过滤功能是否开启，默认该功能未启用。 6059 6060**系统能力：** SystemCapability.Web.Webview.Core 6061 6062**返回值：** 6063 6064| 类型 | 说明 | 6065| ------------------------------------------------------------ | ---------------------- | 6066| boolean | 返回true代表广告过滤功能已开启，返回false代表广告过滤功能关闭。 | 6067 6068**示例：** 6069 6070```ts 6071// xxx.ets 6072import { webview } from '@kit.ArkWeb'; 6073import { BusinessError } from '@kit.BasicServicesKit'; 6074 6075@Entry 6076@Component 6077struct WebComponent { 6078 controller: webview.WebviewController = new webview.WebviewController(); 6079 6080 build() { 6081 Column() { 6082 Button('isAdsBlockEnabled') 6083 .onClick(() => { 6084 try { 6085 let isAdsBlockEnabled: boolean = this.controller.isAdsBlockEnabled(); 6086 console.log("isAdsBlockEnabled:", isAdsBlockEnabled); 6087 } catch (error) { 6088 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6089 } 6090 }) 6091 Web({ src: 'www.example.com', controller: this.controller }) 6092 } 6093 } 6094} 6095``` 6096 6097### isAdsBlockEnabledForCurPage<sup>12+</sup> 6098 6099isAdsBlockEnabledForCurPage() : boolean 6100 6101查询当前网页是否开启广告过滤功能。 6102当Web组件使能广告过滤功能后，默认所有页面都是开启广告过滤的，支持通过[addAdsBlockDisallowedList](#addadsblockdisallowedlist12)指定域名禁用广告过滤。 6103 6104**系统能力：** SystemCapability.Web.Webview.Core 6105 6106**返回值：** 6107 6108| 类型 | 说明 | 6109| ------------------------------------------------------------ | ---------------------- | 6110| boolean | 返回true代表此网页已开启广告过滤，返回false代表当前网页已关闭广告过滤。 | 6111 6112**示例：** 6113 6114```ts 6115// xxx.ets 6116import { webview } from '@kit.ArkWeb'; 6117import { BusinessError } from '@kit.BasicServicesKit'; 6118 6119@Entry 6120@Component 6121struct WebComponent { 6122 controller: webview.WebviewController = new webview.WebviewController(); 6123 6124 build() { 6125 Column() { 6126 Button('isAdsBlockEnabledForCurPage') 6127 .onClick(() => { 6128 try { 6129 let isAdsBlockEnabledForCurPage: boolean = this.controller.isAdsBlockEnabledForCurPage(); 6130 console.log("isAdsBlockEnabledForCurPage:", isAdsBlockEnabledForCurPage); 6131 } catch (error) { 6132 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6133 } 6134 }) 6135 Web({ src: 'www.example.com', controller: this.controller }) 6136 } 6137 } 6138} 6139``` 6140 6141### setRenderProcessMode<sup>12+</sup> 6142 6143static setRenderProcessMode(mode: RenderProcessMode): void 6144 6145设置ArkWeb渲染子进程模式。 6146 6147**系统能力：** SystemCapability.Web.Webview.Core 6148 6149**参数：** 6150 6151| 参数名 | 类型 | 必填 | 说明 | 6152| ----------- | ------------- | ---- | ------------------------ | 6153| mode | [RenderProcessMode](#renderprocessmode12)| 是 | 渲染子进程模式。可以先调用[getRenderProcessMode()](#getrenderprocessmode12)查看当前设备的ArkWeb渲染子进程模式，枚举值0为单子进程模式，枚举值1为多子进程模式。如果传入RenderProcessMode枚举值之外的非法数字，则默认识别为多渲染子进程模式。 | 6154 6155**错误码：** 6156 6157以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6158 6159| 错误码ID | 错误信息 | 6160| -------- | ------------------------ | 6161| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 6162 6163**示例：** 6164 6165```ts 6166// xxx.ets 6167import { webview } from '@kit.ArkWeb'; 6168import { BusinessError } from '@kit.BasicServicesKit'; 6169 6170@Entry 6171@Component 6172struct WebComponent { 6173 controller: webview.WebviewController = new webview.WebviewController(); 6174 6175 build() { 6176 Column() { 6177 Button('setRenderProcessMode') 6178 .onClick(() => { 6179 try { 6180 webview.WebviewController.setRenderProcessMode(webview.RenderProcessMode.MULTIPLE); 6181 } catch (error) { 6182 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6183 } 6184 }) 6185 Web({ src: 'www.example.com', controller: this.controller }) 6186 } 6187 } 6188} 6189``` 6190### getRenderProcessMode<sup>12+</sup> 6191 6192static getRenderProcessMode(): RenderProcessMode 6193 6194查询ArkWeb的渲染子进程模式。 6195 6196**系统能力：** SystemCapability.Web.Webview.Core 6197 6198**返回值：** 6199 6200| 类型 | 说明 | 6201| ----------------------------------------- | ------------------------------------------------------------ | 6202| [RenderProcessMode](#renderprocessmode12) | 渲染子进程模式类型。调用[getRenderProcessMode()](#getrenderprocessmode12)获取当前设备的ArkWeb渲染子进程模式，枚举值0为单子进程模式，枚举值1为多子进程模式。如果获取的值不在RenderProcessMode枚举值范围内，则默认为多渲染子进程模式。 | 6203 6204 6205**示例：** 6206 6207```ts 6208// xxx.ets 6209import { webview } from '@kit.ArkWeb'; 6210 6211@Entry 6212@Component 6213struct WebComponent { 6214 controller: webview.WebviewController = new webview.WebviewController(); 6215 6216 build() { 6217 Column() { 6218 Button('getRenderProcessMode') 6219 .onClick(() => { 6220 let mode = webview.WebviewController.getRenderProcessMode(); 6221 console.log("getRenderProcessMode: " + mode); 6222 }) 6223 Web({ src: 'www.example.com', controller: this.controller }) 6224 } 6225 } 6226} 6227``` 6228 6229### terminateRenderProcess<sup>12+</sup> 6230 6231terminateRenderProcess(): boolean 6232 6233销毁渲染进程。 6234 6235调用该接口将会主动销毁相关联的渲染进程。如果渲染进程尚未启动，或者已销毁则没有任何影响。此外销毁渲染进程会同时影响所有与该渲染进程关联的其他实例。 6236 6237**系统能力：** SystemCapability.Web.Webview.Core 6238 6239**返回值：** 6240 6241| 类型 | 说明 | 6242| ------------------------------------------------------------ | ---------------------- | 6243| boolean | 返回销毁渲染进程的结果，如果渲染进程可以被销毁则返回true，否则返回false。 如果渲染进程已被销毁则直接返回true。| 6244 6245**错误码：** 6246 6247以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6248 6249| 错误码ID | 错误信息 | 6250| -------- | ------------------------------------------------------------ | 6251| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6252 6253**示例：** 6254 6255```ts 6256// xxx.ets 6257import { webview } from '@kit.ArkWeb'; 6258 6259@Entry 6260@Component 6261struct WebComponent { 6262 controller: webview.WebviewController = new webview.WebviewController(); 6263 6264 build() { 6265 Column() { 6266 Button('terminateRenderProcess') 6267 .onClick(() => { 6268 let result = this.controller.terminateRenderProcess(); 6269 console.log("terminateRenderProcess result: " + result); 6270 }) 6271 Web({ src: 'www.example.com', controller: this.controller }) 6272 } 6273 } 6274} 6275``` 6276 6277### postUrl<sup>11+</sup> 6278 6279postUrl(url: string, postData: ArrayBuffer): void 6280 6281使用"POST"方法加载带有postData的url。如果url不是网络url，则会使用[loadUrl](#loadurl)方法加载url，忽略postData参数。 6282 6283**系统能力：** SystemCapability.Web.Webview.Core 6284 6285**参数：** 6286 6287| 参数名 | 类型 | 必填 | 说明 | 6288| ------- | ---------------- | ---- | :-------------------- | 6289| url | string | 是 | 需要加载的 URL。 | 6290| postData | ArrayBuffer | 是 | 使用"POST"方法传递数据。 该请求必须采用"application/x-www-form-urlencoded"编码。| 6291 6292**错误码：** 6293 6294以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6295 6296| 错误码ID | 错误信息 | 6297| -------- | ------------------------------------------------------------ | 6298| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6299| 17100002 | Invalid url. | 6300| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 6301 6302**示例：** 6303 6304```ts 6305// xxx.ets 6306import { webview } from '@kit.ArkWeb'; 6307import { BusinessError } from '@kit.BasicServicesKit'; 6308 6309class TestObj { 6310 constructor() { 6311 } 6312 6313 test(str: string): ArrayBuffer { 6314 let buf = new ArrayBuffer(str.length); 6315 let buff = new Uint8Array(buf); 6316 6317 for (let i = 0; i < str.length; i++) { 6318 buff[i] = str.charCodeAt(i); 6319 } 6320 return buf; 6321 } 6322} 6323 6324@Entry 6325@Component 6326struct WebComponent { 6327 controller: webview.WebviewController = new webview.WebviewController(); 6328 @State testObjtest: TestObj = new TestObj(); 6329 6330 build() { 6331 Column() { 6332 Button('postUrl') 6333 .onClick(() => { 6334 try { 6335 // 数据转化为ArrayBuffer类型。 6336 let postData = this.testObjtest.test("Name=test&Password=test"); 6337 this.controller.postUrl('www.example.com', postData); 6338 } catch (error) { 6339 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6340 } 6341 }) 6342 Web({ src: '', controller: this.controller }) 6343 } 6344 } 6345} 6346``` 6347 6348### createWebPrintDocumentAdapter<sup>11+</sup> 6349 6350createWebPrintDocumentAdapter(jobName: string): print.PrintDocumentAdapter 6351 6352创建web相关打印功能。 6353 6354**系统能力：** SystemCapability.Web.Webview.Core 6355 6356**参数：** 6357 6358| 参数名 | 类型 | 必填 | 说明 | 6359| ------- | ------ | ---- | :-------------------- | 6360| jobName | string | 是 | 需要打印的文件名。 | 6361 6362**返回值：** 6363 6364| 类型 | 说明 | 6365| -------------------- | ------------------------- | 6366| print.printDocumentAdapter | 返回打印文档的适配器。 | 6367 6368**错误码：** 6369 6370以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6371 6372| 错误码ID | 错误信息 | 6373| -------- | -------------------------------------------------------------------------- | 6374| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 6375| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6376 6377**示例：** 6378 6379```ts 6380// xxx.ets 6381import { webview } from '@kit.ArkWeb'; 6382import { BusinessError, print } from '@kit.BasicServicesKit'; 6383 6384@Entry 6385@Component 6386struct WebComponent { 6387 controller: webview.WebviewController = new webview.WebviewController(); 6388 6389 build() { 6390 Column() { 6391 Button('createWebPrintDocumentAdapter') 6392 .onClick(() => { 6393 try { 6394 let webPrintDocadapter = this.controller.createWebPrintDocumentAdapter('example.pdf'); 6395 print.print('example_jobid', webPrintDocadapter, null, getContext()); 6396 } catch (error) { 6397 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6398 } 6399 }) 6400 Web({ src: 'www.example.com', controller: this.controller }) 6401 } 6402 } 6403} 6404``` 6405### isIncognitoMode<sup>11+</sup> 6406 6407isIncognitoMode(): boolean 6408 6409查询当前是否是隐私模式的Webview。 6410 6411**系统能力：** SystemCapability.Web.Webview.Core 6412 6413**返回值：** 6414 6415| 类型 | 说明 | 6416| -------------------- | ------------------------- | 6417| boolean | 返回是否是隐私模式的Webview。 | 6418 6419**错误码：** 6420 6421以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6422 6423| 错误码ID | 错误信息 | 6424| -------- | -------------------------------------------------------------------------- | 6425| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6426 6427**示例：** 6428 6429```ts 6430// xxx.ets 6431import { webview } from '@kit.ArkWeb'; 6432import { BusinessError } from '@kit.BasicServicesKit'; 6433 6434@Entry 6435@Component 6436struct WebComponent { 6437 controller: webview.WebviewController = new webview.WebviewController(); 6438 6439 build() { 6440 Column() { 6441 Button('isIncognitoMode') 6442 .onClick(() => { 6443 try { 6444 let result = this.controller.isIncognitoMode(); 6445 console.log('isIncognitoMode' + result); 6446 } catch (error) { 6447 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6448 } 6449 }) 6450 Web({ src: 'www.example.com', controller: this.controller }) 6451 } 6452 } 6453} 6454``` 6455 6456### getSecurityLevel<sup>11+</sup> 6457 6458getSecurityLevel(): SecurityLevel 6459 6460获取当前网页的安全级别。 6461 6462**系统能力：** SystemCapability.Web.Webview.Core 6463 6464**返回值：** 6465 6466| 类型 | 说明 | 6467| ----------------------------------- | --------------------------- | 6468| [SecurityLevel](#securitylevel11) | 当前网页的安全级别，具体值为NONE、SECURE、WARNING、DANGEROUS。 | 6469 6470**错误码：** 6471 6472以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6473 6474| 错误码ID | 错误信息 | 6475| -------- | ------------------------------------------------------------ | 6476| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6477 6478**示例：** 6479 6480```ts 6481import { webview } from '@kit.ArkWeb'; 6482 6483@Entry 6484@Component 6485struct WebComponent { 6486 controller: webview.WebviewController = new webview.WebviewController(); 6487 6488 build() { 6489 Column() { 6490 Web({ src: 'www.example.com', controller: this.controller }) 6491 .onPageEnd((event) => { 6492 if (event) { 6493 let securityLevel = this.controller.getSecurityLevel(); 6494 console.info('securityLevel: ', securityLevel); 6495 } 6496 }) 6497 } 6498 } 6499} 6500``` 6501 6502### setScrollable<sup>12+</sup> 6503 6504setScrollable(enable: boolean, type?: ScrollType): void 6505 6506设置网页是否允许滚动。 6507 6508**系统能力：** SystemCapability.Web.Webview.Core 6509 6510**参数：** 6511 6512| 参数名 | 类型 | 必填 | 说明 | 6513| ------ | -------- | ---- | ---------------------- | 6514| enable | boolean | 是 | 表示是否将网页设置为允许滚动，true表示设置为允许滚动，false表示禁止滚动。 | 6515| type | [ScrollType](#scrolltype12) | 否 | 网页可触发的滚动类型，支持缺省配置。<br/> - enable为false时，表示禁止ScrollType类型的滚动，当ScrollType缺省时表示禁止所有类型网页滚动。<br/> - enable为true时，ScrollType缺省与否，都表示允许所有类型的网页滚动。| 6516 6517**错误码：** 6518 6519以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6520 6521| 错误码ID | 错误信息 | 6522| -------- | ------------------------------------------------------------ | 6523| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 6524| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6525 6526**示例：** 6527 6528```ts 6529// xxx.ets 6530import { webview } from '@kit.ArkWeb'; 6531import { BusinessError } from '@kit.BasicServicesKit'; 6532 6533@Entry 6534@Component 6535struct WebComponent { 6536 controller: webview.WebviewController = new webview.WebviewController(); 6537 6538 build() { 6539 Column() { 6540 Button('setScrollable') 6541 .onClick(() => { 6542 try { 6543 this.controller.setScrollable(true); 6544 } catch (error) { 6545 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6546 } 6547 }) 6548 Web({ src: 'www.example.com', controller: this.controller }) 6549 } 6550 } 6551} 6552``` 6553 6554### getScrollable<sup>12+</sup> 6555 6556getScrollable(): boolean 6557 6558获取当前网页是否允许滚动。 6559 6560**系统能力：** SystemCapability.Web.Webview.Core 6561 6562**返回值：** 6563 6564| 类型 | 说明 | 6565| ------ | -------------- | 6566| boolean | 当前网页是否允许滚动，true为允许滚动，false为禁止滚动。 | 6567 6568**错误码：** 6569 6570以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6571 6572| 错误码ID | 错误信息 | 6573| -------- | ------------------------------------------------------------ | 6574| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6575 6576**示例：** 6577 6578```ts 6579// xxx.ets 6580import { webview } from '@kit.ArkWeb'; 6581import { BusinessError } from '@kit.BasicServicesKit'; 6582 6583@Entry 6584@Component 6585struct WebComponent { 6586 controller: webview.WebviewController = new webview.WebviewController(); 6587 6588 build() { 6589 Column() { 6590 Button('getScrollable') 6591 .onClick(() => { 6592 try { 6593 let scrollEnabled = this.controller.getScrollable(); 6594 console.log("scrollEnabled: " + scrollEnabled); 6595 } catch (error) { 6596 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6597 } 6598 }) 6599 Web({ src: 'www.example.com', controller: this.controller }) 6600 } 6601 } 6602} 6603``` 6604 6605### setPrintBackground<sup>12+</sup> 6606 6607setPrintBackground(enable: boolean): void 6608 6609设置是否打印网页背景。 6610 6611**系统能力：** SystemCapability.Web.Webview.Core 6612 6613**参数：** 6614 6615| 参数名 | 类型 | 必填 | 说明 | 6616| -------- | ------- | ---- | -------------------------------------- | 6617| enable | boolean | 是 | 表示是否打印网页背景，true表示设置为打印网页背景，false表示取消网页背景打印。 | 6618 6619**错误码：** 6620 6621以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6622 6623| 错误码ID | 错误信息 | 6624| -------- | ------------------------------------------------------------ | 6625| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 6626| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6627 6628**示例：** 6629 6630```ts 6631import { webview } from '@kit.ArkWeb'; 6632import { BusinessError } from '@kit.BasicServicesKit'; 6633 6634@Entry 6635@Component 6636struct WebComponent { 6637 controller: webview.WebviewController = new webview.WebviewController(); 6638 6639 build() { 6640 Column() { 6641 Button('setPrintBackground') 6642 .onClick(() => { 6643 try { 6644 this.controller.setPrintBackground(false); 6645 } catch (error) { 6646 console.error(`ErrorCode:${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6647 } 6648 }) 6649 Web({ src: 'www.example.com', controller: this.controller }) 6650 } 6651 } 6652} 6653``` 6654 6655### getPrintBackground<sup>12+</sup> 6656 6657getPrintBackground(): boolean 6658 6659查询webview是否打印网页背景。 6660 6661**系统能力：** SystemCapability.Web.Webview.Core 6662 6663**返回值：** 6664 6665| 类型 | 说明 | 6666| -------------------- | ------------------------- | 6667| boolean | 返回Webview是否打印网页背景。 | 6668 6669**错误码：** 6670 6671以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6672 6673| 错误码ID | 错误信息 | 6674| -------- | ------------------------------------------------------------ | 6675| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6676 6677**示例：** 6678 6679```ts 6680import { webview } from '@kit.ArkWeb'; 6681import { BusinessError } from '@kit.BasicServicesKit'; 6682 6683@Entry 6684@Component 6685struct WebComponent { 6686 controller: webview.WebviewController = new webview.WebviewController(); 6687 6688 build() { 6689 Column() { 6690 Button('setPrintBackground') 6691 .onClick(() => { 6692 try { 6693 let enable = this.controller.getPrintBackground(); 6694 console.log("getPrintBackground: " + enable); 6695 } catch (error) { 6696 console.error(`ErrorCode:${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6697 } 6698 }) 6699 Web({ src: 'www.example.com', controller: this.controller }) 6700 } 6701 } 6702} 6703``` 6704 6705### getLastJavascriptProxyCallingFrameUrl<sup>12+</sup> 6706 6707getLastJavascriptProxyCallingFrameUrl(): string 6708 6709通过[registerJavaScriptProxy](#registerjavascriptproxy)或者[javaScriptProxy](ts-basic-components-web.md#javascriptproxy)注入JavaScript对象到window对象中。该接口可以获取最后一次调用注入的对象的frame的url。 6710 6711**系统能力：** SystemCapability.Web.Webview.Core 6712 6713**错误码：** 6714 6715以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6716 6717| 错误码ID | 错误信息 | 6718| -------- | ------------------------------------------------------------ | 6719| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6720 6721**示例：** 6722 6723```ts 6724// xxx.ets 6725import { webview } from '@kit.ArkWeb'; 6726import { BusinessError } from '@kit.BasicServicesKit'; 6727 6728class TestObj { 6729 mycontroller: webview.WebviewController; 6730 6731 constructor(controller: webview.WebviewController) { 6732 this.mycontroller = controller; 6733 } 6734 6735 test(testStr: string): string { 6736 console.log('Web Component str' + testStr + " url " + this.mycontroller.getLastJavascriptProxyCallingFrameUrl()); 6737 return testStr; 6738 } 6739 6740 toString(): void { 6741 console.log('Web Component toString ' + " url " + this.mycontroller.getLastJavascriptProxyCallingFrameUrl()); 6742 } 6743 6744 testNumber(testNum: number): number { 6745 console.log('Web Component number' + testNum + " url " + this.mycontroller.getLastJavascriptProxyCallingFrameUrl()); 6746 return testNum; 6747 } 6748 6749 testBool(testBol: boolean): boolean { 6750 console.log('Web Component boolean' + testBol + " url " + this.mycontroller.getLastJavascriptProxyCallingFrameUrl()); 6751 return testBol; 6752 } 6753} 6754 6755class WebObj { 6756 mycontroller: webview.WebviewController; 6757 6758 constructor(controller: webview.WebviewController) { 6759 this.mycontroller = controller; 6760 } 6761 6762 webTest(): string { 6763 console.log('Web test ' + " url " + this.mycontroller.getLastJavascriptProxyCallingFrameUrl()); 6764 return "Web test"; 6765 } 6766 6767 webString(): void { 6768 console.log('Web test toString ' + " url " + this.mycontroller.getLastJavascriptProxyCallingFrameUrl()); 6769 } 6770} 6771 6772@Entry 6773@Component 6774struct Index { 6775 controller: webview.WebviewController = new webview.WebviewController(); 6776 @State testObjtest: TestObj = new TestObj(this.controller); 6777 @State webTestObj: WebObj = new WebObj(this.controller); 6778 6779 build() { 6780 Column() { 6781 Button('refresh') 6782 .onClick(() => { 6783 try { 6784 this.controller.refresh(); 6785 } catch (error) { 6786 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6787 } 6788 }) 6789 Button('Register JavaScript To Window') 6790 .onClick(() => { 6791 try { 6792 this.controller.registerJavaScriptProxy(this.testObjtest, "objName", ["test", "toString", "testNumber", "testBool"]); 6793 this.controller.registerJavaScriptProxy(this.webTestObj, "objTestName", ["webTest", "webString"]); 6794 } catch (error) { 6795 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6796 } 6797 }) 6798 Button('deleteJavaScriptRegister') 6799 .onClick(() => { 6800 try { 6801 this.controller.deleteJavaScriptRegister("objName"); 6802 this.controller.deleteJavaScriptRegister("objTestName"); 6803 } catch (error) { 6804 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6805 } 6806 }) 6807 Web({ src: $rawfile('index.html'), controller: this.controller }) 6808 .javaScriptAccess(true) 6809 } 6810 } 6811} 6812``` 6813 6814加载的html文件。 6815```html 6816<!-- index.html --> 6817<!DOCTYPE html> 6818<html> 6819 <meta charset="utf-8"> 6820 <body> 6821 <button type="button" onclick="htmlTest()">Click Me!</button> 6822 <p id="demo"></p> 6823 <p id="webDemo"></p> 6824 </body> 6825 <script type="text/javascript"> 6826 function htmlTest() { 6827 // This function call expects to return "ArkUI Web Component" 6828 let str=objName.test("webtest data"); 6829 objName.testNumber(1); 6830 objName.testBool(true); 6831 document.getElementById("demo").innerHTML=str; 6832 console.log('objName.test result:'+ str) 6833 6834 // This function call expects to return "Web test" 6835 let webStr = objTestName.webTest(); 6836 document.getElementById("webDemo").innerHTML=webStr; 6837 console.log('objTestName.webTest result:'+ webStr) 6838 } 6839</script> 6840</html> 6841``` 6842 6843### pauseAllTimers<sup>12+</sup> 6844 6845pauseAllTimers(): void 6846 6847暂停所有WebView的定时器。 6848 6849**系统能力：** SystemCapability.Web.Webview.Core 6850 6851**错误码：** 6852 6853以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6854 6855| 错误码ID | 错误信息 | 6856| -------- | ------------------------------------------------------------ | 6857| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6858 6859**示例：** 6860 6861```ts 6862import { webview } from '@kit.ArkWeb'; 6863import { BusinessError } from '@kit.BasicServicesKit'; 6864 6865@Entry 6866@Component 6867struct WebComponent { 6868 controller: webview.WebviewController = new webview.WebviewController(); 6869 6870 build() { 6871 Column() { 6872 Row() { 6873 Button('PauseAllTimers') 6874 .onClick(() => { 6875 try { 6876 webview.WebviewController.pauseAllTimers(); 6877 } catch (error) { 6878 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6879 } 6880 }) 6881 } 6882 Web({ src: $rawfile("index.html"), controller: this.controller }) 6883 } 6884 } 6885} 6886``` 6887加载的html文件。 6888 6889```html 6890<!DOCTYPE html> 6891<html> 6892 <body> 6893 <button style="width:300px;height:150px;font-size:50px" onclick="startTimer()">start</button> 6894 <button style="width:300px;height:150px;font-size:50px" onclick="resetTimer()">reset</button> 6895 <input style="width:300px;height:150px;font-size:50px" value="0" id="show_num"> 6896 </body> 6897</html> 6898<script> 6899 var timer = null; 6900 var num = 0; 6901 6902 function startTimer() { 6903 timer = setInterval(function() { 6904 document.getElementById("show_num").value = ++num; 6905 }, 1000); 6906 } 6907</script> 6908``` 6909 6910### resumeAllTimers<sup>12+</sup> 6911 6912resumeAllTimers(): void 6913 6914恢复从pauseAllTimers()接口中被暂停的所有的定时器。 6915 6916**系统能力：** SystemCapability.Web.Webview.Core 6917 6918**错误码：** 6919 6920以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 6921 6922| 错误码ID | 错误信息 | 6923| -------- | ------------------------------------------------------------ | 6924| 17100001 | Init error. The WebviewController must be associated with a Web component. | 6925 6926**示例：** 6927 6928```ts 6929import { webview } from '@kit.ArkWeb'; 6930import { BusinessError } from '@kit.BasicServicesKit'; 6931 6932@Entry 6933@Component 6934struct WebComponent { 6935 controller: webview.WebviewController = new webview.WebviewController(); 6936 6937 build() { 6938 Column() { 6939 Row() { 6940 Button('ResumeAllTimers') 6941 .onClick(() => { 6942 try { 6943 webview.WebviewController.resumeAllTimers(); 6944 } catch (error) { 6945 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6946 } 6947 }) 6948 Button('PauseAllTimers') 6949 .onClick(() => { 6950 try { 6951 webview.WebviewController.pauseAllTimers(); 6952 } catch (error) { 6953 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6954 } 6955 }) 6956 } 6957 Web({ src: $rawfile("index.html"), controller: this.controller }) 6958 } 6959 } 6960} 6961``` 6962加载的html文件。 6963 6964```html 6965<!DOCTYPE html> 6966<html> 6967 <body> 6968 <button style="width:300px;height:150px;font-size:50px" onclick="startTimer()">start</button> 6969 <button style="width:300px;height:150px;font-size:50px" onclick="resetTimer()">reset</button> 6970 <input style="width:300px;height:150px;font-size:50px" value="0" id="show_num"> 6971 </body> 6972</html> 6973<script> 6974 var timer = null; 6975 var num = 0; 6976 6977 function startTimer() { 6978 timer = setInterval(function() { 6979 document.getElementById("show_num").value = ++num; 6980 }, 1000); 6981 } 6982 6983 function resetTimer() { 6984 clearInterval(timer); 6985 document.getElementById("show_num").value = 0; 6986 num = 0; 6987 } 6988</script> 6989``` 6990 6991### stopAllMedia<sup>12+</sup> 6992 6993stopAllMedia(): void 6994 6995控制网页所有音视频停止。 6996 6997**系统能力：** SystemCapability.Web.Webview.Core 6998 6999**错误码：** 7000 7001以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7002 7003| 错误码ID | 错误信息 | 7004| -------- | ------------------------------------------------------------ | 7005| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7006 7007**示例：** 7008 7009```ts 7010// xxx.ets 7011import { webview } from '@kit.ArkWeb'; 7012import { BusinessError } from '@kit.BasicServicesKit'; 7013 7014@Entry 7015@Component 7016struct WebComponent { 7017 controller: webview.WebviewController = new webview.WebviewController(); 7018 7019 build() { 7020 Column() { 7021 Button('stopAllMedia') 7022 .onClick(() => { 7023 try { 7024 this.controller.stopAllMedia(); 7025 } catch (error) { 7026 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7027 } 7028 }) 7029 Web({ src: 'www.example.com', controller: this.controller }) 7030 } 7031 } 7032} 7033``` 7034 7035### pauseAllMedia<sup>12+</sup> 7036 7037pauseAllMedia(): void 7038 7039控制网页所有音视频暂停。 7040 7041**系统能力：** SystemCapability.Web.Webview.Core 7042 7043**错误码：** 7044 7045以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7046 7047| 错误码ID | 错误信息 | 7048| -------- | ------------------------------------------------------------ | 7049| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7050 7051**示例：** 7052 7053```ts 7054// xxx.ets 7055import { webview } from '@kit.ArkWeb'; 7056import { BusinessError } from '@kit.BasicServicesKit'; 7057 7058@Entry 7059@Component 7060struct WebComponent { 7061 controller: webview.WebviewController = new webview.WebviewController(); 7062 7063 build() { 7064 Column() { 7065 Button('pauseAllMedia') 7066 .onClick(() => { 7067 try { 7068 this.controller.pauseAllMedia(); 7069 } catch (error) { 7070 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7071 } 7072 }) 7073 Web({ src: 'www.example.com', controller: this.controller }) 7074 } 7075 } 7076} 7077``` 7078 7079### resumeAllMedia<sup>12+</sup> 7080 7081resumeAllMedia(): void 7082 7083控制网页被pauseAllMedia接口暂停的音视频继续播放。 7084 7085**系统能力：** SystemCapability.Web.Webview.Core 7086 7087**错误码：** 7088 7089以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7090 7091| 错误码ID | 错误信息 | 7092| -------- | ------------------------------------------------------------ | 7093| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7094 7095**示例：** 7096 7097```ts 7098// xxx.ets 7099import { webview } from '@kit.ArkWeb'; 7100import { BusinessError } from '@kit.BasicServicesKit'; 7101 7102@Entry 7103@Component 7104struct WebComponent { 7105 controller: webview.WebviewController = new webview.WebviewController(); 7106 7107 build() { 7108 Column() { 7109 Button('resumeAllMedia') 7110 .onClick(() => { 7111 try { 7112 this.controller.resumeAllMedia(); 7113 } catch (error) { 7114 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7115 } 7116 }) 7117 Web({ src: 'www.example.com', controller: this.controller }) 7118 } 7119 } 7120} 7121``` 7122 7123### closeAllMediaPresentations<sup>12+</sup> 7124 7125closeAllMediaPresentations(): void 7126 7127控制网页所有全屏视频关闭。 7128 7129**系统能力：** SystemCapability.Web.Webview.Core 7130 7131**错误码：** 7132 7133以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7134 7135| 错误码ID | 错误信息 | 7136| -------- | ------------------------------------------------------------ | 7137| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7138 7139**示例：** 7140 7141```ts 7142// xxx.ets 7143import { webview } from '@kit.ArkWeb'; 7144import { BusinessError } from '@kit.BasicServicesKit'; 7145 7146@Entry 7147@Component 7148struct WebComponent { 7149 controller: webview.WebviewController = new webview.WebviewController(); 7150 7151 build() { 7152 Column() { 7153 Button('closeAllMediaPresentations') 7154 .onClick(() => { 7155 try { 7156 this.controller.closeAllMediaPresentations(); 7157 } catch (error) { 7158 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7159 } 7160 }) 7161 Web({ src: 'www.example.com', controller: this.controller }) 7162 } 7163 } 7164} 7165``` 7166 7167### getMediaPlaybackState<sup>12+</sup> 7168 7169getMediaPlaybackState(): MediaPlaybackState 7170 7171查询当前所有音视频播控状态。 7172 7173**系统能力：** SystemCapability.Web.Webview.Core 7174 7175**返回值：** 7176 7177| 类型 | 说明 | 7178| ------------------------------------------- | --------------------------------------------------------- | 7179| [MediaPlaybackState](#mediaplaybackstate12) | 当前网页的播控状态，具体值为NONE、PLAYING、PAUSED、STOPPED。 | 7180 7181**错误码：** 7182 7183以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7184 7185| 错误码ID | 错误信息 | 7186| -------- | ------------------------------------------------------------ | 7187| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7188 7189**示例：** 7190 7191```ts 7192// xxx.ets 7193import { webview } from '@kit.ArkWeb'; 7194import { BusinessError } from '@kit.BasicServicesKit'; 7195 7196@Entry 7197@Component 7198struct WebComponent { 7199 controller: webview.WebviewController = new webview.WebviewController(); 7200 7201 build() { 7202 Column() { 7203 Button('getMediaPlaybackState') 7204 .onClick(() => { 7205 try { 7206 console.log("MediaPlaybackState : " + this.controller.getMediaPlaybackState()); 7207 } catch (error) { 7208 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7209 } 7210 }) 7211 Web({ src: 'www.example.com', controller: this.controller }) 7212 } 7213 } 7214} 7215``` 7216 7217### setWebSchemeHandler<sup>12+</sup> 7218 7219setWebSchemeHandler(scheme: string, handler: WebSchemeHandler): void 7220 7221为当前Web组件设置[WebSchemeHandler](#webschemehandler12), [WebSchemeHandler](#webschemehandler12)类用于拦截指定scheme的请求。 7222 7223**系统能力：** SystemCapability.Web.Webview.Core 7224 7225**参数：** 7226 7227| 参数名 | 类型 | 必填 | 说明 | 7228| ------ | ------ | ---- | :------------------------ | 7229| scheme | string | 是 | 要拦截的协议。 | 7230| handler | [WebSchemeHandler](#webschemehandler12) | 是 | 拦截此协议的拦截器。 | 7231 7232**错误码：** 7233 7234以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7235 7236| 错误码ID | 错误信息 | 7237| -------- | ------------------------------------------------------------ | 7238| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 7239| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7240 7241**示例：** 7242 7243```ts 7244// xxx.ets 7245import { webview } from '@kit.ArkWeb'; 7246import { BusinessError } from '@kit.BasicServicesKit'; 7247 7248@Entry 7249@Component 7250struct WebComponent { 7251 controller: webview.WebviewController = new webview.WebviewController(); 7252 schemeHandler: webview.WebSchemeHandler = new webview.WebSchemeHandler(); 7253 7254 build() { 7255 Column() { 7256 Button('setWebSchemeHandler') 7257 .onClick(() => { 7258 try { 7259 this.controller.setWebSchemeHandler('http', this.schemeHandler); 7260 } catch (error) { 7261 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7262 } 7263 }) 7264 Web({ src: 'www.example.com', controller: this.controller }) 7265 } 7266 } 7267} 7268``` 7269 7270### clearWebSchemeHandler<sup>12+</sup> 7271 7272clearWebSchemeHandler(): void 7273 7274清除当前Web组件设置的所有WebSchemeHandler。 7275 7276**系统能力：** SystemCapability.Web.Webview.Core 7277 7278**错误码：** 7279 7280以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7281 7282| 错误码ID | 错误信息 | 7283| -------- | ------------------------------------------------------------ | 7284| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7285 7286**示例：** 7287 7288```ts 7289// xxx.ets 7290import { webview } from '@kit.ArkWeb'; 7291import { BusinessError } from '@kit.BasicServicesKit'; 7292 7293@Entry 7294@Component 7295struct WebComponent { 7296 controller: webview.WebviewController = new webview.WebviewController(); 7297 7298 build() { 7299 Column() { 7300 Button('clearWebSchemeHandler') 7301 .onClick(() => { 7302 try { 7303 this.controller.clearWebSchemeHandler(); 7304 } catch (error) { 7305 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7306 } 7307 }) 7308 Web({ src: 'www.example.com', controller: this.controller }) 7309 } 7310 } 7311} 7312``` 7313 7314### setServiceWorkerWebSchemeHandler<sup>12+</sup> 7315 7316setServiceWorkerWebSchemeHandler(scheme: string, handler: WebSchemeHandler): void 7317 7318为当前应用的所有Web组件设置用于拦截ServiceWorker的WebSchemeHandler。 7319 7320**系统能力：** SystemCapability.Web.Webview.Core 7321 7322**参数：** 7323 7324| 参数名 | 类型 | 必填 | 说明 | 7325| ------ | ------ | ---- | :------------------------ | 7326| scheme | string | 是 | 要拦截的协议。 | 7327| handler | [WebSchemeHandler](#webschemehandler12) | 是 | 拦截此协议的拦截器。 | 7328 7329**错误码：** 7330 7331以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7332 7333| 错误码ID | 错误信息 | 7334| -------- | ------------------------------------------------------------ | 7335| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 7336 7337**示例：** 7338 7339```ts 7340// xxx.ets 7341import { webview } from '@kit.ArkWeb'; 7342import { BusinessError } from '@kit.BasicServicesKit'; 7343 7344@Entry 7345@Component 7346struct WebComponent { 7347 controller: webview.WebviewController = new webview.WebviewController(); 7348 schemeHandler: webview.WebSchemeHandler = new webview.WebSchemeHandler(); 7349 7350 build() { 7351 Column() { 7352 Button('setWebSchemeHandler') 7353 .onClick(() => { 7354 try { 7355 webview.WebviewController.setServiceWorkerWebSchemeHandler('http', this.schemeHandler); 7356 } catch (error) { 7357 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7358 } 7359 }) 7360 Web({ src: 'www.example.com', controller: this.controller }) 7361 } 7362 } 7363} 7364``` 7365 7366### clearServiceWorkerWebSchemeHandler<sup>12+</sup> 7367 7368clearServiceWorkerWebSchemeHandler(): void 7369 7370清除应用中设置的所有用于拦截ServiceWorker的WebSchemeHandler。 7371 7372**系统能力：** SystemCapability.Web.Webview.Core 7373 7374**示例：** 7375 7376```ts 7377// xxx.ets 7378import { webview } from '@kit.ArkWeb'; 7379 7380@Entry 7381@Component 7382struct WebComponent { 7383 controller: webview.WebviewController = new webview.WebviewController(); 7384 7385 build() { 7386 Column() { 7387 Button('clearServiceWorkerWebSchemeHandler') 7388 .onClick(() => { 7389 webview.WebviewController.clearServiceWorkerWebSchemeHandler(); 7390 }) 7391 Web({ src: 'www.example.com', controller: this.controller }) 7392 } 7393 } 7394} 7395``` 7396 7397### startCamera<sup>12+</sup> 7398 7399startCamera(): void 7400 7401开启当前网页摄像头捕获。 7402 7403**系统能力：** SystemCapability.Web.Webview.Core 7404 7405**错误码：** 7406 7407以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7408 7409| 错误码ID | 错误信息 | 7410| -------- | ------------------------------------------------------------ | 7411| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7412 7413**示例：** 7414```ts 7415// xxx.ets 7416import { webview } from '@kit.ArkWeb'; 7417import { BusinessError } from '@kit.BasicServicesKit'; 7418import { abilityAccessCtrl, PermissionRequestResult, common } from '@kit.AbilityKit'; 7419 7420let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 7421try { 7422 let context: Context = getContext(this) as common.UIAbilityContext; 7423 atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA'], (err: BusinessError, data: PermissionRequestResult) => { 7424 console.info('data:' + JSON.stringify(data)); 7425 console.info('data permissions:' + data.permissions); 7426 console.info('data authResults:' + data.authResults); 7427 }) 7428} catch (error) { 7429 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7430} 7431 7432@Entry 7433@Component 7434struct WebComponent { 7435 controller: webview.WebviewController = new webview.WebviewController(); 7436 7437 build() { 7438 Column() { 7439 Button("startCamera").onClick(() => { 7440 try { 7441 this.controller.startCamera(); 7442 } catch (error) { 7443 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7444 } 7445 }) 7446 Button("stopCamera").onClick(() => { 7447 try { 7448 this.controller.stopCamera(); 7449 } catch (error) { 7450 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7451 } 7452 }) 7453 Button("closeCamera").onClick(() => { 7454 try { 7455 this.controller.closeCamera(); 7456 } catch (error) { 7457 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 7458 } 7459 }) 7460 Web({ src: $rawfile('index.html'), controller: this.controller }) 7461 .onPermissionRequest((event) => { 7462 if (event) { 7463 AlertDialog.show({ 7464 title: 'title', 7465 message: 'text', 7466 primaryButton: { 7467 value: 'deny', 7468 action: () => { 7469 event.request.deny(); 7470 } 7471 }, 7472 secondaryButton: { 7473 value: 'onConfirm', 7474 action: () => { 7475 event.request.grant(event.request.getAccessibleResource()); 7476 } 7477 }, 7478 cancel: () => { 7479 event.request.deny(); 7480 } 7481 }) 7482 } 7483 }) 7484 } 7485 } 7486} 7487 7488``` 7489加载的html文件。 7490 ```html 7491<!-- index.html --> 7492<!DOCTYPE html> 7493<html> 7494 <head> 7495 <meta charset="UTF-8"> 7496 </head> 7497 <body> 7498 <video id="video" width="400px" height="400px" autoplay="autoplay"> 7499 </video> 7500 <input type="button" title="HTML5摄像头" value="开启摄像头" onclick="getMedia()" /> 7501 <script> 7502 function getMedia() { 7503 let constraints = { 7504 video: { 7505 width: 500, 7506 height: 500 7507 }, 7508 audio: true 7509 } 7510 let video = document.getElementById("video"); 7511 let promise = navigator.mediaDevices.getUserMedia(constraints); 7512 promise.then(function(MediaStream) { 7513 video.srcObject = MediaStream; 7514 video.play(); 7515 }) 7516 } 7517 </script> 7518 </body> 7519</html> 7520 ``` 7521 7522### stopCamera<sup>12+</sup> 7523 7524stopCamera(): void 7525 7526停止当前网页摄像头捕获。 7527 7528**系统能力：** SystemCapability.Web.Webview.Core 7529 7530**错误码：** 7531 7532以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7533 7534| 错误码ID | 错误信息 | 7535| -------- | ------------------------------------------------------------ | 7536| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7537 7538**示例：** 7539 7540完整示例代码参考[startCamera](#startcamera12)。 7541 7542### closeCamera<sup>12+</sup> 7543 7544closeCamera(): void 7545 7546关闭当前网页摄像头捕获。 7547 7548**系统能力：** SystemCapability.Web.Webview.Core 7549 7550**错误码：** 7551 7552以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7553 7554| 错误码ID | 错误信息 | 7555| -------- | ------------------------------------------------------------ | 7556| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7557 7558**示例：** 7559 7560完整示例代码参考[startCamera](#startcamera12)。 7561 7562### precompileJavaScript<sup>12+</sup> 7563 7564precompileJavaScript(url: string, script: string | Uint8Array, cacheOptions: CacheOptions): Promise\<number\> 7565 7566预编译JavaScript生成字节码缓存或根据提供的参数更新已有的字节码缓存。 7567接口通过提供的文件信息、E-Tag响应头和Last-Modified响应头判断是否需要更新已有的字节码缓存。 7568 7569**系统能力：** SystemCapability.Web.Webview.Core 7570 7571**参数：** 7572 7573| 参数名 | 类型 | 必填 | 说明 | 7574| ------- | ------ | ---- | :-------------------- | 7575| url | string | 是 | 本地JavaScript文件对应的网络地址，即业务网页请求该文件的服务器版本时使用的网络地址。网络地址仅支持http或https协议，长度不超过2048。如果该网络地址对应的缓存失效，则业务网页将通过网络请求对应的资源。 | 7576| script | string \| Uint8Array | 是 | 本地JavaScript的文本内容。内容不能为空。 | 7577| cacheOptions | [CacheOptions](#cacheoptions12) | 是 | 用于控制字节码缓存更新。 | 7578 7579**返回值：** 7580 7581| 类型 | 说明 | 7582| ----------------------------------- | --------------------------- | 7583| Promise\<number\> | 生成字节码缓存的错误码，0表示无错误，-1表示内部错误。 | 7584 7585**错误码：** 7586 7587以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 7588 7589| 错误码ID | 错误信息 | 7590| -------- | ------------------------------------------------------------ | 7591| 401 | Invalid input parameter.Possible causes: 1. Mandatory parameters are left unspecified.2. Incorrect parameter types.3. Parameter verification failed. | 7592| 17100001 | Init error. The WebviewController must be associated with a Web component. | 7593 7594**示例：** 7595 7596接口推荐配合动态组件使用，使用离线的Web组件用于生成字节码缓存，并在适当的时机加载业务用Web组件使用这些字节码缓存。下方是代码示例： 7597 75981. 首先，在EntryAbility中将UIContext存到localStorage中。 7599 7600 ```ts 7601 // EntryAbility.ets 7602 import { UIAbility } from '@kit.AbilityKit'; 7603 import { window } from '@kit.ArkUI'; 7604 7605 const localStorage: LocalStorage = new LocalStorage('uiContext'); 7606 7607 export default class EntryAbility extends UIAbility { 7608 storage: LocalStorage = localStorage; 7609 7610 onWindowStageCreate(windowStage: window.WindowStage) { 7611 windowStage.loadContent('pages/Index', this.storage, (err, data) => { 7612 if (err.code) { 7613 return; 7614 } 7615 7616 this.storage.setOrCreate<UIContext>("uiContext", windowStage.getMainWindowSync().getUIContext()); 7617 }); 7618 } 7619 } 7620 ``` 7621 76222. 编写动态组件所需基础代码。 7623 7624 ```ts 7625 // DynamicComponent.ets 7626 import { NodeController, BuilderNode, FrameNode, UIContext } from '@kit.ArkUI'; 7627 7628 export interface BuilderData { 7629 url: string; 7630 controller: WebviewController; 7631 } 7632 7633 const storage = LocalStorage.getShared(); 7634 7635 export class NodeControllerImpl extends NodeController { 7636 private rootNode: BuilderNode<BuilderData[]> | null = null; 7637 private wrappedBuilder: WrappedBuilder<BuilderData[]> | null = null; 7638 7639 constructor(wrappedBuilder: WrappedBuilder<BuilderData[]>) { 7640 super(); 7641 this.wrappedBuilder = wrappedBuilder; 7642 } 7643 7644 makeNode(): FrameNode | null { 7645 if (this.rootNode != null) { 7646 return this.rootNode.getFrameNode(); 7647 } 7648 return null; 7649 } 7650 7651 initWeb(url: string, controller: WebviewController) { 7652 if(this.rootNode != null) { 7653 return; 7654 } 7655 7656 const uiContext: UIContext = storage.get<UIContext>("uiContext") as UIContext; 7657 if (!uiContext) { 7658 return; 7659 } 7660 this.rootNode = new BuilderNode(uiContext); 7661 this.rootNode.build(this.wrappedBuilder, { url: url, controller: controller }); 7662 } 7663 } 7664 7665 export const createNode = (wrappedBuilder: WrappedBuilder<BuilderData[]>, data: BuilderData) => { 7666 const baseNode = new NodeControllerImpl(wrappedBuilder); 7667 baseNode.initWeb(data.url, data.controller); 7668 return baseNode; 7669 } 7670 ``` 7671 76723. 编写用于生成字节码缓存的组件，本例中的本地Javascript资源内容通过文件读取接口读取rawfile目录下的本地文件。 7673 7674 <!--code_no_check--> 7675 ```ts 7676 // PrecompileWebview.ets 7677 import { BuilderData } from "./DynamicComponent"; 7678 import { Config, configs } from "./PrecompileConfig"; 7679 7680 @Builder 7681 function WebBuilder(data: BuilderData) { 7682 Web({ src: data.url, controller: data.controller }) 7683 .onControllerAttached(() => { 7684 precompile(data.controller, configs); 7685 }) 7686 .fileAccess(true) 7687 } 7688 7689 export const precompileWebview = wrapBuilder<BuilderData[]>(WebBuilder); 7690 7691 export const precompile = async (controller: WebviewController, configs: Array<Config>) => { 7692 for (const config of configs) { 7693 let content = await readRawFile(config.localPath); 7694 7695 try { 7696 controller.precompileJavaScript(config.url, content, config.options) 7697 .then(errCode => { 7698 console.error("precompile successfully! " + errCode); 7699 }).catch((errCode: number) => { 7700 console.error("precompile failed. " + errCode); 7701 }); 7702 } catch (err) { 7703 console.error("precompile failed. " + err.code + " " + err.message); 7704 } 7705 } 7706 } 7707 7708 async function readRawFile(path: string) { 7709 try { 7710 return await getContext().resourceManager.getRawFileContent(path);; 7711 } catch (err) { 7712 return new Uint8Array(0); 7713 } 7714 } 7715 ``` 7716 7717JavaScript资源的获取方式也可通过[网络请求](../apis-network-kit/js-apis-http.md)的方式获取，但此方法获取到的http响应头非标准HTTP响应头格式，需额外将响应头转换成标准HTTP响应头格式后使用。如通过网络请求获取到的响应头是e-tag，则需要将其转换成E-Tag后使用。 7718 77194. 编写业务用组件代码。 7720 7721 <!--code_no_check--> 7722 ```ts 7723 // BusinessWebview.ets 7724 import { BuilderData } from "./DynamicComponent"; 7725 7726 @Builder 7727 function WebBuilder(data: BuilderData) { 7728 // 此处组件可根据业务需要自行扩展 7729 Web({ src: data.url, controller: data.controller }) 7730 .cacheMode(CacheMode.Default) 7731 } 7732 7733 export const businessWebview = wrapBuilder<BuilderData[]>(WebBuilder); 7734 ``` 7735 77365. 编写资源配置信息。 7737 7738 ```ts 7739 // PrecompileConfig.ets 7740 import { webview } from '@kit.ArkWeb' 7741 7742 export interface Config { 7743 url: string, 7744 localPath: string, // 本地资源路径 7745 options: webview.CacheOptions 7746 } 7747 7748 export let configs: Array<Config> = [ 7749 { 7750 url: "https://www.example.com/example.js", 7751 localPath: "example.js", 7752 options: { 7753 responseHeaders: [ 7754 { headerKey: "E-Tag", headerValue: "aWO42N9P9dG/5xqYQCxsx+vDOoU="}, 7755 { headerKey: "Last-Modified", headerValue: "Wed, 21 Mar 2024 10:38:41 GMT"} 7756 ] 7757 } 7758 } 7759 ] 7760 ``` 7761 77626. 在页面中使用。 7763 7764 <!--code_no_check--> 7765 ```ts 7766 // Index.ets 7767 import { webview } from '@kit.ArkWeb'; 7768 import { NodeController } from '@kit.ArkUI'; 7769 import { createNode } from "./DynamicComponent" 7770 import { precompileWebview } from "./PrecompileWebview" 7771 import { businessWebview } from "./BusinessWebview" 7772 7773 @Entry 7774 @Component 7775 struct Index { 7776 @State precompileNode: NodeController | undefined = undefined; 7777 precompileController: webview.WebviewController = new webview.WebviewController(); 7778 7779 @State businessNode: NodeController | undefined = undefined; 7780 businessController: webview.WebviewController = new webview.WebviewController(); 7781 7782 aboutToAppear(): void { 7783 // 初始化用于注入本地资源的Web组件 7784 this.precompileNode = createNode(precompileWebview, 7785 { url: "https://www.example.com/empty.html", controller: this.precompileController}); 7786 } 7787 7788 build() { 7789 Column() { 7790 // 在适当的时机加载业务用Web组件，本例以Button点击触发为例 7791 Button("加载页面") 7792 .onClick(() => { 7793 this.businessNode = createNode(businessWebview, { 7794 url: "https://www.example.com/business.html", 7795 controller: this.businessController 7796 }); 7797 }) 7798 // 用于业务的Web组件 7799 NodeContainer(this.businessNode); 7800 } 7801 } 7802 } 7803 ``` 7804 7805当需要更新本地已经生成的编译字节码时，修改cacheOptions参数中responseHeaders中的E-Tag或Last-Modified响应头对应的值，再次调用接口即可。 7806 7807### onCreateNativeMediaPlayer<sup>12+</sup> 7808 7809onCreateNativeMediaPlayer(callback: CreateNativeMediaPlayerCallback): void 7810 7811注册回调函数，开启[应用接管网页媒体播放功能](ts-basic-components-web.md#enablenativemediaplayer12)后，当网页中有播放媒体时，触发注册的回调函数。 7812如果应用接管网页媒体播放功能未开启，则注册的回调函数不会被触发。 7813 7814**系统能力：** SystemCapability.Web.Webview.Core 7815 7816**参数：** 7817 7818| 参数名 | 类型 | 必填 | 说明 | 7819|--------|------|------|------| 7820| callback | [CreateNativeMediaPlayerCallback](#createnativemediaplayercallback12) | 是 | 接管网页媒体播放的回调函数。 | 7821 7822**示例：** 7823 7824```ts 7825// xxx.ets 7826import { webview } from '@kit.ArkWeb'; 7827 7828class ActualNativeMediaPlayerListener { 7829 handler: webview.NativeMediaPlayerHandler; 7830 7831 constructor(handler: webview.NativeMediaPlayerHandler) { 7832 this.handler = handler; 7833 } 7834 7835 onPlaying() { 7836 // 本地播放器开始播放。 7837 this.handler.handleStatusChanged(webview.PlaybackStatus.PLAYING); 7838 } 7839 onPaused() { 7840 // 本地播放器暂停播放。 7841 this.handler.handleStatusChanged(webview.PlaybackStatus.PAUSED); 7842 } 7843 onSeeking() { 7844 // 本地播放器开始执行跳转到目标时间点。 7845 this.handler.handleSeeking(); 7846 } 7847 onSeekDone() { 7848 // 本地播放器 seek 完成。 7849 this.handler.handleSeekFinished(); 7850 } 7851 onEnded() { 7852 // 本地播放器播放完成。 7853 this.handler.handleEnded(); 7854 } 7855 onVolumeChanged() { 7856 // 获取本地播放器的音量。 7857 let volume: number = getVolume(); 7858 this.handler.handleVolumeChanged(volume); 7859 } 7860 onCurrentPlayingTimeUpdate() { 7861 // 更新播放时间。 7862 let currentTime: number = getCurrentPlayingTime(); 7863 // 将时间单位换算成秒。 7864 let currentTimeInSeconds = convertToSeconds(currentTime); 7865 this.handler.handleTimeUpdate(currentTimeInSeconds); 7866 } 7867 onBufferedChanged() { 7868 // 缓存发生了变化。 7869 // 获取本地播放器的缓存时长。 7870 let bufferedEndTime: number = getCurrentBufferedTime(); 7871 // 将时间单位换算成秒。 7872 let bufferedEndTimeInSeconds = convertToSeconds(bufferedEndTime); 7873 this.handler.handleBufferedEndTimeChanged(bufferedEndTimeInSeconds); 7874 7875 // 检查缓存状态。 7876 // 如果缓存状态发生了变化，则向 ArkWeb 内核通知缓存状态。 7877 let lastReadyState: webview.ReadyState = getLastReadyState(); 7878 let currentReadyState: webview.ReadyState = getCurrentReadyState(); 7879 if (lastReadyState != currentReadyState) { 7880 this.handler.handleReadyStateChanged(currentReadyState); 7881 } 7882 } 7883 onEnterFullscreen() { 7884 // 本地播放器进入了全屏状态。 7885 let isFullscreen: boolean = true; 7886 this.handler.handleFullscreenChanged(isFullscreen); 7887 } 7888 onExitFullscreen() { 7889 // 本地播放器退出了全屏状态。 7890 let isFullscreen: boolean = false; 7891 this.handler.handleFullscreenChanged(isFullscreen); 7892 } 7893 onUpdateVideoSize(width: number, height: number) { 7894 // 当本地播放器解析出视频宽高时， 通知 ArkWeb 内核。 7895 this.handler.handleVideoSizeChanged(width, height); 7896 } 7897 onDurationChanged(duration: number) { 7898 // 本地播放器解析到了新的媒体时长， 通知 ArkWeb 内核。 7899 this.handler.handleDurationChanged(duration); 7900 } 7901 onError(error: webview.MediaError, errorMessage: string) { 7902 // 本地播放器出错了，通知 ArkWeb 内核。 7903 this.handler.handleError(error, errorMessage); 7904 } 7905 onNetworkStateChanged(state: webview.NetworkState) { 7906 // 本地播放器的网络状态发生了变化， 通知 ArkWeb 内核。 7907 this.handler.handleNetworkStateChanged(state); 7908 } 7909 onPlaybackRateChanged(playbackRate: number) { 7910 // 本地播放器的播放速率发生了变化， 通知 ArkWeb 内核。 7911 this.handler.handlePlaybackRateChanged(playbackRate); 7912 } 7913 onMutedChanged(muted: boolean) { 7914 // 本地播放器的静音状态发生了变化， 通知 ArkWeb 内核。 7915 this.handler.handleMutedChanged(muted); 7916 } 7917 7918 // ... 监听本地播放器其他的状态 ... 7919} 7920 7921class NativeMediaPlayerImpl implements webview.NativeMediaPlayerBridge { 7922 constructor(handler: webview.NativeMediaPlayerHandler, mediaInfo: webview.MediaInfo) { 7923 // 1. 创建一个本地播放器的状态监听。 7924 let listener: ActualNativeMediaPlayerListener = new ActualNativeMediaPlayerListener(handler); 7925 // 2. 创建一个本地播放器。 7926 // 3. 监听该本地播放器。 7927 // ... 7928 } 7929 7930 updateRect(x: number, y: number, width: number, height: number) { 7931 // <video> 标签的位置和大小发生了变化。 7932 // 根据该信息变化，作出相应的改变。 7933 } 7934 7935 play() { 7936 // 启动本地播放器播放。 7937 } 7938 7939 pause() { 7940 // 暂停本地播放器播放。 7941 } 7942 7943 seek(targetTime: number) { 7944 // 本地播放器跳转到指定的时间点。 7945 } 7946 7947 release() { 7948 // 销毁本地播放器。 7949 } 7950 7951 setVolume(volume: number) { 7952 // ArkWeb 内核要求调整本地播放器的音量。 7953 // 设置本地播放器的音量。 7954 } 7955 7956 setMuted(muted: boolean) { 7957 // 将本地播放器静音或取消静音。 7958 } 7959 7960 setPlaybackRate(playbackRate: number) { 7961 // 调整本地播放器的播放速度。 7962 } 7963 7964 enterFullscreen() { 7965 // 将本地播放器设置为全屏播放。 7966 } 7967 7968 exitFullscreen() { 7969 // 将本地播放器退出全屏播放。 7970 } 7971 7972 resumePlayer() { 7973 // 重新创建应用内播放器。 7974 // 恢复应用内播放器的状态信息。 7975 } 7976 7977 suspendPlayer(type: webview.SuspendType) { 7978 // 记录应用内播放器的状态信息。 7979 // 销毁应用内播放器。 7980 } 7981} 7982 7983@Entry 7984@Component 7985struct WebComponent { 7986 controller: webview.WebviewController = new webview.WebviewController() 7987 build() { 7988 Column() { 7989 Web({ src: 'www.example.com', controller: this.controller }) 7990 .enableNativeMediaPlayer({enable: true, shouldOverlay: false}) 7991 .onPageBegin((event) => { 7992 this.controller.onCreateNativeMediaPlayer((handler: webview.NativeMediaPlayerHandler, mediaInfo: webview.MediaInfo) => { 7993 if (!shouldHandle(mediaInfo)) { 7994 // 本地播放器不接管该媒体。 7995 // ArkWeb 内核将用自己的播放器来播放该媒体。 7996 return null; 7997 } 7998 let nativePlayer: webview.NativeMediaPlayerBridge = new NativeMediaPlayerImpl(handler, mediaInfo); 7999 return nativePlayer; 8000 }); 8001 }) 8002 } 8003 } 8004} 8005 8006// stub 8007function getVolume() { 8008 return 1; 8009} 8010function getCurrentPlayingTime() { 8011 return 1; 8012} 8013function getCurrentBufferedTime() { 8014 return 1; 8015} 8016function convertToSeconds(input: number) { 8017 return input; 8018} 8019function getLastReadyState() { 8020 return webview.ReadyState.HAVE_NOTHING; 8021} 8022function getCurrentReadyState() { 8023 return webview.ReadyState.HAVE_NOTHING; 8024} 8025function shouldHandle(mediaInfo: webview.MediaInfo) { 8026 return true; 8027} 8028``` 8029 8030### enableWholeWebPageDrawing<sup>12+</sup> 8031 8032static enableWholeWebPageDrawing(): void 8033 8034设置开启网页全量绘制能力。仅在web初始化时设置。 8035 8036**系统能力：** SystemCapability.Web.Webview.Core 8037 8038**示例：** 8039 8040```ts 8041// xxx.ets 8042import { webview } from '@kit.ArkWeb'; 8043import { BusinessError } from '@kit.BasicServicesKit'; 8044 8045@Entry 8046@Component 8047struct WebComponent { 8048 controller: webview.WebviewController = new webview.WebviewController(); 8049 8050 aboutToAppear(): void { 8051 try { 8052 webview.WebviewController.enableWholeWebPageDrawing(); 8053 } catch (error) { 8054 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8055 } 8056 } 8057 8058 build() { 8059 Column() { 8060 Web({ src: 'www.example.com', controller: this.controller }) 8061 } 8062 } 8063} 8064``` 8065 8066### webPageSnapshot<sup>12+</sup> 8067 8068webPageSnapshot(info: SnapshotInfo, callback: AsyncCallback\<SnapshotResult>): void 8069 8070获取网页全量绘制结果。 8071 8072**系统能力：** SystemCapability.Web.Webview.Core 8073 8074**参数：** 8075 8076| 参数名 | 类型 | 必填 | 说明 | 8077| ----------- | ------------- | ---- | ------------------------ | 8078| info | [SnapshotInfo](#snapshotinfo12)| 是 | 全量绘制结果入参。 | 8079| callback | [SnapshotResult](#snapshotresult12)| 是 | 全量绘制回调结果。 | 8080 8081**示例：** 8082 8083```ts 8084// xxx.ets 8085import { webview } from '@kit.ArkWeb'; 8086import { BusinessError } from '@kit.BasicServicesKit'; 8087 8088@Entry 8089@Component 8090struct WebComponent { 8091 controller: webview.WebviewController = new webview.WebviewController(); 8092 8093 build() { 8094 Column() { 8095 Button('webPageSnapshot') 8096 .onClick(() => { 8097 try { 8098 this.controller.webPageSnapshot({ id: "1234", size: { width: 100, height: 100 } }, (error, result) => { 8099 if (error) { 8100 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8101 return; 8102 } 8103 if (result) { 8104 console.info(`return value is:${result}`); 8105 //开发者可以根据需要处理返回结果 8106 } 8107 }); 8108 } catch (error) { 8109 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8110 } 8111 }) 8112 Web({ src: 'www.example.com', controller: this.controller }) 8113 } 8114 } 8115} 8116``` 8117 8118### injectOfflineResources<sup>12+</sup> 8119 8120injectOfflineResources(resourceMaps: Array\<[OfflineResourceMap](#offlineresourcemap12)\>): void 8121 8122将本地离线资源注入到内存缓存中，以提升页面首次启动速度。 8123内存缓存中的资源由内核自动管理，当注入的资源过多导致内存压力过大，内核自动释放未使用的资源，应避免注入大量资源到内存缓存中。 8124正常情况下，资源的有效期由提供的Cache-Control或Expires响应头控制其有效期，默认的有效期为86400秒，即1天。 8125资源的MIMEType通过提供的Content-Type响应头配置，Content-Type需符合标准，否则无法正常使用，MODULE_JS必须提供有效的MIMEType，其他类型可不提供。 8126以此方式注入的资源，仅支持通过HTML中的标签加载。如果业务网页中的script标签使用了crossorigin属性，则必须在接口的responseHeaders参数中设置Cross-Origin响应头的值为anoymous或use-credentials。 8127当调用`webview.WebviewController.SetRenderProcessMode(webview.RenderProcessMode.MULTIPLE)`接口后，应用会启动多渲染进程模式，此接口在此场景下不会生效。 8128 8129**系统能力：** SystemCapability.Web.Webview.Core 8130 8131**参数：** 8132 8133| 参数名 | 类型 | 必填 | 说明 | 8134| ------- | ------ | ---- | :-------------------- | 8135| resourceMaps | Array\<[OfflineResourceMap](#offlineresourcemap12)\> | 是 | 本地离线资源配置对象，单次调用最大支持注入30个资源，单个资源最大支持10Mb。 | 8136 8137**错误码：** 8138 8139以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 8140 8141| 错误码ID | 错误信息 | 8142| -------- | ------------------------------------------------------------ | 8143| 401 | Invalid input parameter.Possible causes: 1. Mandatory parameters are left unspecified.2. Incorrect parameter types.3. Parameter verification failed. | 8144| 17100001 | Init error. The WebviewController must be associated with a Web component. | 8145| 17100002 | Invalid url. | 8146 8147**示例：** 8148 8149接口推荐配合动态组件使用，使用离线的Web组件用于将资源注入到内核的内存缓存中，并在适当的时机加载业务用Web组件使用这些资源。下方是代码示例： 81501. 首先，在EntryAbility中将UIContext存到localStorage中。 8151 8152 ```ts 8153 // EntryAbility.ets 8154 import { UIAbility } from '@kit.AbilityKit'; 8155 import { window } from '@kit.ArkUI'; 8156 8157 const localStorage: LocalStorage = new LocalStorage('uiContext'); 8158 8159 export default class EntryAbility extends UIAbility { 8160 storage: LocalStorage = localStorage; 8161 8162 onWindowStageCreate(windowStage: window.WindowStage) { 8163 windowStage.loadContent('pages/Index', this.storage, (err, data) => { 8164 if (err.code) { 8165 return; 8166 } 8167 8168 this.storage.setOrCreate<UIContext>("uiContext", windowStage.getMainWindowSync().getUIContext()); 8169 }); 8170 } 8171 } 8172 ``` 8173 81742. 编写动态组件所需基础代码。 8175 8176 ```ts 8177 // DynamicComponent.ets 8178 import { NodeController, BuilderNode, FrameNode, UIContext } from '@kit.ArkUI'; 8179 8180 export interface BuilderData { 8181 url: string; 8182 controller: WebviewController; 8183 } 8184 8185 const storage = LocalStorage.getShared(); 8186 8187 export class NodeControllerImpl extends NodeController { 8188 private rootNode: BuilderNode<BuilderData[]> | null = null; 8189 private wrappedBuilder: WrappedBuilder<BuilderData[]> | null = null; 8190 8191 constructor(wrappedBuilder: WrappedBuilder<BuilderData[]>) { 8192 super(); 8193 this.wrappedBuilder = wrappedBuilder; 8194 } 8195 8196 makeNode(): FrameNode | null { 8197 if (this.rootNode != null) { 8198 return this.rootNode.getFrameNode(); 8199 } 8200 return null; 8201 } 8202 8203 initWeb(url: string, controller: WebviewController) { 8204 if(this.rootNode != null) { 8205 return; 8206 } 8207 8208 const uiContext: UIContext = storage.get<UIContext>("uiContext") as UIContext; 8209 if (!uiContext) { 8210 return; 8211 } 8212 this.rootNode = new BuilderNode(uiContext); 8213 this.rootNode.build(this.wrappedBuilder, { url: url, controller: controller }); 8214 } 8215 } 8216 8217 export const createNode = (wrappedBuilder: WrappedBuilder<BuilderData[]>, data: BuilderData) => { 8218 const baseNode = new NodeControllerImpl(wrappedBuilder); 8219 baseNode.initWeb(data.url, data.controller); 8220 return baseNode; 8221 } 8222 ``` 8223 82243. 编写用于注入资源的组件代码，本例中的本地资源内容通过文件读取接口读取rawfile目录下的本地文件。 8225 8226 <!--code_no_check--> 8227 ```ts 8228 // InjectWebview.ets 8229 import { webview } from '@kit.ArkWeb'; 8230 import { resourceConfigs } from "./Resource"; 8231 import { BuilderData } from "./DynamicComponent"; 8232 8233 @Builder 8234 function WebBuilder(data: BuilderData) { 8235 Web({ src: data.url, controller: data.controller }) 8236 .onControllerAttached(async () => { 8237 try { 8238 data.controller.injectOfflineResources(await getData ()); 8239 } catch (err) { 8240 console.error("error: " + err.code + " " + err.message); 8241 } 8242 }) 8243 .fileAccess(true) 8244 } 8245 8246 export const injectWebview = wrapBuilder<BuilderData[]>(WebBuilder); 8247 8248 export async function getData() { 8249 const resourceMapArr: Array<webview.OfflineResourceMap> = []; 8250 8251 // 读取配置，从rawfile目录中读取文件内容 8252 for (let config of resourceConfigs) { 8253 let buf: Uint8Array = new Uint8Array(0); 8254 if (config.localPath) { 8255 buf = await readRawFile(config.localPath); 8256 } 8257 8258 resourceMapArr.push({ 8259 urlList: config.urlList, 8260 resource: buf, 8261 responseHeaders: config.responseHeaders, 8262 type: config.type, 8263 }) 8264 } 8265 8266 return resourceMapArr; 8267 } 8268 8269 export async function readRawFile(url: string) { 8270 try { 8271 return await getContext().resourceManager.getRawFileContent(url); 8272 } catch (err) { 8273 return new Uint8Array(0); 8274 } 8275 } 8276 ``` 8277 82784. 编写业务用组件代码。 8279 8280 <!--code_no_check--> 8281 ```ts 8282 // BusinessWebview.ets 8283 import { BuilderData } from "./DynamicComponent"; 8284 8285 @Builder 8286 function WebBuilder(data: BuilderData) { 8287 // 此处组件可根据业务需要自行扩展 8288 Web({ src: data.url, controller: data.controller }) 8289 .cacheMode(CacheMode.Default) 8290 } 8291 8292 export const businessWebview = wrapBuilder<BuilderData[]>(WebBuilder); 8293 ``` 8294 82955. 编写资源配置信息。 8296 8297 ```ts 8298 // Resource.ets 8299 import { webview } from '@kit.ArkWeb'; 8300 8301 export interface ResourceConfig { 8302 urlList: Array<string>, 8303 type: webview.OfflineResourceType, 8304 responseHeaders: Array<Header>, 8305 localPath: string, // 本地资源存放在rawfile目录下的路径 8306 } 8307 8308 export const resourceConfigs: Array<ResourceConfig> = [ 8309 { 8310 localPath: "example.png", 8311 urlList: [ 8312 "https://www.example.com/", 8313 "https://www.example.com/path1/example.png", 8314 "https://www.example.com/path2/example.png", 8315 ], 8316 type: webview.OfflineResourceType.IMAGE, 8317 responseHeaders: [ 8318 { headerKey: "Cache-Control", headerValue: "max-age=1000" }, 8319 { headerKey: "Content-Type", headerValue: "image/png" }, 8320 ] 8321 }, 8322 { 8323 localPath: "example.js", 8324 urlList: [ // 仅提供一个url，这个url既作为资源的源，也作为资源的网络请求地址 8325 "https://www.example.com/example.js", 8326 ], 8327 type: webview.OfflineResourceType.CLASSIC_JS, 8328 responseHeaders: [ 8329 // 以<script crossorigin="anoymous" />方式使用，提供额外的响应头 8330 { headerKey: "Cross-Origin", headerValue:"anonymous" } 8331 ] 8332 }, 8333 ]; 8334 ``` 8335 83366. 在页面中使用。 8337 <!--code_no_check--> 8338 ```ts 8339 // Index.ets 8340 import { webview } from '@kit.ArkWeb'; 8341 import { NodeController } from '@kit.ArkUI'; 8342 import { createNode } from "./DynamicComponent" 8343 import { injectWebview } from "./InjectWebview" 8344 import { businessWebview } from "./BusinessWebview" 8345 8346 @Entry 8347 @Component 8348 struct Index { 8349 @State injectNode: NodeController | undefined = undefined; 8350 injectController: webview.WebviewController = new webview.WebviewController(); 8351 8352 @State businessNode: NodeController | undefined = undefined; 8353 businessController: webview.WebviewController = new webview.WebviewController(); 8354 8355 aboutToAppear(): void { 8356 // 初始化用于注入本地资源的Web组件, 提供一个空的html页面作为url即可 8357 this.injectNode = createNode(injectWebview, 8358 { url: "https://www.example.com/empty.html", controller: this.injectController}); 8359 } 8360 8361 build() { 8362 Column() { 8363 // 在适当的时机加载业务用Web组件，本例以Button点击触发为例 8364 Button("加载页面") 8365 .onClick(() => { 8366 this.businessNode = createNode(businessWebview, { 8367 url: "https://www.example.com/business.html", 8368 controller: this.businessController 8369 }); 8370 }) 8371 // 用于业务的Web组件 8372 NodeContainer(this.businessNode); 8373 } 8374 } 8375 } 8376 ``` 8377 83787. 加载的HTML网页示例。 8379 8380 ```HTML 8381 <!DOCTYPE html> 8382 <html lang="en"> 8383 <head></head> 8384 <body> 8385 <img src="https://www.example.com/path1/request.png" /> 8386 <img src="https://www.example.com/path2/request.png" /> 8387 <script src="https://www.example.com/example.js" crossorigin="anonymous"></script> 8388 </body> 8389 </html> 8390 ``` 8391 8392### setHostIP<sup>12+</sup> 8393 8394static setHostIP(hostName: string, address: string, aliveTime: number): void 8395 8396设置主机域名解析后的IP地址。 8397 8398**系统能力：** SystemCapability.Web.Webview.Core 8399 8400**参数：** 8401 8402| 参数名 | 类型 | 必填 | 说明 | 8403| --------- | -------- | ---- | ------------------------------------ | 8404| hostName | string | 是 | 要添加DNS记录的主机域名。 | 8405| address | string | 是 | 主机域名解析地址（支持IPv4，IPv6）。 | 8406| aliveTime | number | 是 | 缓存有效时间（秒）。 | 8407 8408**错误码：** 8409 8410以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 8411 8412| 错误码ID | 错误信息 | 8413| -------- | ------------------------ | 8414| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.2. Incorrect parameter types.3. Parameter verification failed. | 8415 8416**示例：** 8417 8418请参考[clearHostIP](#clearhostip12)。 8419 8420### clearHostIP<sup>12+</sup> 8421 8422static clearHostIP(hostName: string): void 8423 8424清除指定主机域名解析后的IP地址。 8425 8426**系统能力：** SystemCapability.Web.Webview.Core 8427 8428**参数：** 8429 8430| 参数名 | 类型 | 必填 | 说明 | 8431| -------- | -------- | ---- | ------------------------- | 8432| hostName | string | 是 | 要清除DNS记录的主机域名。 | 8433 8434**错误码：** 8435 8436以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 8437 8438| 错误码ID | 错误信息 | 8439| -------- | ------------------------ | 8440| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.2. Incorrect parameter types.3. Parameter verification failed. | 8441 8442**示例：** 8443 8444```ts 8445// xxx.ets 8446import { webview } from '@kit.ArkWeb'; 8447import { BusinessError } from '@kit.BasicServicesKit'; 8448 8449@Entry 8450@Component 8451struct WebComponent { 8452 controller: webview.WebviewController = new webview.WebviewController(); 8453 8454 build() { 8455 Column() { 8456 // url加载前设置生效. 8457 Button('setHostIP') 8458 .onClick(() => { 8459 try { 8460 webview.WebviewController.setHostIP('www.example.com', '127.0.0.1', 30); 8461 } catch (error) { 8462 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8463 } 8464 }) 8465 Button('clearHostIP') 8466 .onClick(() => { 8467 try { 8468 webview.WebviewController.clearHostIP('www.example.com'); 8469 } catch (error) { 8470 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8471 } 8472 }) 8473 Web({ src: 'www.example.com', controller: this.controller }) 8474 } 8475 } 8476} 8477``` 8478 8479### getSurfaceId<sup>12+</sup> 8480 8481getSurfaceId(): string 8482 8483获取ArkWeb对应Surface的ID，仅Web组件渲染模式是ASYNC_RENDER时有效。getSurfaceId需要在Web组件初始化之后才能获取到值。 8484 8485**系统能力：** SystemCapability.Web.Webview.Core 8486 8487**返回值：** 8488 8489| 类型 | 说明 | 8490| ------ | ------------------- | 8491| string | ArkWeb持有Surface的ID。 | 8492 8493**示例：** 8494 8495```ts 8496// xxx.ets 8497import { webview } from '@kit.ArkWeb'; 8498import { image } from '@kit.ImageKit'; 8499import { BusinessError } from '@kit.BasicServicesKit'; 8500 8501@Entry 8502@Component 8503struct Example{ 8504 controller: webview.WebviewController = new webview.WebviewController(); 8505 8506 @State imagePixelMap: image.PixelMap | undefined = undefined; 8507 8508 build(){ 8509 Column(){ 8510 Button("截图") 8511 .onClick(()=>{ 8512 try { 8513 let surfaceId = this.controller.getSurfaceId(); 8514 console.log("surfaceId: " + surfaceId); 8515 if(surfaceId.length != 0) { 8516 let region:image.Region = { x: 0, y: 0, size: { height: 800, width: 1000}} 8517 this.imagePixelMap = image.createPixelMapFromSurfaceSync(surfaceId, region) 8518 } 8519 } catch (error) { 8520 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8521 } 8522 }) 8523 Image(this.imagePixelMap) 8524 .height(100) 8525 Web({src: 'www.example.com', controller: this.controller}) 8526 } 8527 } 8528} 8529``` 8530 8531### setUrlTrustList<sup>12+</sup> 8532 8533setUrlTrustList(urlTrustList: string): void 8534 8535设置当前web的url白名单，只有白名单内的url才能允许加载/跳转，否则将拦截并弹出告警页。 8536 8537**系统能力：** SystemCapability.Web.Webview.Core 8538 8539**参数：** 8540 8541| 参数名 | 类型 | 必填 | 说明 | 8542| ------- | ------ | ---- | :-------------------- | 8543| urlTrustList | string | 是 | url白名单列表，使用json格式配置，最大支持10MB。<br/>白名单设置接口为覆盖方式，多次调用接口时，以最后一次设置为准。<br/>当本参数为空字符串时，表示取消白名单，放行所有url的访问。<br/>json格式示例：<br/>{<br> "UrlPermissionList": [<br/> {<br/> "scheme": "https",<br/> "host": "www\.example1.com",<br/> "port": 443,<br/> "path": "pathA/pathB"<br/> },<br/> {<br/> "scheme": "http",<br/> "host": "www\.example2.com",<br/> "port": 80,<br/> "path": "test1/test2/test3"<br/> }<br/> ]<br/>} | 8544 8545**白名单json格式参数** 8546| 字段 | 参数类型 | 必填 | 参数描述 | 8547| -------- | -------- | ---- | ------------------------- | 8548| scheme | string | 否 | 可选参数，不设置即不匹配该项，支持协议：http、https。 | 8549| host | string | 是 | 必选参数，精准匹配，即url的host字段和规则字段完全一致才会放行，可允许同一host多条规则同时生效。 | 8550| port | number | 否 | 可选字段，不设置即不匹配该项。 | 8551| path | string | 否 | 可选字段，不设置即不匹配该项，匹配方式为前缀匹配，以"pathA/pathB/pathC"为例：pathA/pathB/pathC三级目录下全部允许访问，其中pathC必须是完整的目录名或者文件名，不允许部分匹配。| 8552 8553**错误码：** 8554 8555以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 8556 8557| 错误码ID | 错误信息 | 8558| -------- | ------------------------------------------------------------ | 8559| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.2. Parameter string is too long.3. Parameter verification failed. | 8560| 17100001 | Init error. The WebviewController must be associated with a Web component. | 8561 8562**示例：** 8563 ```ts 8564 // xxx.ets 8565 import { webview } from '@kit.ArkWeb'; 8566 import { BusinessError } from '@kit.BasicServicesKit'; 8567 8568 @Entry 8569 @Component 8570 struct WebComponent { 8571 controller: webview.WebviewController = new webview.WebviewController(); 8572 urltrustList: string = "{\"UrlPermissionList\":[{\"scheme\":\"http\", \"host\":\"trust.example.com\", \"port\":80, \"path\":\"test\"}]}" 8573 8574 build() { 8575 Column() { 8576 Button('Setting the trustlist') 8577 .onClick(() => { 8578 try { 8579 // 设置白名单，只允许访问trust网页 8580 this.controller.setUrlTrustList(this.urltrustList); 8581 } catch (error) { 8582 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8583 } 8584 }) 8585 Button('Cancel the trustlist.') 8586 .onClick(() => { 8587 try { 8588 // 白名单传入空字符串表示关闭白名单机制，所有url都可以允许访问 8589 this.controller.setUrlTrustList(""); 8590 } catch (error) { 8591 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8592 } 8593 }) 8594 Button('Access the trust web') 8595 .onClick(() => { 8596 try { 8597 // 白名单生效，可以访问trust网页 8598 this.controller.loadUrl('http://trust.example.com/test'); 8599 } catch (error) { 8600 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8601 } 8602 }) 8603 Button('Access the untrust web') 8604 .onClick(() => { 8605 try { 8606 // 白名单生效，此时不可以访问untrust网页，并弹出错误页 8607 this.controller.loadUrl('http://untrust.example.com/test'); 8608 } catch (error) { 8609 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8610 } 8611 }) 8612 Web({ src: 'http://untrust.example.com/test', controller: this.controller }).onControllerAttached(() => { 8613 try { 8614 // onControllerAttached回调中设置白名单，可以保证在加载url之前生效，此时不可以访问untrust网页，并弹出错误页 8615 this.controller.setUrlTrustList(this.urltrustList); 8616 } catch (error) { 8617 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8618 } 8619 }) 8620 } 8621 } 8622 } 8623 ``` 8624 8625### setPathAllowingUniversalAccess<sup>12+</sup> 8626 8627setPathAllowingUniversalAccess(pathList: Array\<string\>): void 8628 8629设置一个路径列表，当file协议访问该路径列表中的资源时，允许跨域访问本地文件。此外，当设置了路径列表时，file协议仅允许访问路径列表中的资源（[fileAccess](ts-basic-components-web.md#fileaccess)的行为将会被此接口行为覆盖）。路径列表中的路径必须满足以下路径格式之一： 8630 86311.应用文件目录的子目录（应用文件目录通过Ability Kit中的[Context.filesDir](../apis-ability-kit/js-apis-inner-application-context.md#context)获取），例如： 8632 8633* /data/storage/el2/base/files/example 8634* /data/storage/el2/base/haps/entry/files/example 8635 86362.应用资源目录及其子目录（应用资源目录通过Ability Kit中的[Context.resourceDir](../apis-ability-kit/js-apis-inner-application-context.md#context)获取），例如： 8637 8638* /data/storage/el1/bundle/entry/resource/resfile 8639* /data/storage/el1/bundle/entry/resource/resfile/example 8640 8641当路径列表中有其中一个路径不满足以上条件之一，则会抛出异常码401，并且设置路径列表失败。当设置的路径列表为空，则file协议可访问范围以[fileAccess](ts-basic-components-web.md#fileaccess)的行为为准。 8642 8643**系统能力：** SystemCapability.Web.Webview.Core 8644 8645**参数：** 8646 8647| 参数名 | 类型 | 必填 | 说明 | 8648| -------- | -------- | ---- | ------------------------- | 8649| pathList | Array\<string\> | 是 | 路径列表 | 8650 8651**错误码：** 8652 8653以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 8654 8655| 错误码ID | 错误信息 | 8656| -------- | ------------------------ | 8657| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Parameter string is too long. 3.Parameter verification failed. | 8658| 17100001 | Init error. The WebviewController must be associated with a Web component. | 8659 8660**示例：** 8661 8662```ts 8663// xxx.ets 8664import { webview } from '@kit.ArkWeb'; 8665import { BusinessError } from '@kit.BasicServicesKit'; 8666 8667@Entry 8668@Component 8669struct WebComponent { 8670 controller: WebviewController = new webview.WebviewController(); 8671 8672 build() { 8673 Row() { 8674 Web({ src: "", controller: this.controller }) 8675 .onControllerAttached(() => { 8676 try { 8677 // 设置允许可以跨域访问的路径列表 8678 this.controller.setPathAllowingUniversalAccess([ 8679 getContext().resourceDir, 8680 getContext().filesDir + "/example" 8681 ]) 8682 this.controller.loadUrl("file://" + getContext().resourceDir + "/index.html") 8683 } catch (error) { 8684 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8685 } 8686 }) 8687 .javaScriptAccess(true) 8688 .fileAccess(true) 8689 .domStorageAccess(true) 8690 } 8691 } 8692} 8693 8694``` 8695 8696加载的html文件，位于应用资源目录resource/rawfile/index.html。 8697```html 8698<!-- index.html --> 8699<!DOCTYPE html> 8700<html lang="en"> 8701 8702<head> 8703 <meta charset="utf-8"> 8704 <title>Demo</title> 8705 <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, viewport-fit=cover"> 8706 <script> 8707 function getFile() { 8708 var file = "file:///data/storage/el1/bundle/entry/resources/resfile/js/script.js"; 8709 var xmlHttpReq = new XMLHttpRequest(); 8710 xmlHttpReq.onreadystatechange = function(){ 8711 console.log("readyState:" + xmlHttpReq.readyState); 8712 console.log("status:" + xmlHttpReq.status); 8713 if(xmlHttpReq.readyState == 4){ 8714 if (xmlHttpReq.status == 200) { 8715 // 如果ets侧正确设置路径列表，则此处能正常获取资源 8716 const element = document.getElementById('text'); 8717 element.textContent = "load " + file + " success"; 8718 } else { 8719 // 如果ets侧不设置路径列表，则此处会触发CORS跨域检查错误 8720 const element = document.getElementById('text'); 8721 element.textContent = "load " + file + " failed"; 8722 } 8723 } 8724 } 8725 xmlHttpReq.open("GET", file); 8726 xmlHttpReq.send(null); 8727 } 8728 8729 </script> 8730</head> 8731 8732<body> 8733<div class="page"> 8734 <button id="example" onclick="getFile()">stealFile</button> 8735</div> 8736<div id="text"></div> 8737</body> 8738 8739</html> 8740``` 8741 8742html中使用file协议通过XMLHttpRequest跨域访问本地js文件，js文件位于resource/rawfile/js/script.js。 8743<!--code_no_check--> 8744```javascript 8745const body = document.body; 8746const element = document.createElement('div'); 8747element.textContent = 'success'; 8748body.appendChild(element); 8749``` 8750 8751### enableBackForwardCache<sup>12+</sup> 8752 8753static enableBackForwardCache(features: BackForwardCacheSupportedFeatures): void 8754 8755开启Web组件前进后退缓存功能，通过参数指定是否允许使用特定的页面进入前进后退缓存。 8756 8757需要在[initializeWebEngine()](#initializewebengine)初始化内核之前调用。 8758 8759**系统能力：** SystemCapability.Web.Webview.Core 8760 8761**参数：** 8762 8763| 参数名 | 类型 | 必填 | 说明 | 8764| ---------------| ------- | ---- | ------------- | 8765| features | [BackForwardCacheSupportedFeatures](#backforwardcachesupportedfeatures12) | 是 | 允许使用特定的页面进入前进后退缓存中。| 8766 8767**示例：** 8768 8769```ts 8770// EntryAbility.ets 8771import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 8772import { hilog } from '@kit.PerformanceAnalysisKit'; 8773import { window } from '@kit.ArkUI'; 8774import { webview } from '@kit.ArkWeb'; 8775 8776export default class EntryAbility extends UIAbility { 8777 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 8778 let features = new webview.BackForwardCacheSupportedFeatures(); 8779 features.nativeEmbed = true; 8780 features.mediaTakeOver = true; 8781 // 如果一个页面同时使用了同层渲染和视频托管的能力，需要 nativeEmbed 和 8782 // mediaTakeOver 同时设置为 true，该页面才可以进入前进后退缓存中。 8783 webview.WebviewController.enableBackForwardCache(features); 8784 webview.WebviewController.initializeWebEngine(); 8785 AppStorage.setOrCreate("abilityWant", want); 8786 } 8787} 8788``` 8789 8790### setBackForwardCacheOptions<sup>12+</sup> 8791 8792setBackForwardCacheOptions(options: BackForwardCacheOptions): void 8793 8794可以设置Web组件中前进后退缓存的相关选项。 8795 8796**系统能力：** SystemCapability.Web.Webview.Core 8797 8798**参数：** 8799 8800| 参数名 | 类型 | 必填 | 说明 | 8801| ---------------| ------- | ---- | ------------- | 8802| options | [BackForwardCacheOptions](#backforwardcacheoptions12) | 是 | 用来控制Web组件前进后退缓存相关选项。| 8803 8804**错误码：** 8805 8806以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 8807 8808| 错误码ID | 错误信息 | 8809| -------- | ------------------------------------------------------------ | 8810| 17100001 | Init error. The WebviewController must be associated with a Web component. | 8811 8812**示例：** 8813 8814```ts 8815// xxx.ts 8816import { webview } from '@kit.ArkWeb'; 8817 8818@Entry 8819@Component 8820struct Index { 8821 controller: webview.WebviewController = new webview.WebviewController(); 8822 8823 build() { 8824 Column() { 8825 Row() { 8826 Button("Add options").onClick((event: ClickEvent) => { 8827 let options = new webview.BackForwardCacheOptions(); 8828 options.size = 3; 8829 options.timeToLive = 10; 8830 this.controller.setBackForwardCacheOptions(options); 8831 }) 8832 Button("Backward").onClick((event: ClickEvent) => { 8833 this.controller.backward(); 8834 }) 8835 Button("Forward").onClick((event: ClickEvent) => { 8836 this.controller.forward(); 8837 }) 8838 } 8839 Web({ src: "https://www.example.com", controller: this.controller }) 8840 } 8841 .height('100%') 8842 .width('100%') 8843 } 8844} 8845``` 8846 8847### trimMemoryByPressureLevel<sup>14+</sup> 8848 8849trimMemoryByPressureLevel(level: PressureLevel): void 8850 8851根据指定的内存压力等级，主动清理Web组件占用的缓存。 8852 8853**系统能力：** SystemCapability.Web.Webview.Core 8854 8855**参数：** 8856 8857| 参数名 | 类型 | 必填 | 说明 | 8858| ------- | ------ | ---- | :-------------------- | 8859| level | [PressureLevel](#pressurelevel14) | 是 | 需要清理内存的内存等级。| 8860 8861**错误码：** 8862 8863以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 8864 8865| 错误码ID | 错误信息 | 8866| -------- | ------------------------------------------------------------ | 8867| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Parameter string is too long. 3.Parameter verification failed. | 8868 8869**示例：** 8870```ts 8871// xxx.ets 8872import { webview } from '@kit.ArkWeb'; 8873import { BusinessError } from '@kit.BasicServicesKit'; 8874 8875@Entry 8876@Component 8877struct WebComponent { 8878 controller: WebviewController = new webview.WebviewController(); 8879 build() { 8880 Column() { 8881 Row() { 8882 Button('trim_Memory') 8883 .onClick(() => { 8884 try { 8885 // 设置当前内存压力等级为适中，释放少量内存 8886 webview.WebviewController.trimMemoryByPressureLevel( 8887 webview.PressureLevel.MEMORY_PRESSURE_LEVEL_MODERATE); 8888 } catch (error) { 8889 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8890 } 8891 }) 8892 }.height('10%') 8893 Web({ src: 'www.example.com', controller: this.controller }) 8894 } 8895 } 8896} 8897``` 8898 8899### createPdf<sup>14+</sup> 8900 8901createPdf(configuration: PdfConfiguration, callback: AsyncCallback\<PdfData\>): void 8902 8903异步callback方式获取指定网页的数据流。 8904 8905**系统能力：** SystemCapability.Web.Webview.Core 8906 8907**参数：** 8908 8909| 参数名 | 类型 | 必填 | 说明 | 8910| ------------- | --------------------------------------- | ---- | ----------------------- | 8911| configuration | [PdfConfiguration](#pdfconfiguration14) | 是 | 生成PDF所需参数。 | 8912| callback | AsyncCallback<[PdfData](#pdfdata14)> | 是 | 回调返回网页PDF数据流。 | 8913 8914**错误码：** 8915 8916以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 8917 8918| 错误码ID | 错误信息 | 8919| -------- | ------------------------------------------------------------ | 8920| 401 | Invalid input parameter. | 8921| 17100001 | Init error. The WebviewController must be associated with a Web component. | 8922 8923**示例**: 8924 8925```ts 8926import { fileIo as fs } from '@kit.CoreFileKit'; 8927import { webview } from '@kit.ArkWeb'; 8928import { BusinessError } from '@kit.BasicServicesKit'; 8929import { common } from '@kit.AbilityKit'; 8930 8931@Entry 8932@Component 8933struct Index { 8934 controller: webview.WebviewController = new webview.WebviewController(); 8935 pdfConfig: webview.PdfConfiguration = { 8936 width: 8.27, 8937 height: 11.69, 8938 marginTop: 0, 8939 marginBottom: 0, 8940 marginRight: 0, 8941 marginLeft: 0, 8942 shouldPrintBackground: true 8943 } 8944 8945 build() { 8946 Column() { 8947 Button('SavePDF') 8948 .onClick(() => { 8949 this.controller.createPdf( 8950 this.pdfConfig, 8951 (error, result: webview.PdfData) => { 8952 try { 8953 // 获取组件上下文 8954 let context = getContext(this) as common.UIAbilityContext; 8955 // 获取沙箱路径，设置pdf文件名 8956 let filePath = context.filesDir + "/test.pdf"; 8957 let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); 8958 fs.write(file.fd, result.pdfArrayBuffer().buffer).then((writeLen: number) => { 8959 console.info("createPDF write data to file succeed and size is:" + writeLen); 8960 }).catch((err: BusinessError) => { 8961 console.error("createPDF write data to file failed with error message: " + err.message + 8962 ", error code: " + err.code); 8963 }).finally(() => { 8964 fs.closeSync(file); 8965 }); 8966 } catch (resError) { 8967 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 8968 } 8969 }); 8970 }) 8971 Web({ src: "www.example.com", controller: this.controller }) 8972 } 8973 } 8974} 8975``` 8976 8977### createPdf<sup>14+</sup> 8978 8979createPdf(configuration: PdfConfiguration): Promise\<PdfData\> 8980 8981以Promise方式异步获取指定网页的数据流。 8982 8983**系统能力：** SystemCapability.Web.Webview.Core 8984 8985**参数：** 8986 8987| 参数名 | 类型 | 必填 | 说明 | 8988| ------------- | --------------------------------------- | ---- | ----------------- | 8989| configuration | [PdfConfiguration](#pdfconfiguration14) | 是 | 生成PDF所需参数。 | 8990 8991**返回值：** 8992 8993| 类型 | 说明 | 8994| ------------------------------ | ----------------------------- | 8995| Promise<[PdfData](#pdfdata14)> | Promise实例，返回网页数据流。 | 8996 8997**错误码：** 8998 8999以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9000 9001| 错误码ID | 错误信息 | 9002| -------- | ------------------------------------------------------------ | 9003| 401 | Invalid input parameter. | 9004| 17100001 | Init error. The WebviewController must be associated with a Web component. | 9005 9006**示例**: 9007 9008```ts 9009import { fileIo as fs } from '@kit.CoreFileKit'; 9010import { webview } from '@kit.ArkWeb'; 9011import { BusinessError } from '@kit.BasicServicesKit'; 9012import { common } from '@kit.AbilityKit'; 9013 9014@Entry 9015@Component 9016struct Index { 9017 controller: webview.WebviewController = new webview.WebviewController(); 9018 pdfConfig: webview.PdfConfiguration = { 9019 width: 8.27, 9020 height: 11.69, 9021 marginTop: 0, 9022 marginBottom: 0, 9023 marginRight: 0, 9024 marginLeft: 0, 9025 shouldPrintBackground: true 9026 } 9027 9028 build() { 9029 Column() { 9030 Button('SavePDF') 9031 .onClick(() => { 9032 this.controller.createPdf(this.pdfConfig) 9033 .then((result: webview.PdfData) => { 9034 try { 9035 // 获取组件上下文 9036 let context = getContext(this) as common.UIAbilityContext; 9037 // 获取沙箱路径，设置pdf文件名 9038 let filePath = context.filesDir + "/test.pdf"; 9039 let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); 9040 fs.write(file.fd, result.pdfArrayBuffer().buffer).then((writeLen: number) => { 9041 console.info("createPDF write data to file succeed and size is:" + writeLen); 9042 }).catch((err: BusinessError) => { 9043 console.error("createPDF write data to file failed with error message: " + err.message + 9044 ", error code: " + err.code); 9045 }).finally(() => { 9046 fs.closeSync(file); 9047 }); 9048 } catch (resError) { 9049 console.error(`ErrorCode: ${(resError as BusinessError).code}, Message: ${(resError as BusinessError).message}`); 9050 } 9051 }) 9052 }) 9053 Web({ src: "www.example.com", controller: this.controller }) 9054 } 9055 } 9056} 9057``` 9058 9059### getScrollOffset<sup>13+</sup> 9060 9061getScrollOffset(): ScrollOffset 9062 9063获取网页当前的滚动偏移量。 9064 9065**系统能力：** SystemCapability.Web.Webview.Core 9066 9067**返回值** 9068 9069| 类型 | 说明 | 9070| :------------------------------ | ---------------------- | 9071| [ScrollOffset](#scrolloffset13) | 网页当前的滚动偏移量。 | 9072 9073**示例：** 9074 9075```ts 9076import { webview } from '@kit.ArkWeb'; 9077import { componentUtils } from '@kit.ArkUI'; 9078 9079@Entry 9080@Component 9081struct WebComponent { 9082 @State testTitle: string = 'webScroll' 9083 controller: webview.WebviewController = new webview.WebviewController(); 9084 @State controllerX: number =-100; 9085 @State controllerY: number =-100; 9086 @State mode: OverScrollMode = OverScrollMode.ALWAYS; 9087 9088 build() { 9089 Column() { 9090 Row() { 9091 Text(this.testTitle) 9092 .fontSize(30) 9093 .fontWeight(FontWeight.Bold) 9094 .margin(5) 9095 } 9096 Column() { 9097 Text(`controllerX: ${this.controllerX}, controllerY: ${this.controllerY}`) 9098 } 9099 .margin({ top: 10, bottom: 10 }) 9100 Web({ src: $rawfile("scrollByTo.html"), controller: this.controller }) 9101 .key("web_01") 9102 .overScrollMode(this.mode) 9103 .onTouch((event) => { 9104 this.controllerX = this.controller.getScrollOffset().x; 9105 this.controllerY = this.controller.getScrollOffset().y; 9106 let componentInfo = componentUtils.getRectangleById("web_01"); 9107 let webHeight = px2vp(componentInfo.size.height); 9108 let pageHeight = this.controller.getPageHeight(); 9109 if (this.controllerY < 0) { 9110 // case1：网页向下过滚动时，可直接使用ScrollOffset.y 9111 console.log(`get downwards overscroll offsetY = ${this.controllerY}`); 9112 } else if ((this.controllerY != 0) && (this.controllerY > (pageHeight - webHeight))) { 9113 // case2：网页向上过滚动时，需计算出网页下边界与Web组件下边界的偏移量 9114 console.log(`get upwards overscroll offsetY = ${this.controllerY - (pageHeight >= webHeight ? (pageHeight - webHeight) : 0)}`); 9115 } else { 9116 // case3：网页未发生过滚动时，可直接使用ScrollOffset.y 9117 console.log(`get scroll offsetY = ${this.controllerY}`); 9118 } 9119 }) 9120 .height(600) 9121 } 9122 .width('100%') 9123 .height('100%') 9124 } 9125} 9126``` 9127 9128## WebCookieManager 9129 9130通过WebCookie可以控制Web组件中的cookie的各种行为，其中每个应用中的所有Web组件共享一个WebCookieManager实例。 9131 9132### getCookie<sup>(deprecated)</sup> 9133 9134static getCookie(url: string): string 9135 9136获取指定url对应cookie的值。 9137 9138> **说明：** 9139> 9140> 从API version9开始支持，从API version 11开始废弃。建议使用[fetchCookieSync](#fetchcookiesync11)替代 9141 9142**系统能力：** SystemCapability.Web.Webview.Core 9143 9144**参数：** 9145 9146| 参数名 | 类型 | 必填 | 说明 | 9147| ------ | ------ | ---- | :------------------------ | 9148| url | string | 是 | 要获取的cookie所属的url，建议使用完整的url。 | 9149 9150**返回值：** 9151 9152| 类型 | 说明 | 9153| ------ | ------------------------- | 9154| string | 指定url对应的cookie的值。 | 9155 9156**错误码：** 9157 9158以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9159 9160| 错误码ID | 错误信息 | 9161| -------- | ------------------------------------------------------ | 9162| 17100002 | Invalid url. | 9163| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 9164 9165**示例：** 9166 9167```ts 9168// xxx.ets 9169import { webview } from '@kit.ArkWeb'; 9170import { BusinessError } from '@kit.BasicServicesKit'; 9171 9172@Entry 9173@Component 9174struct WebComponent { 9175 controller: webview.WebviewController = new webview.WebviewController(); 9176 9177 build() { 9178 Column() { 9179 Button('getCookie') 9180 .onClick(() => { 9181 try { 9182 let value = webview.WebCookieManager.getCookie('https://www.example.com'); 9183 console.log("value: " + value); 9184 } catch (error) { 9185 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9186 } 9187 }) 9188 Web({ src: 'www.example.com', controller: this.controller }) 9189 } 9190 } 9191} 9192``` 9193 9194### fetchCookieSync<sup>11+</sup> 9195 9196static fetchCookieSync(url: string, incognito?: boolean): string 9197 9198获取指定url对应cookie的值。 9199 9200> **说明：** 9201> 9202> 系统会自动清理过期的cookie，对于同名key的数据，新数据将会覆盖前一个数据。 9203> 9204> 为了获取可正常使用的cookie值，fetchCookieSync需传入完整链接。 9205> 9206> fetchCookieSync用于获取所有的cookie值，每条cookie值之间会通过"; "进行分隔，但无法单独获取某一条特定的cookie值。 9207 9208**系统能力：** SystemCapability.Web.Webview.Core 9209 9210**参数：** 9211 9212| 参数名 | 类型 | 必填 | 说明 | 9213| ------ | ------ | ---- | :------------------------ | 9214| url | string | 是 | 要获取的cookie所属的url，建议使用完整的url。 | 9215| incognito | boolean | 否 | true表示获取隐私模式下webview的内存cookies，false表示正常非隐私模式下的cookies。 | 9216 9217**返回值：** 9218 9219| 类型 | 说明 | 9220| ------ | ------------------------- | 9221| string | 指定url对应的cookie的值。 | 9222 9223**错误码：** 9224 9225以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9226 9227| 错误码ID | 错误信息 | 9228| -------- | ------------------------------------------------------ | 9229| 17100002 | Invalid url. | 9230| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 9231 9232**示例：** 9233 9234```ts 9235// xxx.ets 9236import { webview } from '@kit.ArkWeb'; 9237import { BusinessError } from '@kit.BasicServicesKit'; 9238 9239@Entry 9240@Component 9241struct WebComponent { 9242 controller: webview.WebviewController = new webview.WebviewController(); 9243 9244 build() { 9245 Column() { 9246 Button('fetchCookieSync') 9247 .onClick(() => { 9248 try { 9249 let value = webview.WebCookieManager.fetchCookieSync('https://www.example.com'); 9250 console.log("fetchCookieSync cookie = " + value); 9251 } catch (error) { 9252 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9253 } 9254 }) 9255 Web({ src: 'www.example.com', controller: this.controller }) 9256 } 9257 } 9258} 9259``` 9260 9261### fetchCookie<sup>11+</sup> 9262 9263static fetchCookie(url: string, callback: AsyncCallback\<string>): void 9264 9265异步callback方式获取指定url对应cookie的值。 9266 9267**系统能力：** SystemCapability.Web.Webview.Core 9268 9269**参数：** 9270 9271| 参数名 | 类型 | 必填 | 说明 | 9272| ------ | ------ | ---- | :------------------------ | 9273| url | string | 是 | 要获取的cookie所属的url，建议使用完整的url。 | 9274| callback | AsyncCallback\<string> | 是 | callback回调，用于获取cookie | 9275 9276**错误码：** 9277 9278以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9279 9280| 错误码ID | 错误信息 | 9281| -------- | ------------------------------------------------------ | 9282| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 9283| 17100002 | Invalid url. | 9284 9285**示例：** 9286 9287```ts 9288// xxx.ets 9289import { webview } from '@kit.ArkWeb'; 9290import { BusinessError } from '@kit.BasicServicesKit'; 9291 9292@Entry 9293@Component 9294struct WebComponent { 9295 controller: webview.WebviewController = new webview.WebviewController(); 9296 9297 build() { 9298 Column() { 9299 Button('fetchCookie') 9300 .onClick(() => { 9301 try { 9302 webview.WebCookieManager.fetchCookie('https://www.example.com', (error, cookie) => { 9303 if (error) { 9304 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9305 return; 9306 } 9307 if (cookie) { 9308 console.log('fetchCookie cookie = ' + cookie); 9309 } 9310 }) 9311 } catch (error) { 9312 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9313 } 9314 }) 9315 Web({ src: 'www.example.com', controller: this.controller }) 9316 } 9317 } 9318} 9319``` 9320 9321### fetchCookie<sup>11+</sup> 9322 9323static fetchCookie(url: string): Promise\<string> 9324 9325以Promise方式异步获取指定url对应cookie的值。 9326 9327**系统能力：** SystemCapability.Web.Webview.Core 9328 9329**参数：** 9330 9331| 参数名 | 类型 | 必填 | 说明 | 9332| ------ | ------ | ---- | :------------------------ | 9333| url | string | 是 | 要获取的cookie所属的url，建议使用完整的url。 | 9334 9335**返回值：** 9336 9337| 类型 | 说明 | 9338| ------ | ------------------------- | 9339| Promise\<string> | Promise实例，用于获取指定url对应的cookie值。 | 9340 9341**错误码：** 9342 9343以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9344 9345| 错误码ID | 错误信息 | 9346| -------- | ------------------------------------------------------ | 9347| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 9348| 17100002 | Invalid url. | 9349 9350**示例：** 9351 9352```ts 9353// xxx.ets 9354import { webview } from '@kit.ArkWeb'; 9355import { BusinessError } from '@kit.BasicServicesKit'; 9356 9357@Entry 9358@Component 9359struct WebComponent { 9360 controller: webview.WebviewController = new webview.WebviewController(); 9361 9362 build() { 9363 Column() { 9364 Button('fetchCookie') 9365 .onClick(() => { 9366 try { 9367 webview.WebCookieManager.fetchCookie('https://www.example.com') 9368 .then(cookie => { 9369 console.log("fetchCookie cookie = " + cookie); 9370 }) 9371 .catch((error: BusinessError) => { 9372 console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); 9373 }) 9374 } catch (error) { 9375 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9376 } 9377 }) 9378 Web({ src: 'www.example.com', controller: this.controller }) 9379 } 9380 } 9381} 9382``` 9383 9384### fetchCookie<sup>14+</sup> 9385 9386static fetchCookie(url: string, incognito: boolean): Promise\<string> 9387 9388以Promise方式异步获取指定url对应cookie的值。 9389 9390**系统能力：** SystemCapability.Web.Webview.Core 9391 9392**参数：** 9393 9394| 参数名 | 类型 | 必填 | 说明 | 9395| ------ | ------ | ---- | :------------------------ | 9396| url | string | 是 | 要获取的cookie所属的url，建议使用完整的url。 | 9397| incognito | boolean | 是 | true表示获取隐私模式下webview的内存cookies，false表示正常非隐私模式下的cookies。 | 9398 9399**返回值：** 9400 9401| 类型 | 说明 | 9402| ------ | ------------------------- | 9403| Promise\<string> | Promise实例，用于获取指定url对应的cookie值。 | 9404 9405**错误码：** 9406 9407以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9408 9409| 错误码ID | 错误信息 | 9410| -------- | ------------------------------------------------------ | 9411| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 9412| 17100002 | Invalid url. | 9413 9414**示例：** 9415 9416```ts 9417// xxx.ets 9418import { webview } from '@kit.ArkWeb'; 9419import { BusinessError } from '@kit.BasicServicesKit'; 9420 9421@Entry 9422@Component 9423struct WebComponent { 9424 controller: webview.WebviewController = new webview.WebviewController(); 9425 9426 build() { 9427 Column() { 9428 Button('fetchCookie') 9429 .onClick(() => { 9430 try { 9431 webview.WebCookieManager.fetchCookie('https://www.example.com', false) 9432 .then(cookie => { 9433 console.log("fetchCookie cookie = " + cookie); 9434 }) 9435 .catch((error: BusinessError) => { 9436 console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); 9437 }) 9438 } catch (error) { 9439 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9440 } 9441 }) 9442 Web({ src: 'www.example.com', controller: this.controller }) 9443 } 9444 } 9445} 9446``` 9447 9448### setCookie<sup>(deprecated)</sup> 9449 9450static setCookie(url: string, value: string): void 9451 9452为指定url设置单个cookie的值。 9453 9454> **说明：** 9455> 9456> 从API version9开始支持，从API version 11开始废弃。建议使用[configCookieSync<sup>11+</sup>](#configcookiesync11)替代 9457 9458**系统能力：** SystemCapability.Web.Webview.Core 9459 9460**参数：** 9461 9462| 参数名 | 类型 | 必填 | 说明 | 9463| ------ | ------ | ---- | :------------------------ | 9464| url | string | 是 | 要设置的cookie所属的url，建议使用完整的url。 | 9465| value | string | 是 | 要设置的cookie的值。 | 9466 9467**错误码：** 9468 9469以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9470 9471| 错误码ID | 错误信息 | 9472| -------- | ------------------------------------------------------ | 9473| 17100002 | Invalid url. | 9474| 17100005 | Invalid cookie value. | 9475| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 9476 9477**示例：** 9478 9479```ts 9480// xxx.ets 9481import { webview } from '@kit.ArkWeb'; 9482import { BusinessError } from '@kit.BasicServicesKit'; 9483 9484@Entry 9485@Component 9486struct WebComponent { 9487 controller: webview.WebviewController = new webview.WebviewController(); 9488 9489 build() { 9490 Column() { 9491 Button('setCookie') 9492 .onClick(() => { 9493 try { 9494 webview.WebCookieManager.setCookie('https://www.example.com', 'a=b'); 9495 } catch (error) { 9496 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9497 } 9498 }) 9499 Web({ src: 'www.example.com', controller: this.controller }) 9500 } 9501 } 9502} 9503``` 9504 9505### configCookieSync<sup>11+</sup> 9506 9507static configCookieSync(url: string, value: string, incognito?: boolean): void 9508 9509为指定url设置单个cookie的值。 9510 9511> **说明：** 9512> 9513> configCookie中的url，可以指定域名的方式来使得页面内请求也附带上cookie。 9514> 9515> 同步cookie的时机建议在Web组件加载之前完成。 9516> 9517> 若通过configCookieSync进行两次或多次设置cookie，则每次设置的cookie之间会通过"; "进行分隔。 9518 9519**系统能力：** SystemCapability.Web.Webview.Core 9520 9521**参数：** 9522 9523| 参数名 | 类型 | 必填 | 说明 | 9524| ------ | ------ | ---- | :------------------------ | 9525| url | string | 是 | 要设置的cookie所属的url，建议使用完整的url。 | 9526| value | string | 是 | 要设置的cookie的值。 | 9527| incognito | boolean | 否 | true表示设置隐私模式下对应url的cookies，false表示设置正常非隐私模式下对应url的cookies。 | 9528 9529**错误码：** 9530 9531以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9532 9533| 错误码ID | 错误信息 | 9534| -------- | ------------------------------------------------------ | 9535| 17100002 | Invalid url. | 9536| 17100005 | Invalid cookie value. | 9537| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 9538 9539**示例：** 9540 9541```ts 9542// xxx.ets 9543import { webview } from '@kit.ArkWeb'; 9544import { BusinessError } from '@kit.BasicServicesKit'; 9545 9546@Entry 9547@Component 9548struct WebComponent { 9549 controller: webview.WebviewController = new webview.WebviewController(); 9550 9551 build() { 9552 Column() { 9553 Button('configCookieSync') 9554 .onClick(() => { 9555 try { 9556 // configCookieSync每次仅支持设置单个cookie值。 9557 webview.WebCookieManager.configCookieSync('https://www.example.com', 'a=b'); 9558 } catch (error) { 9559 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9560 } 9561 }) 9562 Web({ src: 'www.example.com', controller: this.controller }) 9563 } 9564 } 9565} 9566``` 9567 9568### configCookieSync<sup>14+</sup> 9569 9570static configCookieSync(url: string, value: string, incognito: boolean, includeHttpOnly: boolean): void 9571 9572为指定url设置cookie的值。 9573 9574**系统能力：** SystemCapability.Web.Webview.Core 9575 9576**参数：** 9577 9578| 参数名 | 类型 | 必填 | 说明 | 9579| ------ | ------ | ---- | :------------------------ | 9580| url | string | 是 | 要设置的cookie所属的url，建议使用完整的url。 | 9581| value | string | 是 | 要设置的cookie的值。 | 9582| incognito | boolean | 是 | true表示设置隐私模式下对应url的cookies，false表示设置正常非隐私模式下对应url的cookies。 | 9583| includeHttpOnly | boolean | 是 | true表示允许覆盖含有http-only的cookies，false表示不允许覆盖含有http-only的cookies。 | 9584 9585**错误码：** 9586 9587以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9588 9589| 错误码ID | 错误信息 | 9590| -------- | ------------------------------------------------------ | 9591| 17100002 | Invalid url. | 9592| 17100005 | Invalid cookie value. | 9593| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 9594 9595**示例：** 9596 9597```ts 9598// xxx.ets 9599import { webview } from '@kit.ArkWeb'; 9600import { BusinessError } from '@kit.BasicServicesKit'; 9601 9602@Entry 9603@Component 9604struct WebComponent { 9605 controller: webview.WebviewController = new webview.WebviewController(); 9606 9607 build() { 9608 Column() { 9609 Button('configCookieSync') 9610 .onClick(() => { 9611 try { 9612 // 仅支持设置单个cookie值。 9613 webview.WebCookieManager.configCookieSync('https://www.example.com', 'a=b', false, false); 9614 } catch (error) { 9615 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9616 } 9617 }) 9618 Web({ src: 'www.example.com', controller: this.controller }) 9619 } 9620 } 9621} 9622``` 9623 9624### configCookie<sup>11+</sup> 9625 9626static configCookie(url: string, value: string, callback: AsyncCallback\<void>): void 9627 9628异步callback方式为指定url设置单个cookie的值。 9629 9630**系统能力：** SystemCapability.Web.Webview.Core 9631 9632**参数：** 9633 9634| 参数名 | 类型 | 必填 | 说明 | 9635| ------ | ------ | ---- | :------------------------ | 9636| url | string | 是 | 要获取的cookie所属的url，建议使用完整的url。 | 9637| value | string | 是 | 要设置的cookie的值。 | 9638| callback | AsyncCallback\<void> | 是 | callback回调，用于获取设置cookie的结果 | 9639 9640**错误码：** 9641 9642以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9643 9644| 错误码ID | 错误信息 | 9645| -------- | ------------------------------------------------------ | 9646| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 9647| 17100002 | Invalid url. | 9648| 17100005 | Invalid cookie value. | 9649 9650**示例：** 9651 9652```ts 9653// xxx.ets 9654import { webview } from '@kit.ArkWeb'; 9655import { BusinessError } from '@kit.BasicServicesKit'; 9656 9657@Entry 9658@Component 9659struct WebComponent { 9660 controller: webview.WebviewController = new webview.WebviewController(); 9661 9662 build() { 9663 Column() { 9664 Button('configCookie') 9665 .onClick(() => { 9666 try { 9667 webview.WebCookieManager.configCookie('https://www.example.com', "a=b", (error) => { 9668 if (error) { 9669 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9670 } 9671 }) 9672 } catch (error) { 9673 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9674 } 9675 }) 9676 Web({ src: 'www.example.com', controller: this.controller }) 9677 } 9678 } 9679} 9680``` 9681 9682### configCookie<sup>11+</sup> 9683 9684static configCookie(url: string, value: string): Promise\<void> 9685 9686以异步Promise方式为指定url设置单个cookie的值。 9687 9688**系统能力：** SystemCapability.Web.Webview.Core 9689 9690**参数：** 9691 9692| 参数名 | 类型 | 必填 | 说明 | 9693| ------ | ------ | ---- | :------------------------ | 9694| url | string | 是 | 要获取的cookie所属的url，建议使用完整的url。 | 9695| value | string | 是 | 要设置的cookie的值。 | 9696 9697**返回值：** 9698 9699| 类型 | 说明 | 9700| ------ | ------------------------- | 9701| Promise\<void> | Promise实例，用于获取指定url设置单个cookie值是否成功。 | 9702 9703**错误码：** 9704 9705以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9706 9707| 错误码ID | 错误信息 | 9708| -------- | ------------------------------------------------------ | 9709| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 9710| 17100002 | Invalid url. | 9711| 17100005 | Invalid cookie value. | 9712 9713**示例：** 9714 9715```ts 9716// xxx.ets 9717import { webview } from '@kit.ArkWeb'; 9718import { BusinessError } from '@kit.BasicServicesKit'; 9719 9720@Entry 9721@Component 9722struct WebComponent { 9723 controller: webview.WebviewController = new webview.WebviewController(); 9724 9725 build() { 9726 Column() { 9727 Button('configCookie') 9728 .onClick(() => { 9729 try { 9730 webview.WebCookieManager.configCookie('https://www.example.com', 'a=b') 9731 .then(() => { 9732 console.log('configCookie success!'); 9733 }) 9734 .catch((error: BusinessError) => { 9735 console.log('error: ' + JSON.stringify(error)); 9736 }) 9737 } catch (error) { 9738 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9739 } 9740 }) 9741 Web({ src: 'www.example.com', controller: this.controller }) 9742 } 9743 } 9744} 9745``` 9746 9747### configCookie<sup>14+</sup> 9748 9749static configCookie(url: string, value: string, incognito: boolean, includeHttpOnly: boolean): Promise\<void> 9750 9751以异步Promise方式为指定url设置单个cookie的值。 9752 9753**系统能力：** SystemCapability.Web.Webview.Core 9754 9755**参数：** 9756 9757| 参数名 | 类型 | 必填 | 说明 | 9758| ------ | ------ | ---- | :------------------------ | 9759| url | string | 是 | 要获取的cookie所属的url，建议使用完整的url。 | 9760| value | string | 是 | 要设置的cookie的值。 | 9761| incognito | boolean | 是 | true表示设置隐私模式下对应url的cookies，false表示设置正常非隐私模式下对应url的cookies。 | 9762| includeHttpOnly | boolean | 是 | true表示允许覆盖含有http-only的cookies，false表示不允许覆盖含有http-only的cookies。 | 9763 9764**返回值：** 9765 9766| 类型 | 说明 | 9767| ------ | ------------------------- | 9768| Promise\<void> | Promise实例，用于获取指定url设置单个cookie值是否成功。 | 9769 9770**错误码：** 9771 9772以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9773 9774| 错误码ID | 错误信息 | 9775| -------- | ------------------------------------------------------ | 9776| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 9777| 17100002 | Invalid url. | 9778| 17100005 | Invalid cookie value. | 9779 9780**示例：** 9781 9782```ts 9783// xxx.ets 9784import { webview } from '@kit.ArkWeb'; 9785import { BusinessError } from '@kit.BasicServicesKit'; 9786 9787@Entry 9788@Component 9789struct WebComponent { 9790 controller: webview.WebviewController = new webview.WebviewController(); 9791 9792 build() { 9793 Column() { 9794 Button('configCookie') 9795 .onClick(() => { 9796 try { 9797 webview.WebCookieManager.configCookie('https://www.example.com', 'a=b', false, false) 9798 .then(() => { 9799 console.log('configCookie success!'); 9800 }) 9801 .catch((error: BusinessError) => { 9802 console.log('error: ' + JSON.stringify(error)); 9803 }) 9804 } catch (error) { 9805 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9806 } 9807 }) 9808 Web({ src: 'www.example.com', controller: this.controller }) 9809 } 9810 } 9811} 9812``` 9813 9814### saveCookieSync<sup>15+</sup> 9815 9816static saveCookieSync(): void 9817 9818将当前存在内存中的cookie同步保存到磁盘中。 9819 9820**系统能力：** SystemCapability.Web.Webview.Core 9821 9822> **说明：** 9823> 9824> saveCookieSync用于强制将需要持久化的cookies写入磁盘。默认情况下，2in1和Tablet设备不会持久化session cookie。 9825 9826**示例：** 9827 9828```ts 9829// xxx.ets 9830import { webview } from '@kit.ArkWeb'; 9831import { BusinessError } from '@kit.BasicServicesKit'; 9832 9833@Entry 9834@Component 9835struct WebComponent { 9836 controller: webview.WebviewController = new webview.WebviewController(); 9837 9838 build() { 9839 Column() { 9840 Button('saveCookieSync') 9841 .onClick(() => { 9842 try { 9843 webview.WebCookieManager.saveCookieSync(); 9844 } catch (error) { 9845 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9846 } 9847 }) 9848 Web({ src: 'www.example.com', controller: this.controller }) 9849 } 9850 } 9851} 9852``` 9853 9854### saveCookieAsync 9855 9856static saveCookieAsync(callback: AsyncCallback\<void>): void 9857 9858将当前存在内存中的cookie异步保存到磁盘中。 9859 9860**系统能力：** SystemCapability.Web.Webview.Core 9861 9862**参数：** 9863 9864| 参数名 | 类型 | 必填 | 说明 | 9865| -------- | ---------------------- | ---- | :------------------------------------------------- | 9866| callback | AsyncCallback\<void> | 是 | callback回调，用于获取cookie是否成功保存。 | 9867 9868**错误码：** 9869 9870以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9871 9872| 错误码ID | 错误信息 | 9873| -------- | ------------------------------------------------------ | 9874| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 9875 9876**示例：** 9877 9878```ts 9879// xxx.ets 9880import { webview } from '@kit.ArkWeb'; 9881import { BusinessError } from '@kit.BasicServicesKit'; 9882 9883@Entry 9884@Component 9885struct WebComponent { 9886 controller: webview.WebviewController = new webview.WebviewController(); 9887 9888 build() { 9889 Column() { 9890 Button('saveCookieAsync') 9891 .onClick(() => { 9892 try { 9893 webview.WebCookieManager.saveCookieAsync((error) => { 9894 if (error) { 9895 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9896 } 9897 }) 9898 } catch (error) { 9899 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9900 } 9901 }) 9902 Web({ src: 'www.example.com', controller: this.controller }) 9903 } 9904 } 9905} 9906``` 9907 9908### saveCookieAsync 9909 9910static saveCookieAsync(): Promise\<void> 9911 9912将当前存在内存中的cookie以Promise方法异步保存到磁盘中。 9913 9914**系统能力：** SystemCapability.Web.Webview.Core 9915 9916**返回值：** 9917 9918| 类型 | 说明 | 9919| ---------------- | ----------------------------------------- | 9920| Promise\<void> | Promise实例，用于获取cookie是否成功保存。 | 9921 9922**错误码：** 9923 9924以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9925 9926| 错误码ID | 错误信息 | 9927| -------- | ------------------------------------------------------ | 9928| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 9929 9930**示例：** 9931 9932```ts 9933// xxx.ets 9934import { webview } from '@kit.ArkWeb'; 9935import { BusinessError } from '@kit.BasicServicesKit'; 9936 9937@Entry 9938@Component 9939struct WebComponent { 9940 controller: webview.WebviewController = new webview.WebviewController(); 9941 9942 build() { 9943 Column() { 9944 Button('saveCookieAsync') 9945 .onClick(() => { 9946 try { 9947 webview.WebCookieManager.saveCookieAsync() 9948 .then(() => { 9949 console.log("saveCookieAsyncCallback success!"); 9950 }) 9951 .catch((error: BusinessError) => { 9952 console.error("error: " + error); 9953 }); 9954 } catch (error) { 9955 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 9956 } 9957 }) 9958 Web({ src: 'www.example.com', controller: this.controller }) 9959 } 9960 } 9961} 9962``` 9963 9964### putAcceptCookieEnabled 9965 9966static putAcceptCookieEnabled(accept: boolean): void 9967 9968设置WebCookieManager实例是否拥有发送和接收cookie的权限。 9969 9970**系统能力：** SystemCapability.Web.Webview.Core 9971 9972**参数：** 9973 9974| 参数名 | 类型 | 必填 | 说明 | 9975| ------ | ------- | ---- | :----------------------------------- | 9976| accept | boolean | 是 | 设置是否拥有发送和接收cookie的权限，默认为true。 | 9977 9978**错误码：** 9979 9980以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 9981 9982| 错误码ID | 错误信息 | 9983| -------- | ------------------------------------------------------ | 9984| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 9985 9986**示例：** 9987 9988```ts 9989// xxx.ets 9990import { webview } from '@kit.ArkWeb'; 9991import { BusinessError } from '@kit.BasicServicesKit'; 9992 9993@Entry 9994@Component 9995struct WebComponent { 9996 controller: webview.WebviewController = new webview.WebviewController(); 9997 9998 build() { 9999 Column() { 10000 Button('putAcceptCookieEnabled') 10001 .onClick(() => { 10002 try { 10003 webview.WebCookieManager.putAcceptCookieEnabled(false); 10004 } catch (error) { 10005 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10006 } 10007 }) 10008 Web({ src: 'www.example.com', controller: this.controller }) 10009 } 10010 } 10011} 10012``` 10013 10014### isCookieAllowed 10015 10016static isCookieAllowed(): boolean 10017 10018获取WebCookieManager实例是否拥有发送和接收cookie的权限。 10019 10020**系统能力：** SystemCapability.Web.Webview.Core 10021 10022**返回值：** 10023 10024| 类型 | 说明 | 10025| ------- | -------------------------------- | 10026| boolean | 是否拥有发送和接收cookie的权限，默认为true。 | 10027 10028**示例：** 10029 10030```ts 10031// xxx.ets 10032import { webview } from '@kit.ArkWeb'; 10033 10034@Entry 10035@Component 10036struct WebComponent { 10037 controller: webview.WebviewController = new webview.WebviewController(); 10038 10039 build() { 10040 Column() { 10041 Button('isCookieAllowed') 10042 .onClick(() => { 10043 let result = webview.WebCookieManager.isCookieAllowed(); 10044 console.log("result: " + result); 10045 }) 10046 Web({ src: 'www.example.com', controller: this.controller }) 10047 } 10048 } 10049} 10050``` 10051 10052### putAcceptThirdPartyCookieEnabled 10053 10054static putAcceptThirdPartyCookieEnabled(accept: boolean): void 10055 10056设置WebCookieManager实例是否拥有发送和接收第三方cookie的权限。 10057 10058**系统能力：** SystemCapability.Web.Webview.Core 10059 10060**参数：** 10061 10062| 参数名 | 类型 | 必填 | 说明 | 10063| ------ | ------- | ---- | :----------------------------------------- | 10064| accept | boolean | 是 | 设置是否拥有发送和接收第三方cookie的权限，默认为false。 | 10065 10066**错误码：** 10067 10068以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10069 10070| 错误码ID | 错误信息 | 10071| -------- | ------------------------------------------------------ | 10072| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 10073 10074**示例：** 10075 10076```ts 10077// xxx.ets 10078import { webview } from '@kit.ArkWeb'; 10079import { BusinessError } from '@kit.BasicServicesKit'; 10080 10081@Entry 10082@Component 10083struct WebComponent { 10084 controller: webview.WebviewController = new webview.WebviewController(); 10085 10086 build() { 10087 Column() { 10088 Button('putAcceptThirdPartyCookieEnabled') 10089 .onClick(() => { 10090 try { 10091 webview.WebCookieManager.putAcceptThirdPartyCookieEnabled(false); 10092 } catch (error) { 10093 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10094 } 10095 }) 10096 Web({ src: 'www.example.com', controller: this.controller }) 10097 } 10098 } 10099} 10100``` 10101 10102### isThirdPartyCookieAllowed 10103 10104static isThirdPartyCookieAllowed(): boolean 10105 10106获取WebCookieManager实例是否拥有发送和接收第三方cookie的权限。 10107 10108**系统能力：** SystemCapability.Web.Webview.Core 10109 10110**返回值：** 10111 10112| 类型 | 说明 | 10113| ------- | -------------------------------------- | 10114| boolean | 是否拥有发送和接收第三方cookie的权限，默认为false。 | 10115 10116**示例：** 10117 10118```ts 10119// xxx.ets 10120import { webview } from '@kit.ArkWeb'; 10121 10122@Entry 10123@Component 10124struct WebComponent { 10125 controller: webview.WebviewController = new webview.WebviewController(); 10126 10127 build() { 10128 Column() { 10129 Button('isThirdPartyCookieAllowed') 10130 .onClick(() => { 10131 let result = webview.WebCookieManager.isThirdPartyCookieAllowed(); 10132 console.log("result: " + result); 10133 }) 10134 Web({ src: 'www.example.com', controller: this.controller }) 10135 } 10136 } 10137} 10138``` 10139 10140### existCookie 10141 10142static existCookie(incognito?: boolean): boolean 10143 10144获取是否存在cookie。 10145 10146**系统能力：** SystemCapability.Web.Webview.Core 10147 10148**参数：** 10149 10150| 参数名 | 类型 | 必填 | 说明 | 10151| ------ | ------- | ---- | :----------------------------------------- | 10152| incognito<sup>11+</sup> | boolean | 否 | true表示隐私模式下查询是否存在cookies，false表示正常非隐私模式下查询是否存在cookies。 | 10153 10154**返回值：** 10155 10156| 类型 | 说明 | 10157| ------- | -------------------------------------- | 10158| boolean | true表示存在cookie，false表示不存在cookie。 | 10159 10160**示例：** 10161 10162```ts 10163// xxx.ets 10164import { webview } from '@kit.ArkWeb'; 10165 10166@Entry 10167@Component 10168struct WebComponent { 10169 controller: webview.WebviewController = new webview.WebviewController(); 10170 10171 build() { 10172 Column() { 10173 Button('existCookie') 10174 .onClick(() => { 10175 let result = webview.WebCookieManager.existCookie(); 10176 console.log("result: " + result); 10177 }) 10178 Web({ src: 'www.example.com', controller: this.controller }) 10179 } 10180 } 10181} 10182``` 10183 10184### deleteEntireCookie<sup>(deprecated)</sup> 10185 10186static deleteEntireCookie(): void 10187 10188清除所有cookie。 10189 10190> **说明：** 10191> 10192> 从API version9开始支持，从API version 11开始废弃。建议使用[clearAllCookiesSync](#clearallcookiessync11)替代 10193 10194**系统能力：** SystemCapability.Web.Webview.Core 10195 10196**示例：** 10197 10198```ts 10199// xxx.ets 10200import { webview } from '@kit.ArkWeb'; 10201 10202@Entry 10203@Component 10204struct WebComponent { 10205 controller: webview.WebviewController = new webview.WebviewController(); 10206 10207 build() { 10208 Column() { 10209 Button('deleteEntireCookie') 10210 .onClick(() => { 10211 webview.WebCookieManager.deleteEntireCookie(); 10212 }) 10213 Web({ src: 'www.example.com', controller: this.controller }) 10214 } 10215 } 10216} 10217``` 10218 10219### clearAllCookiesSync<sup>11+</sup> 10220 10221static clearAllCookiesSync(incognito?: boolean): void 10222 10223清除所有cookie。 10224 10225**系统能力：** SystemCapability.Web.Webview.Core 10226 10227**参数：** 10228 10229| 参数名 | 类型 | 必填 | 说明 | 10230| ------ | ------- | ---- | :----------------------------------------- | 10231| incognito | boolean | 否 | true表示清除隐私模式下webview的所有内存cookies，false表示清除正常非隐私模式下的持久化cookies。 | 10232 10233**示例：** 10234 10235```ts 10236// xxx.ets 10237import { webview } from '@kit.ArkWeb'; 10238 10239@Entry 10240@Component 10241struct WebComponent { 10242 controller: webview.WebviewController = new webview.WebviewController(); 10243 10244 build() { 10245 Column() { 10246 Button('clearAllCookiesSync') 10247 .onClick(() => { 10248 webview.WebCookieManager.clearAllCookiesSync(); 10249 }) 10250 Web({ src: 'www.example.com', controller: this.controller }) 10251 } 10252 } 10253} 10254``` 10255 10256### clearAllCookies<sup>11+</sup> 10257 10258static clearAllCookies(callback: AsyncCallback\<void>): void 10259 10260异步callback方式清除所有cookie。 10261 10262**系统能力：** SystemCapability.Web.Webview.Core 10263 10264**参数：** 10265 10266| 参数名 | 类型 | 必填 | 说明 | 10267| -------- | ---------------------- | ---- | :------------------------------------------------- | 10268| callback | AsyncCallback\<void> | 是 | callback回调，用于获取清除所有cookie是否成功。 | 10269 10270**错误码：** 10271 10272以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10273 10274| 错误码ID | 错误信息 | 10275| -------- | ------------------------------------------------------ | 10276| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 10277 10278**示例：** 10279 10280```ts 10281// xxx.ets 10282import { webview } from '@kit.ArkWeb'; 10283import { BusinessError } from '@kit.BasicServicesKit'; 10284 10285@Entry 10286@Component 10287struct WebComponent { 10288 controller: webview.WebviewController = new webview.WebviewController(); 10289 10290 build() { 10291 Column() { 10292 Button('clearAllCookies') 10293 .onClick(() => { 10294 try { 10295 webview.WebCookieManager.clearAllCookies((error) => { 10296 if (error) { 10297 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10298 } 10299 }) 10300 } catch (error) { 10301 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10302 } 10303 }) 10304 Web({ src: 'www.example.com', controller: this.controller }) 10305 } 10306 } 10307} 10308``` 10309 10310### clearAllCookies<sup>11+</sup> 10311 10312static clearAllCookies(): Promise\<void> 10313 10314异步promise方式清除所有cookie。 10315 10316**系统能力：** SystemCapability.Web.Webview.Core 10317 10318**返回值：** 10319 10320| 类型 | 说明 | 10321| ---------------- | ----------------------------------------- | 10322| Promise\<void> | Promise实例，用于获取清除所有cookie是否成功。 | 10323 10324**错误码：** 10325 10326以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10327 10328| 错误码ID | 错误信息 | 10329| -------- | ------------------------------------------------------ | 10330| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 10331 10332**示例：** 10333 10334```ts 10335// xxx.ets 10336import { webview } from '@kit.ArkWeb'; 10337import { BusinessError } from '@kit.BasicServicesKit'; 10338 10339@Entry 10340@Component 10341struct WebComponent { 10342 controller: webview.WebviewController = new webview.WebviewController(); 10343 10344 build() { 10345 Column() { 10346 Button('clearAllCookies') 10347 .onClick(() => { 10348 try { 10349 webview.WebCookieManager.clearAllCookies() 10350 .then(() => { 10351 console.log("clearAllCookies success!"); 10352 }) 10353 .catch((error: BusinessError) => { 10354 console.error("error: " + error); 10355 }); 10356 } catch (error) { 10357 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10358 } 10359 }) 10360 Web({ src: 'www.example.com', controller: this.controller }) 10361 } 10362 } 10363} 10364``` 10365 10366### deleteSessionCookie<sup>(deprecated)</sup> 10367 10368static deleteSessionCookie(): void 10369 10370清除所有会话cookie。 10371 10372> **说明：** 10373> 10374> 从API version9开始支持，从API version 11开始废弃。建议使用[clearSessionCookiesync](#clearsessioncookiesync11)替代 10375 10376**系统能力：** SystemCapability.Web.Webview.Core 10377 10378**示例：** 10379 10380```ts 10381// xxx.ets 10382import { webview } from '@kit.ArkWeb'; 10383 10384@Entry 10385@Component 10386struct WebComponent { 10387 controller: webview.WebviewController = new webview.WebviewController(); 10388 10389 build() { 10390 Column() { 10391 Button('deleteSessionCookie') 10392 .onClick(() => { 10393 webview.WebCookieManager.deleteSessionCookie(); 10394 }) 10395 Web({ src: 'www.example.com', controller: this.controller }) 10396 } 10397 } 10398} 10399``` 10400 10401### clearSessionCookieSync<sup>11+</sup> 10402 10403static clearSessionCookieSync(): void 10404 10405清除所有会话cookie。 10406 10407**系统能力：** SystemCapability.Web.Webview.Core 10408 10409**示例：** 10410 10411```ts 10412// xxx.ets 10413import { webview } from '@kit.ArkWeb'; 10414 10415@Entry 10416@Component 10417struct WebComponent { 10418 controller: webview.WebviewController = new webview.WebviewController(); 10419 10420 build() { 10421 Column() { 10422 Button('clearSessionCookieSync') 10423 .onClick(() => { 10424 webview.WebCookieManager.clearSessionCookieSync(); 10425 }) 10426 Web({ src: 'www.example.com', controller: this.controller }) 10427 } 10428 } 10429} 10430``` 10431 10432### clearSessionCookie<sup>11+</sup> 10433 10434static clearSessionCookie(callback: AsyncCallback\<void>): void 10435 10436异步callback方式清除所有会话cookie。 10437 10438**系统能力：** SystemCapability.Web.Webview.Core 10439 10440**参数：** 10441 10442| 参数名 | 类型 | 必填 | 说明 | 10443| -------- | ---------------------- | ---- | :------------------------------------------------- | 10444| callback | AsyncCallback\<void> | 是 | callback回调，用于获取清除所有会话cookie是否成功。 | 10445 10446**错误码：** 10447 10448以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10449 10450| 错误码ID | 错误信息 | 10451| -------- | ------------------------------------------------------ | 10452| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 10453 10454**示例：** 10455 10456```ts 10457// xxx.ets 10458import { webview } from '@kit.ArkWeb'; 10459import { BusinessError } from '@kit.BasicServicesKit'; 10460 10461@Entry 10462@Component 10463struct WebComponent { 10464 controller: webview.WebviewController = new webview.WebviewController(); 10465 10466 build() { 10467 Column() { 10468 Button('clearSessionCookie') 10469 .onClick(() => { 10470 try { 10471 webview.WebCookieManager.clearSessionCookie((error) => { 10472 if (error) { 10473 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10474 } 10475 }) 10476 } catch (error) { 10477 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10478 } 10479 }) 10480 Web({ src: 'www.example.com', controller: this.controller }) 10481 } 10482 } 10483} 10484``` 10485 10486### clearSessionCookie<sup>11+</sup> 10487 10488static clearSessionCookie(): Promise\<void> 10489 10490异步promise方式清除所有会话cookie。 10491 10492**系统能力：** SystemCapability.Web.Webview.Core 10493 10494**返回值：** 10495 10496| 类型 | 说明 | 10497| ---------------- | ----------------------------------------- | 10498| Promise\<void> | Promise实例，用于获取清除所有会话cookie是否成功。 | 10499 10500**错误码：** 10501 10502以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10503 10504| 错误码ID | 错误信息 | 10505| -------- | ------------------------------------------------------ | 10506| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 10507 10508**示例：** 10509 10510```ts 10511// xxx.ets 10512import { webview } from '@kit.ArkWeb'; 10513import { BusinessError } from '@kit.BasicServicesKit'; 10514 10515@Entry 10516@Component 10517struct WebComponent { 10518 controller: webview.WebviewController = new webview.WebviewController(); 10519 10520 build() { 10521 Column() { 10522 Button('clearSessionCookie') 10523 .onClick(() => { 10524 try { 10525 webview.WebCookieManager.clearSessionCookie() 10526 .then(() => { 10527 console.log("clearSessionCookie success!"); 10528 }) 10529 .catch((error: BusinessError) => { 10530 console.error("error: " + error); 10531 }); 10532 } catch (error) { 10533 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10534 } 10535 }) 10536 Web({ src: 'www.example.com', controller: this.controller }) 10537 } 10538 } 10539} 10540``` 10541 10542## WebStorage 10543 10544通过WebStorage可管理Web SQL数据库接口和HTML5 Web存储接口，每个应用中的所有Web组件共享一个WebStorage。 10545 10546> **说明：** 10547> 10548> 目前调用WebStorage下的方法，都需要先加载Web组件。 10549 10550### deleteOrigin 10551 10552static deleteOrigin(origin: string): void 10553 10554清除指定源所使用的存储。 10555 10556**系统能力：** SystemCapability.Web.Webview.Core 10557 10558**参数：** 10559 10560| 参数名 | 类型 | 必填 | 说明 | 10561| ------ | ------ | ---- | ------------------------ | 10562| origin | string | 是 | 指定源的字符串索引，来自于[getOrigins](#getorigins)。 | 10563 10564**错误码：** 10565 10566以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10567 10568| 错误码ID | 错误信息 | 10569| -------- | ------------------------------------------------------ | 10570| 17100011 | Invalid origin. | 10571| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 10572 10573**示例：** 10574 10575```ts 10576// xxx.ets 10577import { webview } from '@kit.ArkWeb'; 10578import { BusinessError } from '@kit.BasicServicesKit'; 10579 10580@Entry 10581@Component 10582struct WebComponent { 10583 controller: webview.WebviewController = new webview.WebviewController(); 10584 origin: string = "resource://rawfile/"; 10585 10586 build() { 10587 Column() { 10588 Button('deleteOrigin') 10589 .onClick(() => { 10590 try { 10591 webview.WebStorage.deleteOrigin(this.origin); 10592 } catch (error) { 10593 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10594 } 10595 10596 }) 10597 Web({ src: $rawfile('index.html'), controller: this.controller }) 10598 .databaseAccess(true) 10599 } 10600 } 10601} 10602``` 10603 10604加载的html文件。 10605 ```html 10606 <!-- index.html --> 10607 <!DOCTYPE html> 10608 <html> 10609 <head> 10610 <meta charset="UTF-8"> 10611 <title>test</title> 10612 <script type="text/javascript"> 10613 10614 var db = openDatabase('mydb','1.0','Test DB',2 * 1024 * 1024); 10615 var msg; 10616 10617 db.transaction(function(tx){ 10618 tx.executeSql('INSERT INTO LOGS (id,log) VALUES(1,"test1")'); 10619 tx.executeSql('INSERT INTO LOGS (id,log) VALUES(2,"test2")'); 10620 msg = '<p>数据表已创建,且插入了两条数据。</p>'; 10621 10622 document.querySelector('#status').innerHTML = msg; 10623 }); 10624 10625 db.transaction(function(tx){ 10626 tx.executeSql('SELECT * FROM LOGS', [], function (tx, results) { 10627 var len = results.rows.length,i; 10628 msg = "<p>查询记录条数：" + len + "</p>"; 10629 10630 document.querySelector('#status').innerHTML += msg; 10631 10632 for(i = 0; i < len; i++){ 10633 msg = "<p><b>" + results.rows.item(i).log + "</b></p>"; 10634 10635 document.querySelector('#status').innerHTML += msg; 10636 } 10637 },null); 10638 }); 10639 10640 </script> 10641 </head> 10642 <body> 10643 <div id="status" name="status">状态信息</div> 10644 </body> 10645 </html> 10646 ``` 10647 10648### getOrigins 10649 10650static getOrigins(callback: AsyncCallback\<Array\<WebStorageOrigin>>): void 10651 10652以回调方式异步获取当前使用Web SQL数据库的所有源的信息。 10653 10654**系统能力：** SystemCapability.Web.Webview.Core 10655 10656**参数：** 10657 10658| 参数名 | 类型 | 必填 | 说明 | 10659| -------- | -------------------------------------- | ---- | ------------------------------------------------------ | 10660| callback | AsyncCallback\<Array\<[WebStorageOrigin](#webstorageorigin)>> | 是 | 以数组方式返回源的信息，信息内容参考[WebStorageOrigin](#webstorageorigin)。 | 10661 10662**错误码：** 10663 10664以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10665 10666| 错误码ID | 错误信息 | 10667| -------- | ------------------------------------------------------ | 10668| 17100012 | Invalid web storage origin. | 10669| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 10670 10671**示例：** 10672 10673```ts 10674// xxx.ets 10675import { webview } from '@kit.ArkWeb'; 10676import { BusinessError } from '@kit.BasicServicesKit'; 10677 10678@Entry 10679@Component 10680struct WebComponent { 10681 controller: webview.WebviewController = new webview.WebviewController(); 10682 10683 build() { 10684 Column() { 10685 Button('getOrigins') 10686 .onClick(() => { 10687 try { 10688 webview.WebStorage.getOrigins((error, origins) => { 10689 if (error) { 10690 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10691 return; 10692 } 10693 for (let i = 0; i < origins.length; i++) { 10694 console.log('origin: ' + origins[i].origin); 10695 console.log('usage: ' + origins[i].usage); 10696 console.log('quota: ' + origins[i].quota); 10697 } 10698 }) 10699 } catch (error) { 10700 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10701 } 10702 10703 }) 10704 Web({ src: $rawfile('index.html'), controller: this.controller }) 10705 .databaseAccess(true) 10706 } 10707 } 10708} 10709``` 10710 10711加载的html文件，请参考[deleteOrigin](#deleteorigin)接口下的html文件。 10712 10713### getOrigins 10714 10715static getOrigins(): Promise\<Array\<WebStorageOrigin>> 10716 10717以Promise方式异步获取当前使用Web SQL数据库的所有源的信息。 10718 10719**系统能力：** SystemCapability.Web.Webview.Core 10720 10721**返回值：** 10722 10723| 类型 | 说明 | 10724| -------------------------------- | ------------------------------------------------------------ | 10725| Promise\<Array\<[WebStorageOrigin](#webstorageorigin)>> | Promise实例，用于获取当前所有源的信息，信息内容参考[WebStorageOrigin](#webstorageorigin)。 | 10726 10727**错误码：** 10728 10729以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10730 10731| 错误码ID | 错误信息 | 10732| -------- | ------------------------------------------------------ | 10733| 17100012 | Invalid web storage origin. | 10734| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 10735 10736**示例：** 10737 10738```ts 10739// xxx.ets 10740import { webview } from '@kit.ArkWeb'; 10741import { BusinessError } from '@kit.BasicServicesKit'; 10742 10743@Entry 10744@Component 10745struct WebComponent { 10746 controller: webview.WebviewController = new webview.WebviewController(); 10747 10748 build() { 10749 Column() { 10750 Button('getOrigins') 10751 .onClick(() => { 10752 try { 10753 webview.WebStorage.getOrigins() 10754 .then(origins => { 10755 for (let i = 0; i < origins.length; i++) { 10756 console.log('origin: ' + origins[i].origin); 10757 console.log('usage: ' + origins[i].usage); 10758 console.log('quota: ' + origins[i].quota); 10759 } 10760 }) 10761 .catch((e: BusinessError) => { 10762 console.log('error: ' + JSON.stringify(e)); 10763 }) 10764 } catch (error) { 10765 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10766 } 10767 10768 }) 10769 Web({ src: $rawfile('index.html'), controller: this.controller }) 10770 .databaseAccess(true) 10771 } 10772 } 10773} 10774``` 10775 10776加载的html文件，请参考[deleteOrigin](#deleteorigin)接口下的html文件。 10777 10778### getOriginQuota 10779 10780static getOriginQuota(origin: string, callback: AsyncCallback\<number>): void 10781 10782使用callback回调异步获取指定源的Web SQL数据库的存储配额，配额以字节为单位。 10783 10784**系统能力：** SystemCapability.Web.Webview.Core 10785 10786**参数：** 10787 10788| 参数名 | 类型 | 必填 | 说明 | 10789| -------- | --------------------- | ---- | ------------------ | 10790| origin | string | 是 | 指定源的字符串索引 | 10791| callback | AsyncCallback\<number> | 是 | 指定源的存储配额 | 10792 10793**错误码：** 10794 10795以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10796 10797| 错误码ID | 错误信息 | 10798| -------- | ------------------------------------------------------ | 10799| 17100011 | Invalid origin. | 10800| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 10801 10802**示例：** 10803 10804```ts 10805// xxx.ets 10806import { webview } from '@kit.ArkWeb'; 10807import { BusinessError } from '@kit.BasicServicesKit'; 10808 10809@Entry 10810@Component 10811struct WebComponent { 10812 controller: webview.WebviewController = new webview.WebviewController(); 10813 origin: string = "resource://rawfile/"; 10814 10815 build() { 10816 Column() { 10817 Button('getOriginQuota') 10818 .onClick(() => { 10819 try { 10820 webview.WebStorage.getOriginQuota(this.origin, (error, quota) => { 10821 if (error) { 10822 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10823 return; 10824 } 10825 console.log('quota: ' + quota); 10826 }) 10827 } catch (error) { 10828 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10829 } 10830 10831 }) 10832 Web({ src: $rawfile('index.html'), controller: this.controller }) 10833 .databaseAccess(true) 10834 } 10835 } 10836} 10837``` 10838 10839加载的html文件，请参考[deleteOrigin](#deleteorigin)接口下的html文件。 10840 10841### getOriginQuota 10842 10843static getOriginQuota(origin: string): Promise\<number> 10844 10845以Promise方式异步获取指定源的Web SQL数据库的存储配额，配额以字节为单位。 10846 10847**系统能力：** SystemCapability.Web.Webview.Core 10848 10849**参数：** 10850 10851| 参数名 | 类型 | 必填 | 说明 | 10852| ------ | ------ | ---- | ------------------ | 10853| origin | string | 是 | 指定源的字符串索引 | 10854 10855**返回值：** 10856 10857| 类型 | 说明 | 10858| --------------- | --------------------------------------- | 10859| Promise\<number> | Promise实例，用于获取指定源的存储配额。 | 10860 10861**错误码：** 10862 10863以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10864 10865| 错误码ID | 错误信息 | 10866| -------- | ------------------------------------------------------ | 10867| 17100011 | Invalid origin. | 10868| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 10869 10870**示例：** 10871 10872```ts 10873// xxx.ets 10874import { webview } from '@kit.ArkWeb'; 10875import { BusinessError } from '@kit.BasicServicesKit'; 10876 10877@Entry 10878@Component 10879struct WebComponent { 10880 controller: webview.WebviewController = new webview.WebviewController(); 10881 origin: string = "resource://rawfile/"; 10882 10883 build() { 10884 Column() { 10885 Button('getOriginQuota') 10886 .onClick(() => { 10887 try { 10888 webview.WebStorage.getOriginQuota(this.origin) 10889 .then(quota => { 10890 console.log('quota: ' + quota); 10891 }) 10892 .catch((e: BusinessError) => { 10893 console.log('error: ' + JSON.stringify(e)); 10894 }) 10895 } catch (error) { 10896 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10897 } 10898 10899 }) 10900 Web({ src: $rawfile('index.html'), controller: this.controller }) 10901 .databaseAccess(true) 10902 } 10903 } 10904} 10905``` 10906 10907加载的html文件，请参考[deleteOrigin](#deleteorigin)接口下的html文件。 10908 10909### getOriginUsage 10910 10911static getOriginUsage(origin: string, callback: AsyncCallback\<number>): void 10912 10913以回调方式异步获取指定源的Web SQL数据库的存储量，存储量以字节为单位。 10914 10915**系统能力：** SystemCapability.Web.Webview.Core 10916 10917**参数：** 10918 10919| 参数名 | 类型 | 必填 | 说明 | 10920| -------- | --------------------- | ---- | ------------------ | 10921| origin | string | 是 | 指定源的字符串索引 | 10922| callback | AsyncCallback\<number> | 是 | 指定源的存储量。 | 10923 10924**错误码：** 10925 10926以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10927 10928| 错误码ID | 错误信息 | 10929| -------- | ------------------------------------------------------ | 10930| 17100011 | Invalid origin. | 10931| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 10932 10933**示例：** 10934 10935```ts 10936// xxx.ets 10937import { webview } from '@kit.ArkWeb'; 10938import { BusinessError } from '@kit.BasicServicesKit'; 10939 10940@Entry 10941@Component 10942struct WebComponent { 10943 controller: webview.WebviewController = new webview.WebviewController(); 10944 origin: string = "resource://rawfile/"; 10945 10946 build() { 10947 Column() { 10948 Button('getOriginUsage') 10949 .onClick(() => { 10950 try { 10951 webview.WebStorage.getOriginUsage(this.origin, (error, usage) => { 10952 if (error) { 10953 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10954 return; 10955 } 10956 console.log('usage: ' + usage); 10957 }) 10958 } catch (error) { 10959 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 10960 } 10961 10962 }) 10963 Web({ src: $rawfile('index.html'), controller: this.controller }) 10964 .databaseAccess(true) 10965 } 10966 } 10967} 10968``` 10969 10970加载的html文件，请参考[deleteOrigin](#deleteorigin)接口下的html文件。 10971 10972### getOriginUsage 10973 10974static getOriginUsage(origin: string): Promise\<number> 10975 10976以Promise方式异步获取指定源的Web SQL数据库的存储量，存储量以字节为单位。 10977 10978**系统能力：** SystemCapability.Web.Webview.Core 10979 10980**参数：** 10981 10982| 参数名 | 类型 | 必填 | 说明 | 10983| ------ | ------ | ---- | ------------------ | 10984| origin | string | 是 | 指定源的字符串索引 | 10985 10986**返回值：** 10987 10988| 类型 | 说明 | 10989| --------------- | ------------------------------------- | 10990| Promise\<number> | Promise实例，用于获取指定源的存储量。 | 10991 10992**错误码：** 10993 10994以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 10995 10996| 错误码ID | 错误信息 | 10997| -------- | ----------------------------------------------------- | 10998| 17100011 | Invalid origin. | 10999| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 11000 11001**示例：** 11002 11003```ts 11004// xxx.ets 11005import { webview } from '@kit.ArkWeb'; 11006import { BusinessError } from '@kit.BasicServicesKit'; 11007 11008@Entry 11009@Component 11010struct WebComponent { 11011 controller: webview.WebviewController = new webview.WebviewController(); 11012 origin: string = "resource://rawfile/"; 11013 11014 build() { 11015 Column() { 11016 Button('getOriginUsage') 11017 .onClick(() => { 11018 try { 11019 webview.WebStorage.getOriginUsage(this.origin) 11020 .then(usage => { 11021 console.log('usage: ' + usage); 11022 }).catch((e: BusinessError) => { 11023 console.error('error: ' + JSON.stringify(e)); 11024 }) 11025 } catch (error) { 11026 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11027 } 11028 }) 11029 Web({ src: $rawfile('index.html'), controller: this.controller }) 11030 .databaseAccess(true) 11031 } 11032 } 11033} 11034``` 11035 11036加载的html文件，请参考[deleteOrigin](#deleteorigin)接口下的html文件。 11037 11038### deleteAllData 11039 11040static deleteAllData(incognito?: boolean): void 11041 11042清除Web SQL数据库当前使用的所有存储。 11043 11044**系统能力：** SystemCapability.Web.Webview.Core 11045 11046**参数：** 11047 11048| 参数名 | 类型 | 必填 | 说明 | 11049| ------ | ------ | ---- | ------------------ | 11050| incognito<sup>11+</sup> | boolean | 否 | true表示删除所有隐私模式下内存中的web数据，false表示删除正常非隐私模式下Web的SQL数据库当前使用的所有存储。 | 11051 11052**示例：** 11053 11054```ts 11055// xxx.ets 11056import { webview } from '@kit.ArkWeb'; 11057import { BusinessError } from '@kit.BasicServicesKit'; 11058 11059@Entry 11060@Component 11061struct WebComponent { 11062 controller: webview.WebviewController = new webview.WebviewController(); 11063 11064 build() { 11065 Column() { 11066 Button('deleteAllData') 11067 .onClick(() => { 11068 try { 11069 webview.WebStorage.deleteAllData(); 11070 } catch (error) { 11071 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11072 } 11073 }) 11074 Web({ src: $rawfile('index.html'), controller: this.controller }) 11075 .databaseAccess(true) 11076 } 11077 } 11078} 11079``` 11080 11081加载的html文件，请参考[deleteOrigin](#deleteorigin)接口下加载的html文件。 11082 11083## WebDataBase 11084 11085Web组件数据库管理对象。 11086 11087> **说明：** 11088> 11089> 目前调用WebDataBase下的方法，都需要先加载Web组件。 11090 11091### getHttpAuthCredentials 11092 11093static getHttpAuthCredentials(host: string, realm: string): Array\<string> 11094 11095检索给定主机和域的HTTP身份验证凭据，该方法为同步方法。 11096 11097**系统能力：** SystemCapability.Web.Webview.Core 11098 11099**参数：** 11100 11101| 参数名 | 类型 | 必填 | 说明 | 11102| ------ | ------ | ---- | ---------------------------- | 11103| host | string | 是 | HTTP身份验证凭据应用的主机。 | 11104| realm | string | 是 | HTTP身份验证凭据应用的域。 | 11105 11106**返回值：** 11107 11108| 类型 | 说明 | 11109| ----- | -------------------------------------------- | 11110| Array\<string> | 包含用户名和密码的组数，检索失败返回空数组。 | 11111 11112**错误码：** 11113 11114以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11115 11116| 错误码ID | 错误信息 | 11117| -------- | ------------------------------------------------------ | 11118| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 11119 11120**示例：** 11121 11122```ts 11123// xxx.ets 11124import { webview } from '@kit.ArkWeb'; 11125import { BusinessError } from '@kit.BasicServicesKit'; 11126 11127@Entry 11128@Component 11129struct WebComponent { 11130 controller: webview.WebviewController = new webview.WebviewController(); 11131 host: string = "www.spincast.org"; 11132 realm: string = "protected example"; 11133 username_password: string[] = []; 11134 11135 build() { 11136 Column() { 11137 Button('getHttpAuthCredentials') 11138 .onClick(() => { 11139 try { 11140 this.username_password = webview.WebDataBase.getHttpAuthCredentials(this.host, this.realm); 11141 console.log('num: ' + this.username_password.length); 11142 } catch (error) { 11143 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11144 } 11145 }) 11146 Web({ src: 'www.example.com', controller: this.controller }) 11147 } 11148 } 11149} 11150``` 11151 11152### saveHttpAuthCredentials 11153 11154static saveHttpAuthCredentials(host: string, realm: string, username: string, password: string): void 11155 11156保存给定主机和域的HTTP身份验证凭据，该方法为同步方法。 11157 11158**系统能力：** SystemCapability.Web.Webview.Core 11159 11160**参数：** 11161 11162| 参数名 | 类型 | 必填 | 说明 | 11163| -------- | ------ | ---- | ---------------------------- | 11164| host | string | 是 | HTTP身份验证凭据应用的主机。 | 11165| realm | string | 是 | HTTP身份验证凭据应用的域。 | 11166| username | string | 是 | 用户名。 | 11167| password | string | 是 | 密码。 | 11168 11169**错误码：** 11170 11171以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11172 11173| 错误码ID | 错误信息 | 11174| -------- | ------------------------------------------------------ | 11175| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 11176 11177**示例：** 11178 11179```ts 11180// xxx.ets 11181import { webview } from '@kit.ArkWeb'; 11182import { BusinessError } from '@kit.BasicServicesKit'; 11183 11184@Entry 11185@Component 11186struct WebComponent { 11187 controller: webview.WebviewController = new webview.WebviewController(); 11188 host: string = "www.spincast.org"; 11189 realm: string = "protected example"; 11190 11191 build() { 11192 Column() { 11193 Button('saveHttpAuthCredentials') 11194 .onClick(() => { 11195 try { 11196 webview.WebDataBase.saveHttpAuthCredentials(this.host, this.realm, "Stromgol", "Laroche"); 11197 } catch (error) { 11198 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11199 } 11200 }) 11201 Web({ src: 'www.example.com', controller: this.controller }) 11202 } 11203 } 11204} 11205``` 11206 11207### existHttpAuthCredentials 11208 11209static existHttpAuthCredentials(): boolean 11210 11211判断是否存在任何已保存的HTTP身份验证凭据，该方法为同步方法。存在返回true，不存在返回false。 11212 11213**系统能力：** SystemCapability.Web.Webview.Core 11214 11215**返回值：** 11216 11217| 类型 | 说明 | 11218| ------- | ------------------------------------------------------------ | 11219| boolean | 是否存在任何已保存的HTTP身份验证凭据。存在返回true，不存在返回false | 11220 11221**示例：** 11222 11223```ts 11224// xxx.ets 11225import { webview } from '@kit.ArkWeb'; 11226import { BusinessError } from '@kit.BasicServicesKit'; 11227 11228@Entry 11229@Component 11230struct WebComponent { 11231 controller: webview.WebviewController = new webview.WebviewController(); 11232 11233 build() { 11234 Column() { 11235 Button('existHttpAuthCredentials') 11236 .onClick(() => { 11237 try { 11238 let result = webview.WebDataBase.existHttpAuthCredentials(); 11239 } catch (error) { 11240 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11241 } 11242 }) 11243 Web({ src: 'www.example.com', controller: this.controller }) 11244 } 11245 } 11246} 11247``` 11248 11249### deleteHttpAuthCredentials 11250 11251static deleteHttpAuthCredentials(): void 11252 11253清除所有已保存的HTTP身份验证凭据，该方法为同步方法。 11254 11255**系统能力：** SystemCapability.Web.Webview.Core 11256 11257**示例：** 11258 11259```ts 11260// xxx.ets 11261import { webview } from '@kit.ArkWeb'; 11262import { BusinessError } from '@kit.BasicServicesKit'; 11263 11264@Entry 11265@Component 11266struct WebComponent { 11267 controller: webview.WebviewController = new webview.WebviewController(); 11268 11269 build() { 11270 Column() { 11271 Button('deleteHttpAuthCredentials') 11272 .onClick(() => { 11273 try { 11274 webview.WebDataBase.deleteHttpAuthCredentials(); 11275 } catch (error) { 11276 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11277 } 11278 }) 11279 Web({ src: 'www.example.com', controller: this.controller }) 11280 } 11281 } 11282} 11283``` 11284 11285## GeolocationPermissions 11286 11287Web组件地理位置权限管理对象。 11288 11289> **说明：** 11290> 11291> 目前调用GeolocationPermissions下的方法，都需要先加载Web组件。 11292 11293### 需要权限 11294 11295访问地理位置时需添加权限：ohos.permission.LOCATION、ohos.permission.APPROXIMATELY_LOCATION、ohos.permission.LOCATION_IN_BACKGROUND，具体权限说明请参考[位置服务](../apis-location-kit/js-apis-geolocation.md)。 11296 11297### allowGeolocation 11298 11299static allowGeolocation(origin: string, incognito?: boolean): void 11300 11301允许指定来源使用地理位置接口。 11302 11303**系统能力：** SystemCapability.Web.Webview.Core 11304 11305**参数：** 11306 11307| 参数名 | 类型 | 必填 | 说明 | 11308| ------ | ------ | ---- | ------------------ | 11309| origin | string | 是 |指定源的字符串索引 | 11310| incognito<sup>11+</sup> | boolean | 否 | true表示隐私模式下允许指定来源使用地理位置，false表示正常非隐私模式下允许指定来源使用地理位置。 | 11311 11312**错误码：** 11313 11314以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11315 11316| 错误码ID | 错误信息 | 11317| -------- | ------------------------------------------------------ | 11318| 17100011 | Invalid origin. | 11319| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 11320 11321**示例：** 11322 11323```ts 11324// xxx.ets 11325import { webview } from '@kit.ArkWeb'; 11326import { BusinessError } from '@kit.BasicServicesKit'; 11327 11328@Entry 11329@Component 11330struct WebComponent { 11331 controller: webview.WebviewController = new webview.WebviewController(); 11332 origin: string = "file:///"; 11333 11334 build() { 11335 Column() { 11336 Button('allowGeolocation') 11337 .onClick(() => { 11338 try { 11339 webview.GeolocationPermissions.allowGeolocation(this.origin); 11340 } catch (error) { 11341 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11342 } 11343 }) 11344 Web({ src: 'www.example.com', controller: this.controller }) 11345 } 11346 } 11347} 11348``` 11349 11350### deleteGeolocation 11351 11352static deleteGeolocation(origin: string, incognito?: boolean): void 11353 11354清除指定来源的地理位置权限状态。 11355 11356**系统能力：** SystemCapability.Web.Webview.Core 11357 11358**参数：** 11359 11360| 参数名 | 类型 | 必填 | 说明 | 11361| ------ | ------ | ---- | ------------------ | 11362| origin | string | 是 | 指定源的字符串索引 | 11363| incognito<sup>11+</sup> | boolean | 否 | true表示隐私模式下清除指定来源的地理位置权限状态，false表示正常非隐私模式下清除指定来源的地理位置权限状态。 | 11364 11365**错误码：** 11366 11367以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11368 11369| 错误码ID | 错误信息 | 11370| -------- | ------------------------------------------------------ | 11371| 17100011 | Invalid origin. | 11372| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 11373 11374**示例：** 11375 11376```ts 11377// xxx.ets 11378import { webview } from '@kit.ArkWeb'; 11379import { BusinessError } from '@kit.BasicServicesKit'; 11380 11381@Entry 11382@Component 11383struct WebComponent { 11384 controller: webview.WebviewController = new webview.WebviewController(); 11385 origin: string = "file:///"; 11386 11387 build() { 11388 Column() { 11389 Button('deleteGeolocation') 11390 .onClick(() => { 11391 try { 11392 webview.GeolocationPermissions.deleteGeolocation(this.origin); 11393 } catch (error) { 11394 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11395 } 11396 }) 11397 Web({ src: 'www.example.com', controller: this.controller }) 11398 } 11399 } 11400} 11401``` 11402 11403### getAccessibleGeolocation 11404 11405static getAccessibleGeolocation(origin: string, callback: AsyncCallback\<boolean>, incognito?: boolean): void 11406 11407以回调方式异步获取指定源的地理位置权限状态。 11408 11409**系统能力：** SystemCapability.Web.Webview.Core 11410 11411**参数：** 11412 11413| 参数名 | 类型 | 必填 | 说明 | 11414| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 11415| origin | string | 是 | 指定源的字符串索引 | 11416| callback | AsyncCallback\<boolean> | 是 | 返回指定源的地理位置权限状态。获取成功，true表示已授权，false表示拒绝访问。获取失败，表示不存在指定源的权限状态。 | 11417| incognito<sup>11+</sup> | boolean | 否 | true表示获取隐私模式下以回调方式异步获取指定源的地理位置权限状态，false表示正常非隐私模式下以回调方式异步获取指定源的地理位置权限状态。 | 11418 11419**错误码：** 11420 11421以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11422 11423| 错误码ID | 错误信息 | 11424| -------- | ------------------------------------------------------ | 11425| 17100011 | Invalid origin. | 11426| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 11427 11428**示例：** 11429 11430```ts 11431// xxx.ets 11432import { webview } from '@kit.ArkWeb'; 11433import { BusinessError } from '@kit.BasicServicesKit'; 11434 11435@Entry 11436@Component 11437struct WebComponent { 11438 controller: webview.WebviewController = new webview.WebviewController(); 11439 origin: string = "file:///"; 11440 11441 build() { 11442 Column() { 11443 Button('getAccessibleGeolocation') 11444 .onClick(() => { 11445 try { 11446 webview.GeolocationPermissions.getAccessibleGeolocation(this.origin, (error, result) => { 11447 if (error) { 11448 console.error(`getAccessibleGeolocationAsync error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11449 return; 11450 } 11451 console.log('getAccessibleGeolocationAsync result: ' + result); 11452 }); 11453 } catch (error) { 11454 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11455 } 11456 }) 11457 Web({ src: 'www.example.com', controller: this.controller }) 11458 } 11459 } 11460} 11461``` 11462 11463### getAccessibleGeolocation 11464 11465static getAccessibleGeolocation(origin: string, incognito?: boolean): Promise\<boolean> 11466 11467以Promise方式异步获取指定源的地理位置权限状态。 11468 11469**系统能力：** SystemCapability.Web.Webview.Core 11470 11471**参数：** 11472 11473| 参数名 | 类型 | 必填 | 说明 | 11474| ------ | -------- | ---- | -------------------- | 11475| origin | string | 是 | 指定源的字符串索引。 | 11476| incognito<sup>11+</sup> | boolean | 否 | true表示获取隐私模式下以Promise方式异步获取指定源的地理位置权限状态，false表示正常非隐私模式下以Promise方式异步获取指定源的地理位置权限状态。 | 11477 11478**返回值：** 11479 11480| 类型 | 说明 | 11481| ---------------- | ------------------------------------------------------------ | 11482| Promise\<boolean> | Promise实例，用于获取指定源的权限状态，获取成功，true表示已授权，false表示拒绝访问。获取失败，表示不存在指定源的权限状态。 | 11483 11484**错误码：** 11485 11486以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11487 11488| 错误码ID | 错误信息 | 11489| -------- | ------------------------------------------------------ | 11490| 17100011 | Invalid origin. | 11491| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 11492 11493**示例：** 11494 11495```ts 11496// xxx.ets 11497import { webview } from '@kit.ArkWeb'; 11498import { BusinessError } from '@kit.BasicServicesKit'; 11499 11500@Entry 11501@Component 11502struct WebComponent { 11503 controller: webview.WebviewController = new webview.WebviewController(); 11504 origin: string = "file:///"; 11505 11506 build() { 11507 Column() { 11508 Button('getAccessibleGeolocation') 11509 .onClick(() => { 11510 try { 11511 webview.GeolocationPermissions.getAccessibleGeolocation(this.origin) 11512 .then(result => { 11513 console.log('getAccessibleGeolocationPromise result: ' + result); 11514 }).catch((error: BusinessError) => { 11515 console.error(`getAccessibleGeolocationPromise error, ErrorCode: ${error.code}, Message: ${error.message}`); 11516 }); 11517 } catch (error) { 11518 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11519 } 11520 }) 11521 Web({ src: 'www.example.com', controller: this.controller }) 11522 } 11523 } 11524} 11525``` 11526 11527### getStoredGeolocation 11528 11529static getStoredGeolocation(callback: AsyncCallback\<Array\<string>>, incognito?: boolean): void 11530 11531以回调方式异步获取已存储地理位置权限状态的所有源信息。 11532 11533**系统能力：** SystemCapability.Web.Webview.Core 11534 11535**参数：** 11536 11537| 参数名 | 类型 | 必填 | 说明 | 11538| -------- | ---------------------------- | ---- | ---------------------------------------- | 11539| callback | AsyncCallback\<Array\<string>> | 是 | 返回已存储地理位置权限状态的所有源信息。 | 11540| incognito<sup>11+</sup> | boolean | 否 | true表示获取隐私模式下以回调方式异步获取已存储地理位置权限状态的所有源信息，false表示正常非隐私模式下以回调方式异步获取已存储地理位置权限状态的所有源信息。 | 11541 11542**错误码：** 11543 11544以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11545 11546| 错误码ID | 错误信息 | 11547| -------- | ------------------------------------------------------ | 11548| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 11549 11550**示例：** 11551 11552```ts 11553// xxx.ets 11554import { webview } from '@kit.ArkWeb'; 11555import { BusinessError } from '@kit.BasicServicesKit'; 11556 11557@Entry 11558@Component 11559struct WebComponent { 11560 controller: webview.WebviewController = new webview.WebviewController(); 11561 11562 build() { 11563 Column() { 11564 Button('getStoredGeolocation') 11565 .onClick(() => { 11566 try { 11567 webview.GeolocationPermissions.getStoredGeolocation((error, origins) => { 11568 if (error) { 11569 console.error(`getStoredGeolocationAsync error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11570 return; 11571 } 11572 let origins_str: string = origins.join(); 11573 console.log('getStoredGeolocationAsync origins: ' + origins_str); 11574 }); 11575 } catch (error) { 11576 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11577 } 11578 }) 11579 Web({ src: 'www.example.com', controller: this.controller }) 11580 } 11581 } 11582} 11583``` 11584 11585### getStoredGeolocation 11586 11587static getStoredGeolocation(incognito?: boolean): Promise\<Array\<string>> 11588 11589以Promise方式异步获取已存储地理位置权限状态的所有源信息。 11590 11591**系统能力：** SystemCapability.Web.Webview.Core 11592 11593**参数：** 11594 11595| 参数名 | 类型 | 必填 | 说明 | 11596| -------- | ---------------------------- | ---- | ---------------------------------------- | 11597| incognito<sup>11+</sup> | boolean | 否 | true表示获取隐私模式下以Promise方式异步获取已存储地理位置权限状态的所有源信息，false表示正常非隐私模式下以Promise方式异步获取已存储地理位置权限状态的所有源信息。 | 11598 11599**返回值：** 11600 11601| 类型 | 说明 | 11602| ---------------------- | --------------------------------------------------------- | 11603| Promise\<Array\<string>> | Promise实例，用于获取已存储地理位置权限状态的所有源信息。 | 11604 11605**错误码：** 11606 11607以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11608 11609| 错误码ID | 错误信息 | 11610| -------- | ------------------------------------------------------ | 11611| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 11612 11613**示例：** 11614 11615```ts 11616// xxx.ets 11617import { webview } from '@kit.ArkWeb'; 11618import { BusinessError } from '@kit.BasicServicesKit'; 11619 11620@Entry 11621@Component 11622struct WebComponent { 11623 controller: webview.WebviewController = new webview.WebviewController(); 11624 11625 build() { 11626 Column() { 11627 Button('getStoredGeolocation') 11628 .onClick(() => { 11629 try { 11630 webview.GeolocationPermissions.getStoredGeolocation() 11631 .then(origins => { 11632 let origins_str: string = origins.join(); 11633 console.log('getStoredGeolocationPromise origins: ' + origins_str); 11634 }).catch((error: BusinessError) => { 11635 console.error(`getStoredGeolocationPromise error, ErrorCode: ${error.code}, Message: ${error.message}`); 11636 }); 11637 } catch (error) { 11638 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11639 } 11640 }) 11641 Web({ src: 'www.example.com', controller: this.controller }) 11642 } 11643 } 11644} 11645``` 11646 11647### deleteAllGeolocation 11648 11649static deleteAllGeolocation(incognito?: boolean): void 11650 11651清除所有来源的地理位置权限状态。 11652 11653**系统能力：** SystemCapability.Web.Webview.Core 11654 11655**参数：** 11656 11657| 参数名 | 类型 | 必填 | 说明 | 11658| -------- | ---------------------------- | ---- | ---------------------------------------- | 11659| incognito<sup>11+</sup> | boolean | 否 | true表示获取隐私模式下清除所有来源的地理位置权限状态，false表示正常非隐私模式下清除所有来源的地理位置权限状态。 | 11660 11661**示例：** 11662 11663```ts 11664// xxx.ets 11665import { webview } from '@kit.ArkWeb'; 11666import { BusinessError } from '@kit.BasicServicesKit'; 11667 11668@Entry 11669@Component 11670struct WebComponent { 11671 controller: webview.WebviewController = new webview.WebviewController(); 11672 11673 build() { 11674 Column() { 11675 Button('deleteAllGeolocation') 11676 .onClick(() => { 11677 try { 11678 webview.GeolocationPermissions.deleteAllGeolocation(); 11679 } catch (error) { 11680 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 11681 } 11682 }) 11683 Web({ src: 'www.example.com', controller: this.controller }) 11684 } 11685 } 11686} 11687``` 11688## WebHeader 11689 11690Web组件返回的请求/响应头对象。 11691 11692**系统能力：** SystemCapability.Web.Webview.Core 11693 11694| 名称 | 类型 | 可读 | 可写 |说明 | 11695| ----------- | ------ | -----|------|------------------- | 11696| headerKey | string | 是 | 是 | 请求/响应头的key。 | 11697| headerValue | string | 是 | 是 | 请求/响应头的value。 | 11698 11699## RequestInfo<sup>12+</sup> 11700 11701Web组件发送的资源请求信息。 11702 11703**系统能力：**: SystemCapability.Web.Webview.Core 11704 11705| 名称 | 类型 | 可读 | 可写 |说明 | 11706| ---------| ------ | -----|------|-------- | 11707| url | string | 是 | 是 | 请求的链接。 | 11708| method | string | 是 | 是 | 请求的方法。 | 11709| formData | string | 是 | 是 | 请求的表单数据。 | 11710 11711## WebHitTestType 11712 11713[getHitTest](#gethittest)接口用于指示游标节点。 11714 11715**系统能力：** SystemCapability.Web.Webview.Core 11716 11717| 名称 | 值 | 说明 | 11718| ------------- | -- |----------------------------------------- | 11719| EditText | 0 |可编辑的区域。 | 11720| Email | 1 |电子邮件地址。 | 11721| HttpAnchor | 2 |超链接，其中src为http。 | 11722| HttpAnchorImg | 3 |带有超链接的图片，其中src为http + HTML::img。 | 11723| Img | 4 |HTML::img标签。 | 11724| Map | 5 |地理地址。 | 11725| Phone | 6 |电话号码。 | 11726| Unknown | 7 |未知内容。 | 11727 11728## SecurityLevel<sup>11+</sup> 11729 11730当前网页的安全级别。 11731 11732**系统能力：** SystemCapability.Web.Webview.Core 11733 11734| 名称 | 值 | 说明 | 11735| ------------- | -- |----------------------------------------- | 11736| NONE | 0 |页面既不绝对安全，也不是不安全，即是中立。例如，部分scheme非http/https的URL。| 11737| SECURE | 1 |页面安全，页面使用的是HTTPS协议，且使用了信任的证书。| 11738| WARNING | 2 |页面不安全。例如，使用HTTP协议或使用HTTPS协议但使用旧版TLS版本。| 11739| DANGEROUS | 3 |页面不安全。尝试HTTPS并失败、页面未通过身份验证、页面上包含不安全活动内容的HTTPS、恶意软件、网络钓鱼或任何其他可能危险的严重安全问题。 | 11740 11741## HitTestValue 11742 11743提供点击区域的元素信息。示例代码参考[getHitTestValue](#gethittestvalue)。 11744 11745**系统能力：** SystemCapability.Web.Webview.Core 11746 11747| 名称 | 类型 | 可读 | 可写 | 说明| 11748| ---- | ---- | ---- | ---- |---- | 11749| type | [WebHitTestType](#webhittesttype) | 是 | 是 | 当前被点击区域的元素类型。| 11750| extra | string | 是 | 是 |点击区域的附加参数信息。若被点击区域为图片或链接，则附加参数信息为其url地址。 | 11751 11752## WebMessage 11753 11754type WebMessage = ArrayBuffer | string 11755 11756用于描述[WebMessagePort](#webmessageport)所支持的数据类型。 11757 11758**系统能力：** SystemCapability.Web.Webview.Core 11759 11760| 类型 | 说明 | 11761| -------- | -------------------------------------- | 11762| string | 字符串类型数据。 | 11763| ArrayBuffer | 二进制类型数据。 | 11764 11765## JsMessageType<sup>10+</sup> 11766 11767[runJavaScriptExt](#runjavascriptext10)接口脚本执行后返回的结果的类型。 11768 11769**系统能力：** SystemCapability.Web.Webview.Core 11770 11771| 名称 | 值 | 说明 | 11772| ------------ | -- |--------------------------------- | 11773| NOT_SUPPORT | 0 |不支持的数据类型。| 11774| STRING | 1 |字符串类型。| 11775| NUMBER | 2 |数值类型。| 11776| BOOLEAN | 3 |布尔类型。| 11777| ARRAY_BUFFER | 4 |原始二进制数据缓冲区。| 11778| ARRAY | 5 |数组类型| 11779 11780## WebMessageType<sup>10+</sup> 11781 11782[webMessagePort](#webmessageport)接口所支持的数据类型。 11783 11784**系统能力：** SystemCapability.Web.Webview.Core 11785 11786| 名称 | 值 | 说明 | 11787| ------------ | -- |------------------------------- | 11788| NOT_SUPPORT | 0 |不支持的数据类型。| 11789| STRING | 1 |字符串类型。| 11790| NUMBER | 2 |数值类型。| 11791| BOOLEAN | 3 |布尔类型。| 11792| ARRAY_BUFFER | 4 |原始二进制数据缓冲区。| 11793| ARRAY | 5 |数组类型。| 11794| ERROR | 6 |错误类型。| 11795 11796## MediaPlaybackState<sup>12+</sup> 11797 11798当前网页的播控状态。 11799 11800**系统能力：** SystemCapability.Web.Webview.Core 11801 11802| 名称 | 值 | 说明 | 11803| ------- | ---- | ------------------ | 11804| NONE | 0 | 页面无音视频启播。 | 11805| PLAYING | 1 | 页面音视频播放中。 | 11806| PAUSED | 2 | 页面音视频暂停。 | 11807| STOPPED | 3 | 页面音视频停止。 | 11808 11809## RenderProcessMode<sup>12+</sup> 11810 11811ArkWeb渲染子进程模式类型。 11812 11813**系统能力：** SystemCapability.Web.Webview.Core 11814 11815| 名称 | 值 | 说明 | 11816| ------------- | -- |----------------------------------------- | 11817| SINGLE | 0 |ArkWeb单渲染子进程模式。该模式下，多个Web复用一个渲染子进程。| 11818| MULTIPLE | 1 |ArkWeb多渲染子进程模式。该模式下，每个Web一个渲染子进程。| 11819 11820 11821## JsMessageExt<sup>10+</sup> 11822 11823[runJavaScriptExt](#runjavascriptext10)接口执行脚本返回的数据对象。 11824 11825### getType<sup>10+</sup> 11826 11827getType(): JsMessageType 11828 11829获取数据对象的类型。完整示例代码参考[runJavaScriptExt](#runjavascriptext10)。 11830 11831**系统能力：** SystemCapability.Web.Webview.Core 11832 11833**返回值：** 11834 11835| 类型 | 说明 | 11836| --------------| --------------------------------------------------------- | 11837| [JsMessageType](#jsmessagetype10) | [runJavaScriptExt](#runjavascriptext10)接口脚本执行后返回的结果的类型。 | 11838 11839### getString<sup>10+</sup> 11840 11841getString(): string 11842 11843获取数据对象的字符串类型数据。完整示例代码参考[runJavaScriptExt](#runjavascriptext10)。 11844 11845**系统能力：** SystemCapability.Web.Webview.Core 11846 11847**返回值：** 11848 11849| 类型 | 说明 | 11850| --------------| ------------- | 11851| string | 返回字符串类型的数据。 | 11852 11853**错误码：** 11854 11855以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11856 11857| 错误码ID | 错误信息 | 11858| -------- | ------------------------------------- | 11859| 17100014 | The type and value of the message do not match. | 11860 11861### getNumber<sup>10+</sup> 11862 11863getNumber(): number 11864 11865获取数据对象的数值类型数据。完整示例代码参考[runJavaScriptExt](#runjavascriptext10)。 11866 11867**系统能力：** SystemCapability.Web.Webview.Core 11868 11869**返回值：** 11870 11871| 类型 | 说明 | 11872| --------------| ------------- | 11873| number | 返回数值类型的数据。 | 11874 11875**错误码：** 11876 11877以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11878 11879| 错误码ID | 错误信息 | 11880| -------- | ------------------------------------- | 11881| 17100014 | The type and value of the message do not match. | 11882 11883### getBoolean<sup>10+</sup> 11884 11885getBoolean(): boolean 11886 11887获取数据对象的布尔类型数据。完整示例代码参考[runJavaScriptExt](#runjavascriptext10)。 11888 11889**系统能力：** SystemCapability.Web.Webview.Core 11890 11891**返回值：** 11892 11893| 类型 | 说明 | 11894| --------------| ------------- | 11895| boolean | 返回布尔类型的数据。 | 11896 11897**错误码：** 11898 11899以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11900 11901| 错误码ID | 错误信息 | 11902| -------- | ------------------------------------- | 11903| 17100014 | The type and value of the message do not match. | 11904 11905### getArrayBuffer<sup>10+</sup> 11906 11907getArrayBuffer(): ArrayBuffer 11908 11909获取数据对象的原始二进制数据。完整示例代码参考[runJavaScriptExt](#runjavascriptext10)。 11910 11911**系统能力：** SystemCapability.Web.Webview.Core 11912 11913**返回值：** 11914 11915| 类型 | 说明 | 11916| --------------| ------------- | 11917| ArrayBuffer | 返回原始二进制数据。 | 11918 11919**错误码：** 11920 11921以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11922 11923| 错误码ID | 错误信息 | 11924| -------- | ------------------------------------- | 11925| 17100014 | The type and value of the message do not match. | 11926 11927### getArray<sup>10+</sup> 11928 11929getArray(): Array\<string | number | boolean\> 11930 11931获取数据对象的数组类型数据。完整示例代码参考[runJavaScriptExt](#runjavascriptext10)。 11932 11933**系统能力：** SystemCapability.Web.Webview.Core 11934 11935**返回值：** 11936 11937| 类型 | 说明 | 11938| --------------| ------------- | 11939| Array\<string \| number \| boolean\> | 返回数组类型的数据。 | 11940 11941**错误码：** 11942 11943以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11944 11945| 错误码ID | 错误信息 | 11946| -------- | ------------------------------------- | 11947| 17100014 | The type and value of the message do not match. | 11948 11949## WebMessageExt<sup>10+</sup> 11950 11951[webMessagePort](#webmessageport)接口接收、发送的数据对象。 11952 11953### getType<sup>10+</sup> 11954 11955getType(): WebMessageType 11956 11957获取数据对象的类型。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 11958 11959**系统能力：** SystemCapability.Web.Webview.Core 11960 11961**返回值：** 11962 11963| 类型 | 说明 | 11964| --------------| --------------------------------------------------------- | 11965| [WebMessageType](#webmessagetype10) | [webMessagePort](#webmessageport)接口所支持的数据类型。 | 11966 11967### getString<sup>10+</sup> 11968 11969getString(): string 11970 11971获取数据对象的字符串类型数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 11972 11973**系统能力：** SystemCapability.Web.Webview.Core 11974 11975**返回值：** 11976 11977| 类型 | 说明 | 11978| --------------| ------------- | 11979| string | 返回字符串类型的数据。 | 11980 11981**错误码：** 11982 11983以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 11984 11985| 错误码ID | 错误信息 | 11986| -------- | ------------------------------------- | 11987| 17100014 | The type and value of the message do not match. | 11988 11989### getNumber<sup>10+</sup> 11990 11991getNumber(): number 11992 11993获取数据对象的数值类型数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 11994 11995**系统能力：** SystemCapability.Web.Webview.Core 11996 11997**返回值：** 11998 11999| 类型 | 说明 | 12000| --------------| ------------- | 12001| number | 返回数值类型的数据。 | 12002 12003**错误码：** 12004 12005以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 12006 12007| 错误码ID | 错误信息 | 12008| -------- | ------------------------------------- | 12009| 17100014 | The type and value of the message do not match. | 12010 12011### getBoolean<sup>10+</sup> 12012 12013getBoolean(): boolean 12014 12015获取数据对象的布尔类型数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12016 12017**系统能力：** SystemCapability.Web.Webview.Core 12018 12019**返回值：** 12020 12021| 类型 | 说明 | 12022| --------------| ------------- | 12023| boolean | 返回布尔类型的数据。 | 12024 12025**错误码：** 12026 12027以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 12028 12029| 错误码ID | 错误信息 | 12030| -------- | ------------------------------------- | 12031| 17100014 | The type and value of the message do not match. | 12032 12033### getArrayBuffer<sup>10+</sup> 12034 12035getArrayBuffer(): ArrayBuffer 12036 12037获取数据对象的原始二进制数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12038 12039**系统能力：** SystemCapability.Web.Webview.Core 12040 12041**返回值：** 12042 12043| 类型 | 说明 | 12044| --------------| ------------- | 12045| ArrayBuffer | 返回原始二进制数据。 | 12046 12047**错误码：** 12048 12049以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 12050 12051| 错误码ID | 错误信息 | 12052| -------- | ------------------------------------- | 12053| 17100014 | The type and value of the message do not match. | 12054 12055### getArray<sup>10+</sup> 12056 12057getArray(): Array\<string | number | boolean\> 12058 12059获取数据对象的数组类型数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12060 12061**系统能力：** SystemCapability.Web.Webview.Core 12062 12063**返回值：** 12064 12065| 类型 | 说明 | 12066| --------------| ------------- | 12067| Array\<string \| number \| boolean\> | 返回数组类型的数据。 | 12068 12069**错误码：** 12070 12071以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 12072 12073| 错误码ID | 错误信息 | 12074| -------- | ------------------------------------- | 12075| 17100014 | The type and value of the message do not match. | 12076 12077### getError<sup>10+</sup> 12078 12079getError(): Error 12080 12081获取数据对象的错误类型数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12082 12083**系统能力：** SystemCapability.Web.Webview.Core 12084 12085**返回值：** 12086 12087| 类型 | 说明 | 12088| --------------| ------------- | 12089| Error | 返回错误对象类型的数据。 | 12090 12091**错误码：** 12092 12093以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 12094 12095| 错误码ID | 错误信息 | 12096| -------- | ------------------------------------- | 12097| 17100014 | The type and value of the message do not match. | 12098 12099### setType<sup>10+</sup> 12100 12101setType(type: WebMessageType): void 12102 12103设置数据对象的类型。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12104 12105**系统能力：** SystemCapability.Web.Webview.Core 12106 12107**参数：** 12108 12109| 参数名 | 类型 | 必填 | 说明 | 12110| ------ | ------ | ---- | ---------------------- | 12111| type | [WebMessageType](#webmessagetype10) | 是 | [webMessagePort](#webmessageport)接口所支持的数据类型。 | 12112 12113**错误码：** 12114 12115| 错误码ID | 错误信息 | 12116| -------- | ------------------------------------- | 12117| 17100014 | The type and value of the message do not match. | 12118| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 12119 12120### setString<sup>10+</sup> 12121 12122setString(message: string): void 12123 12124设置数据对象的字符串类型数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12125 12126**系统能力：** SystemCapability.Web.Webview.Core 12127 12128**参数：** 12129 12130| 参数名 | 类型 | 必填 | 说明 | 12131| ------ | ------ | ---- | -------------------- | 12132| message | string | 是 | 字符串类型数据。 | 12133 12134**错误码：** 12135 12136| 错误码ID | 错误信息 | 12137| -------- | ------------------------------------- | 12138| 17100014 | The type and value of the message do not match. | 12139| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 12140 12141### setNumber<sup>10+</sup> 12142 12143setNumber(message: number): void 12144 12145设置数据对象的数值类型数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12146 12147**系统能力：** SystemCapability.Web.Webview.Core 12148 12149**参数：** 12150 12151| 参数名 | 类型 | 必填 | 说明 | 12152| ------ | ------ | ---- | -------------------- | 12153| message | number | 是 | 数值类型数据。 | 12154 12155**错误码：** 12156 12157| 错误码ID | 错误信息 | 12158| -------- | ------------------------------------- | 12159| 17100014 | The type and value of the message do not match. | 12160| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 12161 12162### setBoolean<sup>10+</sup> 12163 12164setBoolean(message: boolean): void 12165 12166设置数据对象的布尔类型数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12167 12168**系统能力：** SystemCapability.Web.Webview.Core 12169 12170**参数：** 12171 12172| 参数名 | 类型 | 必填 | 说明 | 12173| ------ | ------ | ---- | -------------------- | 12174| message | boolean | 是 | 布尔类型数据。 | 12175 12176**错误码：** 12177 12178| 错误码ID | 错误信息 | 12179| -------- | ------------------------------------- | 12180| 17100014 | The type and value of the message do not match. | 12181| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 12182 12183### setArrayBuffer<sup>10+</sup> 12184 12185setArrayBuffer(message: ArrayBuffer): void 12186 12187设置数据对象的原始二进制数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12188 12189**系统能力：** SystemCapability.Web.Webview.Core 12190 12191**参数：** 12192 12193| 参数名 | 类型 | 必填 | 说明 | 12194| ------ | ------ | ---- | -------------------- | 12195| message | ArrayBuffer | 是 | 原始二进制类型数据。 | 12196 12197**错误码：** 12198 12199以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 12200 12201| 错误码ID | 错误信息 | 12202| -------- | ------------------------------------- | 12203| 17100014 | The type and value of the message do not match. | 12204| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 12205 12206### setArray<sup>10+</sup> 12207 12208setArray(message: Array\<string | number | boolean\>): void 12209 12210设置数据对象的数组类型数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12211 12212**系统能力：** SystemCapability.Web.Webview.Core 12213 12214**参数：** 12215 12216| 参数名 | 类型 | 必填 | 说明 | 12217| ------ | ------ | ---- | -------------------- | 12218| message | Array\<string \| number \| boolean\> | 是 | 数组类型数据。 | 12219 12220**错误码：** 12221 12222以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 12223 12224| 错误码ID | 错误信息 | 12225| -------- | ------------------------------------- | 12226| 17100014 | The type and value of the message do not match. | 12227| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 12228 12229### setError<sup>10+</sup> 12230 12231setError(message: Error): void 12232 12233设置数据对象的错误对象类型数据。完整示例代码参考[onMessageEventExt](#onmessageeventext10)。 12234 12235**系统能力：** SystemCapability.Web.Webview.Core 12236 12237**参数：** 12238 12239| 参数名 | 类型 | 必填 | 说明 | 12240| ------ | ------ | ---- | -------------------- | 12241| message | Error | 是 | 错误对象类型数据。 | 12242 12243**错误码：** 12244 12245以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 12246 12247| 错误码ID | 错误信息 | 12248| -------- | ------------------------------------- | 12249| 17100014 | The type and value of the message do not match. | 12250| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 12251 12252## WebStorageOrigin 12253 12254提供Web SQL数据库的使用信息。 12255 12256**系统能力：** SystemCapability.Web.Webview.Core 12257 12258| 名称 | 类型 | 可读 | 可写 | 说明 | 12259| ------ | ------ | ---- | ---- | ---- | 12260| origin | string | 是 | 是 | 指定源的字符串索引。 | 12261| usage | number | 是 | 是 | 指定源的存储量。 | 12262| quota | number | 是 | 是 | 指定源的存储配额。 | 12263 12264## BackForwardList 12265 12266当前Webview的历史信息列表。 12267 12268**系统能力：** SystemCapability.Web.Webview.Core 12269 12270| 名称 | 类型 | 可读 | 可写 | 说明 | 12271| ------------ | ------ | ---- | ---- | ------------------------------------------------------------ | 12272| currentIndex | number | 是 | 是 | 当前在页面历史列表中的索引。 | 12273| size | number | 是 | 是 | 历史列表中索引的数量，最多保存50条，超过时起始记录会被覆盖。 | 12274 12275### getItemAtIndex 12276 12277getItemAtIndex(index: number): HistoryItem 12278 12279获取历史列表中指定索引的历史记录项信息。 12280 12281**系统能力：** SystemCapability.Web.Webview.Core 12282 12283**参数：** 12284 12285| 参数名 | 类型 | 必填 | 说明 | 12286| ------ | ------ | ---- | ---------------------- | 12287| index | number | 是 | 指定历史列表中的索引。 | 12288 12289**返回值：** 12290 12291| 类型 | 说明 | 12292| --------------------------- | ------------ | 12293| [HistoryItem](#historyitem) | 历史记录项。 | 12294 12295**错误码：** 12296 12297以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 12298 12299| 错误码ID | 错误信息 | 12300| -------- | ------------------------------------------------------ | 12301| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 12302 12303**示例：** 12304 12305```ts 12306// xxx.ets 12307import { webview } from '@kit.ArkWeb'; 12308import { BusinessError } from '@kit.BasicServicesKit'; 12309import { image } from '@kit.ImageKit'; 12310 12311@Entry 12312@Component 12313struct WebComponent { 12314 controller: webview.WebviewController = new webview.WebviewController(); 12315 @State icon: image.PixelMap | undefined = undefined; 12316 12317 build() { 12318 Column() { 12319 Button('getBackForwardEntries') 12320 .onClick(() => { 12321 try { 12322 let list = this.controller.getBackForwardEntries(); 12323 let historyItem = list.getItemAtIndex(list.currentIndex); 12324 console.log("HistoryItem: " + JSON.stringify(historyItem)); 12325 this.icon = historyItem.icon; 12326 } catch (error) { 12327 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12328 } 12329 }) 12330 Web({ src: 'www.example.com', controller: this.controller }) 12331 } 12332 } 12333} 12334``` 12335 12336## HistoryItem 12337 12338页面历史记录项。 12339 12340**系统能力：** SystemCapability.Web.Webview.Core 12341 12342| 名称 | 类型 | 可读 | 可写 | 说明 | 12343| ------------- | -------------------------------------- | ---- | ---- | ---------------------------- | 12344| icon | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | 是 | 否 | 历史页面图标的PixelMap对象。 | 12345| historyUrl | string | 是 | 是 | 历史记录项的url地址。 | 12346| historyRawUrl | string | 是 | 是 | 历史记录项的原始url地址。 | 12347| title | string | 是 | 是 | 历史记录项的标题。 | 12348 12349## WebCustomScheme 12350 12351自定义协议配置。 12352 12353**系统能力：** SystemCapability.Web.Webview.Core 12354 12355| 名称 | 类型 | 可读 | 可写 | 说明 | 12356| -------------- | --------- | ---- | ---- | ---------------------------- | 12357| schemeName | string | 是 | 是 | 自定义协议名称。最大长度为32，其字符仅支持小写字母、数字、'.'、'+'、'-', 同时需要以字母开头。 | 12358| isSupportCORS | boolean | 是 | 是 | 是否支持跨域请求。 | 12359| isSupportFetch | boolean | 是 | 是 | 是否支持fetch请求。 | 12360| isStandard<sup>12+</sup> | boolean | 是 | 是 | 设置了该选项的scheme是否将作为标准scheme进行处理。标准scheme需要符合RFC 1738第3.1节中定义的URL规范化和解析规则。 | 12361| isLocal<sup>12+</sup> | boolean | 是 | 是 | 设置了该选项的scheme是否将使用与应用于“FILE”的安全规则相同的安全规则来处理。 | 12362| isDisplayIsolated<sup>12+</sup> | boolean | 是 | 是 | 设置了该选项的scheme的内容是否只能从相同scheme的其他内容中显示或访问。 | 12363| isSecure<sup>12+</sup> | boolean | 是 | 是 | 设置了该选项的scheme是否将使用与应用于“https”的安全规则相同的安全规则来处理。 | 12364| isCspBypassing<sup>12+</sup> | boolean | 是 | 是 | 设置了该选项的scheme可以绕过内容安全策略（CSP）检查。在大多数情况下，当设置isStandard为true时，不应设置此值。 | 12365| isCodeCacheSupported<sup>12+</sup> | boolean | 是 | 是 | 设置了该选项的scheme的js资源是否支持生成code cache。默认值：false。 | 12366 12367## SecureDnsMode<sup>10+</sup> 12368 12369Web组件使用HTTPDNS的模式。 12370 12371**系统能力：** SystemCapability.Web.Webview.Core 12372 12373| 名称 | 值 | 说明 | 12374| ------------- | -- |----------------------------------------- | 12375| OFF | 0 |不使用HTTPDNS， 可以用于撤销之前使用的HTTPDNS配置。| 12376| AUTO | 1 |自动模式，用于解析的设定dns服务器不可用时，可自动回落至系统DNS。| 12377| SECURE_ONLY | 2 |强制使用设定的HTTPDNS服务器进行域名解析。| 12378 12379## WebDownloadState<sup>11+</sup> 12380 12381下载任务的状态。 12382 12383**系统能力：** SystemCapability.Web.Webview.Core 12384 12385| 名称 | 值 | 说明 | 12386| ------------- | -- |----------------------------------------- | 12387| IN_PROGRESS | 0 |下载任务正在进行中。| 12388| COMPLETED | 1 |下载任务已经完成。| 12389| CANCELED | 2 |下载任务已经被取消。| 12390| INTERRUPTED | 3 |下载任务被中断。| 12391| PENDING | 4 |下载任务等待开始。| 12392| PAUSED | 5 |下载任务已经被暂停。| 12393| UNKNOWN | 6 |下载任务未知状态。| 12394 12395## WebDownloadErrorCode<sup>11+</sup> 12396 12397下载任务的错误码。 12398 12399**系统能力：** SystemCapability.Web.Webview.Core 12400 12401| 名称 | 值 | 说明 | 12402| ------------- | -- |----------------------------------------- | 12403| ERROR_UNKNOWN | 0 |未知的错误。| 12404| FILE_FAILED | 1 | 常规文件操作失败。| 12405| FILE_ACCESS_DENIED | 2 | 没有权限访问文件。| 12406| FILE_NO_SPACE | 3 | 磁盘没有足够的空间。| 12407| FILE_NAME_TOO_LONG | 5 | 文件名字过长。| 12408| FILE_TOO_LARGE | 6 | 文件太大。| 12409| FILE_TRANSIENT_ERROR | 10 | 出现了一些临时问题，例如内存不足、文件正在使用以及同时打开的文件过多。| 12410| FILE_BLOCKED | 11 | 由于某些本地策略，文件被阻止访问。| 12411| FILE_TOO_SHORT | 13 | 当尝试恢复下载时，发现文件不够长，可能该文件已不存在。| 12412| FILE_HASH_MISMATCH | 14 | 哈希不匹配。| 12413| FILE_SAME_AS_SOURCE | 15 | 文件已存在。| 12414| NETWORK_FAILED | 20 | 一般网络错误。| 12415| NETWORK_TIMEOUT | 21 | 网络超时。| 12416| NETWORK_DISCONNECTED | 22 | 网络断开连接。| 12417| NETWORK_SERVER_DOWN | 23 | 服务器关闭。| 12418| NETWORK_INVALID_REQUEST | 24 | 无效的网络请求，可能重定向到不支持的方案或无效的URL。| 12419| SERVER_FAILED | 30 | 服务器返回了一个一般性错误。| 12420| SERVER_NO_RANGE | 31 | 服务器不支持范围请求。| 12421| SERVER_BAD_CONTENT | 33 | 服务器没有请求的数据。| 12422| SERVER_UNAUTHORIZED | 34 | 服务器不允许下载该文件。| 12423| SERVER_CERT_PROBLEM | 35 | 服务器证书错误。| 12424| SERVER_FORBIDDEN | 36 | 服务器访问被禁止。| 12425| SERVER_UNREACHABLE | 37 | 无法访问服务器。| 12426| SERVER_CONTENT_LENGTH_MISMATCH | 38 | 接收到的数据与内容长度不匹配。| 12427| SERVER_CROSS_ORIGIN_REDIRECT | 39 | 发生意外的跨站重定向。| 12428| USER_CANCELED | 40 | 用户取消了下载。| 12429| USER_SHUTDOWN | 41 | 用户关闭了应用。| 12430| CRASH | 50 | 应用发生了崩溃。| 12431 12432## WebDownloadItem<sup>11+</sup> 12433 12434 表示下载任务，您可以使用此对象来操作相应的下载任务。 12435 12436> **说明：** 12437> 12438> 在下载过程中，下载的进程会通过WebDownloadDelegate通知给使用者，使用者可以通过参数WebDownloadItem来操作下载任务。 12439 12440### getGuid<sup>11+</sup> 12441 12442getGuid(): string 12443 12444获取下载任务的唯一ID。 12445 12446**系统能力：** SystemCapability.Web.Webview.Core 12447 12448**返回值：** 12449 12450| 类型 | 说明 | 12451| ------ | ------------------------- | 12452| string | 下载任务的唯一ID。 | 12453 12454**示例：** 12455 12456```ts 12457// xxx.ets 12458import { webview } from '@kit.ArkWeb'; 12459import { BusinessError } from '@kit.BasicServicesKit'; 12460 12461@Entry 12462@Component 12463struct WebComponent { 12464 controller: webview.WebviewController = new webview.WebviewController(); 12465 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 12466 12467 build() { 12468 Column() { 12469 Button('setDownloadDelegate') 12470 .onClick(() => { 12471 try { 12472 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 12473 console.log("will start a download."); 12474 // 传入一个下载路径，并开始下载。 12475 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 12476 }) 12477 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 12478 console.log("download update guid: " + webDownloadItem.getGuid()); 12479 }) 12480 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 12481 console.log("download failed guid: " + webDownloadItem.getGuid()); 12482 }) 12483 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 12484 console.log("download finish guid: " + webDownloadItem.getGuid()); 12485 }) 12486 this.controller.setDownloadDelegate(this.delegate); 12487 } catch (error) { 12488 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12489 } 12490 }) 12491 Button('startDownload') 12492 .onClick(() => { 12493 try { 12494 this.controller.startDownload('https://www.example.com'); 12495 } catch (error) { 12496 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12497 } 12498 }) 12499 Web({ src: 'www.example.com', controller: this.controller }) 12500 } 12501 } 12502} 12503``` 12504 12505### getCurrentSpeed<sup>11+</sup> 12506 12507getCurrentSpeed(): number 12508 12509获取下载的速度，单位：字节每秒。 12510 12511**系统能力：** SystemCapability.Web.Webview.Core 12512 12513**返回值：** 12514 12515| 类型 | 说明 | 12516| ------ | ------------------------- | 12517| number | 下载的速度（字节每秒）。 | 12518 12519**示例：** 12520 12521```ts 12522// xxx.ets 12523import { webview } from '@kit.ArkWeb'; 12524import { BusinessError } from '@kit.BasicServicesKit'; 12525 12526@Entry 12527@Component 12528struct WebComponent { 12529 controller: webview.WebviewController = new webview.WebviewController(); 12530 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 12531 12532 build() { 12533 Column() { 12534 Button('setDownloadDelegate') 12535 .onClick(() => { 12536 try { 12537 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 12538 console.log("will start a download."); 12539 // 传入一个下载路径，并开始下载。 12540 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 12541 }) 12542 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 12543 console.log("download update current speed: " + webDownloadItem.getCurrentSpeed()); 12544 }) 12545 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 12546 console.log("download failed guid: " + webDownloadItem.getGuid()); 12547 }) 12548 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 12549 console.log("download finish guid: " + webDownloadItem.getGuid()); 12550 }) 12551 this.controller.setDownloadDelegate(this.delegate); 12552 } catch (error) { 12553 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12554 } 12555 }) 12556 Button('startDownload') 12557 .onClick(() => { 12558 try { 12559 this.controller.startDownload('https://www.example.com'); 12560 } catch (error) { 12561 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12562 } 12563 }) 12564 Web({ src: 'www.example.com', controller: this.controller }) 12565 } 12566 } 12567} 12568``` 12569 12570### getPercentComplete<sup>11+</sup> 12571 12572getPercentComplete(): number 12573 12574获取下载的进度，100代表下载完成。 12575 12576**系统能力：** SystemCapability.Web.Webview.Core 12577 12578**返回值：** 12579 12580| 类型 | 说明 | 12581| ------ | ------------------------- | 12582| number | 下载完成的进度，100代表下载完成。 | 12583 12584**示例：** 12585 12586```ts 12587// xxx.ets 12588import { webview } from '@kit.ArkWeb'; 12589import { BusinessError } from '@kit.BasicServicesKit'; 12590 12591@Entry 12592@Component 12593struct WebComponent { 12594 controller: webview.WebviewController = new webview.WebviewController(); 12595 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 12596 12597 build() { 12598 Column() { 12599 Button('setDownloadDelegate') 12600 .onClick(() => { 12601 try { 12602 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 12603 console.log("will start a download."); 12604 // 传入一个下载路径，并开始下载。 12605 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 12606 }) 12607 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 12608 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 12609 }) 12610 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 12611 console.log("download failed guid: " + webDownloadItem.getGuid()); 12612 }) 12613 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 12614 console.log("download finish guid: " + webDownloadItem.getGuid()); 12615 }) 12616 this.controller.setDownloadDelegate(this.delegate); 12617 } catch (error) { 12618 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12619 } 12620 }) 12621 Button('startDownload') 12622 .onClick(() => { 12623 try { 12624 this.controller.startDownload('https://www.example.com'); 12625 } catch (error) { 12626 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12627 } 12628 }) 12629 Web({ src: 'www.example.com', controller: this.controller }) 12630 } 12631 } 12632} 12633``` 12634 12635### getTotalBytes<sup>11+</sup> 12636 12637getTotalBytes(): number 12638 12639获取待下载文件的总长度。 12640 12641**系统能力：** SystemCapability.Web.Webview.Core 12642 12643**返回值：** 12644 12645| 类型 | 说明 | 12646| ------ | ------------------------- | 12647| number | 待下载文件的总长度。 | 12648 12649**示例：** 12650 12651```ts 12652// xxx.ets 12653import { webview } from '@kit.ArkWeb'; 12654import { BusinessError } from '@kit.BasicServicesKit'; 12655 12656@Entry 12657@Component 12658struct WebComponent { 12659 controller: webview.WebviewController = new webview.WebviewController(); 12660 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 12661 12662 build() { 12663 Column() { 12664 Button('setDownloadDelegate') 12665 .onClick(() => { 12666 try { 12667 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 12668 console.log("will start a download."); 12669 // 传入一个下载路径，并开始下载。 12670 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 12671 }) 12672 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 12673 console.log("download update total bytes: " + webDownloadItem.getTotalBytes()); 12674 }) 12675 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 12676 console.log("download failed guid: " + webDownloadItem.getGuid()); 12677 }) 12678 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 12679 console.log("download finish guid: " + webDownloadItem.getGuid()); 12680 }) 12681 this.controller.setDownloadDelegate(this.delegate); 12682 } catch (error) { 12683 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12684 } 12685 }) 12686 Button('startDownload') 12687 .onClick(() => { 12688 try { 12689 this.controller.startDownload('https://www.example.com'); 12690 } catch (error) { 12691 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12692 } 12693 }) 12694 Web({ src: 'www.example.com', controller: this.controller }) 12695 } 12696 } 12697} 12698``` 12699 12700### getState<sup>11+</sup> 12701 12702getState(): WebDownloadState 12703 12704获取下载的状态。 12705 12706**系统能力：** SystemCapability.Web.Webview.Core 12707 12708**返回值：** 12709 12710| 类型 | 说明 | 12711| ------ | ------------------------- | 12712| [WebDownloadState](#webdownloadstate11) | 下载的状态。 | 12713 12714**示例：** 12715 12716```ts 12717// xxx.ets 12718import { webview } from '@kit.ArkWeb'; 12719import { BusinessError } from '@kit.BasicServicesKit'; 12720 12721@Entry 12722@Component 12723struct WebComponent { 12724 controller: webview.WebviewController = new webview.WebviewController(); 12725 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 12726 12727 build() { 12728 Column() { 12729 Button('setDownloadDelegate') 12730 .onClick(() => { 12731 try { 12732 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 12733 console.log("will start a download."); 12734 // 传入一个下载路径，并开始下载。 12735 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 12736 }) 12737 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 12738 console.log("download update download state: " + webDownloadItem.getState()); 12739 }) 12740 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 12741 console.log("download failed guid: " + webDownloadItem.getGuid()); 12742 }) 12743 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 12744 console.log("download finish guid: " + webDownloadItem.getGuid()); 12745 }) 12746 this.controller.setDownloadDelegate(this.delegate); 12747 } catch (error) { 12748 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12749 } 12750 }) 12751 Button('startDownload') 12752 .onClick(() => { 12753 try { 12754 this.controller.startDownload('https://www.example.com'); 12755 } catch (error) { 12756 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12757 } 12758 }) 12759 Web({ src: 'www.example.com', controller: this.controller }) 12760 } 12761 } 12762} 12763``` 12764 12765### getLastErrorCode<sup>11+</sup> 12766 12767getLastErrorCode(): WebDownloadErrorCode 12768 12769获取下载的错误码。 12770 12771**系统能力：** SystemCapability.Web.Webview.Core 12772 12773**返回值：** 12774 12775| 类型 | 说明 | 12776| ------ | ------------------------- | 12777| [WebDownloadErrorCode](#webdownloaderrorcode11) | 下载发生错误的时候的错误码。 | 12778 12779**示例：** 12780 12781```ts 12782// xxx.ets 12783import { webview } from '@kit.ArkWeb'; 12784import { BusinessError } from '@kit.BasicServicesKit'; 12785 12786@Entry 12787@Component 12788struct WebComponent { 12789 controller: webview.WebviewController = new webview.WebviewController(); 12790 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 12791 12792 build() { 12793 Column() { 12794 Button('setDownloadDelegate') 12795 .onClick(() => { 12796 try { 12797 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 12798 console.log("will start a download."); 12799 // 传入一个下载路径，并开始下载。 12800 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 12801 }) 12802 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 12803 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 12804 }) 12805 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 12806 console.log("download failed guid: " + webDownloadItem.getGuid()); 12807 console.log("download error code: " + webDownloadItem.getLastErrorCode()); 12808 }) 12809 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 12810 console.log("download finish guid: " + webDownloadItem.getGuid()); 12811 }) 12812 this.controller.setDownloadDelegate(this.delegate); 12813 } catch (error) { 12814 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12815 } 12816 }) 12817 Button('startDownload') 12818 .onClick(() => { 12819 try { 12820 this.controller.startDownload('https://www.example.com'); 12821 } catch (error) { 12822 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12823 } 12824 }) 12825 Web({ src: 'www.example.com', controller: this.controller }) 12826 } 12827 } 12828} 12829``` 12830 12831### getMethod<sup>11+</sup> 12832 12833getMethod(): string 12834 12835获取下载任务的请求方式。 12836 12837**系统能力：** SystemCapability.Web.Webview.Core 12838 12839**返回值：** 12840 12841| 类型 | 说明 | 12842| ------ | ------------------------- | 12843| string | 下载的请求方式。 | 12844 12845**示例：** 12846 12847```ts 12848// xxx.ets 12849import { webview } from '@kit.ArkWeb'; 12850import { BusinessError } from '@kit.BasicServicesKit'; 12851 12852@Entry 12853@Component 12854struct WebComponent { 12855 controller: webview.WebviewController = new webview.WebviewController(); 12856 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 12857 12858 build() { 12859 Column() { 12860 Button('setDownloadDelegate') 12861 .onClick(() => { 12862 try { 12863 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 12864 console.log("will start a download， method:" + webDownloadItem.getMethod()); 12865 // 传入一个下载路径，并开始下载。 12866 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 12867 }) 12868 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 12869 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 12870 }) 12871 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 12872 console.log("download failed guid: " + webDownloadItem.getGuid()); 12873 }) 12874 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 12875 console.log("download finish guid: " + webDownloadItem.getGuid()); 12876 }) 12877 this.controller.setDownloadDelegate(this.delegate); 12878 } catch (error) { 12879 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12880 } 12881 }) 12882 Button('startDownload') 12883 .onClick(() => { 12884 try { 12885 this.controller.startDownload('https://www.example.com'); 12886 } catch (error) { 12887 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12888 } 12889 }) 12890 Web({ src: 'www.example.com', controller: this.controller }) 12891 } 12892 } 12893} 12894``` 12895 12896### getMimeType<sup>11+</sup> 12897 12898getMimeType(): string 12899 12900获取下载的媒体类型（例如，一个声音文件可能被标记为 audio/ogg ，一个图像文件可能是 image/png）。 12901 12902**系统能力：** SystemCapability.Web.Webview.Core 12903 12904**返回值：** 12905 12906| 类型 | 说明 | 12907| ------ | ------------------------- | 12908| string | 下载的媒体类型（例如，一个声音文件可能被标记为 audio/ogg ，一个图像文件可能是 image/png）。| 12909 12910**示例：** 12911 12912```ts 12913// xxx.ets 12914import { webview } from '@kit.ArkWeb'; 12915import { BusinessError } from '@kit.BasicServicesKit'; 12916 12917@Entry 12918@Component 12919struct WebComponent { 12920 controller: webview.WebviewController = new webview.WebviewController(); 12921 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 12922 12923 build() { 12924 Column() { 12925 Button('setDownloadDelegate') 12926 .onClick(() => { 12927 try { 12928 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 12929 console.log("will start a download， mime type:" + webDownloadItem.getMimeType()); 12930 // 传入一个下载路径，并开始下载。 12931 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 12932 }) 12933 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 12934 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 12935 }) 12936 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 12937 console.log("download failed guid: " + webDownloadItem.getGuid()); 12938 }) 12939 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 12940 console.log("download finish guid: " + webDownloadItem.getGuid()); 12941 }) 12942 this.controller.setDownloadDelegate(this.delegate); 12943 } catch (error) { 12944 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12945 } 12946 }) 12947 Button('startDownload') 12948 .onClick(() => { 12949 try { 12950 this.controller.startDownload('https://www.example.com'); 12951 } catch (error) { 12952 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 12953 } 12954 }) 12955 Web({ src: 'www.example.com', controller: this.controller }) 12956 } 12957 } 12958} 12959``` 12960 12961### getUrl<sup>11+</sup> 12962 12963getUrl(): string 12964 12965获取下载的请求地址。 12966 12967**系统能力：** SystemCapability.Web.Webview.Core 12968 12969**返回值：** 12970 12971| 类型 | 说明 | 12972| ------ | ------------------------- | 12973| string | 下载的请求地址。 | 12974 12975**示例：** 12976 12977```ts 12978// xxx.ets 12979import { webview } from '@kit.ArkWeb'; 12980import { BusinessError } from '@kit.BasicServicesKit'; 12981 12982@Entry 12983@Component 12984struct WebComponent { 12985 controller: webview.WebviewController = new webview.WebviewController(); 12986 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 12987 12988 build() { 12989 Column() { 12990 Button('setDownloadDelegate') 12991 .onClick(() => { 12992 try { 12993 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 12994 console.log("will start a download, url:" + webDownloadItem.getUrl()); 12995 // 传入一个下载路径，并开始下载。 12996 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 12997 }) 12998 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 12999 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13000 }) 13001 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13002 console.log("download failed guid: " + webDownloadItem.getGuid()); 13003 }) 13004 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13005 console.log("download finish guid: " + webDownloadItem.getGuid()); 13006 }) 13007 this.controller.setDownloadDelegate(this.delegate); 13008 } catch (error) { 13009 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13010 } 13011 }) 13012 Button('startDownload') 13013 .onClick(() => { 13014 try { 13015 this.controller.startDownload('https://www.example.com'); 13016 } catch (error) { 13017 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13018 } 13019 }) 13020 Web({ src: 'www.example.com', controller: this.controller }) 13021 } 13022 } 13023} 13024``` 13025 13026### getSuggestedFileName<sup>11+</sup> 13027 13028getSuggestedFileName(): string 13029 13030获取下载的建议文件名。 13031 13032**系统能力：** SystemCapability.Web.Webview.Core 13033 13034**返回值：** 13035 13036| 类型 | 说明 | 13037| ------ | ------------------------- | 13038| string | 下载的建议文件名。 | 13039 13040**示例：** 13041 13042```ts 13043// xxx.ets 13044import { webview } from '@kit.ArkWeb'; 13045import { BusinessError } from '@kit.BasicServicesKit'; 13046 13047@Entry 13048@Component 13049struct WebComponent { 13050 controller: webview.WebviewController = new webview.WebviewController(); 13051 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13052 13053 build() { 13054 Column() { 13055 Button('setDownloadDelegate') 13056 .onClick(() => { 13057 try { 13058 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13059 console.log("will start a download, suggest name:" + webDownloadItem.getSuggestedFileName()); 13060 // 传入一个下载路径，并开始下载。 13061 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13062 }) 13063 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13064 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13065 }) 13066 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13067 console.log("download failed guid: " + webDownloadItem.getGuid()); 13068 }) 13069 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13070 console.log("download finish guid: " + webDownloadItem.getGuid()); 13071 }) 13072 this.controller.setDownloadDelegate(this.delegate); 13073 } catch (error) { 13074 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13075 } 13076 }) 13077 Button('startDownload') 13078 .onClick(() => { 13079 try { 13080 this.controller.startDownload('https://www.example.com'); 13081 } catch (error) { 13082 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13083 } 13084 }) 13085 Web({ src: 'www.example.com', controller: this.controller }) 13086 } 13087 } 13088} 13089``` 13090 13091### getReceivedBytes<sup>11+</sup> 13092 13093getReceivedBytes(): number 13094 13095获取已经接收的字节数。 13096 13097**系统能力：** SystemCapability.Web.Webview.Core 13098 13099**返回值：** 13100 13101| 类型 | 说明 | 13102| ------ | ------------------------- | 13103| number | 已经接收的字节数。 | 13104 13105**示例：** 13106 13107```ts 13108// xxx.ets 13109import { webview } from '@kit.ArkWeb'; 13110import { BusinessError } from '@kit.BasicServicesKit'; 13111 13112@Entry 13113@Component 13114struct WebComponent { 13115 controller: webview.WebviewController = new webview.WebviewController(); 13116 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13117 13118 build() { 13119 Column() { 13120 Button('setDownloadDelegate') 13121 .onClick(() => { 13122 try { 13123 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13124 console.log("will start a download."); 13125 // 传入一个下载路径，并开始下载。 13126 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13127 }) 13128 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13129 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13130 console.log("download update received bytes: " + webDownloadItem.getReceivedBytes()); 13131 }) 13132 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13133 console.log("download failed guid: " + webDownloadItem.getGuid()); 13134 }) 13135 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13136 console.log("download finish guid: " + webDownloadItem.getGuid()); 13137 }) 13138 this.controller.setDownloadDelegate(this.delegate); 13139 } catch (error) { 13140 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13141 } 13142 }) 13143 Button('startDownload') 13144 .onClick(() => { 13145 try { 13146 this.controller.startDownload('https://www.example.com'); 13147 } catch (error) { 13148 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13149 } 13150 }) 13151 Web({ src: 'www.example.com', controller: this.controller }) 13152 } 13153 } 13154} 13155``` 13156 13157### getFullPath<sup>11+</sup> 13158 13159getFullPath(): string 13160 13161获取下载文件在磁盘上的全路径。 13162 13163**系统能力：** SystemCapability.Web.Webview.Core 13164 13165**返回值：** 13166 13167| 类型 | 说明 | 13168| ------ | ------------------------- | 13169| string | 下载文件在磁盘上的全路径。 | 13170 13171**示例：** 13172 13173```ts 13174// xxx.ets 13175import { webview } from '@kit.ArkWeb'; 13176import { BusinessError } from '@kit.BasicServicesKit'; 13177 13178@Entry 13179@Component 13180struct WebComponent { 13181 controller: webview.WebviewController = new webview.WebviewController(); 13182 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13183 13184 build() { 13185 Column() { 13186 Button('setDownloadDelegate') 13187 .onClick(() => { 13188 try { 13189 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13190 console.log("will start a download."); 13191 // 传入一个下载路径，并开始下载。 13192 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13193 }) 13194 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13195 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13196 }) 13197 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13198 console.log("download failed guid: " + webDownloadItem.getGuid()); 13199 }) 13200 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13201 console.log("download finish guid: " + webDownloadItem.getGuid()); 13202 console.log("download finish full path: " + webDownloadItem.getFullPath()); 13203 }) 13204 this.controller.setDownloadDelegate(this.delegate); 13205 } catch (error) { 13206 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13207 } 13208 }) 13209 Button('startDownload') 13210 .onClick(() => { 13211 try { 13212 this.controller.startDownload('https://www.example.com'); 13213 } catch (error) { 13214 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13215 } 13216 }) 13217 Web({ src: 'www.example.com', controller: this.controller }) 13218 } 13219 } 13220} 13221``` 13222 13223### serialize<sup>11+</sup> 13224 13225serialize(): Uint8Array 13226 13227将失败的下载序列化到一个字节数组。 13228 13229**系统能力：** SystemCapability.Web.Webview.Core 13230 13231**返回值：** 13232 13233| 类型 | 说明 | 13234| ------ | ------------------------- | 13235| Uint8Array | 失败的下载序列化后的字节数组。 | 13236 13237**示例：** 13238 13239```ts 13240// xxx.ets 13241import { webview } from '@kit.ArkWeb'; 13242import { BusinessError } from '@kit.BasicServicesKit'; 13243 13244@Entry 13245@Component 13246struct WebComponent { 13247 controller: webview.WebviewController = new webview.WebviewController(); 13248 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13249 failedData: Uint8Array = new Uint8Array(); 13250 13251 build() { 13252 Column() { 13253 Button('setDownloadDelegate') 13254 .onClick(() => { 13255 try { 13256 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13257 console.log("will start a download."); 13258 // 传入一个下载路径，并开始下载。 13259 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13260 }) 13261 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13262 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13263 }) 13264 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13265 console.log("download failed guid: " + webDownloadItem.getGuid()); 13266 // 序列化失败的下载到一个字节数组。 13267 this.failedData = webDownloadItem.serialize(); 13268 }) 13269 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13270 console.log("download finish guid: " + webDownloadItem.getGuid()); 13271 }) 13272 this.controller.setDownloadDelegate(this.delegate); 13273 } catch (error) { 13274 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13275 } 13276 }) 13277 Button('startDownload') 13278 .onClick(() => { 13279 try { 13280 this.controller.startDownload('https://www.example.com'); 13281 } catch (error) { 13282 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13283 } 13284 }) 13285 Web({ src: 'www.example.com', controller: this.controller }) 13286 } 13287 } 13288} 13289``` 13290 13291### deserialize<sup>11+</sup> 13292 13293static deserialize(serializedData: Uint8Array): WebDownloadItem 13294 13295将序列化后的字节数组反序列化为一个WebDownloadItem对象。 13296 13297**系统能力：** SystemCapability.Web.Webview.Core 13298 13299**参数：** 13300 13301| 参数名 | 类型 | 必填 | 说明 | 13302| ------------------ | ------- | ---- | ------------- | 13303| serializedData | Uint8Array | 是 | 序列化后的下载。| 13304 13305**返回值：** 13306 13307| 类型 | 说明 | 13308| ------ | ------------------------- | 13309| [WebDownloadItem](#webdownloaditem11) | 从字节数组反序列化为一个WebDownloadItem对象。 | 13310 13311**错误码：** 13312 13313以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 13314 13315| 错误码ID | 错误信息 | 13316| -------- | ------------------------------------------------------------ | 13317| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. | 13318 13319**示例：** 13320 13321```ts 13322// xxx.ets 13323import { webview } from '@kit.ArkWeb'; 13324import { BusinessError } from '@kit.BasicServicesKit'; 13325 13326@Entry 13327@Component 13328struct WebComponent { 13329 controller: webview.WebviewController = new webview.WebviewController(); 13330 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13331 failedData: Uint8Array = new Uint8Array(); 13332 13333 build() { 13334 Column() { 13335 Button('setDownloadDelegate') 13336 .onClick(() => { 13337 try { 13338 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13339 console.log("will start a download."); 13340 // 传入一个下载路径，并开始下载。 13341 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13342 }) 13343 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13344 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13345 }) 13346 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13347 console.log("download failed guid: " + webDownloadItem.getGuid()); 13348 // 序列化失败的下载到一个字节数组。 13349 this.failedData = webDownloadItem.serialize(); 13350 }) 13351 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13352 console.log("download finish guid: " + webDownloadItem.getGuid()); 13353 }) 13354 this.controller.setDownloadDelegate(this.delegate); 13355 } catch (error) { 13356 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13357 } 13358 }) 13359 Button('startDownload') 13360 .onClick(() => { 13361 try { 13362 this.controller.startDownload('https://www.example.com'); 13363 } catch (error) { 13364 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13365 } 13366 }) 13367 Button('resumeDownload') 13368 .onClick(() => { 13369 try { 13370 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 13371 } catch (error) { 13372 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13373 } 13374 }) 13375 Web({ src: 'www.example.com', controller: this.controller }) 13376 } 13377 } 13378} 13379``` 13380 13381### start<sup>11+</sup> 13382 13383start(downloadPath: string): void 13384 13385开始下载到指定目录，参数为下载文件的磁盘存储路径(包含文件名)。 13386 13387> **说明：** 13388> 13389>该接口应在WebDownloadDelegate的onBeforeDownload回调中使用。若在WebDownloadDelegate的onBeforeDownload中未调用start('xxx')，则下载任务将保持在PENDING状态。处于PENDING状态的下载会将文件下载到临时目录，临时文件会在WebDownloadItem.start指定目标路径后被重命名为目标路径，未下载完成的部分会在WebDownloadItem.start指定目标路径后直接下载到目标路径。如果在调用WebDownloadItem.start之前不希望下载到临时文件路径，可以先通过WebDownloadItem.cancel取消当前下载任务，随后通过WebDownloadManager.resumeDownload恢复被取消的下载任务。 13390 13391**系统能力：** SystemCapability.Web.Webview.Core 13392 13393**参数：** 13394 13395| 参数名 | 类型 | 必填 | 说明 | 13396| ------ | ---------------------- | ---- | ------------------------------| 13397| downloadPath | string | 是 | 下载文件的路径(包含文件名)。| 13398 13399**错误码：** 13400 13401以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 13402 13403| 错误码ID | 错误信息 | 13404| -------- | ------------------------------------------------------------ | 13405| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. | 13406 13407**示例：** 13408 13409```ts 13410// xxx.ets 13411import { webview } from '@kit.ArkWeb'; 13412import { BusinessError } from '@kit.BasicServicesKit'; 13413 13414@Entry 13415@Component 13416struct WebComponent { 13417 controller: webview.WebviewController = new webview.WebviewController(); 13418 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13419 failedData: Uint8Array = new Uint8Array(); 13420 13421 build() { 13422 Column() { 13423 Button('setDownloadDelegate') 13424 .onClick(() => { 13425 try { 13426 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13427 console.log("will start a download."); 13428 // 传入一个下载路径，并开始下载。 13429 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13430 }) 13431 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13432 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13433 }) 13434 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13435 console.log("download failed guid: " + webDownloadItem.getGuid()); 13436 // 序列化失败的下载到一个字节数组。 13437 this.failedData = webDownloadItem.serialize(); 13438 }) 13439 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13440 console.log("download finish guid: " + webDownloadItem.getGuid()); 13441 }) 13442 this.controller.setDownloadDelegate(this.delegate); 13443 } catch (error) { 13444 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13445 } 13446 }) 13447 Button('startDownload') 13448 .onClick(() => { 13449 try { 13450 this.controller.startDownload('https://www.example.com'); 13451 } catch (error) { 13452 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13453 } 13454 }) 13455 Button('resumeDownload') 13456 .onClick(() => { 13457 try { 13458 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 13459 } catch (error) { 13460 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13461 } 13462 }) 13463 Web({ src: 'www.example.com', controller: this.controller }) 13464 } 13465 } 13466} 13467``` 13468 13469### cancel<sup>11+</sup> 13470 13471cancel(): void 13472 13473取消一个正在下载的下载任务。 13474 13475**系统能力：** SystemCapability.Web.Webview.Core 13476 13477**示例：** 13478 13479```ts 13480// xxx.ets 13481import { webview } from '@kit.ArkWeb'; 13482import { BusinessError } from '@kit.BasicServicesKit'; 13483 13484@Entry 13485@Component 13486struct WebComponent { 13487 controller: webview.WebviewController = new webview.WebviewController(); 13488 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13489 download: webview.WebDownloadItem = new webview.WebDownloadItem(); 13490 failedData: Uint8Array = new Uint8Array(); 13491 13492 build() { 13493 Column() { 13494 Button('setDownloadDelegate') 13495 .onClick(() => { 13496 try { 13497 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13498 console.log("will start a download."); 13499 // 传入一个下载路径，并开始下载。 13500 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13501 }) 13502 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13503 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13504 this.download = webDownloadItem; 13505 }) 13506 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13507 console.log("download failed guid: " + webDownloadItem.getGuid()); 13508 // 序列化失败的下载到一个字节数组。 13509 this.failedData = webDownloadItem.serialize(); 13510 }) 13511 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13512 console.log("download finish guid: " + webDownloadItem.getGuid()); 13513 }) 13514 this.controller.setDownloadDelegate(this.delegate); 13515 } catch (error) { 13516 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13517 } 13518 }) 13519 Button('startDownload') 13520 .onClick(() => { 13521 try { 13522 this.controller.startDownload('https://www.example.com'); 13523 } catch (error) { 13524 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13525 } 13526 }) 13527 Button('resumeDownload') 13528 .onClick(() => { 13529 try { 13530 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 13531 } catch (error) { 13532 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13533 } 13534 }) 13535 Button('cancel') 13536 .onClick(() => { 13537 try { 13538 this.download.cancel(); 13539 } catch (error) { 13540 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13541 } 13542 }) 13543 Web({ src: 'www.example.com', controller: this.controller }) 13544 } 13545 } 13546} 13547``` 13548 13549### pause<sup>11+</sup> 13550 13551pause(): void 13552 13553暂停一个正在下载的下载任务。 13554 13555**系统能力：** SystemCapability.Web.Webview.Core 13556 13557**错误码：** 13558 13559以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 13560 13561| 错误码ID | 错误信息 | 13562| -------- | ------------------------------------------------------------ | 13563| 17100019 | The download task is not started yet. | 13564 13565**示例：** 13566 13567```ts 13568// xxx.ets 13569import { webview } from '@kit.ArkWeb'; 13570import { BusinessError } from '@kit.BasicServicesKit'; 13571 13572@Entry 13573@Component 13574struct WebComponent { 13575 controller: webview.WebviewController = new webview.WebviewController(); 13576 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13577 download: webview.WebDownloadItem = new webview.WebDownloadItem(); 13578 failedData: Uint8Array = new Uint8Array(); 13579 13580 build() { 13581 Column() { 13582 Button('setDownloadDelegate') 13583 .onClick(() => { 13584 try { 13585 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13586 console.log("will start a download."); 13587 // 传入一个下载路径，并开始下载。 13588 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13589 }) 13590 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13591 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13592 this.download = webDownloadItem; 13593 }) 13594 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13595 console.log("download failed guid: " + webDownloadItem.getGuid()); 13596 // 序列化失败的下载到一个字节数组。 13597 this.failedData = webDownloadItem.serialize(); 13598 }) 13599 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13600 console.log("download finish guid: " + webDownloadItem.getGuid()); 13601 }) 13602 this.controller.setDownloadDelegate(this.delegate); 13603 } catch (error) { 13604 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13605 } 13606 }) 13607 Button('startDownload') 13608 .onClick(() => { 13609 try { 13610 this.controller.startDownload('https://www.example.com'); 13611 } catch (error) { 13612 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13613 } 13614 }) 13615 Button('resumeDownload') 13616 .onClick(() => { 13617 try { 13618 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 13619 } catch (error) { 13620 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13621 } 13622 }) 13623 Button('cancel') 13624 .onClick(() => { 13625 try { 13626 this.download.cancel(); 13627 } catch (error) { 13628 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13629 } 13630 }) 13631 Button('pause') 13632 .onClick(() => { 13633 try { 13634 this.download.pause(); 13635 } catch (error) { 13636 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13637 } 13638 }) 13639 Web({ src: 'www.example.com', controller: this.controller }) 13640 } 13641 } 13642} 13643``` 13644 13645### resume<sup>11+</sup> 13646 13647resume(): void 13648 13649恢复一个暂停的下载任务。 13650 13651**系统能力：** SystemCapability.Web.Webview.Core 13652 13653**错误码：** 13654 13655以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 13656 13657| 错误码ID | 错误信息 | 13658| -------- | ------------------------------------------------------------ | 13659| 17100016 | The download task is not paused. | 13660 13661**示例：** 13662 13663```ts 13664// xxx.ets 13665import { webview } from '@kit.ArkWeb'; 13666import { BusinessError } from '@kit.BasicServicesKit'; 13667 13668@Entry 13669@Component 13670struct WebComponent { 13671 controller: webview.WebviewController = new webview.WebviewController(); 13672 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13673 download: webview.WebDownloadItem = new webview.WebDownloadItem(); 13674 failedData: Uint8Array = new Uint8Array(); 13675 13676 build() { 13677 Column() { 13678 Button('setDownloadDelegate') 13679 .onClick(() => { 13680 try { 13681 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13682 console.log("will start a download."); 13683 // 传入一个下载路径，并开始下载。 13684 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13685 }) 13686 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13687 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13688 this.download = webDownloadItem; 13689 }) 13690 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13691 console.log("download failed guid: " + webDownloadItem.getGuid()); 13692 // 序列化失败的下载到一个字节数组。 13693 this.failedData = webDownloadItem.serialize(); 13694 }) 13695 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13696 console.log("download finish guid: " + webDownloadItem.getGuid()); 13697 }) 13698 this.controller.setDownloadDelegate(this.delegate); 13699 } catch (error) { 13700 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13701 } 13702 }) 13703 Button('startDownload') 13704 .onClick(() => { 13705 try { 13706 this.controller.startDownload('https://www.example.com'); 13707 } catch (error) { 13708 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13709 } 13710 }) 13711 Button('resumeDownload') 13712 .onClick(() => { 13713 try { 13714 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 13715 } catch (error) { 13716 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13717 } 13718 }) 13719 Button('cancel') 13720 .onClick(() => { 13721 try { 13722 this.download.cancel(); 13723 } catch (error) { 13724 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13725 } 13726 }) 13727 Button('pause') 13728 .onClick(() => { 13729 try { 13730 this.download.pause(); 13731 } catch (error) { 13732 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13733 } 13734 }) 13735 Button('resume') 13736 .onClick(() => { 13737 try { 13738 this.download.resume(); 13739 } catch (error) { 13740 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13741 } 13742 }) 13743 Web({ src: 'www.example.com', controller: this.controller }) 13744 } 13745 } 13746} 13747``` 13748 13749## WebDownloadDelegate<sup>11+</sup> 13750 13751 下载任务的状态会通过该类的回调接口通知给用户。 13752 13753### onBeforeDownload<sup>11+</sup> 13754 13755onBeforeDownload(callback: Callback\<WebDownloadItem>): void 13756 13757下载开始前通知给用户，用户需要在此接口中调用WebDownloadItem.start("xxx")并提供下载路径，否则下载会一直处于PENDING状态。 13758 13759> **说明：** 13760> 13761>处于PENDING状态的下载任务会首先将文件保存至临时目录。在调用WebDownloadItem.start并指定目标路径后，临时文件将被重命名为目标文件名，未完成下载的部分会在调用WebDownloadItem.start并指定目标路径后直接下载到目标路径。若希望避免在调用WebDownloadItem.start前生成临时文件，可先通过WebDownloadItem.cancel来取消当前的下载任务，之后再使用WebDownloadManager.resumeDownload来恢复被取消的下载任务。 13762 13763**系统能力：** SystemCapability.Web.Webview.Core 13764 13765**参数：** 13766 13767| 参数名 | 类型 | 必填 | 说明 | 13768| ------- | ------ | ---- | :------------- | 13769| callback | Callback\<[WebDownloadItem](#webdownloaditem11)> | 是 | 触发下载的回调。 | 13770 13771**示例：** 13772 13773```ts 13774// xxx.ets 13775import { webview } from '@kit.ArkWeb'; 13776import { BusinessError } from '@kit.BasicServicesKit'; 13777 13778@Entry 13779@Component 13780struct WebComponent { 13781 controller: webview.WebviewController = new webview.WebviewController(); 13782 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13783 download: webview.WebDownloadItem = new webview.WebDownloadItem(); 13784 failedData: Uint8Array = new Uint8Array(); 13785 13786 build() { 13787 Column() { 13788 Button('setDownloadDelegate') 13789 .onClick(() => { 13790 try { 13791 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13792 console.log("will start a download."); 13793 // 传入一个下载路径，并开始下载。 13794 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13795 }) 13796 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13797 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13798 this.download = webDownloadItem; 13799 }) 13800 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13801 console.log("download failed guid: " + webDownloadItem.getGuid()); 13802 // 序列化失败的下载到一个字节数组。 13803 this.failedData = webDownloadItem.serialize(); 13804 }) 13805 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13806 console.log("download finish guid: " + webDownloadItem.getGuid()); 13807 }) 13808 this.controller.setDownloadDelegate(this.delegate); 13809 } catch (error) { 13810 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13811 } 13812 }) 13813 Button('startDownload') 13814 .onClick(() => { 13815 try { 13816 this.controller.startDownload('https://www.example.com'); 13817 } catch (error) { 13818 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13819 } 13820 }) 13821 Button('resumeDownload') 13822 .onClick(() => { 13823 try { 13824 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 13825 } catch (error) { 13826 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13827 } 13828 }) 13829 Button('cancel') 13830 .onClick(() => { 13831 try { 13832 this.download.cancel(); 13833 } catch (error) { 13834 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13835 } 13836 }) 13837 Button('pause') 13838 .onClick(() => { 13839 try { 13840 this.download.pause(); 13841 } catch (error) { 13842 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13843 } 13844 }) 13845 Button('resume') 13846 .onClick(() => { 13847 try { 13848 this.download.resume(); 13849 } catch (error) { 13850 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13851 } 13852 }) 13853 Web({ src: 'www.example.com', controller: this.controller }) 13854 } 13855 } 13856} 13857``` 13858 13859### onDownloadUpdated<sup>11+</sup> 13860 13861onDownloadUpdated(callback: Callback\<WebDownloadItem>): void 13862 13863下载过程中的回调，通过该回调的参数可以了解下载进度等信息。 13864 13865**系统能力：** SystemCapability.Web.Webview.Core 13866 13867**参数：** 13868 13869| 参数名 | 类型 | 必填 | 说明 | 13870| ------- | ------ | ---- | :------------- | 13871| callback | Callback\<[WebDownloadItem](#webdownloaditem11)> | 是 | 下载的回调已更新。 | 13872 13873**示例：** 13874 13875```ts 13876// xxx.ets 13877import { webview } from '@kit.ArkWeb'; 13878import { BusinessError } from '@kit.BasicServicesKit'; 13879 13880@Entry 13881@Component 13882struct WebComponent { 13883 controller: webview.WebviewController = new webview.WebviewController(); 13884 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13885 download: webview.WebDownloadItem = new webview.WebDownloadItem(); 13886 failedData: Uint8Array = new Uint8Array(); 13887 13888 build() { 13889 Column() { 13890 Button('setDownloadDelegate') 13891 .onClick(() => { 13892 try { 13893 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13894 console.log("will start a download."); 13895 // 传入一个下载路径，并开始下载。 13896 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13897 }) 13898 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 13899 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 13900 this.download = webDownloadItem; 13901 }) 13902 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 13903 console.log("download failed guid: " + webDownloadItem.getGuid()); 13904 // 序列化失败的下载到一个字节数组。 13905 this.failedData = webDownloadItem.serialize(); 13906 }) 13907 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 13908 console.log("download finish guid: " + webDownloadItem.getGuid()); 13909 }) 13910 this.controller.setDownloadDelegate(this.delegate); 13911 } catch (error) { 13912 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13913 } 13914 }) 13915 Button('startDownload') 13916 .onClick(() => { 13917 try { 13918 this.controller.startDownload('https://www.example.com'); 13919 } catch (error) { 13920 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13921 } 13922 }) 13923 Button('resumeDownload') 13924 .onClick(() => { 13925 try { 13926 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 13927 } catch (error) { 13928 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13929 } 13930 }) 13931 Button('cancel') 13932 .onClick(() => { 13933 try { 13934 this.download.cancel(); 13935 } catch (error) { 13936 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13937 } 13938 }) 13939 Button('pause') 13940 .onClick(() => { 13941 try { 13942 this.download.pause(); 13943 } catch (error) { 13944 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13945 } 13946 }) 13947 Button('resume') 13948 .onClick(() => { 13949 try { 13950 this.download.resume(); 13951 } catch (error) { 13952 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 13953 } 13954 }) 13955 Web({ src: 'www.example.com', controller: this.controller }) 13956 } 13957 } 13958} 13959``` 13960 13961### onDownloadFinish<sup>11+</sup> 13962 13963onDownloadFinish(callback: Callback\<WebDownloadItem>): void 13964 13965下载完成的通知。 13966 13967**系统能力：** SystemCapability.Web.Webview.Core 13968 13969**参数：** 13970 13971| 参数名 | 类型 | 必填 | 说明 | 13972| ------- | ------ | ---- | :------------- | 13973| callback | Callback\<[WebDownloadItem](#webdownloaditem11)> | 是 | 下载的回调已完成。 | 13974 13975**示例：** 13976 13977```ts 13978// xxx.ets 13979import { webview } from '@kit.ArkWeb'; 13980import { BusinessError } from '@kit.BasicServicesKit'; 13981 13982@Entry 13983@Component 13984struct WebComponent { 13985 controller: webview.WebviewController = new webview.WebviewController(); 13986 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 13987 download: webview.WebDownloadItem = new webview.WebDownloadItem(); 13988 failedData: Uint8Array = new Uint8Array(); 13989 13990 build() { 13991 Column() { 13992 Button('setDownloadDelegate') 13993 .onClick(() => { 13994 try { 13995 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 13996 console.log("will start a download."); 13997 // 传入一个下载路径，并开始下载。 13998 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 13999 }) 14000 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 14001 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 14002 this.download = webDownloadItem; 14003 }) 14004 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 14005 console.log("download failed guid: " + webDownloadItem.getGuid()); 14006 // 序列化失败的下载到一个字节数组。 14007 this.failedData = webDownloadItem.serialize(); 14008 }) 14009 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 14010 console.log("download finish guid: " + webDownloadItem.getGuid()); 14011 }) 14012 this.controller.setDownloadDelegate(this.delegate); 14013 } catch (error) { 14014 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14015 } 14016 }) 14017 Button('startDownload') 14018 .onClick(() => { 14019 try { 14020 this.controller.startDownload('https://www.example.com'); 14021 } catch (error) { 14022 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14023 } 14024 }) 14025 Button('resumeDownload') 14026 .onClick(() => { 14027 try { 14028 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 14029 } catch (error) { 14030 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14031 } 14032 }) 14033 Button('cancel') 14034 .onClick(() => { 14035 try { 14036 this.download.cancel(); 14037 } catch (error) { 14038 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14039 } 14040 }) 14041 Button('pause') 14042 .onClick(() => { 14043 try { 14044 this.download.pause(); 14045 } catch (error) { 14046 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14047 } 14048 }) 14049 Button('resume') 14050 .onClick(() => { 14051 try { 14052 this.download.resume(); 14053 } catch (error) { 14054 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14055 } 14056 }) 14057 Web({ src: 'www.example.com', controller: this.controller }) 14058 } 14059 } 14060} 14061``` 14062 14063### onDownloadFailed<sup>11+</sup> 14064 14065onDownloadFailed(callback: Callback\<WebDownloadItem>): void 14066 14067下载失败的通知。 14068 14069**系统能力：** SystemCapability.Web.Webview.Core 14070 14071**参数：** 14072 14073| 参数名 | 类型 | 必填 | 说明 | 14074| ------- | ------ | ---- | :------------- | 14075| callback | Callback\<[WebDownloadItem](#webdownloaditem11)> | 是 | 下载回调失败。 | 14076 14077**示例：** 14078 14079```ts 14080// xxx.ets 14081import { webview } from '@kit.ArkWeb'; 14082import { BusinessError } from '@kit.BasicServicesKit'; 14083 14084@Entry 14085@Component 14086struct WebComponent { 14087 controller: webview.WebviewController = new webview.WebviewController(); 14088 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 14089 download: webview.WebDownloadItem = new webview.WebDownloadItem(); 14090 failedData: Uint8Array = new Uint8Array(); 14091 14092 build() { 14093 Column() { 14094 Button('setDownloadDelegate') 14095 .onClick(() => { 14096 try { 14097 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 14098 console.log("will start a download."); 14099 // 传入一个下载路径，并开始下载。 14100 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 14101 }) 14102 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 14103 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 14104 this.download = webDownloadItem; 14105 }) 14106 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 14107 console.log("download failed guid: " + webDownloadItem.getGuid()); 14108 // 序列化失败的下载到一个字节数组。 14109 this.failedData = webDownloadItem.serialize(); 14110 }) 14111 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 14112 console.log("download finish guid: " + webDownloadItem.getGuid()); 14113 }) 14114 this.controller.setDownloadDelegate(this.delegate); 14115 } catch (error) { 14116 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14117 } 14118 }) 14119 Button('startDownload') 14120 .onClick(() => { 14121 try { 14122 this.controller.startDownload('https://www.example.com'); 14123 } catch (error) { 14124 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14125 } 14126 }) 14127 Button('resumeDownload') 14128 .onClick(() => { 14129 try { 14130 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 14131 } catch (error) { 14132 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14133 } 14134 }) 14135 Button('cancel') 14136 .onClick(() => { 14137 try { 14138 this.download.cancel(); 14139 } catch (error) { 14140 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14141 } 14142 }) 14143 Button('pause') 14144 .onClick(() => { 14145 try { 14146 this.download.pause(); 14147 } catch (error) { 14148 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14149 } 14150 }) 14151 Button('resume') 14152 .onClick(() => { 14153 try { 14154 this.download.resume(); 14155 } catch (error) { 14156 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14157 } 14158 }) 14159 Web({ src: 'www.example.com', controller: this.controller }) 14160 } 14161 } 14162} 14163``` 14164 14165## WebDownloadManager<sup>11+</sup> 14166 14167可以通过该类提供的接口来恢复失败的下载任务。 14168 14169### setDownloadDelegate<sup>11+</sup> 14170 14171static setDownloadDelegate(delegate: WebDownloadDelegate): void 14172 14173设置用于接收从WebDownloadManager触发的下载进度的委托。 14174 14175**系统能力：** SystemCapability.Web.Webview.Core 14176 14177**参数：** 14178 14179| 参数名 | 类型 | 必填 | 说明 | 14180| ---------------| ------- | ---- | ------------- | 14181| delegate | [WebDownloadDelegate](#webdownloaddelegate11) | 是 | 用来接收下载进回调的委托。 | 14182 14183**示例：** 14184 14185```ts 14186// xxx.ets 14187import { webview } from '@kit.ArkWeb'; 14188import { BusinessError } from '@kit.BasicServicesKit'; 14189 14190@Entry 14191@Component 14192struct WebComponent { 14193 controller: webview.WebviewController = new webview.WebviewController(); 14194 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 14195 download: webview.WebDownloadItem = new webview.WebDownloadItem(); 14196 failedData: Uint8Array = new Uint8Array(); 14197 14198 build() { 14199 Column() { 14200 Button('setDownloadDelegate') 14201 .onClick(() => { 14202 try { 14203 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 14204 console.log("will start a download."); 14205 // 传入一个下载路径，并开始下载。 14206 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 14207 }) 14208 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 14209 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 14210 this.download = webDownloadItem; 14211 }) 14212 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 14213 console.log("download failed guid: " + webDownloadItem.getGuid()); 14214 // 序列化失败的下载到一个字节数组。 14215 this.failedData = webDownloadItem.serialize(); 14216 }) 14217 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 14218 console.log("download finish guid: " + webDownloadItem.getGuid()); 14219 }) 14220 this.controller.setDownloadDelegate(this.delegate); 14221 webview.WebDownloadManager.setDownloadDelegate(this.delegate); 14222 } catch (error) { 14223 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14224 } 14225 }) 14226 Button('startDownload') 14227 .onClick(() => { 14228 try { 14229 this.controller.startDownload('https://www.example.com'); 14230 } catch (error) { 14231 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14232 } 14233 }) 14234 Button('resumeDownload') 14235 .onClick(() => { 14236 try { 14237 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 14238 } catch (error) { 14239 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14240 } 14241 }) 14242 Button('cancel') 14243 .onClick(() => { 14244 try { 14245 this.download.cancel(); 14246 } catch (error) { 14247 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14248 } 14249 }) 14250 Button('pause') 14251 .onClick(() => { 14252 try { 14253 this.download.pause(); 14254 } catch (error) { 14255 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14256 } 14257 }) 14258 Button('resume') 14259 .onClick(() => { 14260 try { 14261 this.download.resume(); 14262 } catch (error) { 14263 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14264 } 14265 }) 14266 Web({ src: 'www.example.com', controller: this.controller }) 14267 } 14268 } 14269} 14270``` 14271 14272### resumeDownload<sup>11+</sup> 14273 14274static resumeDownload(webDownloadItem: WebDownloadItem): void 14275 14276恢复一个失败的下载任务。 14277 14278**系统能力：** SystemCapability.Web.Webview.Core 14279 14280**参数：** 14281 14282| 参数名 | 类型 | 必填 | 说明 | 14283| ---------------| ------- | ---- | ------------- | 14284| webDownloadItem | [WebDownloadItem](#webdownloaditem11) | 是 | 待恢复的下载任务。 | 14285 14286**错误码：** 14287 14288以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 14289 14290| 错误码ID | 错误信息 | 14291| -------- | ------------------------------------- | 14292| 17100018 | No WebDownloadDelegate has been set yet. | 14293 14294**示例：** 14295 14296```ts 14297// xxx.ets 14298import { webview } from '@kit.ArkWeb'; 14299import { BusinessError } from '@kit.BasicServicesKit'; 14300 14301@Entry 14302@Component 14303struct WebComponent { 14304 controller: webview.WebviewController = new webview.WebviewController(); 14305 delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate(); 14306 download: webview.WebDownloadItem = new webview.WebDownloadItem(); 14307 failedData: Uint8Array = new Uint8Array(); 14308 14309 build() { 14310 Column() { 14311 Button('setDownloadDelegate') 14312 .onClick(() => { 14313 try { 14314 this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => { 14315 console.log("will start a download."); 14316 // 传入一个下载路径，并开始下载。 14317 webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName()); 14318 }) 14319 this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => { 14320 console.log("download update percent complete: " + webDownloadItem.getPercentComplete()); 14321 this.download = webDownloadItem; 14322 }) 14323 this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => { 14324 console.log("download failed guid: " + webDownloadItem.getGuid()); 14325 // 序列化失败的下载到一个字节数组。 14326 this.failedData = webDownloadItem.serialize(); 14327 }) 14328 this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => { 14329 console.log("download finish guid: " + webDownloadItem.getGuid()); 14330 }) 14331 this.controller.setDownloadDelegate(this.delegate); 14332 webview.WebDownloadManager.setDownloadDelegate(this.delegate); 14333 } catch (error) { 14334 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14335 } 14336 }) 14337 Button('startDownload') 14338 .onClick(() => { 14339 try { 14340 this.controller.startDownload('https://www.example.com'); 14341 } catch (error) { 14342 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14343 } 14344 }) 14345 Button('resumeDownload') 14346 .onClick(() => { 14347 try { 14348 webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData)); 14349 } catch (error) { 14350 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14351 } 14352 }) 14353 Button('cancel') 14354 .onClick(() => { 14355 try { 14356 this.download.cancel(); 14357 } catch (error) { 14358 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14359 } 14360 }) 14361 Button('pause') 14362 .onClick(() => { 14363 try { 14364 this.download.pause(); 14365 } catch (error) { 14366 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14367 } 14368 }) 14369 Button('resume') 14370 .onClick(() => { 14371 try { 14372 this.download.resume(); 14373 } catch (error) { 14374 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14375 } 14376 }) 14377 Web({ src: 'www.example.com', controller: this.controller }) 14378 } 14379 } 14380} 14381``` 14382 14383## ProxySchemeFilter<sup>15+</sup> 14384 14385使用代理的请求的scheme信息。 14386 14387**系统能力：** SystemCapability.Web.Webview.Core 14388 14389| 名称 | 值 | 说明 | 14390| ------------- | -- |----------------------------------------- | 14391| MATCH_ALL_SCHEMES | 0 |所有的scheme都会使用代理。| 14392| MATCH_HTTP | 1 |HTTP请求会使用代理。| 14393| MATCH_HTTPS | 2 |HTTPS请求会使用代理。| 14394 14395## ProxyConfig<sup>15+</sup> 14396 14397可以通过该类提供的接口对代理进行配置。 14398 14399### insertProxyRule<sup>15+</sup> 14400 14401insertProxyRule(proxyRule: string, schemeFilter?: ProxySchemeFilter): void 14402 14403插入一条代理规则，与schemeFilter匹配的URL都会使用指定代理。如果schemeFilter为空，所有URL都将使用指定代理。 14404 14405**系统能力：** SystemCapability.Web.Webview.Core 14406 14407**参数：** 14408 14409| 参数名 | 类型 | 必填 | 说明 | 14410| ---------------| ------- | ---- | ------------- | 14411| proxyRule | string | 是 | URL要使用的代理。 | 14412| schemeFilter | [ProxySchemeFilter](#proxyschemefilter15) | 否 | 与schemeFilter匹配的URL会使用代理。默认值：MATCH_ALL_SCHEMES | 14413 14414**错误码：** 14415 14416以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)说明文档。 14417 14418| 错误码ID | 错误信息 | 14419| -------- | ------------------------------------- | 14420| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 14421 14422**示例：** 14423 14424完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14425 14426### insertDirectRule<sup>15+</sup> 14427 14428insertDirectRule(schemeFilter?: ProxySchemeFilter): void 14429 14430插入一条代理规则，指明符合schemeFilter条件的URL将直接连接到服务器。 14431 14432**系统能力：** SystemCapability.Web.Webview.Core 14433 14434**参数：** 14435 14436| 参数名 | 类型 | 必填 | 说明 | 14437| ---------------| ------- | ---- | ------------- | 14438| schemeFilter | [ProxySchemeFilter](#proxyschemefilter15) | 否 | 与schemeFilter匹配的URL会直接与服务器相连。默认值：MATCH_ALL_SCHEMES | 14439 14440**错误码：** 14441 14442以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)说明文档。 14443 14444| 错误码ID | 错误信息 | 14445| -------- | ------------------------------------- | 14446| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 14447 14448**示例：** 14449 14450完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14451 14452### insertBypassRule<sup>15+</sup> 14453 14454insertBypassRule(bypassRule: string): void 14455 14456插入一条bypass规则，指明哪些URL应该绕过代理并直接连接到服务器。 14457 14458**系统能力：** SystemCapability.Web.Webview.Core 14459 14460**参数：** 14461 14462| 参数名 | 类型 | 必填 | 说明 | 14463| ---------------| ------- | ---- | ------------- | 14464| bypassRule | string | 是 | 与bypassRule匹配的URL会绕过代理。 | 14465 14466**错误码：** 14467 14468以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)说明文档。 14469 14470| 错误码ID | 错误信息 | 14471| -------- | ------------------------------------- | 14472| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 14473 14474**示例：** 14475 14476完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14477 14478### bypassHostnamesWithoutPeriod<sup>15+</sup> 14479 14480bypassHostnamesWithoutPeriod(): void 14481 14482没有点字符的域名将跳过代理并直接连接到服务器。 14483 14484**系统能力：** SystemCapability.Web.Webview.Core 14485 14486**示例：** 14487 14488完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14489 14490### clearImplicitRules<sup>15+</sup> 14491 14492clearImplicitRules(): void 14493 14494默认情况下，如果某些主机名是本地IP地址或localhost地址，它们会绕过代理。调用此函数以覆盖默认行为，并强制将localhost或本地IP地址通过代理发送。 14495 14496**系统能力：** SystemCapability.Web.Webview.Core 14497 14498**示例：** 14499 14500完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14501 14502### enableReverseBypass<sup>15+</sup> 14503 14504enableReverseBypass(reverse: boolean): void 14505 14506反转bypass规则。 14507 14508**系统能力：** SystemCapability.Web.Webview.Core 14509 14510**参数：** 14511 14512| 参数名 | 类型 | 必填 | 说明 | 14513| ---------------| ------- | ---- | ------------- | 14514| reverse | boolean | 是 | 参数值默认是false，表示与[insertBypassRule](#insertbypassrule15)中的bypassRule匹配的URL会绕过代理，参数值为true时，表示与[insertBypassRule](#insertbypassrule15)中的bypassRule匹配的URL会使用代理。 | 14515 14516**错误码：** 14517 14518以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)说明文档。 14519 14520| 错误码ID | 错误信息 | 14521| -------- | ------------------------------------- | 14522| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 14523 14524**示例：** 14525 14526完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14527 14528### getBypassRules<sup>15+</sup> 14529 14530getBypassRules(): Array\<string\> 14531 14532获取不使用代理的URL列表。 14533 14534**系统能力：** SystemCapability.Web.Webview.Core 14535 14536**返回值：** 14537 14538| 类型 | 说明 | 14539| ------ | ------------------------- | 14540| Array\<string\> | 不使用代理的URL列表。 | 14541 14542**示例：** 14543 14544完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14545 14546### getProxyRules<sup>15+</sup> 14547 14548getProxyRules(): Array\<ProxyRule\> 14549 14550获取代理规则。 14551 14552**系统能力：** SystemCapability.Web.Webview.Core 14553 14554**返回值：** 14555 14556| 类型 | 说明 | 14557| ------ | ------------------------- | 14558| Array\<[ProxyRule](#proxyrule15)\> | 代理规则。 | 14559 14560**示例：** 14561 14562完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14563 14564### isReverseBypassEnabled<sup>15+</sup> 14565 14566isReverseBypassEnabled(): boolean 14567 14568获取[enableReverseBypass](#enablereversebypass15)的参数值，详见[enableReverseBypass](#enablereversebypass15)。 14569 14570**系统能力：** SystemCapability.Web.Webview.Core 14571 14572**返回值：** 14573 14574| 类型 | 说明 | 14575| ------ | ------------------------- | 14576| boolean | [enableReverseBypass](#enablereversebypass15)的参数值。参数值为false，表示与[insertBypassRule](#insertbypassrule15)中的bypassRule匹配的URL会绕过代理，参数值为true时，表示与[insertBypassRule](#insertbypassrule15)中的bypassRule匹配的URL会使用代理。 | 14577 14578**示例：** 14579 14580完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14581 14582 14583## ProxyRule<sup>15+</sup> 14584 14585[insertProxyRule](#insertproxyrule15)中使用的代理规则。 14586 14587### getSchemeFilter<sup>15+</sup> 14588 14589getSchemeFilter(): ProxySchemeFilter 14590 14591获取代理规则中的[ProxySchemeFilter](#proxyschemefilter15)信息。 14592 14593**系统能力：** SystemCapability.Web.Webview.Core 14594 14595**返回值：** 14596 14597| 类型 | 说明 | 14598| ------ | ------------------------- | 14599| [ProxySchemeFilter](#proxyschemefilter15) | 代理规则中的[ProxySchemeFilter](#proxyschemefilter15)信息。 | 14600 14601**示例：** 14602 14603完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14604 14605### getUrl<sup>15+</sup> 14606 14607getUrl(): string 14608 14609获取代理规则中的代理的URL信息。 14610 14611**系统能力：** SystemCapability.Web.Webview.Core 14612 14613**返回值：** 14614 14615| 类型 | 说明 | 14616| ------ | ------------------------- | 14617| string | 代理规则中的代理的Url信息。 | 14618 14619**示例：** 14620 14621完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14622 14623## OnProxyConfigChangeCallback<sup>15+</sup> 14624 14625type OnProxyConfigChangeCallback = () => void 14626 14627回调函数，回调成功表示代理设置成功。 14628 14629**系统能力：** SystemCapability.Web.Webview.Core 14630 14631**示例：** 14632 14633完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14634 14635## ProxyController<sup>15+</sup> 14636 14637此类用于为应用程序设置代理。 14638 14639### applyProxyOverride<sup>15+</sup> 14640 14641static applyProxyOverride(proxyConfig: ProxyConfig, callback: OnProxyConfigChangeCallback): void 14642 14643设置应用中所有Web使用的代理配置，与[insertBypassRule](#insertbypassrule15)中插入的bypass规则匹配的URL将不会使用代理，而是直接向URL指定的源地址发起请求。代理设置成功后，不保证网络连接后会立即使用新的代理设置，在加载页面之前请等待监听器触发，这个监听器将在UI线程上被调用。 14644 14645**系统能力：** SystemCapability.Web.Webview.Core 14646 14647**参数：** 14648 14649| 参数名 | 类型 | 必填 | 说明 | 14650| ---------------| ------- | ---- | ------------- | 14651| proxyConfig | [ProxyConfig](#proxyconfig15) | 是 | 对代理的配置。 | 14652| callback | [OnProxyConfigChangeCallback](#onproxyconfigchangecallback15) | 是 | 代理设置成功的回调。 | 14653 14654**错误码：** 14655 14656以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)说明文档。 14657 14658| 错误码ID | 错误信息 | 14659| -------- | ------------------------------------- | 14660| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 14661 14662**示例：** 14663 14664完整示例代码参考[removeProxyOverride](#removeproxyoverride15)。 14665 14666### removeProxyOverride<sup>15+</sup> 14667 14668static removeProxyOverride(callback: OnProxyConfigChangeCallback): void 14669 14670移除代理配置。移除代理配置后，不保证网络连接后会立即使用新的代理设置，在加载页面之前等待监听器，这个监听器将在UI线程上被调用。 14671 14672**系统能力：** SystemCapability.Web.Webview.Core 14673 14674**参数：** 14675 14676| 参数名 | 类型 | 必填 | 说明 | 14677| ---------------| ------- | ---- | ------------- | 14678| callback | [OnProxyConfigChangeCallback](#onproxyconfigchangecallback15) | 是 | 代理设置成功的回调。 | 14679 14680**错误码：** 14681 14682以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)说明文档。 14683 14684| 错误码ID | 错误信息 | 14685| -------- | ------------------------------------- | 14686| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 14687 14688**示例：** 14689 14690```ts 14691// xxx.ets 14692import { webview } from '@kit.ArkWeb'; 14693import { BusinessError } from '@kit.BasicServicesKit'; 14694 14695@Entry 14696@Component 14697struct WebComponent { 14698 controller: webview.WebviewController = new webview.WebviewController(); 14699 proxyRules: webview.ProxyRule[] = []; 14700 14701 build() { 14702 Row() { 14703 Column() { 14704 Button("applyProxyOverride").onClick(()=>{ 14705 let proxyConfig:webview.ProxyConfig = new webview.ProxyConfig(); 14706 //优先使用第一个代理配置https://proxy.XXX.com 14707 //代理失败后会回落到直连服务器insertDirectRule 14708 try { 14709 proxyConfig.insertProxyRule("https://proxy.XXX.com", webview.ProxySchemeFilter.MATCH_ALL_SCHEMES); 14710 } catch (error) { 14711 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14712 } 14713 try { 14714 proxyConfig.insertDirectRule(webview.ProxySchemeFilter.MATCH_HTTP); 14715 } catch (error) { 14716 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14717 } 14718 try { 14719 proxyConfig.insertBypassRule("*.example.com"); 14720 } catch (error) { 14721 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14722 } 14723 proxyConfig.clearImplicitRules(); 14724 proxyConfig.bypassHostnamesWithoutPeriod(); 14725 try { 14726 proxyConfig.enableReverseBypass(true); 14727 } catch (error) { 14728 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14729 } 14730 let bypassRules = proxyConfig.getBypassRules(); 14731 for (let i = 0; i < bypassRules.length; i++) { 14732 console.log("bypassRules: " + bypassRules[i]); 14733 } 14734 this.proxyRules = proxyConfig.getProxyRules(); 14735 for (let i = 0; i < this.proxyRules.length; i++) { 14736 console.log("SchemeFiletr: " + this.proxyRules[i].getSchemeFilter()); 14737 console.log("Url: " + this.proxyRules[i].getUrl()); 14738 } 14739 let isReverseBypassRule = proxyConfig.isReverseBypassEnabled(); 14740 console.log("isReverseBypassRules: " + isReverseBypassRule); 14741 try { 14742 webview.ProxyController.applyProxyOverride(proxyConfig, () => { 14743 console.log("PROXYCONTROLLER proxy changed"); 14744 }); 14745 } catch (error) { 14746 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14747 } 14748 }) 14749 Button("loadUrl-https").onClick(()=>{ 14750 this.controller.loadUrl("https://www.example.com") 14751 }) 14752 Button("loadUrl-http").onClick(()=>{ 14753 this.controller.loadUrl("http://www.example.com") 14754 }) 14755 Button("removeProxyOverride").onClick(()=>{ 14756 try { 14757 webview.ProxyController.removeProxyOverride(() => { 14758 console.log("PROXYCONTROLLER proxy changed"); 14759 }); 14760 } catch (error) { 14761 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14762 } 14763 }) 14764 Web({ src: 'www.example.com', controller: this.controller}) 14765 } 14766 .width('100%') 14767 } 14768 .height('100%') 14769 } 14770} 14771 14772``` 14773 14774## WebHttpBodyStream<sup>12+</sup> 14775 14776POST、PUT请求的数据体，支持BYTES、FILE、BLOB、CHUNKED类型的数据。注意本类中其他接口需要在[initialize](#initialize12)成功后才能调用。 14777 14778### initialize<sup>12+</sup> 14779 14780initialize(): Promise\<void\> 14781 14782初始化WebHttpBodyStream。 14783 14784**系统能力：** SystemCapability.Web.Webview.Core 14785 14786**返回值：** 14787 14788| 类型 | 说明 | 14789| ------ | ------------------------- | 14790| Promise\<void\> | Promise实例，用于获取WebHttpBodyStream是否初始化成功。 | 14791 14792**错误码：** 14793 14794以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 14795 14796| 错误码ID | 错误信息 | 14797| -------- | ------------------------------------- | 14798| 17100022 | Failed to initialize the HTTP body stream. | 14799 14800**示例：** 14801 14802```ts 14803// xxx.ets 14804import { webview } from '@kit.ArkWeb'; 14805import { BusinessError } from '@kit.BasicServicesKit'; 14806import { buffer } from '@kit.ArkTS'; 14807import { WebNetErrorList } from '@ohos.web.netErrorList' 14808 14809@Entry 14810@Component 14811struct WebComponent { 14812 controller: webview.WebviewController = new webview.WebviewController(); 14813 schemeHandler: webview.WebSchemeHandler = new webview.WebSchemeHandler(); 14814 htmlData: string = "<html><body bgcolor=\"white\">Source:<pre>source</pre></body></html>"; 14815 14816 build() { 14817 Column() { 14818 Button('postUrl') 14819 .onClick(() => { 14820 try { 14821 let postData = buffer.from(this.htmlData); 14822 this.controller.postUrl('https://www.example.com', postData.buffer); 14823 } catch (error) { 14824 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14825 } 14826 }) 14827 Web({ src: 'https://www.example.com', controller: this.controller }) 14828 .onControllerAttached(() => { 14829 try { 14830 this.schemeHandler.onRequestStart((request: webview.WebSchemeHandlerRequest, resourceHandler: webview.WebResourceHandler) => { 14831 console.log("[schemeHandler] onRequestStart"); 14832 try { 14833 let stream = request.getHttpBodyStream(); 14834 if (stream) { 14835 stream.initialize().then(() => { 14836 if (!stream) { 14837 return; 14838 } 14839 console.log("[schemeHandler] onRequestStart postDataStream size:" + stream.getSize()); 14840 console.log("[schemeHandler] onRequestStart postDataStream position:" + stream.getPosition()); 14841 console.log("[schemeHandler] onRequestStart postDataStream isChunked:" + stream.isChunked()); 14842 console.log("[schemeHandler] onRequestStart postDataStream isEof:" + stream.isEof()); 14843 console.log("[schemeHandler] onRequestStart postDataStream isInMemory:" + stream.isInMemory()); 14844 stream.read(stream.getSize()).then((buffer) => { 14845 if (!stream) { 14846 return; 14847 } 14848 console.log("[schemeHandler] onRequestStart postDataStream readlength:" + buffer.byteLength); 14849 console.log("[schemeHandler] onRequestStart postDataStream isEof:" + stream.isEof()); 14850 console.log("[schemeHandler] onRequestStart postDataStream position:" + stream.getPosition()); 14851 }).catch((error: BusinessError) => { 14852 console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); 14853 }) 14854 }).catch((error: BusinessError) => { 14855 console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); 14856 }) 14857 } else { 14858 console.log("[schemeHandler] onRequestStart has no http body stream"); 14859 } 14860 } catch (error) { 14861 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14862 } 14863 14864 return false; 14865 }) 14866 14867 this.schemeHandler.onRequestStop((request: webview.WebSchemeHandlerRequest) => { 14868 console.log("[schemeHandler] onRequestStop"); 14869 }); 14870 14871 this.controller.setWebSchemeHandler('https', this.schemeHandler); 14872 } catch (error) { 14873 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 14874 } 14875 }) 14876 .javaScriptAccess(true) 14877 .domStorageAccess(true) 14878 } 14879 } 14880} 14881 14882``` 14883 14884### read<sup>12+</sup> 14885 14886read(size: number): Promise\<ArrayBuffer\> 14887 14888读取WebHttpBodyStream中的数据。 14889 14890**系统能力：** SystemCapability.Web.Webview.Core 14891 14892**参数：** 14893 14894| 参数名 | 类型 | 必填 | 说明 | 14895| --------| ------- | ---- | ---------------------------| 14896| size | number | 是 | 读取WebHttpBodyStream中的字节数。 | 14897 14898**返回值：** 14899 14900| 类型 | 说明 | 14901| ------ | ------------------------- | 14902| Promise\<ArrayBuffer\> | Promise实例，用于获取WebHttpBodyStream中读取的数据。 | 14903 14904**错误码：** 14905 14906以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 14907 14908| 错误码ID | 错误信息 | 14909| -------- | ------------------------------------- | 14910| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 14911 14912**示例：** 14913 14914完整示例代码参考[initialize](#initialize12)。 14915 14916### getSize<sup>12+</sup> 14917 14918getSize(): number 14919 14920获取WebHttpBodyStream中的数据大小，分块传输时总是返回零。 14921 14922**系统能力：** SystemCapability.Web.Webview.Core 14923 14924**返回值：** 14925 14926| 类型 | 说明 | 14927| ------ | ------------------------- | 14928| number | 获取WebHttpBodyStream中的数据大小。 | 14929 14930**示例：** 14931 14932完整示例代码参考[initialize](#initialize12)。 14933 14934### getPosition<sup>12+</sup> 14935 14936getPosition(): number 14937 14938读取WebHttpBodyStream中当前的读取位置。 14939 14940**系统能力：** SystemCapability.Web.Webview.Core 14941 14942**返回值：** 14943 14944| 类型 | 说明 | 14945| ------ | ------------------------- | 14946| number | WebHttpBodyStream中当前的读取位置。 | 14947 14948**示例：** 14949 14950完整示例代码参考[initialize](#initialize12)。 14951 14952### isChunked<sup>12+</sup> 14953 14954isChunked(): boolean 14955 14956WebHttpBodyStream是否采用分块传输。 14957 14958**系统能力：** SystemCapability.Web.Webview.Core 14959 14960**返回值：** 14961 14962| 类型 | 说明 | 14963| ------ | ------------------------- | 14964| boolean | WebHttpBodyStream是否采用分块传输。 | 14965 14966**示例：** 14967 14968完整示例代码参考[initialize](#initialize12)。 14969 14970### isEof<sup>12+</sup> 14971 14972isEof(): boolean 14973 14974判断WebHttpBodyStream中的所有数据是否都已被读取。如果所有数据都已被读取，则返回true。对于分块传输类型的 WebHttpBodyStream，在第一次读取尝试之前返回false。 14975 14976**系统能力：** SystemCapability.Web.Webview.Core 14977 14978**返回值：** 14979 14980| 类型 | 说明 | 14981| ------ | ------------------------- | 14982| boolean | WebHttpBodyStream中的所有数据是否都已被读取。 | 14983 14984**示例：** 14985 14986完整示例代码参考[initialize](#initialize12)。 14987 14988### isInMemory<sup>12+</sup> 14989 14990isInMemory(): boolean 14991 14992判断WebHttpBodyStream中的上传数据是否在内存中。如果WebHttpBodyStream中的上传数据完全在内存中，并且所有读取请求都将同步成功，则返回true。对于分块传输类型的数据，预期返回false。 14993 14994**系统能力：** SystemCapability.Web.Webview.Core 14995 14996**返回值：** 14997 14998| 类型 | 说明 | 14999| ------ | ------------------------- | 15000| boolean | WebHttpBodyStream中的上传数据是否在内存中。 | 15001 15002**示例：** 15003 15004完整示例代码参考[initialize](#initialize12)。 15005 15006## WebSchemeHandlerRequest<sup>12+</sup> 15007 15008通过WebSchemeHandler拦截到的请求。 15009 15010### getHeader<sup>12+</sup> 15011 15012getHeader(): Array\<WebHeader\> 15013 15014获取资源请求头信息。 15015 15016**系统能力：** SystemCapability.Web.Webview.Core 15017 15018**返回值：** 15019 15020| 类型 | 说明 | 15021| -------------------------- | ---------- | 15022| Array\<[WebHeader](#webheader)\> | 返回资源请求头信息。 | 15023 15024**示例：** 15025 15026完整示例代码参考[onRequestStart](#onrequeststart12)。 15027 15028### getRequestUrl<sup>12+</sup> 15029 15030getRequestUrl(): string 15031 15032获取资源请求的URL信息。 15033 15034**系统能力：** SystemCapability.Web.Webview.Core 15035 15036**返回值：** 15037 15038| 类型 | 说明 | 15039| ------ | ------------- | 15040| string | 返回资源请求的URL信息。 | 15041 15042**示例：** 15043 15044完整示例代码参考[onRequestStart](#onrequeststart12)。 15045 15046### getRequestMethod<sup>12+</sup> 15047 15048getRequestMethod(): string 15049 15050获取请求方法。 15051 15052**系统能力：** SystemCapability.Web.Webview.Core 15053 15054**返回值：** 15055 15056| 类型 | 说明 | 15057| ------ | ------------- | 15058| string | 返回请求方法。 | 15059 15060**示例：** 15061 15062完整示例代码参考[onRequestStart](#onrequeststart12)。 15063 15064### getReferrer<sup>12+</sup> 15065 15066getReferrer(): string 15067 15068获取referrer。 15069 15070**系统能力：** SystemCapability.Web.Webview.Core 15071 15072**返回值：** 15073 15074| 类型 | 说明 | 15075| ------ | ------------- | 15076| string | 获取到的referrer。 | 15077 15078**示例：** 15079 15080完整示例代码参考[onRequestStart](#onrequeststart12)。 15081 15082### isMainFrame<sup>12+</sup> 15083 15084isMainFrame(): boolean 15085 15086判断资源请求是否为主frame。 15087 15088**系统能力：** SystemCapability.Web.Webview.Core 15089 15090**返回值：** 15091 15092| 类型 | 说明 | 15093| ------ | ------------- | 15094| boolean | 判断资源请求是否为主frame。 | 15095 15096**示例：** 15097 15098完整示例代码参考[onRequestStart](#onrequeststart12)。 15099 15100### hasGesture<sup>12+</sup> 15101 15102hasGesture(): boolean 15103 15104获取资源请求是否与手势（如点击）相关联。 15105 15106**系统能力：** SystemCapability.Web.Webview.Core 15107 15108**返回值：** 15109 15110| 类型 | 说明 | 15111| ------ | ------------- | 15112| boolean | 返回资源请求是否与手势（如点击）相关联。 | 15113 15114**示例：** 15115 15116完整示例代码参考[onRequestStart](#onrequeststart12)。 15117 15118### getHttpBodyStream<sup>12+</sup> 15119 15120getHttpBodyStream(): WebHttpBodyStream | null 15121 15122获取资源请求中的WebHttpBodyStream。 15123 15124**系统能力：** SystemCapability.Web.Webview.Core 15125 15126**返回值：** 15127 15128| 类型 | 说明 | 15129| ------ | ------------- | 15130| [WebHttpBodyStream](#webhttpbodystream12) \| null | 返回资源请求中的WebHttpBodyStream，如果没有则返回null。 | 15131 15132**示例：** 15133 15134完整示例代码参考[onRequestStart](#onrequeststart12)。 15135 15136### getRequestResourceType<sup>12+</sup> 15137 15138getRequestResourceType(): WebResourceType 15139 15140获取资源请求的资源类型。 15141 15142**系统能力：** SystemCapability.Web.Webview.Core 15143 15144**返回值：** 15145 15146| 类型 | 说明 | 15147| ------ | ------------- | 15148| [WebResourceType](#webresourcetype12) | 返回资源请求的资源类型。 | 15149 15150**示例：** 15151 15152完整示例代码参考[onRequestStart](#onrequeststart12)。 15153 15154### getFrameUrl<sup>12+</sup> 15155 15156getFrameUrl(): string 15157 15158获取触发此请求的Frame的URL。 15159 15160**系统能力：** SystemCapability.Web.Webview.Core 15161 15162**返回值：** 15163 15164| 类型 | 说明 | 15165| ------ | ------------- | 15166| string | 返回触发此请求的Frame的URL。 | 15167 15168**示例：** 15169 15170完整示例代码参考[onRequestStart](#onrequeststart12)。 15171 15172## WebSchemeHandlerResponse<sup>12+</sup> 15173 15174请求的响应，可以为被拦截的请求创建一个Response并填充自定义的内容返回给Web组件。 15175 15176### constructor<sup>12+</sup> 15177 15178constructor() 15179 15180Response的构造函数。 15181 15182**系统能力：** SystemCapability.Web.Webview.Core 15183 15184**示例：** 15185 15186```ts 15187// xxx.ets 15188import { webview } from '@kit.ArkWeb'; 15189import { BusinessError } from '@kit.BasicServicesKit'; 15190import { WebNetErrorList } from '@ohos.web.netErrorList'; 15191 15192@Entry 15193@Component 15194struct WebComponent { 15195 controller: webview.WebviewController = new webview.WebviewController(); 15196 schemeHandler: webview.WebSchemeHandler = new webview.WebSchemeHandler(); 15197 15198 build() { 15199 Column() { 15200 Button('response').onClick(() => { 15201 let response = new webview.WebSchemeHandlerResponse(); 15202 try { 15203 response.setUrl("http://www.example.com") 15204 response.setStatus(200) 15205 response.setStatusText("OK") 15206 response.setMimeType("text/html") 15207 response.setEncoding("utf-8") 15208 response.setHeaderByName("header1", "value1", false) 15209 response.setNetErrorCode(WebNetErrorList.NET_OK) 15210 console.log("[schemeHandler] getUrl:" + response.getUrl()) 15211 console.log("[schemeHandler] getStatus:" + response.getStatus()) 15212 console.log("[schemeHandler] getStatusText:" + response.getStatusText()) 15213 console.log("[schemeHandler] getMimeType:" + response.getMimeType()) 15214 console.log("[schemeHandler] getEncoding:" + response.getEncoding()) 15215 console.log("[schemeHandler] getHeaderByValue:" + response.getHeaderByName("header1")) 15216 console.log("[schemeHandler] getNetErrorCode:" + response.getNetErrorCode()) 15217 15218 } catch (error) { 15219 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 15220 } 15221 }) 15222 Web({ src: 'https://www.example.com', controller: this.controller }) 15223 } 15224 } 15225} 15226 15227``` 15228 15229### setUrl<sup>12+</sup> 15230 15231setUrl(url: string): void 15232 15233给当前的Response设置重定向或因HSTS而更改后的URL，设置了url后会触发请求的跳转。 15234 15235**系统能力：** SystemCapability.Web.Webview.Core 15236 15237**参数：** 15238 15239| 参数名 | 类型 | 必填 | 说明 | 15240| --------| ------- | ---- | ---------------------------| 15241| url | string | 是 | 即将要跳转的URL。 | 15242 15243**示例：** 15244 15245示例完整示例代码参考[constructor](#constructor12)。 15246 15247**错误码：** 15248 15249以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15250 15251| 错误码ID | 错误信息 | 15252| -------- | ----------------------- | 15253| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 15254 15255### setNetErrorCode<sup>12+</sup> 15256 15257setNetErrorCode(code: WebNetErrorList): void 15258 15259给当前的Response设置网络错误码。 15260 15261**系统能力：** SystemCapability.Web.Webview.Core 15262 15263**参数：** 15264 15265| 参数名 | 类型 | 必填 | 说明 | 15266| --------| ------- | ---- | ---------------------------| 15267| code | [WebNetErrorList](js-apis-netErrorList.md#webneterrorlist) | 是 | 网络错误码。 | 15268 15269**错误码：** 15270 15271以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15272 15273| 错误码ID | 错误信息 | 15274| -------- | ----------------------- | 15275| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 15276 15277**示例：** 15278 15279示例完整示例代码参考[constructor](#constructor12)。 15280 15281### setStatus<sup>12+</sup> 15282 15283setStatus(code: number): void 15284 15285给当前的Response设置HTTP状态码。 15286 15287**系统能力：** SystemCapability.Web.Webview.Core 15288 15289**参数：** 15290 15291| 参数名 | 类型 | 必填 | 说明 | 15292| --------| ------- | ---- | ---------------------------| 15293| code | number | 是 | Http状态码。 | 15294 15295**错误码：** 15296 15297以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15298 15299| 错误码ID | 错误信息 | 15300| -------- | ----------------------- | 15301| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 15302 15303**示例：** 15304 15305示例完整示例代码参考[constructor](#constructor12)。 15306 15307### setStatusText<sup>12+</sup> 15308 15309setStatusText(text: string): void 15310 15311给当前的Response设置状态文本。 15312 15313**系统能力：** SystemCapability.Web.Webview.Core 15314 15315**参数：** 15316 15317| 参数名 | 类型 | 必填 | 说明 | 15318| --------| ------- | ---- | ---------------------------| 15319| text | string | 是 | 状态文本。 | 15320 15321**错误码：** 15322 15323以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15324 15325| 错误码ID | 错误信息 | 15326| -------- | ----------------------- | 15327| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 15328 15329**示例：** 15330 15331示例完整示例代码参考[constructor](#constructor12)。 15332 15333### setMimeType<sup>12+</sup> 15334 15335setMimeType(type: string): void 15336 15337给当前的Response设置媒体类型。 15338 15339**系统能力：** SystemCapability.Web.Webview.Core 15340 15341**参数：** 15342 15343| 参数名 | 类型 | 必填 | 说明 | 15344| --------| ------- | ---- | ---------------------------| 15345| type | string | 是 | 媒体类型。 | 15346 15347**错误码：** 15348 15349以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15350 15351| 错误码ID | 错误信息 | 15352| -------- | ----------------------- | 15353| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 15354 15355**示例：** 15356 15357示例完整示例代码参考[constructor](#constructor12)。 15358 15359### setEncoding<sup>12+</sup> 15360 15361setEncoding(encoding: string): void 15362 15363给当前的Response设置字符集。 15364 15365**系统能力：** SystemCapability.Web.Webview.Core 15366 15367**参数：** 15368 15369| 参数名 | 类型 | 必填 | 说明 | 15370| --------| ------- | ---- | ---------------------------| 15371| encoding | string | 是 | 字符集。 | 15372 15373**错误码：** 15374 15375以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15376 15377| 错误码ID | 错误信息 | 15378| -------- | ----------------------- | 15379| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 15380 15381**示例：** 15382 15383示例完整示例代码参考[constructor](#constructor12)。 15384 15385### setHeaderByName<sup>12+</sup> 15386 15387setHeaderByName(name: string, value: string, overwrite: boolean): void 15388 15389给当前的Response设置头信息。 15390 15391**系统能力：** SystemCapability.Web.Webview.Core 15392 15393**参数：** 15394 15395| 参数名 | 类型 | 必填 | 说明 | 15396| --------| ------- | ---- | ---------------------------| 15397| name | string | 是 | 头部（header）的名称。 | 15398| value | string | 是 | 头部（header）的值。 | 15399| overwrite | boolean | 是 | 如果为true，将覆盖现有的头部，否则不覆盖。 | 15400 15401**错误码：** 15402 15403以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15404 15405| 错误码ID | 错误信息 | 15406| -------- | ----------------------- | 15407| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 15408 15409**示例：** 15410 15411示例完整示例代码参考[constructor](#constructor12)。 15412 15413### getUrl<sup>12+</sup> 15414 15415getUrl(): string 15416 15417获取重定向或由于HSTS而更改后的URL。 15418风险提示：如果想获取url来做JavascriptProxy通信接口认证，请使用[getLastJavascriptProxyCallingFrameUrl<sup>12+</sup>](#getlastjavascriptproxycallingframeurl12) 15419 15420**系统能力：** SystemCapability.Web.Webview.Core 15421 15422**返回值：** 15423 15424| 类型 | 说明 | 15425| ------- | --------------------------------------- | 15426| string | 获取经过重定向或由于HSTS而更改后的URL。| 15427 15428**示例：** 15429 15430示例完整示例代码参考[constructor](#constructor12)。 15431 15432### getNetErrorCode<sup>12+</sup> 15433 15434getNetErrorCode(): WebNetErrorList 15435 15436获取Response的网络错误码。 15437 15438**系统能力：** SystemCapability.Web.Webview.Core 15439 15440**返回值：** 15441 15442| 类型 | 说明 | 15443| ------- | --------------------------------------- | 15444| [WebNetErrorList](js-apis-netErrorList.md#webneterrorlist) | 获取Response的网络错误码。| 15445 15446**示例：** 15447 15448示例完整示例代码参考[constructor](#constructor12)。 15449 15450### getStatus<sup>12+</sup> 15451 15452getStatus(): number 15453 15454获取Response的Http状态码。 15455 15456**系统能力：** SystemCapability.Web.Webview.Core 15457 15458**返回值：** 15459 15460| 类型 | 说明 | 15461| ------- | --------------------------------------- | 15462| number | 获取Response的Http状态码。| 15463 15464**示例：** 15465 15466示例完整示例代码参考[constructor](#constructor12)。 15467 15468### getStatusText<sup>12+</sup> 15469 15470getStatusText(): string 15471 15472获取Response的状态文本。 15473 15474**系统能力：** SystemCapability.Web.Webview.Core 15475 15476**返回值：** 15477 15478| 类型 | 说明 | 15479| ------- | --------------------------------------- | 15480| string | 状态文本。| 15481 15482**示例：** 15483 15484示例完整示例代码参考[constructor](#constructor12)。 15485 15486### getMimeType<sup>12+</sup> 15487 15488getMimeType(): string 15489 15490获取Response的媒体类型。 15491 15492**系统能力：** SystemCapability.Web.Webview.Core 15493 15494**返回值：** 15495 15496| 类型 | 说明 | 15497| ------- | --------------------------------------- | 15498| string | 媒体类型。| 15499 15500**示例：** 15501 15502示例完整示例代码参考[constructor](#constructor12)。 15503 15504### getEncoding<sup>12+</sup> 15505 15506getEncoding(): string 15507 15508获取Response的字符集。 15509 15510**系统能力：** SystemCapability.Web.Webview.Core 15511 15512**返回值：** 15513 15514| 类型 | 说明 | 15515| ------- | --------------------------------------- | 15516| string | 字符集。| 15517 15518**示例：** 15519 15520示例完整示例代码参考[constructor](#constructor12)。 15521 15522### getHeaderByName<sup>12+</sup> 15523 15524getHeaderByName(name: string): string 15525 15526获取Response的字符集。 15527 15528**系统能力：** SystemCapability.Web.Webview.Core 15529 15530**参数：** 15531 15532| 参数名 | 类型 | 必填 | 说明 | 15533| ------- | ---------------- | ---- | -------------------- | 15534| name | string | 是 | 头部（header）的名称。 | 15535 15536 15537**返回值：** 15538 15539| 类型 | 说明 | 15540| ------- | --------------------------------------- | 15541| string | 头部（header）的值。| 15542 15543**示例：** 15544 15545示例完整示例代码参考[constructor](#constructor12)。 15546 15547## WebResourceHandler<sup>12+</sup> 15548 15549通过WebResourceHandler，可以提供自定义的返回头以及返回体给Web组件。 15550 15551### didReceiveResponse<sup>12+</sup> 15552 15553didReceiveResponse(response: WebSchemeHandlerResponse): void 15554 15555将构造的响应头传递给被拦截的请求。 15556 15557**系统能力：** SystemCapability.Web.Webview.Core 15558 15559**参数：** 15560 15561| 参数名 | 类型 | 必填 | 说明 | 15562| ---------------| ------- | ---- | ------------- | 15563| response | [WebSchemeHandlerResponse](#webschemehandlerresponse12) | 是 | 该拦截请求的响应。 | 15564 15565**错误码：** 15566 15567以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15568 15569| 错误码ID | 错误信息 | 15570| -------- | ------------------------------------- | 15571| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 15572| 17100021 | The resource handler is invalid. | 15573 15574**示例：** 15575 15576示例请参考[OnRequestStart](#onrequeststart12)。 15577 15578### didReceiveResponseBody<sup>12+</sup> 15579 15580didReceiveResponseBody(data: ArrayBuffer): void 15581 15582将构造的响应体传递给被拦截的请求。 15583 15584**系统能力：** SystemCapability.Web.Webview.Core 15585 15586**参数：** 15587 15588| 参数名 | 类型 | 必填 | 说明 | 15589| ---------------| ------- | ---- | ------------- | 15590| data | ArrayBuffer | 是 | 响应体数据。 | 15591 15592**错误码：** 15593 15594以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15595 15596| 错误码ID | 错误信息 | 15597| -------- | ------------------------------------- | 15598| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 15599| 17100021 | The resource handler is invalid. | 15600 15601**示例：** 15602 15603示例请参考[OnRequestStart](#onrequeststart12)。 15604 15605### didFinish<sup>12+</sup> 15606 15607didFinish(): void 15608 15609通知Web组件被拦截的请求已经完成，并且没有更多的数据可用，调用前需要优先调用[didReceiveResponse](#didreceiveresponse12)将构造的响应头传递给被拦截的请求。 15610 15611**系统能力：** SystemCapability.Web.Webview.Core 15612 15613**错误码：** 15614 15615以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15616 15617| 错误码ID | 错误信息 | 15618| -------- | ------------------------------------- | 15619| 17100021 | The resource handler is invalid. | 15620 15621**示例：** 15622 15623示例请参考[OnRequestStart](#onrequeststart12)。 15624 15625### didFail<sup>12+</sup> 15626 15627didFail(code: WebNetErrorList): void 15628 15629通知ArkWeb内核被拦截请求应该返回失败，调用前需要优先调用[didReceiveResponse](#didreceiveresponse12)将构造的响应头传递给被拦截的请求。 15630 15631**系统能力：** SystemCapability.Web.Webview.Core 15632 15633**参数：** 15634 15635| 参数名 | 类型 | 必填 | 说明 | 15636| --------| ------- | ---- | ---------------------------| 15637| code | [WebNetErrorList](js-apis-netErrorList.md#webneterrorlist) | 是 | 网络错误码。 | 15638 15639**错误码：** 15640 15641以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15642 15643| 错误码ID | 错误信息 | 15644| -------- | ------------------------------------- | 15645| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 15646| 17100021 | The resource handler is invalid. | 15647 15648**系统能力：** SystemCapability.Web.Webview.Core 15649 15650**示例：** 15651 15652示例请参考[OnRequestStart](#onrequeststart12)。 15653 15654## WebSchemeHandler<sup>12+</sup> 15655 15656用于拦截指定scheme的请求的拦截器。 15657 15658### onRequestStart<sup>12+</sup> 15659 15660onRequestStart(callback: (request: WebSchemeHandlerRequest, handler: WebResourceHandler) => boolean): void 15661 15662当请求开始时的回调，在该回调函数中可以决定是否拦截该请求。当回调返回false是表示不拦截此请求，此时handler失效；当回调返回true，表示拦截此请求。 15663 15664**系统能力：** SystemCapability.Web.Webview.Core 15665 15666**参数**： 15667 15668| 参数名 | 类型 | 必填 | 说明 | 15669| -------- | -------------------- | ---- | ---------- | 15670| callback | (request: [WebSchemeHandlerRequest](#webschemehandlerrequest12), handler: [WebResourceHandler](#webresourcehandler12)) => boolean | 是 | 拦截对应scheme请求开始时触发的回调。request为请求，handler用于提供自定义的返回头以及返回体给Web组件，返回值表示该请求是否拦截。 | 15671 15672**错误码：** 15673 15674以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15675 15676| 错误码ID | 错误信息 | 15677| -------- | ------------------------------------- | 15678| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 15679 15680**示例：** 15681 15682```ts 15683// xxx.ets 15684import { webview } from '@kit.ArkWeb'; 15685import { BusinessError } from '@kit.BasicServicesKit'; 15686import { buffer } from '@kit.ArkTS'; 15687import { WebNetErrorList } from '@ohos.web.netErrorList'; 15688 15689@Entry 15690@Component 15691struct WebComponent { 15692 controller: webview.WebviewController = new webview.WebviewController(); 15693 schemeHandler: webview.WebSchemeHandler = new webview.WebSchemeHandler(); 15694 htmlData: string = "<html><body bgcolor=\"white\">Source:<pre>source</pre></body></html>"; 15695 15696 build() { 15697 Column() { 15698 Web({ src: 'https://www.example.com', controller: this.controller }) 15699 .onControllerAttached(() => { 15700 try { 15701 this.schemeHandler.onRequestStart((request: webview.WebSchemeHandlerRequest, resourceHandler: webview.WebResourceHandler) => { 15702 console.log("[schemeHandler] onRequestStart"); 15703 try { 15704 console.log("[schemeHandler] onRequestStart url:" + request.getRequestUrl()); 15705 console.log("[schemeHandler] onRequestStart method:" + request.getRequestMethod()); 15706 console.log("[schemeHandler] onRequestStart referrer:" + request.getReferrer()); 15707 console.log("[schemeHandler] onRequestStart isMainFrame:" + request.isMainFrame()); 15708 console.log("[schemeHandler] onRequestStart hasGesture:" + request.hasGesture()); 15709 console.log("[schemeHandler] onRequestStart header size:" + request.getHeader().length); 15710 console.log("[schemeHandler] onRequestStart resource type:" + request.getRequestResourceType()); 15711 console.log("[schemeHandler] onRequestStart frame url:" + request.getFrameUrl()); 15712 let header = request.getHeader(); 15713 for (let i = 0; i < header.length; i++) { 15714 console.log("[schemeHandler] onRequestStart header:" + header[i].headerKey + " " + header[i].headerValue); 15715 } 15716 let stream = request.getHttpBodyStream(); 15717 if (stream) { 15718 console.log("[schemeHandler] onRequestStart has http body stream"); 15719 } else { 15720 console.log("[schemeHandler] onRequestStart has no http body stream"); 15721 } 15722 } catch (error) { 15723 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 15724 } 15725 15726 if (request.getRequestUrl().endsWith("example.com")) { 15727 return false; 15728 } 15729 15730 let response = new webview.WebSchemeHandlerResponse(); 15731 try { 15732 response.setNetErrorCode(WebNetErrorList.NET_OK); 15733 response.setStatus(200); 15734 response.setStatusText("OK"); 15735 response.setMimeType("text/html"); 15736 response.setEncoding("utf-8"); 15737 response.setHeaderByName("header1", "value1", false); 15738 } catch (error) { 15739 console.error(`[schemeHandler] ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 15740 } 15741 15742 // 调用 didFinish/didFail 前需要优先调用 didReceiveResponse 将构造的响应头传递给被拦截的请求。 15743 let buf = buffer.from(this.htmlData) 15744 try { 15745 if (buf.length == 0) { 15746 console.log("[schemeHandler] length 0"); 15747 resourceHandler.didReceiveResponse(response); 15748 // 如果认为buf.length为0是正常情况，则调用resourceHandler.didFinish，否则调用resourceHandler.didFail 15749 resourceHandler.didFail(WebNetErrorList.ERR_FAILED); 15750 } else { 15751 console.log("[schemeHandler] length 1"); 15752 resourceHandler.didReceiveResponse(response); 15753 resourceHandler.didReceiveResponseBody(buf.buffer); 15754 resourceHandler.didFinish(); 15755 } 15756 } catch (error) { 15757 console.error(`[schemeHandler] ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 15758 } 15759 return true; 15760 }) 15761 15762 this.schemeHandler.onRequestStop((request: webview.WebSchemeHandlerRequest) => { 15763 console.log("[schemeHandler] onRequestStop"); 15764 }); 15765 15766 this.controller.setWebSchemeHandler('https', this.schemeHandler); 15767 } catch (error) { 15768 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 15769 } 15770 }) 15771 .javaScriptAccess(true) 15772 .domStorageAccess(true) 15773 } 15774 } 15775} 15776``` 15777### onRequestStop<sup>12+</sup> 15778 15779onRequestStop(callback: Callback\<WebSchemeHandlerRequest\>): void 15780 15781当请求完成时的回调，仅当前面onRequestStart中回调决定拦截此请求中触发。触发的时机有以下两点： 15782 157831.WebResourceHandler调用didFail或者didFinish。 15784 157852.此请求因为其他原因中断。 15786 15787**系统能力：** SystemCapability.Web.Webview.Core 15788 15789**参数**： 15790 15791| 参数名 | 类型 | 必填 | 说明 | 15792| -------- | -------------------- | ---- | ---------- | 15793| callback | Callback\<[WebSchemeHandlerRequest](#webschemehandlerrequest12)\> | 是 | 对应请求结束的回调函数。 | 15794 15795**错误码：** 15796 15797以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 15798 15799| 错误码ID | 错误信息 | 15800| -------- | ------------------------------------- | 15801| 401 | Invalid input parameter. | 15802 15803**示例：** 15804 15805完整示例代码参考[onRequestStart](#onrequeststart12)。 15806 15807## CacheOptions<sup>12+</sup> 15808 15809Web组件预编译JavaScript生成字节码缓存的配置对象，用于控制字节码缓存更新。 15810 15811**系统能力：** SystemCapability.Web.Webview.Core 15812 15813| 名称 | 类型 | 可读 | 可写 |说明 | 15814| ----------- | ------ | -----|------|------------------- | 15815| responseHeaders | Array<[WebHeader](#webheader)> | 是 | 是 | 请求此JavaScript文件时服务器返回的响应头，使用E-Tag或Last-Modified标识文件版本，判断是否需要更新。 | 15816 15817## PlaybackStatus<sup>12+</sup> 15818 15819[handleStatusChanged](#handlestatuschanged12) 接口参数， 用于表示播放器的播放状态。 15820 15821**系统能力：** SystemCapability.Web.Webview.Core 15822 15823| 名称 | 值 | 说明 | 15824|------|----|------| 15825| PAUSED | 0 | 播放状态为播放状态。 | 15826| PLAYING | 1 | 播放状态为暂停状态。 | 15827 15828## NetworkState<sup>12+<sup> 15829 15830播放器的网络状态。 15831 15832**系统能力：** SystemCapability.Web.Webview.Core 15833 15834| 名称 | 值 | 说明 | 15835|------|----|------| 15836| EMPTY | 0 | 播放器还没有开始下载数据。 | 15837| IDLE | 1 | 播放器网络状态空闲，比如媒体分片下载完成，下一个分片还没有开始下载。 | 15838| LOADING | 2 | 播放器正在下载媒体数据。 | 15839| NETWORK_ERROR | 3 | 发生了网络错误。 | 15840 15841## ReadyState<sup>12+<sup> 15842 15843播放器的缓存状态。 15844 15845**系统能力：** SystemCapability.Web.Webview.Core 15846 15847| 名称 | 值 | 说明 | 15848|------|----|------| 15849| HAVE_NOTHING | 0 | 没有缓存。 | 15850| HAVE_METADATA | 1 | 只缓存了媒体元数据。 | 15851| HAVE_CURRENT_DATA | 2 | 只缓存到当前的播放进度。 | 15852| HAVE_FUTURE_DATA | 3 | 缓存时长超过了当前的播放进度, 但是仍有可能导致卡顿。 | 15853| HAVE_ENOUGH_DATA | 4 | 缓存了足够的数据，保证播放流畅。 | 15854 15855## MediaError<sup>12+<sup> 15856 15857播放器的错误类型。 15858 15859**系统能力：** SystemCapability.Web.Webview.Core 15860 15861| 名称 | 值 | 说明 | 15862|------|----|------| 15863| NETWORK_ERROR | 1 | 网络错误。 | 15864| FORMAT_ERROR | 2 | 媒体格式错误。 | 15865| DECODE_ERROR | 3 | 解码错误。 | 15866 15867## NativeMediaPlayerHandler<sup>12+<sup> 15868 15869[CreateNativeMediaPlayerCallback](#createnativemediaplayercallback12) 回调函数的参数。 15870应用通过该对象，将播放器的状态报告给ArkWeb内核。 15871 15872### handleStatusChanged<sup>12+<sup> 15873 15874handleStatusChanged(status: PlaybackStatus): void 15875 15876当播放器的播放状态发生变化时，调用该方法将播放状态通知给 ArkWeb 内核。 15877 15878**系统能力：** SystemCapability.Web.Webview.Core 15879 15880**参数：** 15881 15882| 参数名 | 类型 | 必填 | 说明 | 15883|--------|------|------|------| 15884| status | [PlaybackStatus](#playbackstatus12) | 是 | 播放器的播放状态。 | 15885 15886**示例：** 15887 15888完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 15889 15890### handleVolumeChanged<sup>12+<sup> 15891 15892handleVolumeChanged(volume: number): void 15893 15894当播放器的音量发生变化时，调用该方法将音量通知给 ArkWeb 内核。 15895 15896**系统能力：** SystemCapability.Web.Webview.Core 15897 15898**参数：** 15899 15900| 参数名 | 类型 | 必填 | 说明 | 15901|--------|------|------|------| 15902| volume | number | 是 | 播放器的音量。 | 15903 15904**示例：** 15905 15906完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 15907 15908### handleMutedChanged<sup>12+<sup> 15909 15910handleMutedChanged(muted: boolean): void 15911 15912当播放器的静音状态发生变化时，调用该方法将静音状态通知给 ArkWeb 内核。 15913 15914**系统能力：** SystemCapability.Web.Webview.Core 15915 15916**参数：** 15917 15918| 参数名 | 类型 | 必填 | 说明 | 15919|--------|------|------|------| 15920| muted | boolean | 是 | 当前播放器是否静音。 | 15921 15922**示例：** 15923 15924完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 15925 15926### handlePlaybackRateChanged<sup>12+<sup> 15927 15928handlePlaybackRateChanged(playbackRate: number): void 15929 15930当播放器的播放速度发生变化时，调用该方法将播放速度通知给 ArkWeb 内核。 15931 15932**系统能力：** SystemCapability.Web.Webview.Core 15933 15934**参数：** 15935 15936| 参数名 | 类型 | 必填 | 说明 | 15937|--------|------|------|------| 15938| playbackRate | number | 是 | 播放速率。 | 15939 15940**示例：** 15941 15942完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 15943 15944### handleDurationChanged<sup>12+<sup> 15945 15946handleDurationChanged(duration: number): void 15947 15948当播放器解析出媒体的总时长时，调用该方法将媒体的总时长通知给 ArkWeb 内核。 15949 15950**系统能力：** SystemCapability.Web.Webview.Core 15951 15952**参数：** 15953 15954| 参数名 | 类型 | 必填 | 说明 | 15955|--------|------|------|------| 15956| duration | number | 是 | 媒体的总时长。单位： 秒 。 | 15957 15958**示例：** 15959 15960完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 15961 15962### handleTimeUpdate<sup>12+<sup> 15963 15964handleTimeUpdate(currentPlayTime: number): void 15965 15966当媒体的播放进度发生变化时，调用该方法将媒体的播放进度通知给 ArkWeb 内核。 15967 15968**系统能力：** SystemCapability.Web.Webview.Core 15969 15970**参数：** 15971 15972| 参数名 | 类型 | 必填 | 说明 | 15973|--------|------|------|------| 15974| currentPlayTime | number | 是 | 当前播放时间。单位： 秒。 | 15975 15976**示例：** 15977 15978完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 15979 15980### handleBufferedEndTimeChanged<sup>12+<sup> 15981 15982handleBufferedEndTimeChanged(bufferedEndTime: number): void 15983 15984当媒体的缓冲时长发生变化时，调用该方法将媒体的缓冲时长通知给 ArkWeb 内核。 15985 15986**系统能力：** SystemCapability.Web.Webview.Core 15987 15988**参数：** 15989 15990| 参数名 | 类型 | 必填 | 说明 | 15991|--------|------|------|------| 15992| bufferedEndTime | number | 是 | 媒体缓冲的时长。 | 15993 15994**示例：** 15995 15996完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 15997 15998### handleEnded<sup>12+<sup> 15999 16000handleEnded(): void 16001 16002当媒体播放结束时，调用该方法通知给 ArkWeb 内核。 16003 16004**系统能力：** SystemCapability.Web.Webview.Core 16005 16006**示例：** 16007 16008完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16009 16010### handleNetworkStateChanged<sup>12+<sup> 16011 16012handleNetworkStateChanged(state: NetworkState): void 16013 16014当播放器的网络状态发生变化时，调用该方法将播放器的网络状态通知给 ArkWeb 内核。 16015 16016**系统能力：** SystemCapability.Web.Webview.Core 16017 16018**参数：** 16019 16020| 参数名 | 类型 | 必填 | 说明 | 16021|--------|------|------|------| 16022| state | [NetworkState](#networkstate12) | 是 | 播放器的网络状态。 | 16023 16024**示例：** 16025 16026完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16027 16028### handleReadyStateChanged<sup>12+<sup> 16029 16030handleReadyStateChanged(state: ReadyState): void 16031 16032当播放器的缓存状态发生变化时，调用该方法将播放器的缓存状态通知给 ArkWeb 内核。 16033 16034**系统能力：** SystemCapability.Web.Webview.Core 16035 16036**参数：** 16037 16038| 参数名 | 类型 | 必填 | 说明 | 16039|--------|------|------|------| 16040| state | [ReadyState](#readystate12) | 是 | 播放器的缓存状态。 | 16041 16042**示例：** 16043 16044完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16045 16046### handleFullscreenChanged<sup>12+<sup> 16047 16048handleFullscreenChanged(fullscreen: boolean): void 16049 16050当播放器的全屏状态发生变化时，调用该方法将播放器的全屏状态通知给 ArkWeb 内核。 16051 16052**系统能力：** SystemCapability.Web.Webview.Core 16053 16054**参数：** 16055 16056| 参数名 | 类型 | 必填 | 说明 | 16057|--------|------|------|------| 16058| fullscreen | boolean | 是 | 是否全屏。 | 16059 16060**示例：** 16061 16062完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16063 16064### handleSeeking<sup>12+<sup> 16065 16066handleSeeking(): void 16067 16068当播放器进入seek 状态时，调用该方法通知 ArkWeb 内核。 16069 16070**系统能力：** SystemCapability.Web.Webview.Core 16071 16072**示例：** 16073 16074完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16075 16076### handleSeekFinished<sup>12+<sup> 16077 16078handleSeekFinished(): void 16079 16080当播放器 seek 完成后，调用该方法通知 ArkWeb 内核。 16081 16082**系统能力：** SystemCapability.Web.Webview.Core 16083 16084**示例：** 16085 16086完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16087 16088### handleError<sup>12+<sup> 16089 16090handleError(error: MediaError, errorMessage: string): void 16091 16092当播放器发生错误时， 调用该方法通知 ArkWeb 内核。 16093 16094**系统能力：** SystemCapability.Web.Webview.Core 16095 16096**参数：** 16097 16098| 参数名 | 类型 | 必填 | 说明 | 16099|--------|------|------|------| 16100| error | [MediaError](#mediaerror12) | 是 | 错误类型。 | 16101| errorMessage | string | 是 | 错误的详细描述。 | 16102 16103**示例：** 16104 16105完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16106 16107### handleVideoSizeChanged<sup>12+<sup> 16108 16109handleVideoSizeChanged(width: number, height: number): void 16110 16111当播放器解析出视频的尺寸时， 调用该方法通知 ArkWeb 内核。 16112 16113**系统能力：** SystemCapability.Web.Webview.Core 16114 16115**参数：** 16116 16117| 参数名 | 类型 | 必填 | 说明 | 16118|--------|------|------|------| 16119| width | number | 是 | 视频的宽。 | 16120| height | number | 是 | 视频的高。 | 16121 16122**示例：** 16123 16124完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16125 16126## SuspendType<sup>12+<sup> 16127 16128表示播放器的挂起类型。 16129 16130**系统能力：** SystemCapability.Web.Webview.Core 16131 16132| 名称 | 值 | 说明 | 16133|------|----|------| 16134| ENTER_BACK_FORWARD_CACHE | 0 | 页面进BFCache。 | 16135| ENTER_BACKGROUND | 1 | 页面进后台。 | 16136| AUTO_CLEANUP | 2 | 系统自动清理。 | 16137 16138## NativeMediaPlayerBridge<sup>12+<sup> 16139 16140[CreateNativeMediaPlayerCallback](#createnativemediaplayercallback12) 回调函数的返回值类型。 16141接管网页媒体的播放器和 ArkWeb 内核之间的一个接口类。 16142ArkWeb 内核通过该接口类的实例对象来控制应用创建的用来接管网页媒体的播放器。 16143 16144### updateRect<sup>12+<sup> 16145 16146updateRect(x: number, y: number, width: number, height: number): void 16147 16148更新 surface 位置信息。 16149 16150**系统能力：** SystemCapability.Web.Webview.Core 16151 16152**参数：** 16153 16154| 参数名 | 类型 | 必填 | 说明 | 16155|--------|------|------|------| 16156| x | number | 是 | surface 相对于 Web 组件的 x 坐标信息。 | 16157| y | number | 是 | surface 相对于 Web 组件的 y 坐标信息。 | 16158| width | number | 是 | surface 的宽度。 | 16159| height | number | 是 | surface 的高度。 | 16160 16161**示例：** 16162 16163完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16164 16165### play<sup>12+<sup> 16166 16167play(): void 16168 16169播放视频。 16170 16171**系统能力：** SystemCapability.Web.Webview.Core 16172 16173**示例：** 16174 16175完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16176 16177### pause<sup>12+<sup> 16178 16179pause(): void 16180 16181暂停播放。 16182 16183**系统能力：** SystemCapability.Web.Webview.Core 16184 16185**示例：** 16186 16187完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16188 16189### seek<sup>12+<sup> 16190 16191seek(targetTime: number): void 16192 16193播放跳转到某个时间点。 16194 16195**系统能力：** SystemCapability.Web.Webview.Core 16196 16197**参数：** 16198 16199| 参数名 | 类型 | 必填 | 说明 | 16200|--------|------|------|------| 16201| targetTime | number | 是 | 单位： 秒。 | 16202 16203**示例：** 16204 16205完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16206 16207### setVolume<sup>12+<sup> 16208 16209setVolume(volume: number): void 16210 16211设置播放器音量值。 16212取值范围: [0, 1.0] 16213 16214**参数：** 16215 16216| 参数名 | 类型 | 必填 | 说明 | 16217|--------|------|------|------| 16218| volume | number | 是 | 播放器的音量。取值范围是从 0 到 1.0 。 其中 0 表示静音， 1.0 表示最大音量。 | 16219 16220**系统能力：** SystemCapability.Web.Webview.Core 16221 16222**示例：** 16223 16224完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16225 16226### setMuted<sup>12+<sup> 16227 16228setMuted(muted: boolean): void 16229 16230设置静音状态。 16231 16232**系统能力：** SystemCapability.Web.Webview.Core 16233 16234**参数：** 16235 16236| 参数名 | 类型 | 必填 | 说明 | 16237|--------|------|------|------| 16238| muted | boolean | 是 | 是否静音。 | 16239 16240**示例：** 16241 16242完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16243 16244### setPlaybackRate<sup>12+<sup> 16245 16246setPlaybackRate(playbackRate: number): void 16247 16248设置播放速度。 16249取值范围: [0, 10.0] 16250 16251**系统能力：** SystemCapability.Web.Webview.Core 16252 16253**参数：** 16254 16255| 参数名 | 类型 | 必填 | 说明 | 16256|--------|------|------|------| 16257| playbackRate | number | 是 | 播放倍率。取值范围是从 0 到 10.0 。其中 1 表示原速播放。 | 16258 16259**示例：** 16260 16261完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16262 16263### release<sup>12+<sup> 16264 16265release(): void 16266 16267销毁播放器。 16268 16269**系统能力：** SystemCapability.Web.Webview.Core 16270 16271**示例：** 16272 16273完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16274 16275### enterFullscreen<sup>12+<sup> 16276 16277enterFullscreen(): void 16278 16279播放器进入全屏。 16280 16281**系统能力：** SystemCapability.Web.Webview.Core 16282 16283**示例：** 16284 16285完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16286 16287### exitFullscreen<sup>12+<sup> 16288 16289exitFullscreen(): void 16290 16291播放器退出全屏。 16292 16293**系统能力：** SystemCapability.Web.Webview.Core 16294 16295**示例：** 16296 16297完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16298 16299### resumePlayer<sup>12+<sup> 16300 16301resumePlayer?(): void 16302 16303通知应用重建应用内播放器，并恢复应用内播放器的状态信息。 16304 16305**系统能力：** SystemCapability.Web.Webview.Core 16306 16307**示例：** 16308 16309完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16310 16311### suspendPlayer<sup>12+<sup> 16312 16313suspendPlayer?(type: SuspendType): void 16314 16315通知应用销毁应用内播放器，并保存应用内播放器的状态信息。 16316 16317**系统能力：** SystemCapability.Web.Webview.Core 16318 16319**参数：** 16320 16321| 参数名 | 类型 | 必填 | 说明 | 16322|--------|------|------|------| 16323| type | [SuspendType](#suspendtype12) | 是 | 播放器挂起类型。| 16324 16325**示例：** 16326 16327完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16328 16329## MediaType<sup>12+<sup> 16330 16331表示媒体类型。 16332 16333**系统能力：** SystemCapability.Web.Webview.Core 16334 16335| 名称 | 值 | 说明 | 16336|------|----|------| 16337| VIDEO | 0 | 视频。 | 16338| AUDIO | 1 | 音频。 | 16339 16340## SourceType<sup>12+<sup> 16341 16342表示媒体源的类型。 16343 16344**系统能力：** SystemCapability.Web.Webview.Core 16345 16346| 名称 | 值 | 说明 | 16347|------|----|------| 16348| URL | 0 | 媒体源的类型是 URL 。 | 16349| MSE | 1 | 媒体源的类型是 blob 。 | 16350 16351## MediaSourceInfo<sup>12+<sup> 16352 16353表示媒体源的信息。 16354 16355**系统能力：** SystemCapability.Web.Webview.Core 16356 16357| 名称 | 类型 | 必填 | 说明 | 16358|------|------|------|------| 16359| type | [SourceType](#sourcetype12) | 是 | 媒体源的类型。 | 16360| source | string | 是 | 媒体源地址。 | 16361| format | string | 是 | 媒体源格式， 可能为空， 需要使用者自己去判断格式。 | 16362 16363## NativeMediaPlayerSurfaceInfo<sup>12+<sup> 16364 16365[应用接管网页媒体播放功能](ts-basic-components-web.md#enablenativemediaplayer12)中用于同层渲染的 surface 信息。 16366 16367**系统能力：** SystemCapability.Web.Webview.Core 16368 16369| 名称 | 类型 | 必填 | 说明 | 16370|------|------|------|------| 16371| id | string | 是 | surface 的id ， 用于同层渲染的NativeImage的 psurfaceid。<br/>详见[NativeEmbedDataInfo](ts-basic-components-web.md#nativeembeddatainfo11)。 | 16372| rect | [RectEvent](#rectevent12) | 是 | surface 的位置信息。 | 16373 16374## Preload<sup>12+<sup> 16375 16376播放器预加载媒体数据。 16377 16378**系统能力：** SystemCapability.Web.Webview.Core 16379 16380| 名称 | 值 | 说明 | 16381|------|----|------| 16382| NONE | 0 | 不预加载。 | 16383| METADATA | 1 | 只预加载媒体的元数据。 | 16384| AUTO | 2 | 预加载足够多的媒体数据，以保证能流畅地播放。 | 16385 16386## MediaInfo<sup>12+<sup> 16387 16388[CreateNativeMediaPlayerCallback](#createnativemediaplayercallback12)回调函数的一个参数。 16389包含了网页中媒体的信息。应用可以根据这些信息来创建接管网页媒体播放的播放器。 16390 16391**系统能力：** SystemCapability.Web.Webview.Core 16392 16393| 名称 | 类型 | 必填 | 说明 | 16394|------|------|------|------| 16395| embedID | string | 是 | 网页中的 `<video>` 或 `<audio>` 的 ID 。| 16396| mediaType | [MediaType](#mediatype12) | 是 | 媒体的类型。 | 16397| mediaSrcList | [MediaSourceInfo](#mediasourceinfo12)[] | 是 | 媒体的源。可能有多个源，应用需要选择一个支持的源来播放。 | 16398| surfaceInfo | [NativeMediaPlayerSurfaceInfo](#nativemediaplayersurfaceinfo12) | 是 | 用于同层渲染的 surface 信息。 | 16399| controlsShown | boolean | 是 | `<video>` 或 `<audio>` 中是否有 `controls`属性。 | 16400| controlList | string[] | 是 | `<video>` 或 `<audio>` 中的 `controlslist` 属性的值。 | 16401| muted | boolean | 是 | 是否要求静音播放。 | 16402| posterUrl | string | 是 | 海报的地址。 | 16403| preload | [Preload](#preload12) | 是 | 是否需要预加载。 | 16404| headers | Record\<string, string\> | 是 | 播放器请求媒体资源时，需要携带的 HTTP 头。 | 16405| attributes | Record\<string, string\> | 是 | `<video>` 或 `<audio>` 标签中的属性。 | 16406 16407 16408## CreateNativeMediaPlayerCallback<sup>12+<sup> 16409 16410type CreateNativeMediaPlayerCallback = (handler: NativeMediaPlayerHandler, mediaInfo: MediaInfo) => NativeMediaPlayerBridge 16411 16412[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)方法的参数。 16413一个回调函数， 创建一个播放器, 用于接管网页中的媒体播放。 16414 16415**系统能力：** SystemCapability.Web.Webview.Core 16416 16417**参数：** 16418 16419| 参数名 | 类型 | 必填 | 说明 | 16420|--------|------|------|------| 16421| handler | [NativeMediaPlayerHandler](#nativemediaplayerhandler12) | 是 | 通过该对象，将播放器的状态报告给 ArkWeb 内核。 | 16422| mediaInfo | [MediaInfo](#mediainfo12) | 是 | 网页媒体的信息。 | 16423 16424**返回值：** 16425 16426| 类型 | 说明 | 16427|------|------| 16428| [NativeMediaPlayerBridge](#nativemediaplayerbridge12) | 接管网页媒体的播放器和 ArkWeb 内核之间的一个接口类。<br/>应用需要实现该接口类。<br/> ArkWeb 内核通过该接口类的对象来控制应用创建的用来接管网页媒体的播放器。<br/>如果应用返回了 null ， 则表示应用不接管这个媒体，由 ArkWeb 内核来播放该媒体。 | 16429 16430**示例：** 16431 16432完整示例代码参考[onCreateNativeMediaPlayer](#oncreatenativemediaplayer12)。 16433 16434## OfflineResourceMap<sup>12+</sup> 16435 16436本地离线资源配置对象，用于配置将被[injectOfflineResources](#injectofflineresources12)接口注入到内存缓存的本地离线资源的相关信息, 内核会根据此信息生成资源缓存，并据此控制缓存的有效期。 16437 16438**系统能力：** SystemCapability.Web.Webview.Core 16439 16440| 名称 | 类型 | 可读 | 可写 |说明 | 16441| ----------- | ------ | -----|------|------------------- | 16442| urlList | Array\<string\> | 是 | 是 | 本地离线资源对应的网络地址列表，列表的第一项将作为资源的源(Origin), 如果仅提供一个网络地址，则使用该地址作为这个资源的源。url仅支持http或https协议，长度不超过2048。 | 16443| resource | Uint8Array | 是 | 是 | 本地离线资源的内容。 | 16444| responseHeaders | Array<[WebHeader](#webheader)> | 是 | 是 | 资源对应的HTTP响应头。其中提供的Cache-Control或Expires响应头将被用于控制资源在内存缓存中的有效期。如果不提供，默认的有效期为86400秒，即1天。其中提供的Content-Type响应头将被用于定义资源的MIMEType，MODULE_JS必须提供有效的MIMEType，其他类型可不提供，无默认值，不符合标准的MIMEType会导致内存缓存失效。如果业务网页中的script标签使用了crossorigin属性，则必须在接口的responseHeaders参数中设置Cross-Origin响应头的值为anoymous或use-credentials。 | 16445| type | [OfflineResourceType](#offlineresourcetype12) | 是 | 是 | 资源的类型，目前仅支持Javascript、图片和CSS类型的资源。 | 16446 16447## OfflineResourceType<sup>12+</sup> 16448 16449[OfflineResourceMap](#offlineresourcemap12)对象对应的本地离线资源的接口类型。 16450 16451**系统能力：** SystemCapability.Web.Webview.Core 16452 16453| 名称 | 值 | 说明 | 16454| ------------ | -- |--------------------------------- | 16455| IMAGE | 0 | 图片类型的资源。 | 16456| CSS | 1 | CSS类型的资源。| 16457| CLASSIC_JS | 2 | 通过<script src="" /\>标签加载的Javascript资源。| 16458| MODULE_JS | 3 |通过<script src="" type="module" /\>标签加载的Javascript资源。| 16459 16460## WebResourceType<sup>12+</sup> 16461 16462资源请求的资源类型。 16463 16464**系统能力：** SystemCapability.Web.Webview.Core 16465 16466| 名称 | 值 | 说明 | 16467| ------------ | -- |--------------------------------- | 16468| MAIN_FRAME | 0 | 顶层页面。 | 16469| SUB_FRAME | 1 | Frame或Iframe。 | 16470| STYLE_SHEET | 2 | CSS样式表。 | 16471| SCRIPT | 3 | 外部脚本。 | 16472| IMAGE | 4 | 图片（jpg/gif/png/以及其他）。 | 16473| FONT_RESOURCE | 5 | 字体。 | 16474| SUB_RESOURCE | 6 | 其他子资源。如果实际类型未知，则是默认类型。 | 16475| OBJECT | 7 | 插件的Object（或embed）标签，或者插件请求的资源。 | 16476| MEDIA | 8 | 媒体资源。 | 16477| WORKER | 9 | 专用工作线程的主资源。 | 16478| SHARED_WORKER | 10 | 共享工作线程的主资源。 | 16479| PREFETCH | 11 | 明确的预取请求。 | 16480| FAVICON | 12 | 网站图标。 | 16481| XHR | 13 | XMLHttpRequest。 | 16482| PING | 14 | <a ping\>/sendBeacon的Ping请求。 | 16483| SERVICE_WORKER | 15 | service worker的主资源。 | 16484| CSP_REPORT | 16 | 内容安全策略违规报告。 | 16485| PLUGIN_RESOURCE | 17 | 插件请求的资源。 | 16486| NAVIGATION_PRELOAD_MAIN_FRAME | 19 | 触发service worker预热的主frame跳转请求。 | 16487| NAVIGATION_PRELOAD_SUB_FRAME | 20 | 触发service worker预热的子frame跳转请求。 | 16488 16489## RectEvent<sup>12+<sup> 16490 16491矩形定义。 16492 16493**系统能力：** SystemCapability.Web.Webview.Core 16494 16495| 名称 | 类型 | 可读 | 可写 | 说明 | 16496| -------------- | --------- | ---- | ---- | ---------------------------- | 16497| x | number | 是 | 是 | 矩形区域左上角x坐标。 | 16498| y | number | 是 | 是 | 矩形区域左上角y坐标。 | 16499| width | number | 是 | 是 | 矩形的宽度。 | 16500| height | number | 是 | 是 | 矩形的高度。 | 16501 16502## BackForwardCacheSupportedFeatures<sup>12+<sup> 16503 16504选择性允许使用以下特性的页面进入前进后退缓存。完整示例代码参考[enableBackForwardCache](#enablebackforwardcache12)。 16505 16506**系统能力：** SystemCapability.Web.Webview.Core 16507 16508| 名称 | 类型 | 必填 | 说明 | 16509|------|------|------|------| 16510| nativeEmbed | boolean | 是 | 是否允许使用同层渲染的页面进入前进后退缓存，默认不允许。如果设置为允许，需要维护为同层渲染元素创建的原生控件的生命周期，避免造成泄漏。 | 16511| mediaTakeOver | boolean | 是 | 是否允许使用视频托管的页面进入前进后退缓存，默认不允许。如果设置为允许，需要维护为视频元素创建的原生控件的生命周期，避免造成泄漏。| 16512 16513### constructor<sup>12+</sup> 16514 16515constructor() 16516 16517BackForwardCacheSupportedFeatures的构造函数。 16518 16519**系统能力：** SystemCapability.Web.Webview.Core 16520 16521## BackForwardCacheOptions<sup>12+<sup> 16522 16523前进后退缓存相关设置对象，用来控制Web组件前进后退缓存相关选项。完整示例代码参考[BackForwardCacheOptions](#backforwardcacheoptions12)。 16524 16525**系统能力：** SystemCapability.Web.Webview.Core 16526 16527| 名称 | 类型 | 必填 | 说明 | 16528|------|------|------|------| 16529| size | number | 是 | 设置每个Web组件允许缓存的最大页面个数。默认为1，最大可设置为50。设置为0或负数时，前进后退缓存功能不生效。Web会根据内存压力对缓存进行回收。 | 16530| timeToLive | number | 是 | 设置每个Web组件允许页面在前进后退缓存中停留的时间，默认为600秒。设置为0或负数时，前进后退缓存功能不生效。| 16531 16532### constructor<sup>12+</sup> 16533 16534constructor() 16535 16536BackForwardCacheOptions的构造函数。 16537 16538**系统能力：** SystemCapability.Web.Webview.Core 16539 16540## AdsBlockManager<sup>12+</sup> 16541 16542通过AdsBlockManager可以向Web组件中设置自定义的广告过滤配置、关闭特定网站的广告过滤功能，其中每个应用中的所有Web组件都共享一个AdsBlockManager实例。 16543 16544### setAdsBlockRules<sup>12+</sup> 16545 16546static setAdsBlockRules(rulesFile: string, replace: boolean): void 16547 16548向Web组件中设置自定义的符合通用easylist语法规则的广告过滤配置文件。 16549 16550> **说明：** 16551> 16552> 此接口设置的广告过滤规则，内部解析成功后会持久化存储，应用重启后不需要重复设置。 16553 16554**系统能力：** SystemCapability.Web.Webview.Core 16555 16556**参数：** 16557 16558| 参数名 | 类型 | 必填 | 说明 | 16559| ---------- | ------ | ---- | -------------------------------- | 16560| rulesFile | string | 是 | 指定了符合 easylist 通用语法的规则文件路径，应用需要有此文件的读权限。 | 16561| replace | boolean | 是 | true表示强制替换掉内置的默认规则，false表示设置的自定义规则将与内置规则共同工作。 | 16562 16563**错误码：** 16564 16565以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 16566 16567| 错误码ID | 错误信息 | 16568| -------- | ----------------------- | 16569| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 16570 16571**示例：** 16572 16573```ts 16574// xxx.ets 16575import { webview } from '@kit.ArkWeb'; 16576import { picker, fileUri } from '@kit.CoreFileKit'; 16577 16578// 演示点击按钮，通过filepicker打开一个easylist规则文件并设置到Web组件中 16579@Entry 16580@Component 16581struct WebComponent { 16582 controller: webview.WebviewController = new webview.WebviewController(); 16583 16584 build() { 16585 Row() { 16586 Flex() { 16587 Button({ type: ButtonType.Capsule }) { 16588 Text("setAdsBlockRules") 16589 } 16590 .onClick(() => { 16591 try { 16592 let documentSelectionOptions: ESObject = new picker.DocumentSelectOptions(); 16593 let documentPicker: ESObject = new picker.DocumentViewPicker(); 16594 documentPicker.select(documentSelectionOptions).then((documentSelectResult: ESObject) => { 16595 if (documentSelectResult && documentSelectResult.length > 0) { 16596 let fileRealPath = new fileUri.FileUri(documentSelectResult[0]); 16597 console.info('DocumentViewPicker.select successfully, uri: ' + fileRealPath); 16598 webview.AdsBlockManager.setAdsBlockRules(fileRealPath.path, true); 16599 } 16600 }) 16601 } catch (err) { 16602 console.error('DocumentViewPicker.select failed with err:' + err); 16603 } 16604 }) 16605 } 16606 } 16607 } 16608} 16609``` 16610 16611### addAdsBlockDisallowedList<sup>12+</sup> 16612 16613static addAdsBlockDisallowedList(domainSuffixes: Array\<string\>): void 16614 16615向AdsBlockManager的DisallowedList中添加一组域名。广告过滤功能开启时，将禁用这些网站的广告过滤功能。 16616 16617> **说明：** 16618> 16619> 此接口设置的域名不会持久化，应用重启需要重新设置。 16620> 16621> 广告过滤特性会使用后缀匹配的方式判断domainSuffix和当前站点的url是否能匹配，例如，当前Web组件打开的网站是https://www.example.com，设置的DisallowList中有'example.com'或者'www.example.com'，后缀匹配成功，此网站将禁用广告过滤，访问'https://m.example.com'也将禁用广告过滤。 16622 16623**系统能力：** SystemCapability.Web.Webview.Core 16624 16625**参数：** 16626 16627| 参数名 | 类型 | 必填 | 说明 | 16628| ---------- | ------ | ---- | -------------------------------- | 16629| domainSuffixes | Array\<string\> | 是 | 一组域名列表，例如['example.com', 'abcd.efg.com'] | 16630 16631**错误码：** 16632 16633以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 16634 16635| 错误码ID | 错误信息 | 16636| -------- | ----------------------- | 16637| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 16638 16639**示例：** 16640 16641```ts 16642// xxx.ets 16643import { webview } from '@kit.ArkWeb'; 16644 16645// 演示通过一个按钮的点击向Web组件设置广告过滤的域名策略 16646@Entry 16647@Component 16648struct WebComponent { 16649 main_url: string = 'https://www.example.com'; 16650 text_input_controller: TextInputController = new TextInputController(); 16651 controller: webview.WebviewController = new webview.WebviewController(); 16652 @State input_text: string = 'https://www.example.com'; 16653 16654 build() { 16655 Column() { 16656 Row() { 16657 Flex() { 16658 TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller}) 16659 .id("input_url") 16660 .height(40) 16661 .margin(5) 16662 .borderColor(Color.Blue) 16663 .onChange((value: string) => { 16664 this.input_text = value; 16665 }) 16666 16667 Button({type: ButtonType.Capsule}) { Text("Go") } 16668 .onClick(() => { 16669 this.controller.loadUrl(this.input_text); 16670 }) 16671 16672 Button({type: ButtonType.Capsule}) { Text("addAdsBlockDisallowedList") } 16673 .onClick(() => { 16674 let arrDomainSuffixes = new Array<string>(); 16675 arrDomainSuffixes.push('example.com'); 16676 arrDomainSuffixes.push('abcdefg.cn'); 16677 webview.AdsBlockManager.addAdsBlockDisallowedList(arrDomainSuffixes); 16678 }) 16679 } 16680 } 16681 Web({ src: this.main_url, controller: this.controller }) 16682 .onControllerAttached(()=>{ 16683 this.controller.enableAdsBlock(true); 16684 }) 16685 } 16686 } 16687} 16688``` 16689 16690### removeAdsBlockDisallowedList<sup>12+</sup> 16691 16692static removeAdsBlockDisallowedList(domainSuffixes: Array\<string\>): void 16693 16694从AdsBlockManager的DisallowedList中删除一组域名。 16695 16696> **说明：** 16697> 16698> AdsBlockManager的DisallowedList不会持久化，应用重启需要重新设置。删除不存在的条目不会触发异常。 16699 16700**系统能力：** SystemCapability.Web.Webview.Core 16701 16702**参数：** 16703 16704| 参数名 | 类型 | 必填 | 说明 | 16705| ---------- | ------ | ---- | -------------------------------- | 16706| domainSuffixes | Array\<string\> | 是 | 一组域名列表，例如['example.com', 'abcd.efg.com'] | 16707 16708**错误码：** 16709 16710以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 16711 16712| 错误码ID | 错误信息 | 16713| -------- | ----------------------- | 16714| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 16715 16716**示例：** 16717 16718```ts 16719// xxx.ets 16720import { webview } from '@kit.ArkWeb'; 16721 16722// 演示通过一个按钮的点击从AdsBlockManager的DisallowedList中删除域名元素 16723@Entry 16724@Component 16725struct WebComponent { 16726 main_url: string = 'https://www.example.com'; 16727 text_input_controller: TextInputController = new TextInputController(); 16728 controller: webview.WebviewController = new webview.WebviewController(); 16729 @State input_text: string = 'https://www.example.com'; 16730 16731 build() { 16732 Column() { 16733 Row() { 16734 Flex() { 16735 TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller}) 16736 .id("input_url") 16737 .height(40) 16738 .margin(5) 16739 .borderColor(Color.Blue) 16740 .onChange((value: string) => { 16741 this.input_text = value; 16742 }) 16743 16744 Button({type: ButtonType.Capsule}) { Text("Go") } 16745 .onClick(() => { 16746 this.controller.loadUrl(this.input_text); 16747 }) 16748 16749 Button({type: ButtonType.Capsule}) { Text("removeAdsBlockDisallowedList") } 16750 .onClick(() => { 16751 let arrDomainSuffixes = new Array<string>(); 16752 arrDomainSuffixes.push('example.com'); 16753 arrDomainSuffixes.push('abcdefg.cn'); 16754 webview.AdsBlockManager.removeAdsBlockDisallowedList(arrDomainSuffixes); 16755 }) 16756 } 16757 } 16758 Web({ src: this.main_url, controller: this.controller }) 16759 .onControllerAttached(()=>{ 16760 this.controller.enableAdsBlock(true); 16761 }) 16762 } 16763 } 16764} 16765``` 16766 16767### clearAdsBlockDisallowedList<sup>12+</sup> 16768 16769static clearAdsBlockDisallowedList(): void 16770 16771清空AdsBlockManager的DisallowedList。 16772 16773**系统能力：** SystemCapability.Web.Webview.Core 16774 16775**示例：** 16776 16777```ts 16778// xxx.ets 16779import { webview } from '@kit.ArkWeb'; 16780 16781@Entry 16782@Component 16783struct WebComponent { 16784 main_url: string = 'https://www.example.com'; 16785 text_input_controller: TextInputController = new TextInputController(); 16786 controller: webview.WebviewController = new webview.WebviewController(); 16787 @State input_text: string = 'https://www.example.com'; 16788 16789 build() { 16790 Column() { 16791 Row() { 16792 Flex() { 16793 TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller}) 16794 .id("input_url") 16795 .height(40) 16796 .margin(5) 16797 .borderColor(Color.Blue) 16798 .onChange((value: string) => { 16799 this.input_text = value; 16800 }) 16801 16802 Button({type: ButtonType.Capsule}) { Text("Go") } 16803 .onClick(() => { 16804 this.controller.loadUrl(this.input_text); 16805 }) 16806 16807 Button({type: ButtonType.Capsule}) { Text("clearAdsBlockDisallowedList") } 16808 .onClick(() => { 16809 webview.AdsBlockManager.clearAdsBlockDisallowedList(); 16810 }) 16811 } 16812 } 16813 Web({ src: this.main_url, controller: this.controller }) 16814 .onControllerAttached(()=>{ 16815 this.controller.enableAdsBlock(true); 16816 }) 16817 } 16818 } 16819} 16820``` 16821 16822### addAdsBlockAllowedList<sup>12+</sup> 16823 16824static addAdsBlockAllowedList(domainSuffixes: Array\<string\>): void 16825 16826向AdsBlockManager的AllowedList中添加一组域名，主要用于重新开启DisallowList中的部分网站的广告过滤。 16827 16828> **说明：** 16829> 16830> 此接口设置的域名不会持久化，应用重启需要重新设置。 16831> 16832> AllowedList的优先级比DisAllowList高，例如，DisallowList中配置了['example.com']，禁用了所有example.com域名下的网页，此时如果需要开启'news.example.com'下的广告过滤，可以使用addAdsBlockAllowedList(['news.example.com'])。 16833 16834**系统能力：** SystemCapability.Web.Webview.Core 16835 16836**参数：** 16837 16838| 参数名 | 类型 | 必填 | 说明 | 16839| ---------- | ------ | ---- | -------------------------------- | 16840| domainSuffixes | Array\<string\> | 是 | 一组域名列表，例如['example.com', 'abcd.efg.com'] | 16841 16842**错误码：** 16843 16844以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 16845 16846| 错误码ID | 错误信息 | 16847| -------- | ----------------------- | 16848| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 16849 16850**示例：** 16851 16852```ts 16853// xxx.ets 16854import { webview } from '@kit.ArkWeb'; 16855 16856// 演示通过一个按钮的点击向Web组件设置广告过滤的域名策略 16857@Entry 16858@Component 16859struct WebComponent { 16860 main_url: string = 'https://www.example.com'; 16861 text_input_controller: TextInputController = new TextInputController(); 16862 controller: webview.WebviewController = new webview.WebviewController(); 16863 @State input_text: string = 'https://www.example.com'; 16864 16865 build() { 16866 Column() { 16867 Row() { 16868 Flex() { 16869 TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller}) 16870 .id("input_url") 16871 .height(40) 16872 .margin(5) 16873 .borderColor(Color.Blue) 16874 .onChange((value: string) => { 16875 this.input_text = value; 16876 }) 16877 16878 Button({type: ButtonType.Capsule}) { Text("Go") } 16879 .onClick(() => { 16880 this.controller.loadUrl(this.input_text); 16881 }) 16882 16883 Button({type: ButtonType.Capsule}) { Text("addAdsBlockAllowedList") } 16884 .onClick(() => { 16885 let arrDisallowDomainSuffixes = new Array<string>(); 16886 arrDisallowDomainSuffixes.push('example.com'); 16887 webview.AdsBlockManager.addAdsBlockDisallowedList(arrDisallowDomainSuffixes); 16888 16889 let arrAllowedDomainSuffixes = new Array<string>(); 16890 arrAllowedDomainSuffixes.push('news.example.com'); 16891 webview.AdsBlockManager.addAdsBlockAllowedList(arrAllowedDomainSuffixes); 16892 }) 16893 } 16894 } 16895 Web({ src: this.main_url, controller: this.controller }) 16896 .onControllerAttached(()=>{ 16897 this.controller.enableAdsBlock(true) 16898 }) 16899 } 16900 } 16901} 16902``` 16903 16904### removeAdsBlockAllowedList<sup>12+</sup> 16905 16906static removeAdsBlockAllowedList(domainSuffixes: Array\<string\>): void 16907 16908从AdsBlockManager的AllowedList中删除一组域名。 16909 16910> **说明：** 16911> 16912> AdsBlockManager的AllowedList不会持久化，应用重启需要重新设置。删除不存在的条目不会触发异常。 16913 16914**系统能力：** SystemCapability.Web.Webview.Core 16915 16916**参数：** 16917 16918| 参数名 | 类型 | 必填 | 说明 | 16919| ---------- | ------ | ---- | -------------------------------- | 16920| domainSuffixes | Array\<string\> | 是 | 一组域名列表，例如['example.com', 'abcd.efg.com'] | 16921 16922**错误码：** 16923 16924以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 16925 16926| 错误码ID | 错误信息 | 16927| -------- | ----------------------- | 16928| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 16929 16930**示例：** 16931 16932```ts 16933// xxx.ets 16934import { webview } from '@kit.ArkWeb'; 16935 16936// 演示通过一个按钮的点击从AdsBlockManager的DisallowedList中删除域名元素 16937@Entry 16938@Component 16939struct WebComponent { 16940 main_url: string = 'https://www.example.com'; 16941 text_input_controller: TextInputController = new TextInputController(); 16942 controller: webview.WebviewController = new webview.WebviewController(); 16943 @State input_text: string = 'https://www.example.com'; 16944 16945 build() { 16946 Column() { 16947 Row() { 16948 Flex() { 16949 TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller}) 16950 .id("input_url") 16951 .height(40) 16952 .margin(5) 16953 .borderColor(Color.Blue) 16954 .onChange((value: string) => { 16955 this.input_text = value; 16956 }) 16957 16958 Button({type: ButtonType.Capsule}) { Text("Go") } 16959 .onClick(() => { 16960 this.controller.loadUrl(this.input_text); 16961 }) 16962 16963 Button({type: ButtonType.Capsule}) { Text("removeAdsBlockAllowedList") } 16964 .onClick(() => { 16965 let arrDomainSuffixes = new Array<string>(); 16966 arrDomainSuffixes.push('example.com'); 16967 arrDomainSuffixes.push('abcdefg.cn'); 16968 webview.AdsBlockManager.removeAdsBlockAllowedList(arrDomainSuffixes); 16969 }) 16970 } 16971 } 16972 Web({ src: this.main_url, controller: this.controller }) 16973 .onControllerAttached(()=>{ 16974 this.controller.enableAdsBlock(true); 16975 }) 16976 } 16977 } 16978} 16979``` 16980 16981### clearAdsBlockAllowedList<sup>12+</sup> 16982 16983static clearAdsBlockAllowedList(): void 16984 16985清空AdsBlockManager的AllowedList。 16986 16987**系统能力：** SystemCapability.Web.Webview.Core 16988 16989**示例：** 16990 16991```ts 16992// xxx.ets 16993import { webview } from '@kit.ArkWeb'; 16994 16995@Entry 16996@Component 16997struct WebComponent { 16998 main_url: string = 'https://www.example.com'; 16999 text_input_controller: TextInputController = new TextInputController(); 17000 controller: webview.WebviewController = new webview.WebviewController(); 17001 @State input_text: string = 'https://www.example.com'; 17002 17003 17004 build() { 17005 Column() { 17006 Row() { 17007 Flex() { 17008 TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller}) 17009 .id("input_url") 17010 .height(40) 17011 .margin(5) 17012 .borderColor(Color.Blue) 17013 .onChange((value: string) => { 17014 this.input_text = value; 17015 }) 17016 17017 Button({type: ButtonType.Capsule}) { Text("Go") } 17018 .onClick(() => { 17019 this.controller.loadUrl(this.input_text); 17020 }) 17021 17022 Button({type: ButtonType.Capsule}) { Text("clearAdsBlockAllowedList") } 17023 .onClick(() => { 17024 webview.AdsBlockManager.clearAdsBlockAllowedList(); 17025 }) 17026 } 17027 } 17028 Web({ src: this.main_url, controller: this.controller }) 17029 .onControllerAttached(()=>{ 17030 this.controller.enableAdsBlock(true); 17031 }) 17032 } 17033 } 17034} 17035``` 17036 17037## SnapshotInfo<sup>12+</sup> 17038 17039获取全量绘制结果入参。 17040 17041**系统能力：** SystemCapability.Web.Webview.Core 17042 17043| 名称 | 类型 | 必填 | 说明 | 17044|------|------|------|------| 17045| id | string | 否 | snapshot的id。| 17046| size | [SizeOptions](../apis-arkui/arkui-ts/ts-types.md#sizeoptions) | 否 | web绘制的尺寸，最多支持16000px * 16000px, 长度单位支持px、vp、%，需保持不同参数传入长度单位一致, 默认单位vp，超过规格时返回最大规格。（示例：width:'100px', height:'200px'。或者 width:'20%', height'30%'。只写数字时单位为vp。）| 17047 17048## SnapshotResult<sup>12+</sup> 17049 17050全量绘制回调结果。 17051 17052**系统能力：** SystemCapability.Web.Webview.Core 17053 17054| 名称 | 类型 | 必填 | 说明 | 17055|------|------|--|---------| 17056| id | string | 否 | snapshot的id。| 17057| status | boolean | 否 | snapshot的状态，正常为true，失败为false，获取全量绘制结果失败，返回size的长宽都为0，map为空。| 17058| size | [SizeOptions](../apis-arkui/arkui-ts/ts-types.md#sizeoptions) | 否 | web绘制的真实尺寸，number类型，单位vp。| 17059| imagePixelMap | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | 否 | 全量绘制结果image.pixelMap格式。| 17060 17061> **说明：** 17062> 17063> 仅支持对渲染进程上的资源进行截图：静态图片和文本。 17064> 不支持动态视频，如果页面有视频则截图时会显示该视频的占位图片。 17065 17066## ScrollType<sup>12+</sup> 17067 17068Scroll滚动类型，用于[setScrollable](#setscrollable12)。 17069 17070**系统能力：** SystemCapability.Web.Webview.Core 17071 17072| 名称 | 值 | 说明 | 17073| ------------ | -- |--------------------------------- | 17074| EVENT | 0 | 滚动事件，表示通过触摸屏，触摸板，鼠标滚轮生成的网页滚动。| 17075 17076## PressureLevel<sup>14+</sup> 17077 17078内存压力等级。在应用主动清理Web组件占用的缓存时，Web内核会根据内存压力等级，进行缓存释放。 17079 17080**系统能力：** SystemCapability.Web.Webview.Core 17081 17082| 名称 | 值 | 说明 | 17083| ------------------------------- | - | ---------- | 17084| MEMORY_PRESSURE_LEVEL_MODERATE | 1 | 中等内存压力等级。这个等级下，Web内核会尝试释放重新分配开销较小且不需要立即使用的缓存。 | 17085| MEMORY_PRESSURE_LEVEL_CRITICAL | 2 | 严重内存压力等级。这个等级下，Web内核会尝试释放所有可能的内存缓存。 | 17086 17087## PdfConfiguration<sup>14+</sup> 17088 17089createPdf函数输入参数。 17090 17091> **说明：** 17092> 17093> 英寸与像素之间转换公式：像素 = 96 * 英寸。 17094 17095**系统能力：** SystemCapability.Web.Webview.Core 17096 17097| 名称 | 类型 | 必填 | 说明 | 17098| --------------------- | ------- | ---- | ------------------------------------------------------------ | 17099| width | number | 是 | 页面宽度。单位：英寸。<br />推荐值：A4纸页面宽度8.27英寸。 | 17100| height | number | 是 | 页面高度。单位：英寸。<br />推荐值：A4纸页面高度11.69英寸。 | 17101| scale | number | 否 | 放大倍数。取值范围：[0.0, 2.0]。如果不在取值范围内，小于0.0设置为0.0，大于2.0设置为2.0。默认值：1.0。 | 17102| marginTop | number | 是 | 上边距。取值范围：[0.0, 页面高度的一半)。如果不在取值范围内，则设置为0.0。单位：英寸。 | 17103| marginBottom | number | 是 | 下边距。取值范围：[0.0, 页面高度的一半)。如果不在取值范围内，则设置为0.0。单位：英寸。 | 17104| marginRight | number | 是 | 右边距。取值范围：[0.0, 页面宽度的一半)。如果不在取值范围内，则设置为0.0。单位：英寸。 | 17105| marginLeft | number | 是 | 左边距。取值范围：[0.0, 页面宽度的一半)。如果不在取值范围内，则设置为0.0。单位：英寸。 | 17106| shouldPrintBackground | boolean | 否 | 是否打印背景颜色。默认值：false。 | 17107 17108## PdfData<sup>14+</sup> 17109 17110createPdf函数输出数据流类。 17111 17112> **说明：** 17113> 17114> 在网页生成PDF过程中，返回的是数据流，由PdfData类封装。 17115 17116### pdfArrayBuffer<sup>14+</sup> 17117 17118pdfArrayBuffer(): Uint8Array 17119 17120获取网页生成的数据流。完整示例代码参考[createPdf](#createpdf14)。 17121 17122**系统能力：** SystemCapability.Web.Webview.Core 17123 17124**返回值：** 17125 17126| 类型 | 说明 | 17127| ---------- | -------- | 17128| Uint8Array | 数据流。 | 17129 17130## ScrollOffset<sup>13+</sup> 17131 17132网页当前的滚动偏移量。 17133 17134**系统能力：** SystemCapability.Web.Webview.Core 17135 17136| 名称 | 类型 | 可读 | 可写 | 说明 | 17137| ---- | ------ | ---- | ---- | ------------------------------------------------------------ | 17138| x | number | 是 | 是 | 网页在水平方向的滚动偏移量。取值为网页左边界x坐标与Web组件左边界x坐标的差值。单位为vp。<br/>当网页向右过滚动时，取值范围为负值。<br/>当网页没有过滚动或者网页向左过滚动时，取值为0或正值。 | 17139| y | number | 是 | 是 | 网页在垂直方向的滚动偏移量。取值为网页上边界y坐标与Web组件上边界y坐标的差值。单位为vp。<br/>当网页向下过滚动时，取值范围为负值。<br/>当网页没有过滚动或者网页向上过滚动时，取值为0或正值。 | 17140
