1# Web 2 3提供具有网页显示能力的Web组件，[@ohos.web.webview](js-apis-webview.md)提供web控制能力。 4 5> **说明：** 6> 7> - 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> - 示例效果请以真机运行为准，当前DevEco Studio预览器不支持。 9 10## 需要权限 11 12访问在线网页时需添加网络权限：ohos.permission.INTERNET，具体申请方式请参考[声明权限](../../security/AccessToken/declare-permissions.md)。 13 14## 子组件 15 16无 17 18## 接口 19 20Web(value: WebOptions) 21 22> **说明：** 23> 24> 不支持转场动画。 25> 26> 同一页面的多个Web组件，必须绑定不同的WebviewController。 27 28**系统能力：** SystemCapability.Web.Webview.Core 29 30**参数：** 31 32| 参数名 | 类型 | 必填 | 说明 | 33| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 34| value | [WebOptions](#weboptions) | 是 | 定义Web选项。 | 35 36**示例：** 37 38加载在线网页。 39 40 ```ts 41 // xxx.ets 42 import { webview } from '@kit.ArkWeb'; 43 44 @Entry 45 @Component 46 struct WebComponent { 47 controller: webview.WebviewController = new webview.WebviewController(); 48 49 build() { 50 Column() { 51 Web({ src: 'www.example.com', controller: this.controller }) 52 } 53 } 54 } 55 ``` 56 57隐私模式Webview加载在线网页。 58 59 ```ts 60 // xxx.ets 61 import { webview } from '@kit.ArkWeb'; 62 63 @Entry 64 @Component 65 struct WebComponent { 66 controller: webview.WebviewController = new webview.WebviewController(); 67 68 build() { 69 Column() { 70 Web({ src: 'www.example.com', controller: this.controller, incognitoMode: true }) 71 } 72 } 73 } 74 ``` 75 76Web组件同步渲染模式。 77 78 ```ts 79 // xxx.ets 80 import { webview } from '@kit.ArkWeb'; 81 82 @Entry 83 @Component 84 struct WebComponent { 85 controller: webview.WebviewController = new webview.WebviewController(); 86 87 build() { 88 Column() { 89 Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER }) 90 } 91 } 92 } 93 ``` 94 95Web组件指定共享渲染进程。 96 97 ```ts 98 // xxx.ets 99 import { webview } from '@kit.ArkWeb'; 100 101 @Entry 102 @Component 103 struct WebComponent { 104 controller: webview.WebviewController = new webview.WebviewController(); 105 106 build() { 107 Column() { 108 Web({ src: 'www.example.com', controller: this.controller, sharedRenderProcessToken: "111" }) 109 Web({ src: 'www.w3.org', controller: this.controller, sharedRenderProcessToken: "111" }) 110 } 111 } 112 } 113 ``` 114 115加载本地网页。 116 117通过$rawfile方式加载。 118 ```ts 119 // xxx.ets 120 import { webview } from '@kit.ArkWeb'; 121 122 @Entry 123 @Component 124 struct WebComponent { 125 controller: webview.WebviewController = new webview.WebviewController(); 126 127 build() { 128 Column() { 129 // 通过$rawfile加载本地资源文件。 130 Web({ src: $rawfile("index.html"), controller: this.controller }) 131 } 132 } 133 } 134 ``` 135 136通过resources协议加载，适用Webview加载带有"#"路由的链接。 137 ```ts 138 // xxx.ets 139 import { webview } from '@kit.ArkWeb'; 140 141 @Entry 142 @Component 143 struct WebComponent { 144 controller: webview.WebviewController = new webview.WebviewController(); 145 146 build() { 147 Column() { 148 // 通过resource协议加载本地资源文件。 149 Web({ src: "resource://rawfile/index.html", controller: this.controller }) 150 } 151 } 152 } 153 ``` 154 155加载沙箱路径下的本地资源文件，需要开启应用中文件系统的访问[fileAccess](#fileaccess)权限。 156 1571. 通过构造的单例对象GlobalContext获取沙箱路径。 158 159 ```ts 160 // GlobalContext.ets 161 export class GlobalContext { 162 private constructor() {} 163 private static instance: GlobalContext; 164 private _objects = new Map<string, Object>(); 165 166 public static getContext(): GlobalContext { 167 if (!GlobalContext.instance) { 168 GlobalContext.instance = new GlobalContext(); 169 } 170 return GlobalContext.instance; 171 } 172 173 getObject(value: string): Object | undefined { 174 return this._objects.get(value); 175 } 176 177 setObject(key: string, objectClass: Object): void { 178 this._objects.set(key, objectClass); 179 } 180 } 181 ``` 182 183 ```ts 184 // xxx.ets 185 import { webview } from '@kit.ArkWeb'; 186 import { GlobalContext } from '../GlobalContext'; 187 188 let url = 'file://' + GlobalContext.getContext().getObject("filesDir") + '/index.html'; 189 190 @Entry 191 @Component 192 struct WebComponent { 193 controller: webview.WebviewController = new webview.WebviewController(); 194 195 build() { 196 Column() { 197 // 加载沙箱路径文件。 198 Web({ src: url, controller: this.controller }) 199 .fileAccess(true) 200 } 201 } 202 } 203 ``` 204 2052. 修改EntryAbility.ets。 206 207 以filesDir为例，获取沙箱路径。若想获取其他路径，请参考[应用文件路径](../../application-models/application-context-stage.md#获取应用文件路径)。 208 209 ```ts 210 // xxx.ets 211 import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 212 import { webview } from '@kit.ArkWeb'; 213 import { GlobalContext } from '../GlobalContext'; 214 215 export default class EntryAbility extends UIAbility { 216 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 217 // 通过在GlobalContext对象上绑定filesDir，可以实现UIAbility组件与UI之间的数据同步。 218 GlobalContext.getContext().setObject("filesDir", this.context.filesDir); 219 console.log("Sandbox path is " + GlobalContext.getContext().getObject("filesDir")); 220 } 221 } 222 ``` 223 224 加载的html文件。 225 226 ```html 227 <!-- index.html --> 228 <!DOCTYPE html> 229 <html> 230 <body> 231 <p>Hello World</p> 232 </body> 233 </html> 234 ``` 235 236## WebOptions 237 238通过[接口](#接口)定义Web选项。 239 240**系统能力：** SystemCapability.Web.Webview.Core 241 242| 名称 | 类型 | 必填 | 说明 | 243| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 244| src | string \| [Resource](../apis-arkui/arkui-ts/ts-types.md#resource) | 是 | 网页资源地址。如果访问本地资源文件，请使用$rawfile或者resource协议。如果加载应用包外沙箱路径的本地资源文件(文件支持html和txt类型)，请使用file://沙箱文件路径。<br>src不能通过状态变量（例如：@State）动态更改地址，如需更改，请通过[loadUrl()](js-apis-webview.md#loadurl)重新加载。 | 245| controller | [WebController](#webcontroller) \| [WebviewController<sup>9+</sup>](#webviewcontroller9) | 是 | 控制器。从API Version 9开始，WebController不再维护，建议使用WebviewController替代。 | 246| renderMode<sup>12+</sup> | [RenderMode](#rendermode12枚举说明)| 否 | 表示当前Web组件的渲染方式，RenderMode.ASYNC_RENDER表示Web组件自渲染，RenderMode.SYNC_RENDER表示支持Web组件统一渲染能力，默认值RenderMode.ASYNC_RENDER, 该模式不支持动态调整。 | 247| incognitoMode<sup>11+</sup> | boolean | 否 | 表示当前创建的webview是否是隐私模式。true表示创建隐私模式的webview, false表示创建正常模式的webview。<br> 默认值：false | 248| sharedRenderProcessToken<sup>12+</sup> | string | 否 | 表示当前Web组件指定共享渲染进程的token, 多渲染进程模式下，相同token的Web组件会优先尝试复用与token相绑定的渲染进程。token与渲染进程的绑定发生在渲染进程的初始化阶段。当渲染进程没有关联的Web组件时，其与token绑定关系将被移除。<br> 默认值： "" | 249 250## WebviewController<sup>9+</sup> 251 252type WebviewController = WebviewController 253 254提供Web控制器的方法。 255 256**系统能力：** SystemCapability.Web.Webview.Core 257 258| 类型 | 说明 | 259| ------ | ---------- | 260| [WebviewController](js-apis-webview.md#webviewcontroller) | 通过WebviewController可以控制Web组件各种行为。一个WebviewController对象只能控制一个Web组件，且必须在Web组件和WebviewController绑定后，才能调用WebviewController上的方法（静态方法除外）。 | 261 262## 属性 263 264通用属性仅支持[aspectRatio](../apis-arkui/arkui-ts/ts-universal-attributes-layout-constraints.md#aspectratio)、[backdropBlur](../apis-arkui/arkui-ts/ts-universal-attributes-background.md#backdropblur)、[backgroundColor](../apis-arkui/arkui-ts/ts-universal-attributes-background.md#backgroundcolor)、[bindContentCover](../apis-arkui/arkui-ts/ts-universal-attributes-modal-transition.md#bindcontentcover)、[bindContextMenu](../apis-arkui/arkui-ts/ts-universal-attributes-menu.md#bindcontextmenu8)、[bindMenu ](../apis-arkui/arkui-ts/ts-universal-attributes-menu.md#bindmenu)、[bindSheet](../apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#bindsheet)、[borderColor](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#bordercolor)、[borderRadius](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#borderradius)、[borderStyle](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#borderstyle)、[borderWidth](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#borderwidth)、[clip](../apis-arkui/arkui-ts/ts-universal-attributes-sharp-clipping.md#clip)、[constraintSize](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#constraintsize)、[defaultFocus](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#defaultfocus9)、[focusable](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#focusable)、[tabIndex](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#tabindex9)、[groupDefaultFocus](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#groupdefaultfocus9)、[displayPriority](../apis-arkui/arkui-ts/ts-universal-attributes-layout-constraints.md#displaypriority)、[enabled](../apis-arkui/arkui-ts/ts-universal-attributes-enable.md#enabled)、[flexBasis](../apis-arkui/arkui-ts/ts-universal-attributes-flex-layout.md#flexbasis)、[flexShrink](../apis-arkui/arkui-ts/ts-universal-attributes-flex-layout.md#flexshrink)、[layoutWeight](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#layoutweight)、[id](../apis-arkui/arkui-ts/ts-universal-attributes-component-id.md)、[gridOffset](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md)、[gridSpan](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md)、[useSizeType](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md)、[height](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#height)、[touchable](../apis-arkui/arkui-ts/ts-universal-attributes-click.md)、[margin](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#margin)、[markAnchor](../apis-arkui/arkui-ts/ts-universal-attributes-location.md#markanchor)、[offset](../apis-arkui/arkui-ts/ts-universal-attributes-location.md#offset)、[width](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#width)、[zIndex](../apis-arkui/arkui-ts/ts-universal-attributes-z-order.md#zindex)、[visibility](../apis-arkui/arkui-ts/ts-universal-attributes-visibility.md#visibility)、[scale](../apis-arkui/arkui-ts/ts-universal-attributes-transformation.md#scale)、[translate](../apis-arkui/arkui-ts/ts-universal-attributes-transformation.md#translate)、[responseRegion](../apis-arkui/arkui-ts/ts-universal-attributes-touch-target.md#responseregion)、[size](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#size)、[opacity](../apis-arkui/arkui-ts/ts-universal-attributes-opacity.md#opacity)、[shadow](../apis-arkui/arkui-ts/ts-universal-attributes-image-effect.md#shadow)、[sharedTransition](../apis-arkui/arkui-ts/ts-transition-animation-shared-elements.md)、[transition](../apis-arkui/arkui-ts/ts-transition-animation-component.md)。 265 266### domStorageAccess 267 268domStorageAccess(domStorageAccess: boolean) 269 270设置是否开启文档对象模型存储接口（DOM Storage API）权限，默认未开启。 271 272**系统能力：** SystemCapability.Web.Webview.Core 273 274**参数：** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| ---------------- | ------- | ---- | ------------------------------------ | 278| domStorageAccess | boolean | 是 | 设置是否开启文档对象模型存储接口（DOM Storage API）权限。默认值：false。 | 279 280**示例：** 281 282 ```ts 283 // xxx.ets 284 import { webview } from '@kit.ArkWeb'; 285 286 @Entry 287 @Component 288 struct WebComponent { 289 controller: webview.WebviewController = new webview.WebviewController(); 290 291 build() { 292 Column() { 293 Web({ src: 'www.example.com', controller: this.controller }) 294 .domStorageAccess(true) 295 } 296 } 297 } 298 ``` 299 300### fileAccess 301 302fileAccess(fileAccess: boolean) 303 304设置是否开启应用中文件系统的访问。[$rawfile(filepath/filename)](../../quick-start/resource-categories-and-access.md)中rawfile路径的文件不受该属性影响而限制访问。 305 306从API version 12开始，fileAccess默认不启用。同时，当fileAccess为false的时候，仅只读资源目录/data/storage/el1/bundle/entry/resources/resfile里面的file协议资源依然可以访问，不受fileAccess管控。 307 308**系统能力：** SystemCapability.Web.Webview.Core 309 310**参数：** 311 312| 参数名 | 类型 | 必填 | 说明 | 313| ---------- | ------- | ---- | ---------------------- | 314| fileAccess | boolean | 是 | API version 11及以前：默认为true，启动应用中文件系统的访问。API version 12及以后：默认为false，不启用应用中文件系统的访问。 | 315 316**示例：** 317 318 ```ts 319 // xxx.ets 320 import { webview } from '@kit.ArkWeb'; 321 322 @Entry 323 @Component 324 struct WebComponent { 325 controller: webview.WebviewController = new webview.WebviewController(); 326 327 build() { 328 Column() { 329 Web({ src: 'www.example.com', controller: this.controller }) 330 .fileAccess(true) 331 } 332 } 333 } 334 ``` 335 336### imageAccess 337 338imageAccess(imageAccess: boolean) 339 340设置是否允许自动加载图片资源，默认允许。 341 342**系统能力：** SystemCapability.Web.Webview.Core 343 344**参数：** 345 346| 参数名 | 类型 | 必填 | 说明 | 347| ----------- | ------- | ---- | --------------- | 348| imageAccess | boolean | 是 | 设置是否允许自动加载图片资源。默认值：true。 | 349 350**示例：** 351 ```ts 352 // xxx.ets 353 import { webview } from '@kit.ArkWeb'; 354 355 @Entry 356 @Component 357 struct WebComponent { 358 controller: webview.WebviewController = new webview.WebviewController(); 359 360 build() { 361 Column() { 362 Web({ src: 'www.example.com', controller: this.controller }) 363 .imageAccess(true) 364 } 365 } 366 } 367 ``` 368 369### javaScriptProxy 370 371javaScriptProxy(javaScriptProxy: JavaScriptProxy) 372 373注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。所有参数不支持更新。注册对象时，同步与异步方法列表请至少选择一项不为空，可同时注册两类方法。同一方法在同步与异步列表中重复注册，将默认异步调用。此接口只支持注册一个对象，若需要注册多个对象请使用[registerJavaScriptProxy<sup>9+</sup>](js-apis-webview.md#registerjavascriptproxy)。 374 375**系统能力：** SystemCapability.Web.Webview.Core 376 377**参数：** 378 379| 参数名 | 类型 | 必填 | 说明 | 380| ---------- | ---------------------------------------- | ---- |---------------------------------------- | 381| javaScriptProxy | [JavaScriptProxy](#javascriptproxy12) | 是 | 参与注册的对象。只能声明方法，不能声明属性。 | 382 383**示例：** 384 385 ```ts 386 // xxx.ets 387 import { webview } from '@kit.ArkWeb'; 388 389 class TestObj { 390 constructor() { 391 } 392 393 test(data1: string, data2: string, data3: string): string { 394 console.log("data1:" + data1); 395 console.log("data2:" + data2); 396 console.log("data3:" + data3); 397 return "AceString"; 398 } 399 400 asyncTest(data: string): void { 401 console.log("async data:" + data); 402 } 403 404 toString(): void { 405 console.log('toString' + "interface instead."); 406 } 407 } 408 409 @Entry 410 @Component 411 struct WebComponent { 412 controller: webview.WebviewController = new webview.WebviewController(); 413 testObj = new TestObj(); 414 build() { 415 Column() { 416 Button('deleteJavaScriptRegister') 417 .onClick(() => { 418 try { 419 this.controller.deleteJavaScriptRegister("objName"); 420 } catch (error) { 421 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 422 } 423 }) 424 Web({ src: 'www.example.com', controller: this.controller }) 425 .javaScriptAccess(true) 426 .javaScriptProxy({ 427 object: this.testObj, 428 name: "objName", 429 methodList: ["test", "toString"], 430 asyncMethodList: ["asyncTest"], 431 controller: this.controller, 432 }) 433 } 434 } 435 } 436 ``` 437 438### javaScriptAccess 439 440javaScriptAccess(javaScriptAccess: boolean) 441 442设置是否允许执行JavaScript脚本，默认允许执行。 443 444**系统能力：** SystemCapability.Web.Webview.Core 445 446**参数：** 447 448| 参数名 | 类型 | 必填 | 说明 | 449| ---------------- | ------- | ---- | ------------------- | 450| javaScriptAccess | boolean | 是 | 是否允许执行JavaScript脚本。默认值：true。 | 451 452**示例：** 453 454 ```ts 455 // xxx.ets 456 import { webview } from '@kit.ArkWeb'; 457 458 @Entry 459 @Component 460 struct WebComponent { 461 controller: webview.WebviewController = new webview.WebviewController(); 462 build() { 463 Column() { 464 Web({ src: 'www.example.com', controller: this.controller }) 465 .javaScriptAccess(true) 466 } 467 } 468 } 469 ``` 470 471### overScrollMode<sup>11+</sup> 472 473overScrollMode(mode: OverScrollMode) 474 475设置Web过滚动模式，默认关闭。当过滚动模式开启时，当用户在Web根页面上滑动到边缘时，Web会通过弹性动画弹回界面，根页面上的内部页面不会触发回弹。 476 477**系统能力：** SystemCapability.Web.Webview.Core 478 479**参数：** 480 481| 参数名 | 类型 | 必填 | 说明 | 482| ---- | --------------------------------------- | ---- | ------------------ | 483| mode | [OverScrollMode](#overscrollmode11枚举说明) | 是 | 设置Web的过滚动模式为关闭或开启。默认值：OverScrollMode.NEVER。 | 484 485**示例：** 486 487 ```ts 488 // xxx.ets 489 import { webview } from '@kit.ArkWeb'; 490 491 @Entry 492 @Component 493 struct WebComponent { 494 controller: webview.WebviewController = new webview.WebviewController(); 495 @State mode: OverScrollMode = OverScrollMode.ALWAYS; 496 build() { 497 Column() { 498 Web({ src: 'www.example.com', controller: this.controller }) 499 .overScrollMode(this.mode) 500 } 501 } 502 } 503 ``` 504 505### mixedMode 506 507mixedMode(mixedMode: MixedMode) 508 509设置是否允许加载超文本传输协议（HTTP）和超文本传输安全协议（HTTPS）混合内容，默认不允许加载HTTP和HTTPS混合内容。 510 511**系统能力：** SystemCapability.Web.Webview.Core 512 513**参数：** 514 515| 参数名 | 类型 | 必填 | 说明 | 516| --------- | --------------------------- | ---- | --------- | 517| mixedMode | [MixedMode](#mixedmode枚举说明) | 是 | 要设置的混合内容。默认值：MixedMode.None。 | 518 519**示例：** 520 521 ```ts 522 // xxx.ets 523 import { webview } from '@kit.ArkWeb'; 524 525 @Entry 526 @Component 527 struct WebComponent { 528 controller: webview.WebviewController = new webview.WebviewController(); 529 @State mode: MixedMode = MixedMode.All; 530 build() { 531 Column() { 532 Web({ src: 'www.example.com', controller: this.controller }) 533 .mixedMode(this.mode) 534 } 535 } 536 } 537 ``` 538 539### onlineImageAccess 540 541onlineImageAccess(onlineImageAccess: boolean) 542 543设置是否允许从网络加载图片资源（通过HTTP和HTTPS访问的资源），默认允许访问。 544 545**系统能力：** SystemCapability.Web.Webview.Core 546 547**参数：** 548 549| 参数名 | 类型 | 必填 | 说明 | 550| ----------------- | ------- | ---- | ---------------- | 551| onlineImageAccess | boolean | 是 | 设置是否允许从网络加载图片资源。默认值：true。 | 552 553**示例：** 554 555 ```ts 556 // xxx.ets 557 import { webview } from '@kit.ArkWeb'; 558 559 @Entry 560 @Component 561 struct WebComponent { 562 controller: webview.WebviewController = new webview.WebviewController(); 563 564 build() { 565 Column() { 566 Web({ src: 'www.example.com', controller: this.controller }) 567 .onlineImageAccess(true) 568 } 569 } 570 } 571 ``` 572 573### zoomAccess 574 575zoomAccess(zoomAccess: boolean) 576 577设置是否支持手势进行缩放，默认允许执行缩放。 578 579**系统能力：** SystemCapability.Web.Webview.Core 580 581**参数：** 582 583| 参数名 | 类型 | 必填 | 说明 | 584| ---------- | ------- | ---- | ------------- | 585| zoomAccess | boolean | 是 | 设置是否支持手势进行缩放。默认值：true。 | 586 587**示例：** 588 589 ```ts 590 // xxx.ets 591 import { webview } from '@kit.ArkWeb'; 592 593 @Entry 594 @Component 595 struct WebComponent { 596 controller: webview.WebviewController = new webview.WebviewController(); 597 598 build() { 599 Column() { 600 Web({ src: 'www.example.com', controller: this.controller }) 601 .zoomAccess(true) 602 } 603 } 604 } 605 ``` 606 607### overviewModeAccess 608 609overviewModeAccess(overviewModeAccess: boolean) 610 611设置是否使用概览模式加载网页，默认使用该方式。当前仅支持移动设备。 612 613**系统能力：** SystemCapability.Web.Webview.Core 614 615**参数：** 616 617| 参数名 | 类型 | 必填 | 说明 | 618| ------------------ | ------- | ---- | --------------- | 619| overviewModeAccess | boolean | 是 | 设置是否使用概览模式加载网页。默认值：true。 | 620 621**示例：** 622 623 ```ts 624 // xxx.ets 625 import { webview } from '@kit.ArkWeb'; 626 627 @Entry 628 @Component 629 struct WebComponent { 630 controller: webview.WebviewController = new webview.WebviewController(); 631 632 build() { 633 Column() { 634 Web({ src: 'www.example.com', controller: this.controller }) 635 .overviewModeAccess(true) 636 } 637 } 638 } 639 ``` 640 641### databaseAccess 642 643databaseAccess(databaseAccess: boolean) 644 645设置是否开启数据库存储API权限，默认不开启。 646 647**系统能力：** SystemCapability.Web.Webview.Core 648 649**参数：** 650 651| 参数名 | 类型 | 必填 | 说明 | 652| -------------- | ------- | ---- | ----------------- | 653| databaseAccess | boolean | 是 | 设置是否开启数据库存储API权限。默认值：false。 | 654 655**示例：** 656 657 ```ts 658 // xxx.ets 659 import { webview } from '@kit.ArkWeb'; 660 661 @Entry 662 @Component 663 struct WebComponent { 664 controller: webview.WebviewController = new webview.WebviewController(); 665 666 build() { 667 Column() { 668 Web({ src: 'www.example.com', controller: this.controller }) 669 .databaseAccess(true) 670 } 671 } 672 } 673 ``` 674 675### geolocationAccess 676 677geolocationAccess(geolocationAccess: boolean) 678 679设置是否开启获取地理位置权限，默认开启。具体使用方式参考[管理位置权限](../../web/web-geolocation-permission.md)。 680 681**系统能力：** SystemCapability.Web.Webview.Core 682 683**参数：** 684 685| 参数名 | 类型 | 必填 | 说明 | 686| ----------------- | ------- | ---- | --------------- | 687| geolocationAccess | boolean | 是 | 设置是否开启获取地理位置权限。默认值：true。 | 688 689**示例：** 690 691 ```ts 692 // xxx.ets 693 import { webview } from '@kit.ArkWeb'; 694 695 @Entry 696 @Component 697 struct WebComponent { 698 controller: webview.WebviewController = new webview.WebviewController(); 699 700 build() { 701 Column() { 702 Web({ src: 'www.example.com', controller: this.controller }) 703 .geolocationAccess(true) 704 } 705 } 706 } 707 ``` 708 709### mediaPlayGestureAccess<sup>9+</sup> 710 711mediaPlayGestureAccess(access: boolean) 712 713设置有声视频播放是否需要用户手动点击，静音视频播放不受该接口管控，默认需要。 714 715**系统能力：** SystemCapability.Web.Webview.Core 716 717**参数：** 718 719| 参数名 | 类型 | 必填 | 说明 | 720| ------ | ------- | ---- | ------------------- | 721| access | boolean | 是 | 设置有声视频播放是否需要用户手动点击。默认值：true。 | 722 723**示例：** 724 725 ```ts 726 // xxx.ets 727 import { webview } from '@kit.ArkWeb'; 728 729 @Entry 730 @Component 731 struct WebComponent { 732 controller: webview.WebviewController = new webview.WebviewController(); 733 @State access: boolean = true; 734 735 build() { 736 Column() { 737 Web({ src: 'www.example.com', controller: this.controller }) 738 .mediaPlayGestureAccess(this.access) 739 } 740 } 741 } 742 ``` 743 744### multiWindowAccess<sup>9+</sup> 745 746multiWindowAccess(multiWindow: boolean) 747 748设置是否开启多窗口权限，默认不开启。 749使能多窗口权限时，需要实现onWindowNew事件，示例代码参考[onWindowNew事件](#onwindownew9)。 750 751**系统能力：** SystemCapability.Web.Webview.Core 752 753**参数：** 754 755| 参数名 | 类型 | 必填 | 说明 | 756| ----------- | ------- | ---- | ------------ | 757| multiWindow | boolean | 是 | 设置是否开启多窗口权限。默认值：false。 | 758 759**示例：** 760 761 ```ts 762 // xxx.ets 763 import { webview } from '@kit.ArkWeb'; 764 765 @Entry 766 @Component 767 struct WebComponent { 768 controller: webview.WebviewController = new webview.WebviewController(); 769 770 build() { 771 Column() { 772 Web({ src: 'www.example.com', controller: this.controller }) 773 .multiWindowAccess(false) 774 } 775 } 776 } 777 ``` 778 779### horizontalScrollBarAccess<sup>9+</sup> 780 781horizontalScrollBarAccess(horizontalScrollBar: boolean) 782 783设置是否显示横向滚动条，包括系统默认滚动条和用户自定义滚动条。默认显示。 784 785> **说明：** 786> 787> - 通过@State变量控制横向滚动条的隐藏/显示后，需要调用controller.refresh()生效。 788> - 通过@State变量频繁动态改变时，建议切换开关变量和Web组件一一对应。 789 790**系统能力：** SystemCapability.Web.Webview.Core 791 792**参数：** 793 794| 参数名 | 类型 | 必填 | 说明 | 795| ------------------- | ------- | ---- | ------------ | 796| horizontalScrollBar | boolean | 是 | 设置是否显示横向滚动条。默认值：true。 | 797 798**示例：** 799 800 ```ts 801 // xxx.ets 802 import { webview } from '@kit.ArkWeb'; 803 import { BusinessError } from '@kit.BasicServicesKit'; 804 805 @Entry 806 @Component 807 struct WebComponent { 808 controller: webview.WebviewController = new webview.WebviewController(); 809 @State isShow: boolean = true; 810 @State btnMsg: string ="隐藏滚动条"; 811 812 build() { 813 Column() { 814 // 通过@State变量改变横向滚动条的隐藏/显示后，需调用this.controller.refresh()后生效 815 Button('refresh') 816 .onClick(() => { 817 if(this.isShow){ 818 this.isShow = false; 819 this.btnMsg="显示滚动条"; 820 }else{ 821 this.isShow = true; 822 this.btnMsg="隐藏滚动条"; 823 } 824 try { 825 this.controller.refresh(); 826 } catch (error) { 827 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 828 } 829 }).height("10%").width("40%") 830 Web({ src: $rawfile('index.html'), controller: this.controller }).height("90%") 831 .horizontalScrollBarAccess(this.isShow) 832 } 833 } 834 } 835 ``` 836 837 加载的html文件。 838 ```html 839 <!--index.html--> 840 <!DOCTYPE html> 841 <html> 842 <head> 843 <meta name="viewport" id="viewport" content="width=device-width,initial-scale=1.0"> 844 <title>Demo</title> 845 <style> 846 body { 847 width:3000px; 848 height:6000px; 849 padding-right:170px; 850 padding-left:170px; 851 border:5px solid blueviolet 852 } 853 </style> 854 </head> 855 <body> 856 Scroll Test 857 </body> 858 </html> 859 ``` 860 861### verticalScrollBarAccess<sup>9+</sup> 862 863verticalScrollBarAccess(verticalScrollBar: boolean) 864 865设置是否显示纵向滚动条，包括系统默认滚动条和用户自定义滚动条。默认显示。 866 867> **说明：** 868> 869> - 通过@State变量控制纵向滚动条的隐藏/显示后，需要调用controller.refresh()生效。 870> - 通过@State变量频繁动态改变时，建议切换开关变量和Web组件一一对应。 871 872**系统能力：** SystemCapability.Web.Webview.Core 873 874**参数：** 875 876| 参数名 | 类型 | 必填 | 说明 | 877| ----------------- | ------- | ---- | ------------ | 878| verticalScrollBar | boolean | 是 | 设置是否显示纵向滚动条。默认值：true。 | 879 880**示例：** 881 882 ```ts 883 // xxx.ets 884 import { webview } from '@kit.ArkWeb'; 885 import { BusinessError } from '@kit.BasicServicesKit'; 886 887 @Entry 888 @Component 889 struct WebComponent { 890 controller: webview.WebviewController = new webview.WebviewController(); 891 @State isShow: boolean = true; 892 @State btnMsg: string ="隐藏滚动条"; 893 894 build() { 895 Column() { 896 // 通过@State变量改变横向滚动条的隐藏/显示后，需调用this.controller.refresh()后生效 897 Button(this.btnMsg) 898 .onClick(() => { 899 if(this.isShow){ 900 this.isShow = false; 901 this.btnMsg="显示滚动条"; 902 }else{ 903 this.isShow = true; 904 this.btnMsg="隐藏滚动条"; 905 } 906 try { 907 this.controller.refresh(); 908 } catch (error) { 909 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 910 } 911 }).height("10%").width("40%") 912 Web({ src: $rawfile('index.html'), controller: this.controller }).height("90%") 913 .verticalScrollBarAccess(this.isShow) 914 } 915 } 916 } 917 ``` 918 919 加载的html文件。 920 ```html 921 <!--index.html--> 922 <!DOCTYPE html> 923 <html> 924 <head> 925 <meta name="viewport" id="viewport" content="width=device-width,initial-scale=1.0"> 926 <title>Demo</title> 927 <style> 928 body { 929 width:3000px; 930 height:6000px; 931 padding-right:170px; 932 padding-left:170px; 933 border:5px solid blueviolet 934 } 935 </style> 936 </head> 937 <body> 938 Scroll Test 939 </body> 940 </html> 941 ``` 942 943### password<sup>(deprecated)</sup> 944 945password(password: boolean) 946 947设置是否应保存密码。该接口为空接口。 948 949> **说明：** 950> 951> 从API version 10开始废弃，并且不再提供新的接口作为替代。 952 953**系统能力：** SystemCapability.Web.Webview.Core 954 955### cacheMode 956 957cacheMode(cacheMode: CacheMode) 958 959设置缓存模式。 960 961**系统能力：** SystemCapability.Web.Webview.Core 962 963**参数：** 964 965| 参数名 | 类型 | 必填 | 说明 | 966| --------- | --------------------------- | ---- | --------- | 967| cacheMode | [CacheMode](#cachemode枚举说明) | 是 | 要设置的缓存模式。默认值：CacheMode.Default。 | 968 969**示例：** 970 971 ```ts 972 // xxx.ets 973 import { webview } from '@kit.ArkWeb'; 974 975 @Entry 976 @Component 977 struct WebComponent { 978 controller: webview.WebviewController = new webview.WebviewController(); 979 @State mode: CacheMode = CacheMode.None; 980 981 build() { 982 Column() { 983 Web({ src: 'www.example.com', controller: this.controller }) 984 .cacheMode(this.mode) 985 } 986 } 987 } 988 ``` 989 990### copyOptions<sup>11+</sup> 991 992copyOptions(value: CopyOptions) 993 994设置剪贴板复制范围选项。 995 996**系统能力：** SystemCapability.Web.Webview.Core 997 998**参数：** 999 1000| 参数名 | 类型 | 必填 | 说明 | 1001| --------- | --------------------------- | ---- | --------- | 1002| value | [CopyOptions](../apis-arkui/arkui-ts/ts-appendix-enums.md#copyoptions9) | 是 | 要设置的剪贴板复制范围选项。默认值：CopyOptions.LocalDevice。 | 1003 1004**示例：** 1005 1006 ```ts 1007import { webview } from '@kit.ArkWeb'; 1008 1009@Entry 1010@Component 1011struct WebComponent { 1012 controller: webview.WebviewController = new webview.WebviewController(); 1013 1014 build() { 1015 Column() { 1016 Web({ src: 'www.example.com', controller: this.controller }) 1017 .copyOptions(CopyOptions.None) 1018 } 1019 } 1020} 1021 ``` 1022 1023### textZoomAtio<sup>(deprecated)</sup> 1024 1025textZoomAtio(textZoomAtio: number) 1026 1027设置页面的文本缩放百分比，默认为100。 1028 1029**系统能力：** SystemCapability.Web.Webview.Core 1030 1031从API version 9开始不再维护，建议使用[textZoomRatio<sup>9+</sup>](#textzoomratio9)代替。 1032 1033**参数：** 1034 1035| 参数名 | 类型 | 必填 | 说明 | 1036| ------------ | ------ | ---- | -------------------------------- | 1037| textZoomAtio | number | 是 | 要设置的页面的文本缩放百分比。取值为整数，范围为(0, +∞)。默认值：100。 | 1038 1039**示例：** 1040 1041 ```ts 1042 // xxx.ets 1043 @Entry 1044 @Component 1045 struct WebComponent { 1046 controller: WebController = new WebController() 1047 @State ratio: number = 150 1048 build() { 1049 Column() { 1050 Web({ src: 'www.example.com', controller: this.controller }) 1051 .textZoomAtio(this.ratio) 1052 } 1053 } 1054 } 1055 ``` 1056 1057### textZoomRatio<sup>9+</sup> 1058 1059textZoomRatio(textZoomRatio: number) 1060 1061设置页面的文本缩放百分比，默认为100。 1062 1063**系统能力：** SystemCapability.Web.Webview.Core 1064 1065**参数：** 1066 1067| 参数名 | 类型 | 必填 | 说明 | 1068| ------------- | ------ | ---- | -------------------------------- | 1069| textZoomRatio | number | 是 | 要设置的页面的文本缩放百分比。取值为整数，范围为(0, +∞)。默认值：100。 | 1070 1071**示例：** 1072 1073 ```ts 1074 // xxx.ets 1075 import { webview } from '@kit.ArkWeb'; 1076 1077 @Entry 1078 @Component 1079 struct WebComponent { 1080 controller: webview.WebviewController = new webview.WebviewController(); 1081 @State ratio: number = 150; 1082 1083 build() { 1084 Column() { 1085 Web({ src: 'www.example.com', controller: this.controller }) 1086 .textZoomRatio(this.ratio) 1087 } 1088 } 1089 } 1090 ``` 1091 1092### initialScale<sup>9+</sup> 1093 1094initialScale(percent: number) 1095 1096设置整体页面的缩放百分比，默认为100。 1097 1098**系统能力：** SystemCapability.Web.Webview.Core 1099 1100**参数：** 1101 1102| 参数名 | 类型 | 必填 | 说明 | 1103| ------- | ------ | ---- | ----------------------------- | 1104| percent | number | 是 | 要设置的整体页面的缩放百分比。默认值：100。 | 1105 1106**示例：** 1107 1108 ```ts 1109 // xxx.ets 1110 import { webview } from '@kit.ArkWeb'; 1111 1112 @Entry 1113 @Component 1114 struct WebComponent { 1115 controller: webview.WebviewController = new webview.WebviewController(); 1116 @State percent: number = 100; 1117 1118 build() { 1119 Column() { 1120 Web({ src: 'www.example.com', controller: this.controller }) 1121 .initialScale(this.percent) 1122 } 1123 } 1124 } 1125 ``` 1126 1127### userAgent<sup>(deprecated)</sup> 1128 1129userAgent(userAgent: string) 1130 1131设置用户代理。 1132 1133> **说明：** 1134> 1135> 从API version 8开始支持，从API version 10开始废弃。建议使用[setCustomUserAgent](js-apis-webview.md#setcustomuseragent10)<sup>10+</sup>替代。 1136 1137**系统能力：** SystemCapability.Web.Webview.Core 1138 1139**参数：** 1140 1141| 参数名 | 类型 | 必填 | 说明 | 1142| --------- | ------ | ---- | --------- | 1143| userAgent | string | 是 | 要设置的用户代理。 | 1144 1145**示例：** 1146 1147 ```ts 1148 // xxx.ets 1149 import { webview } from '@kit.ArkWeb'; 1150 1151 @Entry 1152 @Component 1153 struct WebComponent { 1154 controller: webview.WebviewController = new webview.WebviewController(); 1155 @State userAgent:string = 'Mozilla/5.0 (Phone; OpenHarmony 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 ArkWeb/4.1.6.1 Mobile DemoApp'; 1156 1157 build() { 1158 Column() { 1159 Web({ src: 'www.example.com', controller: this.controller }) 1160 .userAgent(this.userAgent) 1161 } 1162 } 1163 } 1164 ``` 1165 1166### blockNetwork<sup>9+</sup> 1167 1168blockNetwork(block: boolean) 1169 1170设置Web组件是否阻止从网络加载资源。 1171 1172**系统能力：** SystemCapability.Web.Webview.Core 1173 1174**参数：** 1175 1176| 参数名 | 类型 | 必填 | 说明 | 1177| ----- | ------- | ---- | ------------------- | 1178| block | boolean | 是 | 设置Web组件是否阻止从网络加载资源。默认值：false。 | 1179 1180**示例：** 1181 1182 ```ts 1183 // xxx.ets 1184 import { webview } from '@kit.ArkWeb'; 1185 1186 @Entry 1187 @Component 1188 struct WebComponent { 1189 controller: webview.WebviewController = new webview.WebviewController(); 1190 @State block: boolean = true; 1191 1192 build() { 1193 Column() { 1194 Web({ src: 'www.example.com', controller: this.controller }) 1195 .blockNetwork(this.block) 1196 } 1197 } 1198 } 1199 ``` 1200 1201### defaultFixedFontSize<sup>9+</sup> 1202 1203defaultFixedFontSize(size: number) 1204 1205设置网页的默认等宽字体大小。 1206 1207**系统能力：** SystemCapability.Web.Webview.Core 1208 1209**参数：** 1210 1211| 参数名 | 类型 | 必填 | 说明 | 1212| ---- | ------ | ---- | ---------------------------------------- | 1213| size | number | 是 | 设置网页的默认等宽字体大小，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。默认值：13。 | 1214 1215**示例：** 1216 1217 ```ts 1218 // xxx.ets 1219 import { webview } from '@kit.ArkWeb'; 1220 1221 @Entry 1222 @Component 1223 struct WebComponent { 1224 controller: webview.WebviewController = new webview.WebviewController(); 1225 @State fontSize: number = 16; 1226 1227 build() { 1228 Column() { 1229 Web({ src: 'www.example.com', controller: this.controller }) 1230 .defaultFixedFontSize(this.fontSize) 1231 } 1232 } 1233 } 1234 ``` 1235 1236### defaultFontSize<sup>9+</sup> 1237 1238defaultFontSize(size: number) 1239 1240设置网页的默认字体大小。 1241 1242**系统能力：** SystemCapability.Web.Webview.Core 1243 1244**参数：** 1245 1246| 参数名 | 类型 | 必填 | 说明 | 1247| ---- | ------ | ---- | ---------------------------------------- | 1248| size | number | 是 | 设置网页的默认字体大小，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。默认值：16。 | 1249 1250**示例：** 1251 1252 ```ts 1253 // xxx.ets 1254 import { webview } from '@kit.ArkWeb'; 1255 1256 @Entry 1257 @Component 1258 struct WebComponent { 1259 controller: webview.WebviewController = new webview.WebviewController(); 1260 @State fontSize: number = 13; 1261 1262 build() { 1263 Column() { 1264 Web({ src: 'www.example.com', controller: this.controller }) 1265 .defaultFontSize(this.fontSize) 1266 } 1267 } 1268 } 1269 ``` 1270 1271### minFontSize<sup>9+</sup> 1272 1273minFontSize(size: number) 1274 1275设置网页字体大小最小值。 1276 1277**系统能力：** SystemCapability.Web.Webview.Core 1278 1279**参数：** 1280 1281| 参数名 | 类型 | 必填 | 说明 | 1282| ---- | ------ | ---- | ---------------------------------------- | 1283| size | number | 是 | 设置网页字体大小最小值，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。默认值：8。 | 1284 1285**示例：** 1286 1287 ```ts 1288 // xxx.ets 1289 import { webview } from '@kit.ArkWeb'; 1290 1291 @Entry 1292 @Component 1293 struct WebComponent { 1294 controller: webview.WebviewController = new webview.WebviewController(); 1295 @State fontSize: number = 13; 1296 1297 build() { 1298 Column() { 1299 Web({ src: 'www.example.com', controller: this.controller }) 1300 .minFontSize(this.fontSize) 1301 } 1302 } 1303 } 1304 ``` 1305 1306### minLogicalFontSize<sup>9+</sup> 1307 1308minLogicalFontSize(size: number) 1309 1310设置网页逻辑字体大小最小值。 1311 1312**系统能力：** SystemCapability.Web.Webview.Core 1313 1314**参数：** 1315 1316| 参数名 | 类型 | 必填 | 说明 | 1317| ---- | ------ | ---- | ---------------------------------------- | 1318| size | number | 是 | 设置网页逻辑字体大小最小值，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。默认值：8。 | 1319 1320**示例：** 1321 1322 ```ts 1323 // xxx.ets 1324 import { webview } from '@kit.ArkWeb'; 1325 1326 @Entry 1327 @Component 1328 struct WebComponent { 1329 controller: webview.WebviewController = new webview.WebviewController(); 1330 @State fontSize: number = 13; 1331 1332 build() { 1333 Column() { 1334 Web({ src: 'www.example.com', controller: this.controller }) 1335 .minLogicalFontSize(this.fontSize) 1336 } 1337 } 1338 } 1339 ``` 1340 1341### webFixedFont<sup>9+</sup> 1342 1343webFixedFont(family: string) 1344 1345设置网页的fixed font字体库。 1346 1347**系统能力：** SystemCapability.Web.Webview.Core 1348 1349**参数：** 1350 1351| 参数名 | 类型 | 必填 | 说明 | 1352| ------ | ------ | ---- | ------------------- | 1353| family | string | 是 | 设置网页的fixed font字体库。默认值：monospace。 | 1354 1355**示例：** 1356 1357 ```ts 1358 // xxx.ets 1359 import { webview } from '@kit.ArkWeb'; 1360 1361 @Entry 1362 @Component 1363 struct WebComponent { 1364 controller: webview.WebviewController = new webview.WebviewController(); 1365 @State family: string = "monospace"; 1366 1367 build() { 1368 Column() { 1369 Web({ src: 'www.example.com', controller: this.controller }) 1370 .webFixedFont(this.family) 1371 } 1372 } 1373 } 1374 ``` 1375 1376### webSansSerifFont<sup>9+</sup> 1377 1378webSansSerifFont(family: string) 1379 1380设置网页的sans serif font字体库。 1381 1382**系统能力：** SystemCapability.Web.Webview.Core 1383 1384**参数：** 1385 1386| 参数名 | 类型 | 必填 | 说明 | 1387| ------ | ------ | ---- | ------------------------ | 1388| family | string | 是 | 设置网页的sans serif font字体库。默认值：sans-serif。 | 1389 1390**示例：** 1391 1392 ```ts 1393 // xxx.ets 1394 import { webview } from '@kit.ArkWeb'; 1395 1396 @Entry 1397 @Component 1398 struct WebComponent { 1399 controller: webview.WebviewController = new webview.WebviewController(); 1400 @State family: string = "sans-serif"; 1401 1402 build() { 1403 Column() { 1404 Web({ src: 'www.example.com', controller: this.controller }) 1405 .webSansSerifFont(this.family) 1406 } 1407 } 1408 } 1409 ``` 1410 1411### webSerifFont<sup>9+</sup> 1412 1413webSerifFont(family: string) 1414 1415设置网页的serif font字体库。 1416 1417**系统能力：** SystemCapability.Web.Webview.Core 1418 1419**参数：** 1420 1421| 参数名 | 类型 | 必填 | 说明 | 1422| ------ | ------ | ---- | ------------------- | 1423| family | string | 是 | 设置网页的serif font字体库。默认值：serif。 | 1424 1425**示例：** 1426 1427 ```ts 1428 // xxx.ets 1429 import { webview } from '@kit.ArkWeb'; 1430 1431 @Entry 1432 @Component 1433 struct WebComponent { 1434 controller: webview.WebviewController = new webview.WebviewController(); 1435 @State family: string = "serif"; 1436 1437 build() { 1438 Column() { 1439 Web({ src: 'www.example.com', controller: this.controller }) 1440 .webSerifFont(this.family) 1441 } 1442 } 1443 } 1444 ``` 1445 1446### webStandardFont<sup>9+</sup> 1447 1448webStandardFont(family: string) 1449 1450设置网页的standard font字体库。 1451 1452**系统能力：** SystemCapability.Web.Webview.Core 1453 1454**参数：** 1455 1456| 参数名 | 类型 | 必填 | 说明 | 1457| ------ | ------ | ---- | ---------------------- | 1458| family | string | 是 | 设置网页的standard font字体库。默认值：sans serif。 | 1459 1460**示例：** 1461 1462 ```ts 1463 // xxx.ets 1464 import { webview } from '@kit.ArkWeb'; 1465 1466 @Entry 1467 @Component 1468 struct WebComponent { 1469 controller: webview.WebviewController = new webview.WebviewController(); 1470 @State family: string = "sans-serif"; 1471 1472 build() { 1473 Column() { 1474 Web({ src: 'www.example.com', controller: this.controller }) 1475 .webStandardFont(this.family) 1476 } 1477 } 1478 } 1479 ``` 1480 1481### webFantasyFont<sup>9+</sup> 1482 1483webFantasyFont(family: string) 1484 1485设置网页的fantasy font字体库。 1486 1487**系统能力：** SystemCapability.Web.Webview.Core 1488 1489**参数：** 1490 1491| 参数名 | 类型 | 必填 | 说明 | 1492| ------ | ------ | ---- | --------------------- | 1493| family | string | 是 | 设置网页的fantasy font字体库。默认值：fantasy。 | 1494 1495**示例：** 1496 1497 ```ts 1498 // xxx.ets 1499 import { webview } from '@kit.ArkWeb'; 1500 @Entry 1501 @Component 1502 struct WebComponent { 1503 controller: webview.WebviewController = new webview.WebviewController(); 1504 @State family: string = "fantasy"; 1505 1506 build() { 1507 Column() { 1508 Web({ src: 'www.example.com', controller: this.controller }) 1509 .webFantasyFont(this.family) 1510 } 1511 } 1512 } 1513 ``` 1514 1515### webCursiveFont<sup>9+</sup> 1516 1517webCursiveFont(family: string) 1518 1519设置网页的cursive font字体库。 1520 1521**系统能力：** SystemCapability.Web.Webview.Core 1522 1523**参数：** 1524 1525| 参数名 | 类型 | 必填 | 说明 | 1526| ------ | ------ | ---- | --------------------- | 1527| family | string | 是 | 设置网页的cursive font字体库。默认值：cursive。 | 1528 1529**示例：** 1530 1531 ```ts 1532 // xxx.ets 1533 import { webview } from '@kit.ArkWeb'; 1534 1535 @Entry 1536 @Component 1537 struct WebComponent { 1538 controller: webview.WebviewController = new webview.WebviewController(); 1539 @State family: string = "cursive"; 1540 1541 build() { 1542 Column() { 1543 Web({ src: 'www.example.com', controller: this.controller }) 1544 .webCursiveFont(this.family) 1545 } 1546 } 1547 } 1548 ``` 1549 1550### darkMode<sup>9+</sup> 1551 1552darkMode(mode: WebDarkMode) 1553 1554设置Web深色模式，默认关闭。当深色模式开启时，Web将启用媒体查询prefers-color-scheme中网页所定义的深色样式，若网页未定义深色样式，则保持原状。如需开启强制深色模式，建议配合[forceDarkAccess](#forcedarkaccess9)使用。 1555 1556**系统能力：** SystemCapability.Web.Webview.Core 1557 1558**参数：** 1559 1560| 参数名 | 类型 | 必填 | 说明 | 1561| ---- | -------------------------------- | ---- | ---------------------- | 1562| mode | [WebDarkMode](#webdarkmode9枚举说明) | 是 | 设置Web的深色模式为关闭、开启或跟随系统。默认值：WebDarkMode.Off。 | 1563 1564**示例：** 1565 1566 ```ts 1567 // xxx.ets 1568 import { webview } from '@kit.ArkWeb'; 1569 1570 @Entry 1571 @Component 1572 struct WebComponent { 1573 controller: webview.WebviewController = new webview.WebviewController(); 1574 @State mode: WebDarkMode = WebDarkMode.On; 1575 1576 build() { 1577 Column() { 1578 Web({ src: 'www.example.com', controller: this.controller }) 1579 .darkMode(this.mode) 1580 } 1581 } 1582 } 1583 ``` 1584 1585### forceDarkAccess<sup>9+</sup> 1586 1587forceDarkAccess(access: boolean) 1588 1589设置网页是否开启强制深色模式。默认关闭。该属性仅在[darkMode](#darkmode9)开启深色模式时生效。 1590 1591**系统能力：** SystemCapability.Web.Webview.Core 1592 1593**参数：** 1594 1595| 参数名 | 类型 | 必填 | 说明 | 1596| ------ | ------- | ---- | --------------- | 1597| access | boolean | 是 | 设置网页是否开启强制深色模式。默认值：false。 | 1598 1599**示例：** 1600 1601 ```ts 1602 // xxx.ets 1603 import { webview } from '@kit.ArkWeb'; 1604 1605 @Entry 1606 @Component 1607 struct WebComponent { 1608 controller: webview.WebviewController = new webview.WebviewController(); 1609 @State mode: WebDarkMode = WebDarkMode.On; 1610 @State access: boolean = true; 1611 1612 build() { 1613 Column() { 1614 Web({ src: 'www.example.com', controller: this.controller }) 1615 .darkMode(this.mode) 1616 .forceDarkAccess(this.access) 1617 } 1618 } 1619 } 1620 ``` 1621 1622### tableData<sup>(deprecated)</sup> 1623 1624tableData(tableData: boolean) 1625 1626设置是否应保存表单数据。该接口为空接口。 1627 1628> **说明：** 1629> 1630> 从API version 10开始废弃，并且不再提供新的接口作为替代。 1631 1632**系统能力：** SystemCapability.Web.Webview.Core 1633 1634### wideViewModeAccess<sup>(deprecated)</sup> 1635 1636wideViewModeAccess(wideViewModeAccess: boolean) 1637 1638设置web是否支持html中meta标签的viewport属性。该接口为空接口。 1639 1640> **说明：** 1641> 1642> 从API version 10开始废弃，并且不再提供新的接口作为替代。 1643 1644**系统能力：** SystemCapability.Web.Webview.Core 1645 1646### pinchSmooth<sup>9+</sup> 1647 1648pinchSmooth(isEnabled: boolean) 1649 1650设置网页是否开启捏合流畅模式，默认不开启。 1651 1652**系统能力：** SystemCapability.Web.Webview.Core 1653 1654**参数：** 1655 1656| 参数名 | 类型 | 必填 | 说明 | 1657| --------- | ------- | ---- | ------------- | 1658| isEnabled | boolean | 是 | 网页是否开启捏合流畅模式。默认值：false。 | 1659 1660**示例：** 1661 1662 ```ts 1663 // xxx.ets 1664 import { webview } from '@kit.ArkWeb'; 1665 1666 @Entry 1667 @Component 1668 struct WebComponent { 1669 controller: webview.WebviewController = new webview.WebviewController(); 1670 1671 build() { 1672 Column() { 1673 Web({ src: 'www.example.com', controller: this.controller }) 1674 .pinchSmooth(true) 1675 } 1676 } 1677 } 1678 ``` 1679 1680### allowWindowOpenMethod<sup>10+</sup> 1681 1682allowWindowOpenMethod(flag: boolean) 1683 1684设置网页是否可以通过JavaScript自动打开新窗口。 1685 1686该属性为true时，可通过JavaScript自动打开新窗口。该属性为false时，用户行为仍可通过JavaScript自动打开新窗口，但非用户行为不能通过JavaScript自动打开新窗口。此处的用户行为是指，在用户对Web组件进行点击等操作后，同时在5秒内请求打开新窗口（window.open）的行为。 1687 1688该属性仅在[javaScriptAccess](#javascriptaccess)开启时生效。 1689 1690该属性在[multiWindowAccess](#multiwindowaccess9)开启时打开新窗口，关闭时打开本地窗口。 1691 1692该属性的默认值与系统属性persist.web.allowWindowOpenMethod.enabled 保持一致，如果未设置系统属性则默认值为false。 1693 1694检查系统配置项persist.web.allowWindowOpenMethod.enabled 是否开启。 1695 1696通过`hdc shell param get persist.web.allowWindowOpenMethod.enabled` 查看，若配置项为0或不存在， 1697可通过命令`hdc shell param set persist.web.allowWindowOpenMethod.enabled 1` 开启配置。 1698 1699**系统能力：** SystemCapability.Web.Webview.Core 1700 1701**参数：** 1702 1703| 参数名 | 类型 | 必填 | 说明 | 1704| ---- | ------- | ---- | ------------------------- | 1705| flag | boolean | 是 | 网页是否可以通过JavaScript自动打开窗口。默认值与系统参数关联，当系统参数persist.web.allowWindowOpenMethod.enabled为true时，默认值为true, 否则为false。 | 1706 1707**示例：** 1708 1709 ```ts 1710 // xxx.ets 1711 import { webview } from '@kit.ArkWeb'; 1712 1713 // 在同一page页有两个Web组件。在WebComponent新开窗口时，会跳转到NewWebViewComp。 1714 @CustomDialog 1715 struct NewWebViewComp { 1716 controller?: CustomDialogController; 1717 webviewController1: webview.WebviewController = new webview.WebviewController(); 1718 1719 build() { 1720 Column() { 1721 Web({ src: "", controller: this.webviewController1 }) 1722 .javaScriptAccess(true) 1723 .multiWindowAccess(false) 1724 .onWindowExit(() => { 1725 console.info("NewWebViewComp onWindowExit"); 1726 if (this.controller) { 1727 this.controller.close(); 1728 } 1729 }) 1730 } 1731 } 1732 } 1733 1734 @Entry 1735 @Component 1736 struct WebComponent { 1737 controller: webview.WebviewController = new webview.WebviewController(); 1738 dialogController: CustomDialogController | null = null; 1739 1740 build() { 1741 Column() { 1742 Web({ src: 'www.example.com', controller: this.controller }) 1743 .javaScriptAccess(true) 1744 // 需要使能multiWindowAccess 1745 .multiWindowAccess(true) 1746 .allowWindowOpenMethod(true) 1747 .onWindowNew((event) => { 1748 if (this.dialogController) { 1749 this.dialogController.close(); 1750 } 1751 let popController: webview.WebviewController = new webview.WebviewController(); 1752 this.dialogController = new CustomDialogController({ 1753 builder: NewWebViewComp({ webviewController1: popController }) 1754 }) 1755 this.dialogController.open(); 1756 // 将新窗口对应WebviewController返回给Web内核。 1757 // 若不调用event.handler.setWebController接口，会造成render进程阻塞。 1758 // 如果没有创建新窗口，调用event.handler.setWebController接口时设置成null，通知Web没有创建新窗口。 1759 event.handler.setWebController(popController); 1760 }) 1761 } 1762 } 1763 } 1764 ``` 1765 1766### mediaOptions<sup>10+</sup> 1767 1768mediaOptions(options: WebMediaOptions) 1769 1770设置Web媒体播放的策略，其中包括：Web中的音频在重新获焦后能够自动续播的有效期、应用内多个Web实例的音频是否独占。 1771 1772> **说明：** 1773> 1774> - 同一Web实例中的多个音频均视为同一音频。 1775> - 该媒体播放策略将同时管控有声视频。 1776> - 属性参数更新后需重新播放音频方可生效。 1777> - 建议为所有Web组件设置相同的audioExclusive值。 1778> - 音视频互相打断在应用内和应用间生效，续播只在应用间生效。 1779 1780**系统能力：** SystemCapability.Web.Webview.Core 1781 1782**参数：** 1783 1784| 参数名 | 类型 | 必填 | 说明 | 1785| ------- | ------------------------------------- | ---- | ---------------------------------------- | 1786| options | [WebMediaOptions](#webmediaoptions10) | 是 | 设置Web的媒体策略。其中，resumeInterval的默认值为0表示不自动续播。默认值：{resumeInterval: 0, audioExclusive: true}。 | 1787 1788**示例：** 1789 1790 ```ts 1791 // xxx.ets 1792 import { webview } from '@kit.ArkWeb'; 1793 1794 @Entry 1795 @Component 1796 struct WebComponent { 1797 controller: webview.WebviewController = new webview.WebviewController(); 1798 @State options: WebMediaOptions = {resumeInterval: 10, audioExclusive: true}; 1799 1800 build() { 1801 Column() { 1802 Web({ src: 'www.example.com', controller: this.controller }) 1803 .mediaOptions(this.options) 1804 } 1805 } 1806 } 1807 ``` 1808 1809### javaScriptOnDocumentStart<sup>11+</sup> 1810 1811javaScriptOnDocumentStart(scripts: Array\<ScriptItem>) 1812 1813将JavaScript脚本注入到Web组件中，当指定页面或者文档开始加载时，该脚本将在其来源与scriptRules匹配的任何页面中执行。 1814 1815> **说明：** 1816> 1817> - 该脚本将在页面的任何JavaScript代码之前运行，并且DOM树此时可能尚未加载、渲染完毕。 1818 1819**系统能力：** SystemCapability.Web.Webview.Core 1820 1821**参数：** 1822 1823| 参数名 | 类型 | 必填 | 说明 | 1824| ------- | ----------------------------------- | ---- | ------------------ | 1825| scripts | Array\<[ScriptItem](#scriptitem11)> | 是 | 需要注入的ScriptItem数组 | 1826 1827**ets示例：** 1828 1829 ```ts 1830 // xxx.ets 1831 import { webview } from '@kit.ArkWeb'; 1832 1833 @Entry 1834 @Component 1835 struct Index { 1836 controller: webview.WebviewController = new webview.WebviewController(); 1837 private localStorage: string = 1838 "if (typeof(Storage) !== 'undefined') {" + 1839 " localStorage.setItem('color', 'Red');" + 1840 "}"; 1841 @State scripts: Array<ScriptItem> = [ 1842 { script: this.localStorage, scriptRules: ["*"] } 1843 ]; 1844 1845 build() { 1846 Column({ space: 20 }) { 1847 Web({ src: $rawfile('index.html'), controller: this.controller }) 1848 .javaScriptAccess(true) 1849 .domStorageAccess(true) 1850 .backgroundColor(Color.Grey) 1851 .javaScriptOnDocumentStart(this.scripts) 1852 .width('100%') 1853 .height('100%') 1854 } 1855 } 1856 } 1857 ``` 1858**HTML示例：** 1859 1860```html 1861<!-- index.html --> 1862<!DOCTYPE html> 1863<html> 1864 <head> 1865 <meta charset="utf-8"> 1866 </head> 1867 <body style="font-size: 30px;" onload='bodyOnLoadLocalStorage()'> 1868 Hello world! 1869 <div id="result"></div> 1870 </body> 1871 <script type="text/javascript"> 1872 function bodyOnLoadLocalStorage() { 1873 if (typeof(Storage) !== 'undefined') { 1874 document.getElementById('result').innerHTML = localStorage.getItem('color'); 1875 } else { 1876 document.getElementById('result').innerHTML = 'Your browser does not support localStorage.'; 1877 } 1878 } 1879 </script> 1880</html> 1881``` 1882 1883### javaScriptOnDocumentEnd<sup>11+</sup> 1884 1885javaScriptOnDocumentEnd(scripts: Array\<ScriptItem>) 1886 1887将JavaScript脚本注入到Web组件中，当指定页面或者文档加载完成时，该脚本将在其来源与scriptRules匹配的任何页面中执行。 1888 1889> **说明：** 1890> 1891> - 该脚本将在页面的任何JavaScript代码之后运行，并且DOM树此时已经加载、渲染完毕。 1892 1893**系统能力：** SystemCapability.Web.Webview.Core 1894 1895**参数：** 1896 1897| 参数名 | 类型 | 必填 | 说明 | 1898| ------- | ----------------------------------- | ---- | ------------------ | 1899| scripts | Array\<[ScriptItem](#scriptitem11)> | 是 | 需要注入的ScriptItem数组 | 1900 1901**示例：** 1902 1903 ```ts 1904// xxx.ets 1905import { webview } from '@kit.ArkWeb'; 1906 1907@Entry 1908@Component 1909struct Index { 1910 controller: webview.WebviewController = new webview.WebviewController(); 1911 private jsStr: string = 1912 "window.document.getElementById(\"result\").innerHTML = 'this is msg from javaScriptOnDocumentEnd'"; 1913 @State scripts: Array<ScriptItem> = [ 1914 { script: this.jsStr, scriptRules: ["*"] } 1915 ]; 1916 1917 build() { 1918 Column({ space: 20 }) { 1919 Web({ src: $rawfile('index.html'), controller: this.controller }) 1920 .javaScriptAccess(true) 1921 .domStorageAccess(true) 1922 .backgroundColor(Color.Grey) 1923 .javaScriptOnDocumentEnd(this.scripts) 1924 .width('100%') 1925 .height('100%') 1926 } 1927 } 1928} 1929 ``` 1930 1931```html 1932<!DOCTYPE html> 1933<html> 1934<head> 1935 <meta charset="utf-8"> 1936</head> 1937<body style="font-size: 30px;"> 1938Hello world! 1939<div id="result">test msg</div> 1940</body> 1941</html> 1942``` 1943 1944### layoutMode<sup>11+</sup> 1945 1946layoutMode(mode: WebLayoutMode) 1947 1948设置Web布局模式。 1949 1950> **说明：** 1951> 1952> 目前只支持两种Web布局模式，分别为Web布局跟随系统（WebLayoutMode.NONE）和Web组件高度基于前端页面高度的自适应网页布局（WebLayoutMode.FIT_CONTENT）。 1953> 1954> Web组件高度基于前端页面自适应布局有如下限制： 1955> - 如果Web组件宽或长度超过7680px，请在Web组件创建的时候指定RenderMode.SYNC_RENDER模式，否则会整个白屏。 1956> - Web组件创建后不支持动态切换layoutMode模式 1957> - Web组件宽高规格：指定RenderMode.SYNC_RENDER模式时，分别不超过50万px；指定RenderMode.ASYNC_RENDER模式时，分别不超过7680px。 1958> - 频繁更改页面宽高会触发Web组件重新布局，影响体验。 1959> - 不支持瀑布流网页（下拉到底部加载更多）。 1960> - 仅支持高度自适应，不支持宽度自适应。 1961> - 由于高度自适应网页高度，您无法通过修改组件高度属性来修改组件高度。 1962 1963**系统能力：** SystemCapability.Web.Webview.Core 1964 1965**参数：** 1966 1967| 参数名 | 类型 | 必填 | 说明 | 1968| ---- | ------------------------------------- | ---- | --------------------- | 1969| mode | [WebLayoutMode](#weblayoutmode11枚举说明) | 是 | 设置web布局模式，跟随系统或自适应布局。默认值：WebLayoutMode.NONE。 | 1970 1971**示例：** 1972 1973 1、指明layoutMode为WebLayoutMode.FIT_CONTENT模式，为避免默认渲染模式下(RenderMode.ASYNC_RENDER)视口高度超过7680px导致页面渲染出错，需要显式指明渲染模式(RenderMode.SYNC_RENDER)。 1974 ```ts 1975 // xxx.ets 1976 import { webview } from '@kit.ArkWeb'; 1977 1978 @Entry 1979 @Component 1980 struct WebComponent { 1981 controller: webview.WebviewController = new webview.WebviewController(); 1982 mode: WebLayoutMode = WebLayoutMode.FIT_CONTENT; 1983 1984 build() { 1985 Column() { 1986 Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER }) 1987 .layoutMode(this.mode) 1988 } 1989 } 1990 } 1991 ``` 1992 1993 2、指明layoutMode为WebLayoutMode.FIT_CONTENT模式，为避免嵌套滚动场景下，Web滚动到边缘时会优先触发过滚动的过界回弹效果影响用户体验，建议指定overScrollMode为OverScrollMode.NEVER。 1994 ```ts 1995 // xxx.ets 1996 import { webview } from '@kit.ArkWeb'; 1997 1998 @Entry 1999 @Component 2000 struct WebComponent { 2001 controller: webview.WebviewController = new webview.WebviewController(); 2002 layoutMode: WebLayoutMode = WebLayoutMode.FIT_CONTENT; 2003 @State overScrollMode: OverScrollMode = OverScrollMode.NEVER; 2004 2005 build() { 2006 Column() { 2007 Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER }) 2008 .layoutMode(this.layoutMode) 2009 .overScrollMode(this.overScrollMode) 2010 } 2011 } 2012 } 2013 ``` 2014 2015### nestedScroll<sup>11+</sup> 2016 2017nestedScroll(value: NestedScrollOptions | NestedScrollOptionsExt) 2018 2019调用以设置嵌套滚动选项。 2020 2021> **说明：** 2022> 2023> - 可以设置上下左右四个方向，或者设置向前、向后两个方向的嵌套滚动模式，实现与父组件的滚动联动。 2024> - value为NestedScrollOptionsExt（上下左右四个方向）类型时，scrollUp、scrollDown、scrollLeft、scrollRight默认滚动选项为[NestedScrollMode.SELF_FIRST](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10)。 2025> - value为NestedScrollOptions（向前、向后两个方向）类型时，scrollForward、scrollBackward默认滚动选项为NestedScrollMode.SELF_FIRST。 2026> - 支持嵌套滚动的容器：[Grid](../apis-arkui/arkui-ts/ts-container-grid.md)、[List](../apis-arkui/arkui-ts/ts-container-list.md)、[Scroll](../apis-arkui/arkui-ts/ts-container-scroll.md)、[Swiper](../apis-arkui/arkui-ts/ts-container-swiper.md)、[Tabs](../apis-arkui/arkui-ts/ts-container-tabs.md)、[WaterFlow](../apis-arkui/arkui-ts/ts-container-waterflow.md)、[Refresh](../apis-arkui/arkui-ts/ts-container-refresh.md)、[bindSheet](../apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#bindsheet)。 2027> - 支持嵌套滚动的输入事件：使用手势、鼠标、触控板。 2028> - 嵌套滚动场景下，由于Web滚动到边缘时会优先触发过滚动的过界回弹效果，建议设置overScrollMode为OverScrollMode.NEVER，避免影响此场景的用户体验。 2029 2030**系统能力：** SystemCapability.Web.Webview.Core 2031 2032**参数：** 2033 2034| 参数名 | 类型 | 必填 | 说明 | 2035| ----- | ---------------------------------------- | ---- | ---------------- | 2036| value | [NestedScrollOptions](../apis-arkui/arkui-ts/ts-container-scrollable-common.md#nestedscrolloptions10对象说明) \| [NestedScrollOptionsExt](#nestedscrolloptionsext14对象说明)<sup>14+</sup> | 是 | 可滚动组件滚动时的嵌套滚动选项。 | 2037 2038**示例：** 2039 2040 ```ts 2041 // xxx.ets 2042 import { webview } from '@kit.ArkWeb'; 2043 @Entry 2044 @Component 2045 struct WebComponent { 2046 controller: webview.WebviewController = new webview.WebviewController(); 2047 2048 build() { 2049 Column() { 2050 Web({ src: 'www.example.com', controller: this.controller }) 2051 .nestedScroll({ 2052 scrollForward: NestedScrollMode.SELF_FIRST, 2053 scrollBackward: NestedScrollMode.SELF_FIRST, 2054 }) 2055 } 2056 } 2057 } 2058 ``` 2059 ```ts 2060 // xxx.ets 2061 import { webview } from '@kit.ArkWeb'; 2062 @Entry 2063 @Component 2064 struct WebComponent { 2065 controller: webview.WebviewController = new webview.WebviewController() 2066 build() { 2067 Scroll(){ 2068 Column() { 2069 Text("嵌套Web") 2070 .height("25%") 2071 .width("100%") 2072 .fontSize(30) 2073 .backgroundColor(Color.Yellow) 2074 Web({ src: $rawfile('index.html'), 2075 controller: this.controller }) 2076 .nestedScroll({ 2077 scrollUp: NestedScrollMode.SELF_FIRST, 2078 scrollDown: NestedScrollMode.PARENT_FIRST, 2079 scrollLeft: NestedScrollMode.SELF_FIRST, 2080 scrollRight: NestedScrollMode.SELF_FIRST, 2081 }) 2082 } 2083 } 2084 } 2085 } 2086 ``` 2087 加载的html文件。 2088 ```html 2089 <!-- index.html --> 2090 <!DOCTYPE html> 2091 <html> 2092 <head> 2093 <style> 2094 .blue { 2095 background-color: lightblue; 2096 } 2097 .green { 2098 background-color: lightgreen; 2099 } 2100 .blue, .green { 2101 width: 100%; 2102 font-size:70px; 2103 height:1000px; 2104 } 2105 </style> 2106 </head> 2107 <body> 2108 <div class="blue" align="center" >滚动1</div> 2109 <div class="green" align="center">滚动2</div> 2110 <div class="blue" align="center">滚动3</div> 2111 <div class="green" align="center">滚动4</div> 2112 <div class="blue" align="center">滚动5</div> 2113 <div class="green" align="center">滚动6</div> 2114 <div class="blue" align="center">滚动7</div> 2115 </body> 2116 </html> 2117 ``` 2118 2119### enableNativeEmbedMode<sup>11+</sup> 2120 2121enableNativeEmbedMode(mode: boolean) 2122 2123设置是否开启同层渲染功能，默认不开启。 2124 2125**系统能力：** SystemCapability.Web.Webview.Core 2126 2127**参数：** 2128 2129| 参数名 | 类型 | 必填 | 说明 | 2130| ----- | ---------------------------------------- | ---- | ---------------- | 2131| mode | boolean | 是 | 是否开启同层渲染功能。默认值：false。 | 2132 2133**示例：** 2134 2135 ```ts 2136 // xxx.ets 2137 import { webview } from '@kit.ArkWeb'; 2138 @Entry 2139 @Component 2140 struct WebComponent { 2141 controller: webview.WebviewController = new webview.WebviewController(); 2142 2143 build() { 2144 Column() { 2145 Web({ src: 'www.example.com', controller: this.controller }) 2146 .enableNativeEmbedMode(true) 2147 } 2148 } 2149 } 2150 ``` 2151### forceDisplayScrollBar<sup>14+</sup> 2152 2153forceDisplayScrollBar(enabled: boolean) 2154 2155 2156设置滚动条是否常驻。默认不常驻，在常驻状态下，当页面大小超过一页时，滚动条出现且不消失。 2157 2158全量展开模式下不支持滚动条常驻，即layoutMode为WebLayoutMode.FIT_CONTENT模式时，参数enabled为false。 2159 2160**系统能力：** SystemCapability.Web.Webview.Core 2161 2162**参数：** 2163 2164| 参数名 | 类型 | 必填 | 说明 | 2165| ------- | -------- | ---- | ------------------ | 2166| enabled | boolean | 是 | 滚动条是否常驻。默认值：false。 | 2167 2168 2169**示例：** 2170 2171 ```ts 2172 // xxx.ets 2173 import { webview } from '@kit.ArkWeb'; 2174 2175 @Entry 2176 @Component 2177 struct WebComponent { 2178 controller: webview.WebviewController = new webview.WebviewController(); 2179 2180 build() { 2181 Column() { 2182 Web({ src: $rawfile('index.html'), controller: this.controller }) 2183 .forceDisplayScrollBar(true) 2184 } 2185 } 2186 } 2187 ``` 2188 2189 加载的html文件。 2190 ```html 2191 <!--index.html--> 2192 <!DOCTYPE html> 2193 <html> 2194 <head> 2195 <meta name="viewport" content="width=device-width, initial-scale=1.0"> 2196 <title>Demo</title> 2197 <style> 2198 body { 2199 width:2560px; 2200 height:2560px; 2201 padding-right:170px; 2202 padding-left:170px; 2203 border:5px solid blueviolet 2204 } 2205 </style> 2206 </head> 2207 <body> 2208 Scroll Test 2209 </body> 2210 </html> 2211 ``` 2212### registerNativeEmbedRule<sup>12+</sup> 2213 2214registerNativeEmbedRule(tag: string, type: string) 2215 2216注册使用同层渲染的HTML标签名和类型。标签名仅支持使用object和embed。标签类型只能使用ASCII可显示字符。 2217 2218若指定类型与w3c定义的object或embed标准类型重合，ArkWeb内核将其识别为非同层标签。 2219 2220本接口同样受enableNativeEmbedMode接口控制，在未使能同层渲染时本接口无效。在不使用本接口的情况下，ArkWeb内核默认将"native/"前缀类型的embed标签识别为同层标签。 2221 2222**系统能力：** SystemCapability.Web.Webview.Core 2223 2224**参数：** 2225 2226| 参数名 | 类型 | 必填 | 说明 | 2227|------|--------| ---- |------------------| 2228| tag | string | 是 | 标签名。 | 2229| type | string | 是 | 标签类型,内核使用前缀匹配此参数。 | 2230 2231**示例：** 2232 2233 ```ts 2234 // xxx.ets 2235 import { webview } from '@kit.ArkWeb'; 2236 2237 @Entry 2238 @Component 2239 struct WebComponent { 2240 controller: webview.WebviewController = new webview.WebviewController(); 2241 2242 build() { 2243 Column() { 2244 Web({ src: 'www.example.com', controller: this.controller }) 2245 .enableNativeEmbedMode(true) 2246 .registerNativeEmbedRule("object", "application/view") 2247 } 2248 } 2249 } 2250 ``` 2251### defaultTextEncodingFormat<sup>12+</sup> 2252 2253defaultTextEncodingFormat(textEncodingFormat: string) 2254 2255设置网页的默认字符编码。 2256 2257**系统能力：** SystemCapability.Web.Webview.Core 2258 2259**参数：** 2260 2261| 参数名 | 类型 | 必填 | 说明 | 2262| ---- | ------ | ---- | ---------------------------------------- | 2263| textEncodingFormat | string | 是 | 默认字符编码。默认值："UTF-8"。 | 2264 2265 **示例：** 2266 2267 ```ts 2268 // xxx.ets 2269 import { webview } from '@kit.ArkWeb'; 2270 2271 @Entry 2272 @Component 2273 struct WebComponent { 2274 controller: webview.WebviewController = new webview.WebviewController(); 2275 2276 build() { 2277 Column() { 2278 Web({ src: $rawfile('index.html'), controller: this.controller }) 2279 // 设置高 2280 .height(500) 2281 .defaultTextEncodingFormat("UTF-8") 2282 .javaScriptAccess(true) 2283 } 2284 } 2285 } 2286 ``` 2287 2288```html 2289 2290<!doctype html> 2291<html> 2292<head> 2293 <meta name="viewport" content="width=device-width" /> 2294 <title>My test html5 page</title> 2295</head> 2296<body> 2297 hello world, 你好世界! 2298</body> 2299</html> 2300``` 2301### metaViewport<sup>12+</sup> 2302 2303metaViewport(enabled: boolean) 2304 2305设置meta标签的viewport属性是否可用。 2306 2307> **说明：** 2308> 2309> - 设置false不支持meta标签viewport属性，将不解析viewport属性，进行默认布局。 2310> - 设置true支持meta标签viewport属性，将解析viewport属性，并根据viewport属性布局。 2311> - 如果设置为异常值将无效。 2312> - 如果设备为2in1，不支持viewport属性。设置为true或者false均不会解析viewport属性，进行默认布局。 2313> - 如果设备为Tablet，设置为true或false均会解析meta标签viewport-fit属性。当viewport-fit=cover时，可通过CSS属性获取安全区域大小。 2314> - 当前通过UserAgent中是否含有"Mobile"字段来判断是否开启前端HTML页面中meta标签的viewport属性。当UserAgent中不含有"Mobile"字段时，meta标签中viewport属性默认关闭，此时可通过显性设置metaViewport属性为true来覆盖关闭状态。 2315 2316**系统能力：** SystemCapability.Web.Webview.Core 2317 2318**参数：** 2319 2320| 参数名 | 类型 | 必填 | 说明 | 2321| ------ | -------- | ---- | -------------------------------- | 2322| enabled | boolean | 是 | 是否支持meta标签的viewport属性。默认值：true。 | 2323 2324**示例：** 2325 2326 ```ts 2327// xxx.ets 2328import { webview } from '@kit.ArkWeb'; 2329 2330@Entry 2331@Component 2332struct WebComponent { 2333 controller: webview.WebviewController = new webview.WebviewController(); 2334 2335 build() { 2336 Column() { 2337 Web({ src: $rawfile('index.html'), controller: this.controller }) 2338 .metaViewport(true) 2339 } 2340 } 2341} 2342 ``` 2343 2344```html 2345<!doctype html> 2346<html> 2347<head> 2348 <meta name="viewport" content="width=device-width, initial-scale=1.0"> 2349</head> 2350<body> 2351 <p>hello world, 你好世界!</p> 2352</body> 2353</html> 2354``` 2355 2356### textAutosizing<sup>12+</sup> 2357 2358textAutosizing(textAutosizing: boolean) 2359 2360设置使能文本自动调整大小。 2361 2362**系统能力：** SystemCapability.Web.Webview.Core 2363 2364**参数：** 2365 2366| 参数名 | 类型 | 必填 | 说明 | 2367| ---- | ------ | ---- | ---------------------------------------- | 2368| textAutosizing | boolean | 是 | 文本自动调整大小。默认值：true。 | 2369 2370 **示例：** 2371 2372 ```ts 2373 // xxx.ets 2374 import { webview } from '@kit.ArkWeb'; 2375 2376 @Entry 2377 @Component 2378 struct WebComponent { 2379 controller: webview.WebviewController = new webview.WebviewController(); 2380 2381 build() { 2382 Column() { 2383 Web({ src: 'www.example.com', controller: this.controller }) 2384 .textAutosizing(false) 2385 } 2386 } 2387 } 2388 ``` 2389### enableNativeMediaPlayer<sup>12+</sup> 2390 2391enableNativeMediaPlayer(config: NativeMediaPlayerConfig) 2392 2393开启[应用接管网页媒体播放功能](../../web/app-takeovers-web-media.md)。 2394 2395**系统能力：** SystemCapability.Web.Webview.Core 2396 2397**参数：** 2398 2399| 参数名 | 类型 | 必填 | 说明 | 2400| ---- | ------ | ---- | ---------------------| 2401| config | [NativeMediaPlayerConfig](#nativemediaplayerconfig12) | 是 | enable: 是否开启该功能。<br/> shouldOverlay: 该功能开启后， 应用接管网页视频的播放器画面是否覆盖网页内容。默认值：{enable: false, shouldOverlay: false}。| 2402 2403 **示例：** 2404 2405 ```ts 2406 // xxx.ets 2407 import { webview } from '@kit.ArkWeb'; 2408 2409 @Entry 2410 @Component 2411 struct WebComponent { 2412 controller: webview.WebviewController = new webview.WebviewController(); 2413 2414 build() { 2415 Column() { 2416 Web({ src: 'www.example.com', controller: this.controller }) 2417 .enableNativeMediaPlayer({enable: true, shouldOverlay: false}) 2418 } 2419 } 2420 } 2421 ``` 2422 2423### selectionMenuOptions<sup>12+</sup> 2424 2425selectionMenuOptions(expandedMenuOptions: Array\<ExpandedMenuItemOptions>) 2426 2427Web组件自定义菜单扩展项接口，允许用户设置扩展项的文本内容、图标、回调方法。 2428 2429该接口只支持选中纯文本，当选中内容包含图片及其他非文本内容时，action信息中会显示乱码。 2430 2431**系统能力：** SystemCapability.Web.Webview.Core 2432 2433**参数：** 2434 2435| 参数名 | 类型 | 必填 | 说明 | 2436| ------------------- | ---------------------------------------------------------- | ---- | ------------- | 2437| expandedMenuOptions | Array<[ExpandedMenuItemOptions](#expandedmenuitemoptions12)> | 是 | 扩展菜单选项。<br/>菜单项数量，及菜单的content大小、startIcon图标尺寸，与ArkUI [Menu](../apis-arkui/arkui-ts/ts-basic-components-menu.md)组件保持一致。| 2438 2439**示例：** 2440 2441 ```ts 2442 // xxx.ets 2443 import { webview } from '@kit.ArkWeb'; 2444 2445 @Entry 2446 @Component 2447 struct WebComponent { 2448 controller: webview.WebviewController = new webview.WebviewController(); 2449 @State menuOptionArray: Array<ExpandedMenuItemOptions> = [ 2450 {content: 'Apple', startIcon: $r('app.media.icon'), action: (selectedText) => { 2451 console.info('select info ' + selectedText.toString()); 2452 }}, 2453 {content: '香蕉', startIcon: $r('app.media.icon'), action: (selectedText) => { 2454 console.info('select info ' + selectedText.toString()); 2455 }} 2456 ]; 2457 2458 build() { 2459 Column() { 2460 Web({ src: $rawfile("index.html"), controller: this.controller }) 2461 .selectionMenuOptions(this.menuOptionArray) 2462 } 2463 } 2464 } 2465 ``` 2466 2467 加载的html文件。 2468 ```html 2469 <!--index.html--> 2470 <!DOCTYPE html> 2471 <html> 2472 <head> 2473 <title>测试网页</title> 2474 </head> 2475 <body> 2476 <h1>selectionMenuOptions Demo</h1> 2477 <span>selection menu options</span> 2478 </body> 2479 </html> 2480 ``` 2481 2482### onAdsBlocked<sup>12+</sup> 2483 2484onAdsBlocked(callback: OnAdsBlockedCallback) 2485 2486一个页面发生广告过滤后，通过此回调接口通知过滤的详细信息。由于页面可能随时发生变化并不断产生网络请求，为了减少通知频次、降低对页面加载过程的影响，仅在页面加载完成时进行首次通知，此后发生的过滤将间隔1秒钟上报，无广告过滤则无通知。 2487 2488**系统能力：** SystemCapability.Web.Webview.Core 2489 2490**参数：** 2491 2492| 参数名 | 类型 | 必填 | 说明 | 2493| ------ | ------ | ---- | --------------------- | 2494| callback | [OnAdsBlockedCallback](#onadsblockedcallback12) | 是 | onAdsBlocked的回调。 | 2495 2496**示例：** 2497 2498 ```ts 2499 // xxx.ets 2500 import { webview } from '@kit.ArkWeb'; 2501 2502 @Entry 2503 @Component 2504 struct WebComponent { 2505 @State totalAdsBlockCounts: number = 0; 2506 controller: webview.WebviewController = new webview.WebviewController(); 2507 2508 build() { 2509 Column() { 2510 Web({ src: 'https://www.example.com', controller: this.controller }) 2511 .onAdsBlocked((details: AdsBlockedDetails) => { 2512 if (details) { 2513 console.log(' Blocked ' + details.adsBlocked.length + ' in ' + details.url); 2514 let adList: Array<string> = Array.from(new Set(details.adsBlocked)); 2515 this.totalAdsBlockCounts += adList.length; 2516 console.log('Total blocked counts :' + this.totalAdsBlockCounts); 2517 } 2518 }) 2519 } 2520 } 2521 } 2522 ``` 2523 2524### keyboardAvoidMode<sup>12+</sup> 2525 2526keyboardAvoidMode(mode: WebKeyboardAvoidMode) 2527 2528Web组件自定义软件键盘避让模式。 2529 2530当UIContext设置的键盘避让模式为[KeyboardAvoidMode.RESIZE](../apis-arkui/js-apis-arkui-UIContext.md#keyboardavoidmode11)模式时，该接口功能不生效。 2531 2532**系统能力：** SystemCapability.Web.Webview.Core 2533 2534**参数：** 2535 2536| 参数名 | 类型 | 必填 | 说明 | 2537| ------------------- | ------------------------------ | ------ | ------------- | 2538| mode | [WebKeyboardAvoidMode](#webkeyboardavoidmode12) | 是 | Web软键盘避让模式。<br>默认是WebKeyboardAvoidMode.RESIZE_CONTENT避让行为。<br>嵌套滚动场景下不推荐使用web软键盘避让，包括RESIZE_VISUAL与RESIZE_CONTENT。| 2539 2540**示例：** 2541 2542 ```ts 2543 // xxx.ets 2544 import { webview } from '@kit.ArkWeb'; 2545 2546 @Entry 2547 @Component 2548 struct WebComponent { 2549 controller: webview.WebviewController = new webview.WebviewController(); 2550 @State avoidMode: WebKeyboardAvoidMode = WebKeyboardAvoidMode.RESIZE_VISUAL; 2551 2552 build() { 2553 Column() { 2554 Web({ src: $rawfile("index.html"), controller: this.controller }) 2555 .keyboardAvoidMode(this.avoidMode) 2556 } 2557 } 2558 } 2559 ``` 2560 2561 加载的html文件。 2562 ```html 2563 <!--index.html--> 2564 <!DOCTYPE html> 2565 <html> 2566 <head> 2567 <title>测试网页</title> 2568 </head> 2569 <body> 2570 <input type="text" placeholder="Text"> 2571 </body> 2572 </html> 2573 ``` 2574 2575### editMenuOptions<sup>12+</sup> 2576 2577editMenuOptions(editMenu: EditMenuOptions) 2578 2579Web组件自定义文本选择菜单。 2580 2581用户可以通过该属性设置自定义的文本菜单。 2582 2583在[onCreateMenu](../apis-arkui/arkui-ts/ts-text-common.md#oncreatemenu)中，可以修改、增加、删除菜单选项，如果希望不显示文本菜单，需要返回空数组。 2584 2585在[onMenuItemClick](../apis-arkui/arkui-ts/ts-text-common.md#onmenuitemclick)中，可以自定义菜单选项的回调函数。该函数在菜单选项被点击后触发，并根据返回值决定是否执行系统默认的回调。返回true不执行系统回调，返回false继续执行系统回调。 2586 2587本接口在与[selectionMenuOptions](#selectionmenuoptions12)同时使用时，会使selectionMenuOptions不生效。 2588 2589**系统能力：** SystemCapability.Web.Webview.Core 2590 2591**参数：** 2592 2593| 参数名 | 类型 | 必填 | 说明 | 2594| ------------------- | ------------------------------ | ------ | ------------- | 2595| editMenu | [EditMenuOptions](../apis-arkui/arkui-ts/ts-text-common.md#editmenuoptions) | 是 | Web自定义文本菜单选项。<br>菜单项数量，及菜单的content大小、icon图标尺寸，与ArkUI [Menu](../apis-arkui/arkui-ts/ts-basic-components-menu.md)组件保持一致。<br>菜单中系统自带的id枚举值（[TextMenuItemId](../apis-arkui/arkui-ts/ts-text-common.md#textmenuitemid12)）在Web中仅支持CUT、COPY、PASTE、SELECT_ALL四项。<br>onMenuItemClick函数中textRange参数在web中无意义，传入值为-1。| 2596 2597**示例** 2598 2599```ts 2600// xxx.ets 2601import { webview } from '@kit.ArkWeb'; 2602 2603@Entry 2604@Component 2605struct WebComponent { 2606 controller: webview.WebviewController = new webview.WebviewController(); 2607 2608 onCreateMenu(menuItems: Array<TextMenuItem>): Array<TextMenuItem> { 2609 let items = menuItems.filter((menuItem) => { 2610 // 过滤用户需要的系统按键 2611 return ( 2612 menuItem.id.equals(TextMenuItemId.CUT) || 2613 menuItem.id.equals(TextMenuItemId.COPY) || 2614 menuItem.id.equals((TextMenuItemId.PASTE)) 2615 ) 2616 }); 2617 let customItem1: TextMenuItem = { 2618 content: 'customItem1', 2619 id: TextMenuItemId.of('customItem1'), 2620 icon: $r('app.media.icon') 2621 }; 2622 let customItem2: TextMenuItem = { 2623 content: $r('app.string.customItem2'), 2624 id: TextMenuItemId.of('customItem2'), 2625 icon: $r('app.media.icon') 2626 }; 2627 items.push(customItem1);// 在选项列表后添加新选项 2628 items.unshift(customItem2);// 在选项列表前添加选项 2629 2630 return items; 2631 } 2632 2633 onMenuItemClick(menuItem: TextMenuItem, textRange: TextRange): boolean { 2634 if (menuItem.id.equals(TextMenuItemId.CUT)) { 2635 // 用户自定义行为 2636 console.log("拦截 id：CUT") 2637 return true; // 返回true不执行系统回调 2638 } else if (menuItem.id.equals(TextMenuItemId.COPY)) { 2639 // 用户自定义行为 2640 console.log("不拦截 id：COPY") 2641 return false; // 返回false执行系统回调 2642 } else if (menuItem.id.equals(TextMenuItemId.of('customItem1'))) { 2643 // 用户自定义行为 2644 console.log("拦截 id：customItem1") 2645 return true;// 用户自定义菜单选项返回true时点击后不关闭菜单，返回false时关闭菜单 2646 } else if (menuItem.id.equals((TextMenuItemId.of($r('app.string.customItem2'))))){ 2647 // 用户自定义行为 2648 console.log("拦截 id：app.string.customItem2") 2649 return true; 2650 } 2651 return false;// 返回默认值false 2652 } 2653 2654 @State EditMenuOptions: EditMenuOptions = { onCreateMenu: this.onCreateMenu, onMenuItemClick: this.onMenuItemClick } 2655 2656 build() { 2657 Column() { 2658 Web({ src: $rawfile("index.html"), controller: this.controller }) 2659 .editMenuOptions(this.EditMenuOptions) 2660 } 2661 } 2662} 2663``` 2664 2665 加载的html文件。 2666```html 2667<!--index.html--> 2668<!DOCTYPE html> 2669<html> 2670 <head> 2671 <title>测试网页</title> 2672 </head> 2673 <body> 2674 <h1>editMenuOptions Demo</h1> 2675 <span>edit menu options</span> 2676 </body> 2677</html> 2678``` 2679 2680### enableHapticFeedback<sup>13+</sup> 2681 2682enableHapticFeedback(enabled: boolean) 2683 2684设置Web组件长按文本选择是否开启振动，默认开启。 需配置"ohos.permission.VIBRATE"。 2685 2686**系统能力：** SystemCapability.Web.Webview.Core 2687 2688**参数：** 2689 2690| 参数名 | 类型 | 必填 | 说明 | 2691| --------- | --------- | ------ | ------------- | 2692| enabled | boolean | 是 | 是否开启振动。默认值：true。 | 2693 2694**示例：** 2695 2696```ts 2697// xxx.ets 2698import { webview } from '@kit.ArkWeb'; 2699 2700@Entry 2701@Component 2702struct WebComponent { 2703 controller: webview.WebviewController = new webview.WebviewController(); 2704 2705 build() { 2706 Column() { 2707 Web({ src: $rawfile("index.html"), controller: this.controller }) 2708 .enableHapticFeedback(true) 2709 } 2710 } 2711} 2712``` 2713 2714 加载的html文件。 2715```html 2716<!--index.html--> 2717<!DOCTYPE html> 2718<html> 2719 <head> 2720 <title>测试网页</title> 2721 </head> 2722 <body> 2723 <h1>enableHapticFeedback Demo</h1> 2724 <span>enable haptic feedback</span> 2725 </body> 2726</html> 2727``` 2728 2729### bindSelectionMenu<sup>13+</sup> 2730 2731bindSelectionMenu(elementType: WebElementType, content: CustomBuilder, responseType: WebResponseType, options?: SelectionMenuOptionsExt) 2732 2733设置自定义选择菜单。 2734 2735**系统能力：** SystemCapability.Web.Webview.Core 2736 2737**参数：** 2738 2739| 参数名 | 类型 | 必填 | 说明 | 2740| ------------ | ------------------------------- | ---- | ----------------------------------- | 2741| elementType | [WebElementType](#webelementtype13枚举说明) | 是 | 菜单的类型。 | 2742| content | [CustomBuilder](../apis-arkui/arkui-ts/ts-types.md#custombuilder8) | 是 | 菜单的内容。 | 2743| responseType | [WebResponseType](#webresponsetype13枚举说明) | 是 | 菜单的响应类型。 | 2744| options | [SelectionMenuOptionsExt](#selectionmenuoptionsext13) | 否 | 菜单的选项。| 2745 2746**示例：** 2747 2748```ts 2749// xxx.ets 2750import { webview } from '@kit.ArkWeb'; 2751 2752interface PreviewBuilderParam { 2753 previewImage: Resource | string | undefined; 2754 width: number; 2755 height: number; 2756} 2757 2758@Builder function PreviewBuilderGlobal($$: PreviewBuilderParam) { 2759 Column() { 2760 Image($$.previewImage) 2761 .objectFit(ImageFit.Fill) 2762 .autoResize(true) 2763 }.width($$.width).height($$.height) 2764} 2765 2766@Entry 2767@Component 2768struct WebComponent { 2769 controller: webview.WebviewController = new webview.WebviewController(); 2770 2771 private result: WebContextMenuResult | undefined = undefined; 2772 @State previewImage: Resource | string | undefined = undefined; 2773 @State previewWidth: number = 0; 2774 @State previewHeight: number = 0; 2775 2776 @Builder 2777 MenuBuilder() { 2778 Menu() { 2779 MenuItem({ content: '复制', }) 2780 .onClick(() => { 2781 this.result?.copy(); 2782 this.result?.closeContextMenu(); 2783 }) 2784 MenuItem({ content: '全选', }) 2785 .onClick(() => { 2786 this.result?.selectAll(); 2787 this.result?.closeContextMenu(); 2788 }) 2789 } 2790 } 2791 build() { 2792 Column() { 2793 Web({ src: $rawfile("index.html"), controller: this.controller }) 2794 .bindSelectionMenu(WebElementType.IMAGE, this.MenuBuilder, WebResponseType.LONG_PRESS, 2795 { 2796 onAppear: () => {}, 2797 onDisappear: () => { 2798 this.result?.closeContextMenu(); 2799 }, 2800 preview: PreviewBuilderGlobal({ 2801 previewImage: this.previewImage, 2802 width: this.previewWidth, 2803 height: this.previewHeight 2804 }), 2805 menuType: MenuType.PREVIEW_MENU 2806 }) 2807 .onContextMenuShow((event) => { 2808 if (event) { 2809 this.result = event.result; 2810 if (event.param.getLinkUrl()) { 2811 return false; 2812 } 2813 this.previewWidth = px2vp(event.param.getPreviewWidth()); 2814 this.previewHeight = px2vp(event.param.getPreviewHeight()); 2815 if (event.param.getSourceUrl().indexOf("resource://rawfile/") == 0) { 2816 this.previewImage = $rawfile(event.param.getSourceUrl().substr(19)); 2817 } else { 2818 this.previewImage = event.param.getSourceUrl(); 2819 } 2820 return true; 2821 } 2822 return false; 2823 }) 2824 } 2825 } 2826} 2827``` 2828 2829 加载的html文件。 2830```html 2831<!--index.html--> 2832<!DOCTYPE html> 2833<html> 2834 <head> 2835 <title>测试网页</title> 2836 </head> 2837 <body> 2838 <h1>bindSelectionMenu Demo</h1> 2839 <img src="./img.png" > 2840 </body> 2841</html> 2842``` 2843 2844### blurOnKeyboardHideMode<sup>14+</sup> 2845 2846blurOnKeyboardHideMode(mode: BlurOnKeyboardHideMode) 2847 2848设置当软键盘收起时Web元素失焦模式。枚举类型的默认值为SILENT，当用户手动收起软键盘时焦点仍在文本框。可更改为BLUR，当用户手动收起软键盘时，焦点会从文本框转移到Web的body上，文本框失焦。 2849 2850**系统能力：** SystemCapability.Web.Webview.Core 2851 2852**参数：** 2853 2854| 参数名 | 类型 | 必填 | 说明 | 2855| ---- | --------------------------------------- | ---- | ------------------ | 2856| mode | [BlurOnKeyboardHideMode](#bluronkeyboardhidemode14枚举说明) | 是 | 设置设置当软键盘收起时Web元素失焦关闭或开启。默认值：BlurOnKeyboardHideMode.SILENT。 | 2857 2858**示例：** 2859 2860 ```ts 2861 // xxx.ets 2862 import { webview } from '@kit.ArkWeb'; 2863 2864 @Entry 2865 @Component 2866 struct WebComponent { 2867 controller: webview.WebviewController = new webview.WebviewController(); 2868 @State blurMode: BlurOnKeyboardHideMode = BlurOnKeyboardHideMode.BLUR; 2869 build() { 2870 Column() { 2871 Web({ src: $rawfile("index.html"), controller: this.controller }) 2872 .blurOnKeyboardHideMode(this.blurMode) 2873 } 2874 } 2875 } 2876 ``` 2877 2878 加载的html文件。 2879```html 2880<!--index.html--> 2881<!DOCTYPE html> 2882<html> 2883 <head> 2884 <title>测试网页</title> 2885 </head> 2886 <body> 2887 <h1>blurOnKeyboardHideMode Demo</h1> 2888 <input type="text" id="input_a"> 2889 <script> 2890 const inputElement = document.getElementById('input_a'); 2891 inputElement.addEventListener('blur', function() { 2892 console.log('Input has lost focus'); 2893 }); 2894 </script> 2895 </body> 2896</html> 2897``` 2898 2899## 事件 2900 2901通用事件仅支持[onAppear](../apis-arkui/arkui-ts/ts-universal-events-show-hide.md#onappear)、[onDisAppear](../apis-arkui/arkui-ts/ts-universal-events-show-hide.md#ondisappear)、[onBlur](../apis-arkui/arkui-ts/ts-universal-focus-event.md#onblur)、[onFocus](../apis-arkui/arkui-ts/ts-universal-focus-event.md#onfocus)、[onDragEnd](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondragend)、[onDragEnter](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondragenter)、[onDragStart](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondragstart)、[onDragMove](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondragmove)、[onDragLeave](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondragleave)、[onDrop](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#ondrop)、[onHover](../apis-arkui/arkui-ts/ts-universal-mouse-key.md#onhover)、[onMouse](../apis-arkui/arkui-ts/ts-universal-mouse-key.md#onmouse)、[onKeyEvent](../apis-arkui/arkui-ts/ts-universal-events-key.md#onkeyevent)、[onTouch](../apis-arkui/arkui-ts/ts-universal-events-touch.md#ontouch)、[onVisibleAreaChange](../apis-arkui/arkui-ts/ts-universal-component-visible-area-change-event.md#onvisibleareachange)。 2902 2903### onAlert 2904 2905onAlert(callback: Callback\<OnAlertEvent, boolean\>) 2906 2907网页触发alert()告警弹窗时触发回调。 2908 2909**系统能力：** SystemCapability.Web.Webview.Core 2910 2911**参数：** 2912 2913| 参数名 | 类型 | 必填 | 说明 | 2914| ------- | --------------------- | ---- | --------------- | 2915| callback | Callback\<[OnAlertEvent](#onalertevent12), boolean\> | 是 | 网页触发alert()告警弹窗时触发<br>返回值boolean。当回调返回true时，应用可以调用自定义弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。当回调返回false时，函数中绘制的自定义弹窗无效。 | 2916 2917**示例：** 2918 2919 ```ts 2920 // xxx.ets 2921 import { webview } from '@kit.ArkWeb'; 2922 2923 @Entry 2924 @Component 2925 struct WebComponent { 2926 controller: webview.WebviewController = new webview.WebviewController(); 2927 2928 build() { 2929 Column() { 2930 Web({ src: $rawfile("index.html"), controller: this.controller }) 2931 .onAlert((event) => { 2932 if (event) { 2933 console.log("event.url:" + event.url); 2934 console.log("event.message:" + event.message); 2935 AlertDialog.show({ 2936 title: 'onAlert', 2937 message: 'text', 2938 primaryButton: { 2939 value: 'cancel', 2940 action: () => { 2941 event.result.handleCancel(); 2942 } 2943 }, 2944 secondaryButton: { 2945 value: 'ok', 2946 action: () => { 2947 event.result.handleConfirm(); 2948 } 2949 }, 2950 cancel: () => { 2951 event.result.handleCancel(); 2952 } 2953 }) 2954 } 2955 return true; 2956 }) 2957 } 2958 } 2959 } 2960 ``` 2961 2962 加载的html文件。 2963 ```html 2964 <!--index.html--> 2965 <!DOCTYPE html> 2966 <html> 2967 <head> 2968 <meta name="viewport" content="width=device-width, initial-scale=1.0" charset="utf-8"> 2969 </head> 2970 <body> 2971 <h1>WebView onAlert Demo</h1> 2972 <button onclick="myFunction()">Click here</button> 2973 <script> 2974 function myFunction() { 2975 alert("Hello World"); 2976 } 2977 </script> 2978 </body> 2979 </html> 2980 ``` 2981 2982### onBeforeUnload 2983 2984onBeforeUnload(callback: Callback\<OnBeforeUnloadEvent, boolean\>) 2985 2986刷新或关闭场景下，在即将离开当前页面时触发此回调。刷新或关闭当前页面应先通过点击等方式获取焦点，才会触发此回调。 2987 2988**系统能力：** SystemCapability.Web.Webview.Core 2989 2990**参数：** 2991 2992| 参数名 | 类型 | 必填 | 说明 | 2993| ------- | --------------------- | ---- | --------------- | 2994| callback | Callback\<[OnBeforeUnloadEvent](#onbeforeunloadevent12), boolean\> | 是 | 刷新或关闭场景下，在即将离开当前页面时触发。<br>返回值boolean。当回调返回true时，应用可以调用自定义弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。当回调返回false时，函数中绘制的自定义弹窗无效。 | 2995 2996**示例：** 2997 2998 ```ts 2999 // xxx.ets 3000 import { webview } from '@kit.ArkWeb'; 3001 3002 @Entry 3003 @Component 3004 struct WebComponent { 3005 controller: webview.WebviewController = new webview.WebviewController(); 3006 3007 build() { 3008 Column() { 3009 Web({ src: $rawfile("index.html"), controller: this.controller }) 3010 .onBeforeUnload((event) => { 3011 if (event) { 3012 console.log("event.url:" + event.url); 3013 console.log("event.message:" + event.message); 3014 AlertDialog.show({ 3015 title: 'onBeforeUnload', 3016 message: 'text', 3017 primaryButton: { 3018 value: 'cancel', 3019 action: () => { 3020 event.result.handleCancel(); 3021 } 3022 }, 3023 secondaryButton: { 3024 value: 'ok', 3025 action: () => { 3026 event.result.handleConfirm(); 3027 } 3028 }, 3029 cancel: () => { 3030 event.result.handleCancel(); 3031 } 3032 }) 3033 } 3034 return true; 3035 }) 3036 } 3037 } 3038 } 3039 ``` 3040 3041 加载的html文件。 3042 ```html 3043 <!--index.html--> 3044 <!DOCTYPE html> 3045 <html> 3046 <head> 3047 <meta name="viewport" content="width=device-width, initial-scale=1.0" charset="utf-8"> 3048 </head> 3049 <body onbeforeunload="return myFunction()"> 3050 <h1>WebView onBeforeUnload Demo</h1> 3051 <a href="https://www.example.com">Click here</a> 3052 <script> 3053 function myFunction() { 3054 return "onBeforeUnload Event"; 3055 } 3056 </script> 3057 </body> 3058 </html> 3059 ``` 3060 3061### onConfirm 3062 3063onConfirm(callback: Callback\<OnConfirmEvent, boolean\>) 3064 3065网页调用confirm()告警时触发此回调。 3066 3067**系统能力：** SystemCapability.Web.Webview.Core 3068 3069**参数：** 3070 3071| 参数名 | 类型 | 必填 | 说明 | 3072| ------- | --------------------- | ---- | --------------- | 3073| callback | Callback\<[OnConfirmEvent](#onconfirmevent12), boolean\> | 是 | 网页调用confirm()告警时触发<br>返回值boolean。当回调返回true时，应用可以调用自定义弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。当回调返回false时，函数中绘制的自定义弹窗无效。 | 3074 3075**示例：** 3076 3077 ```ts 3078 // xxx.ets 3079 import { webview } from '@kit.ArkWeb'; 3080 3081 @Entry 3082 @Component 3083 struct WebComponent { 3084 controller: webview.WebviewController = new webview.WebviewController(); 3085 3086 build() { 3087 Column() { 3088 Web({ src: $rawfile("index.html"), controller: this.controller }) 3089 .onConfirm((event) => { 3090 if (event) { 3091 console.log("event.url:" + event.url); 3092 console.log("event.message:" + event.message); 3093 AlertDialog.show({ 3094 title: 'onConfirm', 3095 message: 'text', 3096 primaryButton: { 3097 value: 'cancel', 3098 action: () => { 3099 event.result.handleCancel(); 3100 } 3101 }, 3102 secondaryButton: { 3103 value: 'ok', 3104 action: () => { 3105 event.result.handleConfirm(); 3106 } 3107 }, 3108 cancel: () => { 3109 event.result.handleCancel(); 3110 } 3111 }) 3112 } 3113 return true; 3114 }) 3115 } 3116 } 3117 } 3118 ``` 3119 3120 加载的html文件。 3121 ```html 3122 <!--index.html--> 3123 <!DOCTYPE html> 3124 <html> 3125 <head> 3126 <meta name="viewport" content="width=device-width, initial-scale=1.0" charset="utf-8"> 3127 </head> 3128 3129 <body> 3130 <h1>WebView onConfirm Demo</h1> 3131 <button onclick="myFunction()">Click here</button> 3132 <p id="demo"></p> 3133 <script> 3134 function myFunction() { 3135 let x; 3136 let r = confirm("click button!"); 3137 if (r == true) { 3138 x = "ok"; 3139 } else { 3140 x = "cancel"; 3141 } 3142 document.getElementById("demo").innerHTML = x; 3143 } 3144 </script> 3145 </body> 3146 </html> 3147 ``` 3148 3149### onPrompt<sup>9+</sup> 3150 3151onPrompt(callback: Callback\<OnPromptEvent, boolean\>) 3152 3153网页调用prompt()告警时触发此回调。 3154 3155**系统能力：** SystemCapability.Web.Webview.Core 3156 3157**参数：** 3158 3159| 参数名 | 类型 | 必填 | 说明 | 3160| ------- | --------------------- | ---- | --------------- | 3161| callback | Callback\<[OnPromptEvent](#onpromptevent12), boolean\> | 是 | 网页调用prompt()告警时触发。<br>返回值boolean。当回调返回true时，应用可以调用自定义弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。当回调返回false时，函数中绘制的自定义弹窗无效。 | 3162 3163**示例：** 3164 3165 ```ts 3166 // xxx.ets 3167 import { webview } from '@kit.ArkWeb'; 3168 3169 @Entry 3170 @Component 3171 struct WebComponent { 3172 controller: webview.WebviewController = new webview.WebviewController(); 3173 3174 build() { 3175 Column() { 3176 Web({ src: $rawfile("index.html"), controller: this.controller }) 3177 .onPrompt((event) => { 3178 if (event) { 3179 console.log("url:" + event.url); 3180 console.log("message:" + event.message); 3181 console.log("value:" + event.value); 3182 AlertDialog.show({ 3183 title: 'onPrompt', 3184 message: 'text', 3185 primaryButton: { 3186 value: 'cancel', 3187 action: () => { 3188 event.result.handleCancel(); 3189 } 3190 }, 3191 secondaryButton: { 3192 value: 'ok', 3193 action: () => { 3194 event.result.handlePromptConfirm(event.value); 3195 } 3196 }, 3197 cancel: () => { 3198 event.result.handleCancel(); 3199 } 3200 }) 3201 } 3202 return true; 3203 }) 3204 } 3205 } 3206 } 3207 ``` 3208 3209 加载的html文件。 3210 ```html 3211 <!--index.html--> 3212 <!DOCTYPE html> 3213 <html> 3214 <head> 3215 <meta name="viewport" content="width=device-width, initial-scale=1.0" charset="utf-8"> 3216 </head> 3217 3218 <body> 3219 <h1>WebView onPrompt Demo</h1> 3220 <button onclick="myFunction()">Click here</button> 3221 <p id="demo"></p> 3222 <script> 3223 function myFunction() { 3224 let message = prompt("Message info", "Hello World"); 3225 if (message != null && message != "") { 3226 document.getElementById("demo").innerHTML = message; 3227 } 3228 } 3229 </script> 3230 </body> 3231 </html> 3232 ``` 3233 3234### onConsole 3235 3236onConsole(callback: Callback\<OnConsoleEvent, boolean\>) 3237 3238通知宿主应用JavaScript console消息。 3239 3240**系统能力：** SystemCapability.Web.Webview.Core 3241 3242**参数：** 3243 3244| 参数名 | 类型 | 必填 | 说明 | 3245| ------- | --------------------------------- | ---- | --------- | 3246| callback | Callback\<[OnConsoleEvent](#onconsoleevent12), boolean\> | 是 | 网页收到JavaScript控制台消息时触发。<br>返回值boolean。当返回true时，该条消息将不会再打印至控制台，反之仍会打印至控制台。 | 3247 3248**示例：** 3249 3250 ```ts 3251 // xxx.ets 3252 import { webview } from '@kit.ArkWeb'; 3253 3254 @Entry 3255 @Component 3256 struct WebComponent { 3257 controller: webview.WebviewController = new webview.WebviewController(); 3258 3259 build() { 3260 Column() { 3261 Button('onconsole message') 3262 .onClick(() => { 3263 this.controller.runJavaScript('myFunction()'); 3264 }) 3265 Web({ src: $rawfile('index.html'), controller: this.controller }) 3266 .onConsole((event) => { 3267 if (event) { 3268 console.log('getMessage:' + event.message.getMessage()); 3269 console.log('getSourceId:' + event.message.getSourceId()); 3270 console.log('getLineNumber:' + event.message.getLineNumber()); 3271 console.log('getMessageLevel:' + event.message.getMessageLevel()); 3272 } 3273 return false; 3274 }) 3275 } 3276 } 3277 } 3278 ``` 3279 3280 加载的html文件。 3281 ```html 3282 <!-- index.html --> 3283 <!DOCTYPE html> 3284 <html> 3285 <body> 3286 <script> 3287 function myFunction() { 3288 console.log("onconsole printf"); 3289 } 3290 </script> 3291 </body> 3292 </html> 3293 ``` 3294 3295### onDownloadStart 3296 3297onDownloadStart(callback: Callback\<OnDownloadStartEvent\>) 3298 3299通知主应用开始下载一个文件。 3300 3301**系统能力：** SystemCapability.Web.Webview.Core 3302 3303**参数：** 3304 3305| 参数名 | 类型 | 必填 | 说明 | 3306| ------------------ | ------ | ---- | ----------------------------------- | 3307| callback | Callback\<[OnDownloadStartEvent](#ondownloadstartevent12)\> | 是 | 开始下载时触发。 | 3308 3309**示例：** 3310 3311 ```ts 3312 // xxx.ets 3313 import { webview } from '@kit.ArkWeb'; 3314 3315 @Entry 3316 @Component 3317 struct WebComponent { 3318 controller: webview.WebviewController = new webview.WebviewController(); 3319 3320 build() { 3321 Column() { 3322 Web({ src: 'www.example.com', controller: this.controller }) 3323 .onDownloadStart((event) => { 3324 if (event) { 3325 console.log('url:' + event.url) 3326 console.log('userAgent:' + event.userAgent) 3327 console.log('contentDisposition:' + event.contentDisposition) 3328 console.log('contentLength:' + event.contentLength) 3329 console.log('mimetype:' + event.mimetype) 3330 } 3331 }) 3332 } 3333 } 3334 } 3335 ``` 3336 3337### onErrorReceive 3338 3339onErrorReceive(callback: Callback\<OnErrorReceiveEvent\>) 3340 3341网页加载遇到错误时触发该回调。主资源与子资源出错都会回调该接口，可以通过request.isMainFrame来判断是否是主资源报错。出于性能考虑，建议此回调中尽量执行简单逻辑。在无网络的情况下，触发此回调。 3342 3343**系统能力：** SystemCapability.Web.Webview.Core 3344 3345**参数：** 3346 3347| 参数名 | 类型 | 必填 | 说明 | 3348| ------- | ---------------------------------------- | ---- | --------------- | 3349| callback | Callback\<[OnErrorReceiveEvent](#onerrorreceiveevent12)\> | 是 | 网页收到 Web 资源加载错误时触发。 | 3350 3351**示例：** 3352 3353 ```ts 3354 // xxx.ets 3355 import { webview } from '@kit.ArkWeb'; 3356 3357 @Entry 3358 @Component 3359 struct WebComponent { 3360 controller: webview.WebviewController = new webview.WebviewController(); 3361 3362 build() { 3363 Column() { 3364 Web({ src: 'www.example.com', controller: this.controller }) 3365 .onErrorReceive((event) => { 3366 if (event) { 3367 console.log('getErrorInfo:' + event.error.getErrorInfo()); 3368 console.log('getErrorCode:' + event.error.getErrorCode()); 3369 console.log('url:' + event.request.getRequestUrl()); 3370 console.log('isMainFrame:' + event.request.isMainFrame()); 3371 console.log('isRedirect:' + event.request.isRedirect()); 3372 console.log('isRequestGesture:' + event.request.isRequestGesture()); 3373 console.log('getRequestHeader_headerKey:' + event.request.getRequestHeader().toString()); 3374 let result = event.request.getRequestHeader(); 3375 console.log('The request header result size is ' + result.length); 3376 for (let i of result) { 3377 console.log('The request header key is : ' + i.headerKey + ', value is : ' + i.headerValue); 3378 } 3379 } 3380 }) 3381 } 3382 } 3383 } 3384 ``` 3385 3386### onHttpErrorReceive 3387 3388onHttpErrorReceive(callback: Callback\<OnHttpErrorReceiveEvent\>) 3389 3390网页加载资源遇到的HTTP错误（响应码>=400)时触发该回调。 3391 3392**系统能力：** SystemCapability.Web.Webview.Core 3393 3394**参数：** 3395 3396| 参数名 | 类型 | 必填 | 说明 | 3397| -------- | ---------------------------------------- | ---- | ---------- | 3398| callback | Callback\<[OnHttpErrorReceiveEvent](#onhttperrorreceiveevent12)\> | 是 | 网页收到加载资源加载HTTP错误时触发。 | 3399 3400**示例：** 3401 3402 ```ts 3403 // xxx.ets 3404 import { webview } from '@kit.ArkWeb'; 3405 3406 @Entry 3407 @Component 3408 struct WebComponent { 3409 controller: webview.WebviewController = new webview.WebviewController(); 3410 3411 build() { 3412 Column() { 3413 Web({ src: 'www.example.com', controller: this.controller }) 3414 .onHttpErrorReceive((event) => { 3415 if (event) { 3416 console.log('url:' + event.request.getRequestUrl()); 3417 console.log('isMainFrame:' + event.request.isMainFrame()); 3418 console.log('isRedirect:' + event.request.isRedirect()); 3419 console.log('isRequestGesture:' + event.request.isRequestGesture()); 3420 console.log('getResponseData:' + event.response.getResponseData()); 3421 console.log('getResponseEncoding:' + event.response.getResponseEncoding()); 3422 console.log('getResponseMimeType:' + event.response.getResponseMimeType()); 3423 console.log('getResponseCode:' + event.response.getResponseCode()); 3424 console.log('getReasonMessage:' + event.response.getReasonMessage()); 3425 let result = event.request.getRequestHeader(); 3426 console.log('The request header result size is ' + result.length); 3427 for (let i of result) { 3428 console.log('The request header key is : ' + i.headerKey + ' , value is : ' + i.headerValue); 3429 } 3430 let resph = event.response.getResponseHeader(); 3431 console.log('The response header result size is ' + resph.length); 3432 for (let i of resph) { 3433 console.log('The response header key is : ' + i.headerKey + ' , value is : ' + i.headerValue); 3434 } 3435 } 3436 }) 3437 } 3438 } 3439 } 3440 ``` 3441 3442### onPageBegin 3443 3444onPageBegin(callback: Callback\<OnPageBeginEvent\>) 3445 3446网页开始加载时触发该回调，且只在主frame触发，iframe或者frameset的内容加载时不会触发此回调。 3447 3448**系统能力：** SystemCapability.Web.Webview.Core 3449 3450**参数：** 3451 3452| 参数名 | 类型 | 必填 | 说明 | 3453| ---- | ------ | ---- | --------- | 3454| callback | Callback\<[OnPageBeginEvent](#onpagebeginevent12)\> | 是 | 网页加载开始时触发。 | 3455 3456**示例：** 3457 3458 ```ts 3459 // xxx.ets 3460 import { webview } from '@kit.ArkWeb'; 3461 3462 @Entry 3463 @Component 3464 struct WebComponent { 3465 controller: webview.WebviewController = new webview.WebviewController(); 3466 3467 build() { 3468 Column() { 3469 Web({ src: 'www.example.com', controller: this.controller }) 3470 .onPageBegin((event) => { 3471 if (event) { 3472 console.log('url:' + event.url); 3473 } 3474 }) 3475 } 3476 } 3477 } 3478 ``` 3479 3480### onPageEnd 3481 3482onPageEnd(callback: Callback\<OnPageEndEvent\>) 3483 3484网页加载完成时触发该回调，且只在主frame触发。 3485 3486**系统能力：** SystemCapability.Web.Webview.Core 3487 3488**参数：** 3489 3490| 参数名 | 类型 | 必填 | 说明 | 3491| ---- | ------ | ---- | --------- | 3492| callback | Callback\<[OnPageEndEvent](#onpageendevent12)\> | 是 | 网页加载结束时触发。 | 3493 3494**示例：** 3495 3496 ```ts 3497 // xxx.ets 3498 import { webview } from '@kit.ArkWeb'; 3499 3500 @Entry 3501 @Component 3502 struct WebComponent { 3503 controller: webview.WebviewController = new webview.WebviewController(); 3504 3505 build() { 3506 Column() { 3507 Web({ src: 'www.example.com', controller: this.controller }) 3508 .onPageEnd((event) => { 3509 if (event) { 3510 console.log('url:' + event.url); 3511 } 3512 }) 3513 } 3514 } 3515 } 3516 ``` 3517 3518### onProgressChange 3519 3520onProgressChange(callback: Callback\<OnProgressChangeEvent\>) 3521 3522网页加载进度变化时触发该回调。 3523 3524**系统能力：** SystemCapability.Web.Webview.Core 3525 3526**参数：** 3527 3528| 参数名 | 类型 | 必填 | 说明 | 3529| ----------- | ------ | ---- | --------------------- | 3530| callback | Callback\<[OnProgressChangeEvent](#onprogresschangeevent12)\> | 是 | 页面加载进度时触发的功能。 | 3531 3532**示例：** 3533 3534 ```ts 3535 // xxx.ets 3536 import { webview } from '@kit.ArkWeb'; 3537 @Entry 3538 @Component 3539 struct WebComponent { 3540 controller: webview.WebviewController = new webview.WebviewController(); 3541 3542 build() { 3543 Column() { 3544 Web({ src: 'www.example.com', controller: this.controller }) 3545 .onProgressChange((event) => { 3546 if (event) { 3547 console.log('newProgress:' + event.newProgress); 3548 } 3549 }) 3550 } 3551 } 3552 } 3553 ``` 3554 3555### onTitleReceive 3556 3557onTitleReceive(callback: Callback\<OnTitleReceiveEvent\>) 3558 3559网页document标题更改时触发该回调，当H5未设置<title\>元素时会返回对应的URL。 3560 3561**系统能力：** SystemCapability.Web.Webview.Core 3562 3563**参数：** 3564 3565| 参数名 | 类型 | 必填 | 说明 | 3566| ----- | ------ | ---- | ------------- | 3567| callback | Callback\<[OnTitleReceiveEvent](#ontitlereceiveevent12)\> | 是 | 定义主应用程序文档标题更改时触发。 | 3568 3569**示例：** 3570 3571 ```ts 3572 // xxx.ets 3573 import { webview } from '@kit.ArkWeb'; 3574 3575 @Entry 3576 @Component 3577 struct WebComponent { 3578 controller: webview.WebviewController = new webview.WebviewController(); 3579 3580 build() { 3581 Column() { 3582 Web({ src: 'www.example.com', controller: this.controller }) 3583 .onTitleReceive((event) => { 3584 if (event) { 3585 console.log('title:' + event.title); 3586 } 3587 }) 3588 } 3589 } 3590 } 3591 ``` 3592 3593### onRefreshAccessedHistory 3594 3595onRefreshAccessedHistory(callback: Callback\<OnRefreshAccessedHistoryEvent\>) 3596 3597加载网页页面完成时触发该回调，用于应用更新其访问的历史链接。 3598 3599**系统能力：** SystemCapability.Web.Webview.Core 3600 3601**参数：** 3602 3603| 参数名 | 类型 | 必填 | 说明 | 3604| ----------- | ------- | ---- | ---------------------------------------- | 3605| callback | Callback\<[OnRefreshAccessedHistoryEvent](#onrefreshaccessedhistoryevent12)\> | 是 | 在网页刷新访问历史记录时触发。 | 3606 3607**示例：** 3608 3609 ```ts 3610 // xxx.ets 3611 import { webview } from '@kit.ArkWeb'; 3612 3613 @Entry 3614 @Component 3615 struct WebComponent { 3616 controller: webview.WebviewController = new webview.WebviewController(); 3617 3618 build() { 3619 Column() { 3620 Web({ src: 'www.example.com', controller: this.controller }) 3621 .onRefreshAccessedHistory((event) => { 3622 if (event) { 3623 console.log('url:' + event.url + ' isReload:' + event.isRefreshed); 3624 } 3625 }) 3626 } 3627 } 3628 } 3629 ``` 3630 3631### onSslErrorReceive<sup>(deprecated)</sup> 3632 3633onSslErrorReceive(callback: (event?: { handler: Function, error: object }) => void) 3634 3635通知用户加载资源时发生SSL错误。 3636 3637> **说明：** 3638> 3639> 从API version 8开始支持，从API version 9开始废弃。建议使用[onSslErrorEventReceive<sup>9+</sup>](#onsslerroreventreceive9)替代。 3640 3641**系统能力：** SystemCapability.Web.Webview.Core 3642 3643### onFileSelectorShow<sup>(deprecated)</sup> 3644 3645onFileSelectorShow(callback: (event?: { callback: Function, fileSelector: object }) => void) 3646 3647调用此函数以处理具有“文件”输入类型的HTML表单，以响应用户按下的“选择文件”按钮。 3648 3649> **说明：** 3650> 3651> 从API version 8开始支持，从API version 9开始废弃。建议使用[onShowFileSelector<sup>9+</sup>](#onshowfileselector9)替代。 3652 3653**系统能力：** SystemCapability.Web.Webview.Core 3654 3655### onRenderExited<sup>9+</sup> 3656 3657onRenderExited(callback: Callback\<OnRenderExitedEvent\>) 3658 3659应用渲染进程异常退出时触发该回调。 3660 3661多个Web组件可能共享单个渲染进程，每个受影响的Web组件都会触发该回调。 3662 3663应用处理该回调时，可以调用绑定的webviewController相关接口来恢复页面。例如[refresh](js-apis-webview.md#refresh)、[loadUrl](js-apis-webview.md#loadurl)等。 3664 3665组件生命周期回调详情可参考[Web组件的生命周期](../../web/web-event-sequence.md)。 3666 3667**系统能力：** SystemCapability.Web.Webview.Core 3668 3669**参数：** 3670 3671| 参数名 | 类型 | 必填 | 说明 | 3672| ---------------- | ---------------------------------------- | ---- | ---------------- | 3673| callback | Callback\<[OnRenderExitedEvent](#onrenderexitedevent12)\> | 是 | 渲染过程退出时触发。 | 3674 3675**示例：** 3676 3677 ```ts 3678 // xxx.ets 3679 import { webview } from '@kit.ArkWeb'; 3680 3681 @Entry 3682 @Component 3683 struct WebComponent { 3684 controller: webview.WebviewController = new webview.WebviewController(); 3685 3686 build() { 3687 Column() { 3688 Web({ src: 'chrome://crash/', controller: this.controller }) 3689 .onRenderExited((event) => { 3690 if (event) { 3691 console.log('reason:' + event.renderExitReason); 3692 } 3693 }) 3694 } 3695 } 3696 } 3697 ``` 3698### onRenderProcessNotResponding<sup>12+</sup> 3699 3700onRenderProcessNotResponding(callback: OnRenderProcessNotRespondingCallback) 3701 3702渲染进程无响应时触发该回调函数。如果Web组件无法处理输入事件，或者无法在合理的时间范围内导航到新的URL，则认为网页进程无响应，并将触发该回调。 3703 3704只要网页进程一直无响应，此回调仍可能会持续触发，直到网页进程再次响应，此时[onRenderProcessResponding](#onrenderprocessresponding12)将会触发。 3705 3706应用可以通过WebviewController接口[terminateRenderProcess](js-apis-webview.md#terminaterenderprocess12)来终止关联的渲染进程，这可能会影响同一渲染进程的其他Web组件。 3707 3708**系统能力：** SystemCapability.Web.Webview.Core 3709 3710**参数：** 3711 3712| 参数名 | 类型 | 必填 | 说明 | 3713| -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | 3714| callback | [OnRenderProcessNotRespondingCallback](#onrenderprocessnotrespondingcallback12) | 是 | 渲染进程无响应时触发的回调。 | 3715 3716**示例：** 3717 3718 ```ts 3719 // xxx.ets 3720 import { webview } from '@kit.ArkWeb'; 3721 3722 @Entry 3723 @Component 3724 struct WebComponent { 3725 controller: webview.WebviewController = new webview.WebviewController(); 3726 3727 build() { 3728 Column() { 3729 Web({ src: 'www.example.com', controller: this.controller }) 3730 .onRenderProcessNotResponding((data) => { 3731 console.log("onRenderProcessNotResponding: [jsStack]= " + data.jsStack + 3732 ", [process]=" + data.pid + ", [reason]=" + data.reason); 3733 }) 3734 } 3735 } 3736 } 3737 ``` 3738 3739### onRenderProcessResponding<sup>12+</sup> 3740 3741onRenderProcessResponding(callback: OnRenderProcessRespondingCallback) 3742 3743渲染进程由无响应状态变回正常运行状态时触发该回调函数,该回调表明该网页并非真正卡死。 3744 3745**系统能力：** SystemCapability.Web.Webview.Core 3746 3747**参数：** 3748 3749| 参数名 | 类型 | 必填 | 说明 | 3750| -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | 3751| callback | [OnRenderProcessRespondingCallback](#onrenderprocessrespondingcallback12) | 是 | 渲染进程由无响应状态变回正常运行状态时触发的回调。 | 3752 3753**示例：** 3754 3755 ```ts 3756 // xxx.ets 3757 import { webview } from '@kit.ArkWeb'; 3758 3759 @Entry 3760 @Component 3761 struct WebComponent { 3762 controller: webview.WebviewController = new webview.WebviewController(); 3763 3764 build() { 3765 Column() { 3766 Web({ src: 'www.example.com', controller: this.controller }) 3767 .onRenderProcessResponding(() => { 3768 console.log("onRenderProcessResponding again"); 3769 }) 3770 } 3771 } 3772 } 3773 ``` 3774 3775### onShowFileSelector<sup>9+</sup> 3776 3777onShowFileSelector(callback: Callback\<OnShowFileSelectorEvent, boolean\>) 3778 3779调用此函数以处理具有“文件”输入类型的HTML表单。如果不调用此函数或返回false，Web组件会提供默认的“选择文件”处理界面。如果返回true，应用可以自定义“选择文件”的响应行为。 3780 3781**系统能力：** SystemCapability.Web.Webview.Core 3782 3783**参数：** 3784 3785| 参数名 | 类型 | 必填 | 说明 | 3786| ------------ | ---------------------------------------- | ---- | ----------------- | 3787| callback | Callback\<[OnShowFileSelectorEvent](#onshowfileselectorevent12), boolean\> | 是 | 用于通知Web组件文件选择的结果。<br>返回值boolean。当返回值为true时，用户可以调用系统提供的弹窗能力。当回调返回false时，函数中绘制的自定义弹窗无效。 | 3788 3789**示例：** 3790 37911. 拉起文件选择器。 3792 3793 ```ts 3794 // xxx.ets 3795 import { webview } from '@kit.ArkWeb'; 3796 import { picker } from '@kit.CoreFileKit'; 3797 import { BusinessError } from '@kit.BasicServicesKit'; 3798 3799 @Entry 3800 @Component 3801 struct WebComponent { 3802 controller: webview.WebviewController = new webview.WebviewController() 3803 3804 build() { 3805 Column() { 3806 Web({ src: $rawfile('index.html'), controller: this.controller }) 3807 .onShowFileSelector((event) => { 3808 console.log('MyFileUploader onShowFileSelector invoked') 3809 const documentSelectOptions = new picker.DocumentSelectOptions(); 3810 let uri: string | null = null; 3811 const documentViewPicker = new picker.DocumentViewPicker(); 3812 documentViewPicker.select(documentSelectOptions).then((documentSelectResult) => { 3813 uri = documentSelectResult[0]; 3814 console.info('documentViewPicker.select to file succeed and uri is:' + uri); 3815 if (event) { 3816 event.result.handleFileList([uri]); 3817 } 3818 }).catch((err: BusinessError) => { 3819 console.error(`Invoke documentViewPicker.select failed, code is ${err.code}, message is ${err.message}`); 3820 }) 3821 return true; 3822 }) 3823 } 3824 } 3825 } 3826 ``` 3827 38282. 拉起图库选择器。 3829 3830 ```ts 3831 // xxx.ets 3832 import { webview } from '@kit.ArkWeb'; 3833 import { picker } from '@kit.CoreFileKit'; 3834 import { photoAccessHelper } from '@kit.MediaLibraryKit'; 3835 3836 @Entry 3837 @Component 3838 export struct WebComponent { 3839 controller: webview.WebviewController = new webview.WebviewController() 3840 3841 async selectFile(result: FileSelectorResult): Promise<void> { 3842 let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions(); 3843 let photoPicker = new photoAccessHelper.PhotoViewPicker(); 3844 // 过滤选择媒体文件类型为IMAGE 3845 photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_VIDEO_TYPE; 3846 // 设置最大选择数量 3847 photoSelectOptions.maxSelectNumber = 5; 3848 let chooseFile: picker.PhotoSelectResult = await photoPicker.select(photoSelectOptions); 3849 // 获取选择的文件列表 3850 result.handleFileList(chooseFile.photoUris); 3851 } 3852 3853 build() { 3854 Column() { 3855 Web({ src: $rawfile('index.html'), controller: this.controller }) 3856 .onShowFileSelector((event) => { 3857 if (event) { 3858 this.selectFile(event.result); 3859 } 3860 return true; 3861 }) 3862 } 3863 } 3864 } 3865 ``` 3866 3867 加载的html文件。 3868 ```html 3869 <!DOCTYPE html> 3870 <html> 3871 <head> 3872 <meta name="viewport" content="width=device-width, initial-scale=1.0" charset="utf-8"> 3873 </head> 3874 <body> 3875 <form id="upload-form" enctype="multipart/form-data"> 3876 <input type="file" id="upload" name="upload"/> 3877 </form> 3878 </body> 3879 </html> 3880 ``` 3881 3882### onResourceLoad<sup>9+</sup> 3883 3884onResourceLoad(callback: Callback\<OnResourceLoadEvent\>) 3885 3886通知Web组件所加载的资源文件url信息。 3887 3888**系统能力：** SystemCapability.Web.Webview.Core 3889 3890**参数：** 3891 3892| 参数名 | 类型 | 必填 | 说明 | 3893| ------ | ------ | ---- | --------------------- | 3894| callback | Callback\<[OnResourceLoadEvent](#onresourceloadevent12)\> | 是 | 加载url时触发。 | 3895 3896**示例：** 3897 3898 ```ts 3899 // xxx.ets 3900 import { webview } from '@kit.ArkWeb'; 3901 3902 @Entry 3903 @Component 3904 struct WebComponent { 3905 controller: webview.WebviewController = new webview.WebviewController(); 3906 3907 build() { 3908 Column() { 3909 Web({ src: 'www.example.com', controller: this.controller }) 3910 .onResourceLoad((event) => { 3911 console.log('onResourceLoad: ' + event.url); 3912 }) 3913 } 3914 } 3915 } 3916 ``` 3917 3918### onScaleChange<sup>9+</sup> 3919 3920onScaleChange(callback: Callback\<OnScaleChangeEvent\>) 3921 3922当前页面显示比例的变化时触发该回调。 3923 3924**系统能力：** SystemCapability.Web.Webview.Core 3925 3926**参数：** 3927 3928| 参数名 | 类型 | 必填 | 说明 | 3929| ------ | ------ | ---- | --------------------- | 3930| callback | Callback\<[OnScaleChangeEvent](#onscalechangeevent12)\> | 是 | 当前页面显示比例的变化时触发。 | 3931 3932**示例：** 3933 3934 ```ts 3935 // xxx.ets 3936 import { webview } from '@kit.ArkWeb'; 3937 3938 @Entry 3939 @Component 3940 struct WebComponent { 3941 controller: webview.WebviewController = new webview.WebviewController(); 3942 3943 build() { 3944 Column() { 3945 Web({ src: 'www.example.com', controller: this.controller }) 3946 .onScaleChange((event) => { 3947 console.log('onScaleChange changed from ' + event.oldScale + ' to ' + event.newScale); 3948 }) 3949 } 3950 } 3951 } 3952 ``` 3953 3954### onUrlLoadIntercept<sup>(deprecated)</sup> 3955 3956onUrlLoadIntercept(callback: (event?: { data:string | WebResourceRequest }) => boolean) 3957 3958当Web组件加载url之前触发该回调，用于判断是否阻止此次访问。默认允许加载。 3959从API version 10开始不再维护，建议使用[onLoadIntercept<sup>10+</sup>](#onloadintercept10)代替。 3960 3961**系统能力：** SystemCapability.Web.Webview.Core 3962 3963**参数：** 3964 3965| 参数名 | 类型 | 必填 | 说明 | 3966| ------ | ------ | ---- | --------------------- | 3967| callback | (event?: { data:string \| [WebResourceRequest](#webresourcerequest) }) => boolean | 是 | url的相关信息。返回值：boolean，true表示阻止此次加载，否则允许此次加载。 | 3968 3969**示例：** 3970 3971 ```ts 3972 // xxx.ets 3973 import { webview } from '@kit.ArkWeb'; 3974 3975 @Entry 3976 @Component 3977 struct WebComponent { 3978 controller: webview.WebviewController = new webview.WebviewController(); 3979 3980 build() { 3981 Column() { 3982 Web({ src: 'www.example.com', controller: this.controller }) 3983 .onUrlLoadIntercept((event) => { 3984 if (event) { 3985 console.log('onUrlLoadIntercept ' + event.data.toString()); 3986 } 3987 return true 3988 }) 3989 } 3990 } 3991 } 3992 ``` 3993 3994### onInterceptRequest<sup>9+</sup> 3995 3996onInterceptRequest(callback: Callback<OnInterceptRequestEvent, WebResourceResponse>) 3997 3998当Web组件加载url之前触发该回调，用于拦截url并返回响应数据。 3999 4000**系统能力：** SystemCapability.Web.Webview.Core 4001 4002**参数：** 4003 4004| 参数名 | 类型 | 必填 | 说明 | 4005| ------ | ------ | ---- | --------------------- | 4006| callback | Callback\<[OnInterceptRequestEvent](#oninterceptrequestevent12)\> | 是 | 当Web组件加载url之前触发。<br>返回值[WebResourceResponse](#webresourceresponse)。返回响应数据则按照响应数据加载，无响应数据则返回null表示按照原来的方式加载。 | 4007 4008**示例：** 4009 4010 ```ts 4011 // xxx.ets 4012 import { webview } from '@kit.ArkWeb'; 4013 4014 @Entry 4015 @Component 4016 struct WebComponent { 4017 controller: webview.WebviewController = new webview.WebviewController(); 4018 responseWeb: WebResourceResponse = new WebResourceResponse(); 4019 heads: Header[] = new Array(); 4020 webData: string = "<!DOCTYPE html>\n" + 4021 "<html>\n" + 4022 "<head>\n" + 4023 "<title>intercept test</title>\n" + 4024 "</head>\n" + 4025 "<body>\n" + 4026 "<h1>intercept test</h1>\n" + 4027 "</body>\n" + 4028 "</html>"; 4029 4030 build() { 4031 Column() { 4032 Web({ src: 'www.example.com', controller: this.controller }) 4033 .onInterceptRequest((event) => { 4034 if (event) { 4035 console.log('url:' + event.request.getRequestUrl()); 4036 } 4037 let head1: Header = { 4038 headerKey: "Connection", 4039 headerValue: "keep-alive" 4040 } 4041 let head2: Header = { 4042 headerKey: "Cache-Control", 4043 headerValue: "no-cache" 4044 } 4045 // 将新元素追加到数组的末尾，并返回数组的新长度。 4046 let length = this.heads.push(head1); 4047 length = this.heads.push(head2); 4048 console.log('The response header result length is :' + length); 4049 const promise: Promise<String> = new Promise((resolve: Function, reject: Function) => { 4050 this.responseWeb.setResponseHeader(this.heads); 4051 this.responseWeb.setResponseData(this.webData); 4052 this.responseWeb.setResponseEncoding('utf-8'); 4053 this.responseWeb.setResponseMimeType('text/html'); 4054 this.responseWeb.setResponseCode(200); 4055 this.responseWeb.setReasonMessage('OK'); 4056 resolve("success"); 4057 }) 4058 promise.then(() => { 4059 console.log("prepare response ready"); 4060 this.responseWeb.setResponseIsReady(true); 4061 }) 4062 this.responseWeb.setResponseIsReady(false); 4063 return this.responseWeb; 4064 }) 4065 } 4066 } 4067 } 4068 ``` 4069 4070### onHttpAuthRequest<sup>9+</sup> 4071 4072onHttpAuthRequest(callback: Callback\<OnHttpAuthRequestEvent, boolean\>) 4073 4074通知收到http auth认证请求。 4075 4076**系统能力：** SystemCapability.Web.Webview.Core 4077 4078**参数：** 4079 4080| 参数名 | 类型 | 必填 | 说明 | 4081| ------ | ------ | ---- | --------------------- | 4082| callback | Callback\<[OnHttpAuthRequestEvent](#onhttpauthrequestevent12), boolean\> | 是 | 当浏览器需要用户的凭据时触发。<br>返回值boolean。返回false表示此次认证失败，否则成功。 | 4083 4084**示例：** 4085 4086 ```ts 4087 // xxx.ets 4088 import { webview } from '@kit.ArkWeb'; 4089 4090 @Entry 4091 @Component 4092 struct WebComponent { 4093 controller: webview.WebviewController = new webview.WebviewController(); 4094 httpAuth: boolean = false; 4095 4096 build() { 4097 Column() { 4098 Web({ src: 'www.example.com', controller: this.controller }) 4099 .onHttpAuthRequest((event) => { 4100 if (event) { 4101 AlertDialog.show({ 4102 title: 'onHttpAuthRequest', 4103 message: 'text', 4104 primaryButton: { 4105 value: 'cancel', 4106 action: () => { 4107 event.handler.cancel(); 4108 } 4109 }, 4110 secondaryButton: { 4111 value: 'ok', 4112 action: () => { 4113 this.httpAuth = event.handler.isHttpAuthInfoSaved(); 4114 if (this.httpAuth == false) { 4115 webview.WebDataBase.saveHttpAuthCredentials( 4116 event.host, 4117 event.realm, 4118 "2222", 4119 "2222" 4120 ) 4121 event.handler.cancel(); 4122 } 4123 } 4124 }, 4125 cancel: () => { 4126 event.handler.cancel(); 4127 } 4128 }) 4129 } 4130 return true; 4131 }) 4132 } 4133 } 4134 } 4135 ``` 4136### onSslErrorEventReceive<sup>9+</sup> 4137 4138onSslErrorEventReceive(callback: Callback\<OnSslErrorEventReceiveEvent\>) 4139 4140通知用户加载资源时发生SSL错误，只支持主资源。 4141如果需要支持子资源，请使用[OnSslErrorEvent](#onsslerrorevent12)接口。 4142 4143**系统能力：** SystemCapability.Web.Webview.Core 4144 4145**参数：** 4146 4147| 参数名 | 类型 | 必填 | 说明 | 4148| ------ | ------ | ---- | --------------------- | 4149| callback | Callback\<[OnSslErrorEventReceiveEvent](#onsslerroreventreceiveevent12)\> | 是 | 当网页收到SSL错误时触发。 | 4150 4151**示例：** 4152 4153 ```ts 4154 // xxx.ets 4155 import { webview } from '@kit.ArkWeb'; 4156 4157 @Entry 4158 @Component 4159 struct WebComponent { 4160 controller: webview.WebviewController = new webview.WebviewController(); 4161 4162 build() { 4163 Column() { 4164 Web({ src: 'www.example.com', controller: this.controller }) 4165 .onSslErrorEventReceive((event) => { 4166 AlertDialog.show({ 4167 title: 'onSslErrorEventReceive', 4168 message: 'text', 4169 primaryButton: { 4170 value: 'confirm', 4171 action: () => { 4172 event.handler.handleConfirm(); 4173 } 4174 }, 4175 secondaryButton: { 4176 value: 'cancel', 4177 action: () => { 4178 event.handler.handleCancel(); 4179 } 4180 }, 4181 cancel: () => { 4182 event.handler.handleCancel(); 4183 } 4184 }) 4185 }) 4186 } 4187 } 4188 } 4189 ``` 4190 4191### onSslErrorEvent<sup>12+</sup> 4192 4193onSslErrorEvent(callback: OnSslErrorEventCallback) 4194 4195通知用户加载资源（主资源+子资源）时发生SSL错误，如果只想处理主资源的SSL错误，请用isMainFrame字段进行区分。 4196 4197**系统能力：** SystemCapability.Web.Webview.Core 4198 4199**参数：** 4200 4201| 参数名 | 类型 | 必填 | 说明 | 4202| ------ | ------ | ---- | --------------------- | 4203| callback | [OnSslErrorEventCallback](#onsslerroreventcallback12) | 是 | 通知用户加载资源时发生SSL错误。 | 4204 4205**示例：** 4206 4207 ```ts 4208 // xxx.ets 4209 import { webview } from '@kit.ArkWeb'; 4210 4211 @Entry 4212 @Component 4213 struct WebComponent { 4214 controller: webview.WebviewController = new webview.WebviewController(); 4215 4216 build() { 4217 Column() { 4218 Web({ src: 'www.example.com', controller: this.controller }) 4219 .onSslErrorEvent((event: SslErrorEvent) => { 4220 console.log("onSslErrorEvent url: " + event.url); 4221 console.log("onSslErrorEvent error: " + event.error); 4222 console.log("onSslErrorEvent originalUrl: " + event.originalUrl); 4223 console.log("onSslErrorEvent referrer: " + event.referrer); 4224 console.log("onSslErrorEvent isFatalError: " + event.isFatalError); 4225 console.log("onSslErrorEvent isMainFrame: " + event.isMainFrame); 4226 AlertDialog.show({ 4227 title: 'onSslErrorEvent', 4228 message: 'text', 4229 primaryButton: { 4230 value: 'confirm', 4231 action: () => { 4232 event.handler.handleConfirm(); 4233 } 4234 }, 4235 secondaryButton: { 4236 value: 'cancel', 4237 action: () => { 4238 event.handler.handleCancel(); 4239 } 4240 }, 4241 cancel: () => { 4242 event.handler.handleCancel(); 4243 } 4244 }) 4245 }) 4246 } 4247 } 4248 } 4249 ``` 4250 4251### onClientAuthenticationRequest<sup>9+</sup> 4252 4253onClientAuthenticationRequest(callback: Callback\<OnClientAuthenticationEvent\>) 4254 4255通知用户收到SSL客户端证书请求事件。 4256 4257**系统能力：** SystemCapability.Web.Webview.Core 4258 4259**参数：** 4260 4261| 参数名 | 类型 | 必填 | 说明 | 4262| ------ | ------ | ---- | --------------------- | 4263| callback | Callback\<[OnClientAuthenticationEvent](#onclientauthenticationevent12)\> | 是 | 当需要用户提供的SSL客户端证书时触发的回调。 | 4264 4265 **示例：** 4266 4267 未对接证书管理的双向认证。 4268 4269 ```ts 4270 // xxx.ets API9 4271 import { webview } from '@kit.ArkWeb'; 4272 4273 @Entry 4274 @Component 4275 struct WebComponent { 4276 controller: webview.WebviewController = new webview.WebviewController(); 4277 4278 build() { 4279 Column() { 4280 Web({ src: 'www.example.com', controller: this.controller }) 4281 .onClientAuthenticationRequest((event) => { 4282 AlertDialog.show({ 4283 title: 'onClientAuthenticationRequest', 4284 message: 'text', 4285 primaryButton: { 4286 value: 'confirm', 4287 action: () => { 4288 event.handler.confirm("/system/etc/user.pk8", "/system/etc/chain-user.pem"); 4289 } 4290 }, 4291 secondaryButton: { 4292 value: 'cancel', 4293 action: () => { 4294 event.handler.cancel(); 4295 } 4296 }, 4297 cancel: () => { 4298 event.handler.ignore(); 4299 } 4300 }) 4301 }) 4302 } 4303 } 4304 } 4305 ``` 4306 4307 对接证书管理的双向认证。 4308 4309 1. 构造单例对象GlobalContext。 4310 4311 ```ts 4312 // GlobalContext.ets 4313 export class GlobalContext { 4314 private constructor() {} 4315 private static instance: GlobalContext; 4316 private _objects = new Map<string, Object>(); 4317 4318 public static getContext(): GlobalContext { 4319 if (!GlobalContext.instance) { 4320 GlobalContext.instance = new GlobalContext(); 4321 } 4322 return GlobalContext.instance; 4323 } 4324 4325 getObject(value: string): Object | undefined { 4326 return this._objects.get(value); 4327 } 4328 4329 setObject(key: string, objectClass: Object): void { 4330 this._objects.set(key, objectClass); 4331 } 4332 } 4333 ``` 4334 4335 4336 2. 实现双向认证。 4337 4338 ```ts 4339 // xxx.ets API10 4340 import { webview } from '@kit.ArkWeb'; 4341 import { common, Want, bundleManager } from '@kit.AbilityKit'; 4342 import { BusinessError } from '@kit.BasicServicesKit'; 4343 import { GlobalContext } from '../GlobalContext'; 4344 4345 let uri = ""; 4346 4347 export default class CertManagerService { 4348 private static sInstance: CertManagerService; 4349 private authUri = ""; 4350 private appUid = ""; 4351 4352 public static getInstance(): CertManagerService { 4353 if (CertManagerService.sInstance == null) { 4354 CertManagerService.sInstance = new CertManagerService(); 4355 } 4356 return CertManagerService.sInstance; 4357 } 4358 4359 async grantAppPm(callback: (message: string) => void) { 4360 let message = ''; 4361 let bundleFlags = bundleManager.BundleFlag.GET_BUNDLE_INFO_DEFAULT | bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION; 4362 // 注：com.example.myapplication需要写实际应用名称 4363 try { 4364 bundleManager.getBundleInfoForSelf(bundleFlags).then((data) => { 4365 console.info('getBundleInfoForSelf successfully. Data: %{public}s', JSON.stringify(data)); 4366 this.appUid = data.appInfo.uid.toString(); 4367 }).catch((err: BusinessError) => { 4368 console.error('getBundleInfoForSelf failed. Cause: %{public}s', err.message); 4369 }); 4370 } catch (err) { 4371 let message = (err as BusinessError).message; 4372 console.error('getBundleInfoForSelf failed: %{public}s', message); 4373 } 4374 4375 // 注：需要在MainAbility.ts文件的onCreate函数里添加GlobalContext.getContext().setObject("AbilityContext", this.context) 4376 let abilityContext = GlobalContext.getContext().getObject("AbilityContext") as common.UIAbilityContext 4377 await abilityContext.startAbilityForResult( 4378 { 4379 bundleName: "com.ohos.certmanager", 4380 abilityName: "MainAbility", 4381 uri: "requestAuthorize", 4382 parameters: { 4383 appUid: this.appUid, // 传入申请应用的appUid 4384 } 4385 } as Want) 4386 .then((data: common.AbilityResult) => { 4387 if (!data.resultCode && data.want) { 4388 if (data.want.parameters) { 4389 this.authUri = data.want.parameters.authUri as string; // 授权成功后获取返回的authUri 4390 } 4391 } 4392 }) 4393 message += "after grantAppPm authUri: " + this.authUri; 4394 uri = this.authUri; 4395 callback(message) 4396 } 4397 } 4398 4399 @Entry 4400 @Component 4401 struct WebComponent { 4402 controller: webview.WebviewController = new webview.WebviewController(); 4403 @State message: string = 'Hello World' // message主要是调试观察使用 4404 certManager = CertManagerService.getInstance(); 4405 4406 build() { 4407 Row() { 4408 Column() { 4409 Row() { 4410 // 第一步：需要先进行授权，获取到uri 4411 Button('GrantApp') 4412 .onClick(() => { 4413 this.certManager.grantAppPm((data) => { 4414 this.message = data; 4415 }); 4416 }) 4417 // 第二步：授权后，双向认证会通过onClientAuthenticationRequest回调将uri传给web进行认证 4418 Button("ClientCertAuth") 4419 .onClick(() => { 4420 this.controller.loadUrl('https://www.example2.com'); // 支持双向认证的服务器网站 4421 }) 4422 } 4423 4424 Web({ src: 'https://www.example1.com', controller: this.controller }) 4425 .fileAccess(true) 4426 .javaScriptAccess(true) 4427 .domStorageAccess(true) 4428 .onlineImageAccess(true) 4429 4430 .onClientAuthenticationRequest((event) => { 4431 AlertDialog.show({ 4432 title: 'ClientAuth', 4433 message: 'Text', 4434 confirm: { 4435 value: 'Confirm', 4436 action: () => { 4437 event.handler.confirm(uri); 4438 } 4439 }, 4440 cancel: () => { 4441 event.handler.cancel(); 4442 } 4443 }) 4444 }) 4445 } 4446 } 4447 .width('100%') 4448 .height('100%') 4449 } 4450 } 4451 ``` 4452 4453### onPermissionRequest<sup>9+</sup> 4454 4455onPermissionRequest(callback: Callback\<OnPermissionRequestEvent\>) 4456 4457通知收到获取权限请求，需配置"ohos.permission.CAMERA"、"ohos.permission.MICROPHONE"权限。 4458 4459**系统能力：** SystemCapability.Web.Webview.Core 4460 4461**参数：** 4462 4463| 参数名 | 类型 | 必填 | 说明 | 4464| ------ | ------ | ---- | --------------------- | 4465| callback | Callback\<[OnPermissionRequestEvent](#onpermissionrequestevent12)\> | 是 | 通知收到获取权限请求触发。 | 4466 4467**示例：** 4468 4469 ```ts 4470 // xxx.ets 4471 import { webview } from '@kit.ArkWeb'; 4472 import { BusinessError } from '@kit.BasicServicesKit'; 4473 import { abilityAccessCtrl } from '@kit.AbilityKit'; 4474 4475 @Entry 4476 @Component 4477 struct WebComponent { 4478 controller: webview.WebviewController = new webview.WebviewController(); 4479 4480 aboutToAppear() { 4481 // 配置Web开启调试模式 4482 webview.WebviewController.setWebDebuggingAccess(true); 4483 let atManager = abilityAccessCtrl.createAtManager(); 4484 atManager.requestPermissionsFromUser(getContext(this), ['ohos.permission.CAMERA', 'ohos.permission.MICROPHONE']) 4485 .then((data) => { 4486 console.info('data:' + JSON.stringify(data)); 4487 console.info('data permissions:' + data.permissions); 4488 console.info('data authResults:' + data.authResults); 4489 }).catch((error: BusinessError) => { 4490 console.error(`Failed to request permissions from user. Code is ${error.code}, message is ${error.message}`); 4491 }) 4492 } 4493 4494 build() { 4495 Column() { 4496 Web({ src: $rawfile('index.html'), controller: this.controller }) 4497 .onPermissionRequest((event) => { 4498 if (event) { 4499 AlertDialog.show({ 4500 title: 'title', 4501 message: 'text', 4502 primaryButton: { 4503 value: 'deny', 4504 action: () => { 4505 event.request.deny(); 4506 } 4507 }, 4508 secondaryButton: { 4509 value: 'onConfirm', 4510 action: () => { 4511 event.request.grant(event.request.getAccessibleResource()); 4512 } 4513 }, 4514 cancel: () => { 4515 event.request.deny(); 4516 } 4517 }) 4518 } 4519 }) 4520 } 4521 } 4522 } 4523 ``` 4524 4525 加载的html文件。 4526 ```html 4527 <!-- index.html --> 4528 <!DOCTYPE html> 4529 <html> 4530 <head> 4531 <meta charset="UTF-8"> 4532 </head> 4533 <body> 4534 <video id="video" width="500px" height="500px" autoplay="autoplay"></video> 4535 <canvas id="canvas" width="500px" height="500px"></canvas> 4536 <br> 4537 <input type="button" title="HTML5摄像头" value="开启摄像头" onclick="getMedia()"/> 4538 <script> 4539 function getMedia() 4540 { 4541 let constraints = { 4542 video: {width: 500, height: 500}, 4543 audio: true 4544 }; 4545 // 获取video摄像头区域 4546 let video = document.getElementById("video"); 4547 // 返回的Promise对象 4548 let promise = navigator.mediaDevices.getUserMedia(constraints); 4549 // then()异步，调用MediaStream对象作为参数 4550 promise.then(function (MediaStream) { 4551 video.srcObject = MediaStream; 4552 video.play(); 4553 }); 4554 } 4555 </script> 4556 </body> 4557 </html> 4558 ``` 4559 4560### onContextMenuShow<sup>9+</sup> 4561 4562onContextMenuShow(callback: Callback\<OnContextMenuShowEvent, boolean\>) 4563 4564长按特定元素（例如图片，链接）或鼠标右键，跳出菜单。 4565 4566**系统能力：** SystemCapability.Web.Webview.Core 4567 4568**参数：** 4569 4570| 参数名 | 类型 | 必填 | 说明 | 4571| ------ | ------ | ---- | --------------------- | 4572| callback | Callback\<[OnContextMenuShowEvent](#oncontextmenushowevent12), boolean\> | 是 | 调用时触发的回调，以允许自定义显示上下文菜单。<br>返回值boolean。自定义菜单返回true，触发的自定义菜单无效返回false。 | 4573 4574**示例：** 4575 4576 ```ts 4577 // xxx.ets 4578 import { webview } from '@kit.ArkWeb'; 4579 import { pasteboard } from '@kit.BasicServicesKit'; 4580 4581 const TAG = 'ContextMenu'; 4582 4583 @Entry 4584 @Component 4585 struct WebComponent { 4586 controller: webview.WebviewController = new webview.WebviewController(); 4587 private result: WebContextMenuResult | undefined = undefined; 4588 @State linkUrl: string = ''; 4589 @State offsetX: number = 0; 4590 @State offsetY: number = 0; 4591 @State showMenu: boolean = false; 4592 4593 @Builder 4594 // 构建自定义菜单及触发功能接口 4595 MenuBuilder() { 4596 // 以垂直列表形式显示的菜单。 4597 Menu() { 4598 // 展示菜单Menu中具体的item菜单项。 4599 MenuItem({ 4600 content: '复制图片', 4601 }) 4602 .width(100) 4603 .height(50) 4604 .onClick(() => { 4605 this.result?.copyImage(); 4606 this.showMenu = false; 4607 }) 4608 MenuItem({ 4609 content: '剪切', 4610 }) 4611 .width(100) 4612 .height(50) 4613 .onClick(() => { 4614 this.result?.cut(); 4615 this.showMenu = false; 4616 }) 4617 MenuItem({ 4618 content: '复制', 4619 }) 4620 .width(100) 4621 .height(50) 4622 .onClick(() => { 4623 this.result?.copy(); 4624 this.showMenu = false; 4625 }) 4626 MenuItem({ 4627 content: '粘贴', 4628 }) 4629 .width(100) 4630 .height(50) 4631 .onClick(() => { 4632 this.result?.paste(); 4633 this.showMenu = false; 4634 }) 4635 MenuItem({ 4636 content: '复制链接', 4637 }) 4638 .width(100) 4639 .height(50) 4640 .onClick(() => { 4641 let pasteData = pasteboard.createData('text/plain', this.linkUrl); 4642 pasteboard.getSystemPasteboard().setData(pasteData, (error) => { 4643 if (error) { 4644 return; 4645 } 4646 }) 4647 this.showMenu = false; 4648 }) 4649 MenuItem({ 4650 content: '全选', 4651 }) 4652 .width(100) 4653 .height(50) 4654 .onClick(() => { 4655 this.result?.selectAll(); 4656 this.showMenu = false; 4657 }) 4658 } 4659 .width(150) 4660 .height(300) 4661 } 4662 4663 build() { 4664 Column() { 4665 Web({ src: $rawfile("index.html"), controller: this.controller }) 4666 // 触发自定义弹窗 4667 .onContextMenuShow((event) => { 4668 if (event) { 4669 this.result = event.result 4670 console.info("x coord = " + event.param.x()); 4671 console.info("link url = " + event.param.getLinkUrl()); 4672 this.linkUrl = event.param.getLinkUrl(); 4673 } 4674 console.info(TAG, `x: ${this.offsetX}, y: ${this.offsetY}`); 4675 this.showMenu = true; 4676 this.offsetX = 0; 4677 this.offsetY = Math.max(px2vp(event?.param.y() ?? 0) - 0, 0); 4678 return true; 4679 }) 4680 .bindPopup(this.showMenu, 4681 { 4682 builder: this.MenuBuilder(), 4683 enableArrow: false, 4684 placement: Placement.LeftTop, 4685 offset: { x: this.offsetX, y: this.offsetY }, 4686 mask: false, 4687 onStateChange: (e) => { 4688 if (!e.isVisible) { 4689 this.showMenu = false; 4690 this.result!.closeContextMenu(); 4691 } 4692 } 4693 }) 4694 } 4695 } 4696 } 4697 ``` 4698 4699 加载的html文件。 4700 ```html 4701 <!-- index.html --> 4702 <!DOCTYPE html> 4703 <html lang="en"> 4704 <body> 4705 <h1>onContextMenuShow</h1> 4706 <a href="http://www.example.com" style="font-size:27px">链接www.example.com</a> 4707 // rawfile下放任意一张图片命名为example.png 4708 <div><img src="example.png"></div> 4709 <p>选中文字鼠标右键弹出菜单</p> 4710 </body> 4711 </html> 4712 ``` 4713 4714### onContextMenuHide<sup>11+</sup> 4715 4716onContextMenuHide(callback: OnContextMenuHideCallback) 4717 4718长按特定元素（例如图片，链接）或鼠标右键，隐藏菜单。 4719 4720**系统能力：** SystemCapability.Web.Webview.Core 4721 4722**参数：** 4723 4724| 参数名 | 类型 | 必填 | 说明 | 4725| ------ | ------ | ---- | --------------------- | 4726| callback | [OnContextMenuHideCallback](#oncontextmenuhidecallback11) | 是 | 菜单相关参数。 | 4727 4728**示例：** 4729 4730 ```ts 4731 // xxx.ets 4732 import { webview } from '@kit.ArkWeb'; 4733 4734 @Entry 4735 @Component 4736 struct WebComponent { 4737 controller: webview.WebviewController = new webview.WebviewController(); 4738 4739 build() { 4740 Column() { 4741 Web({ src: 'www.example.com', controller: this.controller }) 4742 .onContextMenuHide(() => { 4743 console.log("onContextMenuHide callback"); 4744 }) 4745 } 4746 } 4747 } 4748 ``` 4749 4750### onScroll<sup>9+</sup> 4751 4752onScroll(callback: Callback\<OnScrollEvent\>) 4753 4754通知网页滚动条滚动位置。 4755 4756**系统能力：** SystemCapability.Web.Webview.Core 4757 4758**参数：** 4759 4760| 参数名 | 类型 | 必填 | 说明 | 4761| ------ | ------ | ---- | --------------------- | 4762| callback | Callback\<[OnScrollEvent](#onscrollevent12)\> | 是 | 当滚动条滑动到指定位置时触发。 | 4763 4764**示例：** 4765 4766 ```ts 4767 // xxx.ets 4768 import { webview } from '@kit.ArkWeb'; 4769 4770 @Entry 4771 @Component 4772 struct WebComponent { 4773 controller: webview.WebviewController = new webview.WebviewController(); 4774 4775 build() { 4776 Column() { 4777 Web({ src: 'www.example.com', controller: this.controller }) 4778 .onScroll((event) => { 4779 console.info("x = " + event.xOffset); 4780 console.info("y = " + event.yOffset); 4781 }) 4782 } 4783 } 4784 } 4785 ``` 4786 4787### onGeolocationShow 4788 4789onGeolocationShow(callback: Callback\<OnGeolocationShowEvent\>) 4790 4791通知用户收到地理位置信息获取请求。 4792 4793**系统能力：** SystemCapability.Web.Webview.Core 4794 4795**参数：** 4796 4797| 参数名 | 类型 | 必填 | 说明 | 4798| ------ | ------ | ---- | --------------------- | 4799| callback | Callback\<[OnGeolocationShowEvent](#ongeolocationshowevent12)\> | 是 | 请求显示地理位置权限时触发。 | 4800 4801**示例：** 4802 4803 ```ts 4804 // xxx.ets 4805 import { webview } from '@kit.ArkWeb'; 4806 4807 @Entry 4808 @Component 4809 struct WebComponent { 4810 controller: webview.WebviewController = new webview.WebviewController(); 4811 4812 build() { 4813 Column() { 4814 Web({ src: $rawfile('index.html'), controller: this.controller }) 4815 .geolocationAccess(true) 4816 .onGeolocationShow((event) => { 4817 if (event) { 4818 AlertDialog.show({ 4819 title: 'title', 4820 message: 'text', 4821 confirm: { 4822 value: 'onConfirm', 4823 action: () => { 4824 event.geolocation.invoke(event.origin, true, true); 4825 } 4826 }, 4827 cancel: () => { 4828 event.geolocation.invoke(event.origin, false, true); 4829 } 4830 }) 4831 } 4832 }) 4833 } 4834 } 4835 } 4836 ``` 4837 4838 加载的html文件。 4839 ```html 4840 <!DOCTYPE html> 4841 <html> 4842 <body> 4843 <p id="locationInfo">位置信息</p> 4844 <button onclick="getLocation()">获取位置</button> 4845 <script> 4846 var locationInfo=document.getElementById("locationInfo"); 4847 function getLocation(){ 4848 if (navigator.geolocation) { 4849 <!-- 前端页面访问设备地理位置 --> 4850 navigator.geolocation.getCurrentPosition(showPosition); 4851 } 4852 } 4853 function showPosition(position){ 4854 locationInfo.innerHTML="Latitude: " + position.coords.latitude + "<br />Longitude: " + position.coords.longitude; 4855 } 4856 </script> 4857 </body> 4858 </html> 4859 ``` 4860 4861### onGeolocationHide 4862 4863onGeolocationHide(callback: () => void) 4864 4865通知用户先前被调用[onGeolocationShow](#ongeolocationshow)时收到地理位置信息获取请求已被取消。 4866 4867**系统能力：** SystemCapability.Web.Webview.Core 4868 4869**参数：** 4870 4871| 参数名 | 类型 | 必填 | 说明 | 4872| ------ | ------ | ---- | --------------------- | 4873| callback | () => void | 是 | 地理位置信息获取请求已被取消的回调函数。 | 4874 4875**示例：** 4876 4877 ```ts 4878 // xxx.ets 4879 import { webview } from '@kit.ArkWeb'; 4880 4881 @Entry 4882 @Component 4883 struct WebComponent { 4884 controller: webview.WebviewController = new webview.WebviewController(); 4885 4886 build() { 4887 Column() { 4888 Web({ src: 'www.example.com', controller: this.controller }) 4889 .geolocationAccess(true) 4890 .onGeolocationHide(() => { 4891 console.log("onGeolocationHide..."); 4892 }) 4893 } 4894 } 4895 } 4896 ``` 4897 4898### onFullScreenEnter<sup>9+</sup> 4899 4900onFullScreenEnter(callback: OnFullScreenEnterCallback) 4901 4902通知开发者Web组件进入全屏模式。 4903 4904**系统能力：** SystemCapability.Web.Webview.Core 4905 4906**参数：** 4907 4908| 参数名 | 类型 | 必填 | 说明 | 4909| ------ | ------ | ---- | --------------------- | 4910| callback | [OnFullScreenEnterCallback](#onfullscreenentercallback12) | 是 | Web组件进入全屏时的回调信息。 | 4911 4912**示例：** 4913 4914 ```ts 4915 // xxx.ets 4916 import { webview } from '@kit.ArkWeb'; 4917 4918 @Entry 4919 @Component 4920 struct WebComponent { 4921 controller: webview.WebviewController = new webview.WebviewController(); 4922 handler: FullScreenExitHandler | null = null; 4923 4924 build() { 4925 Column() { 4926 Web({ src: 'www.example.com', controller: this.controller }) 4927 .onFullScreenEnter((event) => { 4928 console.log("onFullScreenEnter videoWidth: " + event.videoWidth + 4929 ", videoHeight: " + event.videoHeight); 4930 // 应用可以通过 this.handler.exitFullScreen() 主动退出全屏。 4931 this.handler = event.handler; 4932 }) 4933 } 4934 } 4935 } 4936 ``` 4937 4938### onFullScreenExit<sup>9+</sup> 4939 4940onFullScreenExit(callback: () => void) 4941 4942通知开发者Web组件退出全屏模式。 4943 4944**系统能力：** SystemCapability.Web.Webview.Core 4945 4946**参数：** 4947 4948| 参数名 | 类型 | 必填 | 说明 | 4949| ------ | ------ | ---- | --------------------- | 4950| callback | () => void | 是 | 退出全屏模式时的回调函数。 | 4951 4952**示例：** 4953 4954 ```ts 4955 // xxx.ets 4956 import { webview } from '@kit.ArkWeb'; 4957 4958 @Entry 4959 @Component 4960 struct WebComponent { 4961 controller: webview.WebviewController = new webview.WebviewController(); 4962 handler: FullScreenExitHandler | null = null; 4963 4964 build() { 4965 Column() { 4966 Web({ src: 'www.example.com', controller: this.controller }) 4967 .onFullScreenExit(() => { 4968 console.log("onFullScreenExit...") 4969 if (this.handler) { 4970 this.handler.exitFullScreen(); 4971 } 4972 }) 4973 .onFullScreenEnter((event) => { 4974 this.handler = event.handler; 4975 }) 4976 } 4977 } 4978 } 4979 ``` 4980 4981### onWindowNew<sup>9+</sup> 4982 4983onWindowNew(callback: Callback\<OnWindowNewEvent\>) 4984 4985使能multiWindowAccess情况下，通知用户新建窗口请求。 4986若不调用event.handler.setWebController接口，会造成render进程阻塞。 4987如果没有创建新窗口，调用event.handler.setWebController接口时设置成null，通知Web没有创建新窗口。 4988 4989应用应谨慎的显示新窗口：不要简单的覆盖在原web组件上，防止误导用户正在查看哪个网站，如果应用显示主页的URL，请确保也以相似的方式显示新窗口的URL。否则请考虑完全禁止创建新窗口。 4990 4991注意：没有可靠的方式判断哪个页面请求了新窗口，该请求可能来自第三方iframe 4992 4993**系统能力：** SystemCapability.Web.Webview.Core 4994 4995**参数：** 4996 4997| 参数名 | 类型 | 必填 | 说明 | 4998| ------ | ------ | ---- | --------------------- | 4999| callback | Callback\<[OnWindowNewEvent](#onwindownewevent12)\> | 是 | 网页要求用户创建窗口时触发的回调。 | 5000 5001**示例：** 5002 5003 ```ts 5004 // xxx.ets 5005 import { webview } from '@kit.ArkWeb'; 5006 5007 // 在同一page页有两个Web组件。在WebComponent新开窗口时，会跳转到NewWebViewComp。 5008 @CustomDialog 5009 struct NewWebViewComp { 5010 controller?: CustomDialogController; 5011 webviewController1: webview.WebviewController = new webview.WebviewController(); 5012 5013 build() { 5014 Column() { 5015 Web({ src: "", controller: this.webviewController1 }) 5016 .javaScriptAccess(true) 5017 .multiWindowAccess(false) 5018 .onWindowExit(() => { 5019 console.info("NewWebViewComp onWindowExit"); 5020 if (this.controller) { 5021 this.controller.close(); 5022 } 5023 }) 5024 } 5025 } 5026 } 5027 5028 @Entry 5029 @Component 5030 struct WebComponent { 5031 controller: webview.WebviewController = new webview.WebviewController(); 5032 dialogController: CustomDialogController | null = null; 5033 5034 build() { 5035 Column() { 5036 Web({ src: 'www.example.com', controller: this.controller }) 5037 .javaScriptAccess(true) 5038 // 需要使能multiWindowAccess 5039 .multiWindowAccess(true) 5040 .allowWindowOpenMethod(true) 5041 .onWindowNew((event) => { 5042 if (this.dialogController) { 5043 this.dialogController.close(); 5044 } 5045 let popController: webview.WebviewController = new webview.WebviewController(); 5046 this.dialogController = new CustomDialogController({ 5047 builder: NewWebViewComp({ webviewController1: popController }) 5048 }) 5049 this.dialogController.open(); 5050 // 将新窗口对应WebviewController返回给Web内核。 5051 // 若不调用event.handler.setWebController接口，会造成render进程阻塞。 5052 // 如果没有创建新窗口，调用event.handler.setWebController接口时设置成null，通知Web没有创建新窗口。 5053 event.handler.setWebController(popController); 5054 }) 5055 } 5056 } 5057 } 5058 ``` 5059 5060### onWindowExit<sup>9+</sup> 5061 5062onWindowExit(callback: () => void) 5063 5064通知用户窗口关闭请求。和[onWindowNew](#onwindownew9)一样，从安全角度讲，应用应该确保用户可以知道他们交互的页面已关闭。 5065 5066**系统能力：** SystemCapability.Web.Webview.Core 5067 5068**参数：** 5069 5070| 参数名 | 类型 | 必填 | 说明 | 5071| ------ | ------ | ---- | --------------------- | 5072| callback | () => void | 是 | 窗口请求关闭的回调函数。 | 5073 5074**示例：** 5075 5076 ```ts 5077 // xxx.ets 5078 import { webview } from '@kit.ArkWeb'; 5079 5080 @Entry 5081 @Component 5082 struct WebComponent { 5083 controller: webview.WebviewController = new webview.WebviewController(); 5084 5085 build() { 5086 Column() { 5087 Web({ src: 'www.example.com', controller: this.controller }) 5088 .onWindowExit(() => { 5089 console.log("onWindowExit..."); 5090 }) 5091 } 5092 } 5093 } 5094 ``` 5095 5096### onSearchResultReceive<sup>9+</sup> 5097 5098onSearchResultReceive(callback: Callback\<OnSearchResultReceiveEvent\>) 5099 5100回调通知调用方网页页内查找的结果。 5101 5102**系统能力：** SystemCapability.Web.Webview.Core 5103 5104**参数：** 5105 5106| 参数名 | 类型 | 必填 | 说明 | 5107| ------ | ------ | ---- | --------------------- | 5108| callback | Callback\<[OnSearchResultReceiveEvent](#onsearchresultreceiveevent12)\> | 是 | 通知调用方网页页内查找的结果。 | 5109 5110**示例：** 5111 5112 ```ts 5113 // xxx.ets 5114 import { webview } from '@kit.ArkWeb'; 5115 5116 @Entry 5117 @Component 5118 struct WebComponent { 5119 controller: webview.WebviewController = new webview.WebviewController(); 5120 5121 build() { 5122 Column() { 5123 Web({ src: 'www.example.com', controller: this.controller }) 5124 .onSearchResultReceive(ret => { 5125 if (ret) { 5126 console.log("on search result receive:" + "[cur]" + ret.activeMatchOrdinal + 5127 "[total]" + ret.numberOfMatches + "[isDone]" + ret.isDoneCounting); 5128 } 5129 }) 5130 } 5131 } 5132 } 5133 ``` 5134 5135### onDataResubmitted<sup>9+</sup> 5136 5137onDataResubmitted(callback: Callback\<OnDataResubmittedEvent\>) 5138 5139设置网页表单可以重新提交时触发的回调函数。 5140 5141**系统能力：** SystemCapability.Web.Webview.Core 5142 5143**参数：** 5144 5145| 参数名 | 类型 | 必填 | 说明 | 5146| ------ | ------ | ---- | --------------------- | 5147| callback | Callback\<[OnDataResubmittedEvent](#ondataresubmittedevent12)\> | 是 | 网页表单可以重新提交时触发。 | 5148 5149**示例：** 5150 5151 ```ts 5152 // xxx.ets 5153 import { webview } from '@kit.ArkWeb'; 5154 import { BusinessError } from '@kit.BasicServicesKit'; 5155 5156 @Entry 5157 @Component 5158 struct WebComponent { 5159 controller: webview.WebviewController = new webview.WebviewController(); 5160 5161 build() { 5162 Column() { 5163 // 在网页中点击提交之后，点击refresh按钮可以重新提交时的触发函数。 5164 Button('refresh') 5165 .onClick(() => { 5166 try { 5167 this.controller.refresh(); 5168 } catch (error) { 5169 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5170 } 5171 }) 5172 Web({ src: $rawfile('index.html'), controller: this.controller }) 5173 .onDataResubmitted((event) => { 5174 console.log('onDataResubmitted'); 5175 event.handler.resend(); 5176 }) 5177 } 5178 } 5179 } 5180 ``` 5181 5182 加载的html文件。 5183 ```html 5184 <!-- index.html --> 5185 <!DOCTYPE html> 5186 <html> 5187 <head> 5188 <meta charset="utf-8"> 5189 </head> 5190 <body> 5191 <form action="http://httpbin.org/post" method="post"> 5192 <input type="text" name="username"> 5193 <input type="submit" name="提交"> 5194 </form> 5195 </body> 5196 </html> 5197 ``` 5198 5199### onPageVisible<sup>9+</sup> 5200 5201onPageVisible(callback: Callback\<OnPageVisibleEvent\>) 5202 5203设置旧页面不再呈现，新页面即将可见时触发的回调函数。 5204 5205**系统能力：** SystemCapability.Web.Webview.Core 5206 5207**参数：** 5208 5209| 参数名 | 类型 | 必填 | 说明 | 5210| ------ | ------ | ---- | --------------------- | 5211| callback | Callback\<[OnPageVisibleEvent](#onpagevisibleevent12)\> | 是 | 旧页面不再呈现，新页面即将可见时触发的回调函数。 | 5212 5213**示例：** 5214 5215 ```ts 5216 // xxx.ets 5217 import { webview } from '@kit.ArkWeb'; 5218 5219 @Entry 5220 @Component 5221 struct WebComponent { 5222 controller: webview.WebviewController = new webview.WebviewController(); 5223 5224 build() { 5225 Column() { 5226 Web({ src: 'www.example.com', controller: this.controller }) 5227 .onPageVisible((event) => { 5228 console.log('onPageVisible url:' + event.url); 5229 }) 5230 } 5231 } 5232 } 5233 ``` 5234 5235### onInterceptKeyEvent<sup>9+</sup> 5236 5237onInterceptKeyEvent(callback: (event: KeyEvent) => boolean) 5238 5239设置键盘事件的回调函数，该回调在被Webview使用前触发。 5240 5241**系统能力：** SystemCapability.Web.Webview.Core 5242 5243**参数：** 5244 5245| 参数名 | 类型 | 必填 | 说明 | 5246| ------ | ------ | ---- | --------------------- | 5247| callback | (event:[KeyEvent](../apis-arkui/arkui-ts/ts-universal-events-key.md#keyevent对象说明)) => boolean | 是 | 触发的KeyEvent事件。返回值：回调函数通过返回boolean类型值来决定是否继续将该KeyEvent传入Webview内核。 | 5248 5249**示例：** 5250 5251 ```ts 5252 // xxx.ets 5253 import { webview } from '@kit.ArkWeb'; 5254 5255 @Entry 5256 @Component 5257 struct WebComponent { 5258 controller: webview.WebviewController = new webview.WebviewController(); 5259 5260 build() { 5261 Column() { 5262 Web({ src: 'www.example.com', controller: this.controller }) 5263 .onInterceptKeyEvent((event) => { 5264 if (event.keyCode == 2017 || event.keyCode == 2018) { 5265 console.info(`onInterceptKeyEvent get event.keyCode ${event.keyCode}`); 5266 return true; 5267 } 5268 return false; 5269 }) 5270 } 5271 } 5272 } 5273 ``` 5274 5275### onTouchIconUrlReceived<sup>9+</sup> 5276 5277onTouchIconUrlReceived(callback: Callback\<OnTouchIconUrlReceivedEvent\>) 5278 5279设置接收到apple-touch-icon url地址时的回调函数。 5280 5281**系统能力：** SystemCapability.Web.Webview.Core 5282 5283**参数：** 5284 5285| 参数名 | 类型 | 必填 | 说明 | 5286| ------ | ------ | ---- | --------------------- | 5287| callback | Callback\<[OnTouchIconUrlReceivedEvent](#ontouchiconurlreceivedevent12)\> | 是 | 接收到的apple-touch-icon url地址时触发。 | 5288 5289**示例：** 5290 5291 ```ts 5292 // xxx.ets 5293 import { webview } from '@kit.ArkWeb'; 5294 5295 @Entry 5296 @Component 5297 struct WebComponent { 5298 controller: webview.WebviewController = new webview.WebviewController(); 5299 5300 build() { 5301 Column() { 5302 Web({ src: 'www.baidu.com', controller: this.controller }) 5303 .onTouchIconUrlReceived((event) => { 5304 console.log('onTouchIconUrlReceived:' + JSON.stringify(event)); 5305 }) 5306 } 5307 } 5308 } 5309 ``` 5310 5311### onFaviconReceived<sup>9+</sup> 5312 5313onFaviconReceived(callback: Callback\<OnFaviconReceivedEvent\>) 5314 5315设置应用为当前页面接收到新的favicon时的回调函数。 5316 5317**系统能力：** SystemCapability.Web.Webview.Core 5318 5319**参数：** 5320 5321| 参数名 | 类型 | 必填 | 说明 | 5322| ------ | ------ | ---- | --------------------- | 5323| callback | Callback\<[OnFaviconReceivedEvent](#onfaviconreceivedevent12)\> | 是 | 当前页面接收到新的favicon时触发。 | 5324 5325**示例：** 5326 5327 ```ts 5328 // xxx.ets 5329 import { webview } from '@kit.ArkWeb'; 5330 import { image } from '@kit.ImageKit'; 5331 5332 @Entry 5333 @Component 5334 struct WebComponent { 5335 controller: webview.WebviewController = new webview.WebviewController(); 5336 @State icon: image.PixelMap | undefined = undefined; 5337 5338 build() { 5339 Column() { 5340 Web({ src: 'www.example.com', controller: this.controller }) 5341 .onFaviconReceived((event) => { 5342 console.log('onFaviconReceived'); 5343 this.icon = event.favicon; 5344 }) 5345 } 5346 } 5347 } 5348 ``` 5349 5350### onAudioStateChanged<sup>10+</sup> 5351 5352onAudioStateChanged(callback: Callback\<OnAudioStateChangedEvent\>) 5353 5354设置网页上的音频播放状态发生改变时的回调函数。 5355 5356**系统能力：** SystemCapability.Web.Webview.Core 5357 5358**参数：** 5359 5360| 参数名 | 类型 | 必填 | 说明 | 5361| ------ | ------ | ---- | --------------------- | 5362| callback | Callback\<[OnAudioStateChangedEvent](#onaudiostatechangedevent12)\> | 是 | 网页上的音频播放状态发生改变时触发。 | 5363 5364**示例：** 5365 5366 ```ts 5367 // xxx.ets 5368 import { webview } from '@kit.ArkWeb'; 5369 5370 @Entry 5371 @Component 5372 struct WebComponent { 5373 controller: webview.WebviewController = new webview.WebviewController(); 5374 @State playing: boolean = false; 5375 5376 build() { 5377 Column() { 5378 Web({ src: 'www.example.com', controller: this.controller }) 5379 .onAudioStateChanged(event => { 5380 this.playing = event.playing; 5381 console.debug('onAudioStateChanged playing: ' + this.playing); 5382 }) 5383 } 5384 } 5385 } 5386 ``` 5387 5388### onFirstContentfulPaint<sup>10+</sup> 5389 5390 onFirstContentfulPaint(callback: Callback\<OnFirstContentfulPaintEvent\>) 5391 5392设置网页首次内容绘制回调函数。 5393 5394**系统能力：** SystemCapability.Web.Webview.Core 5395 5396**参数：** 5397 5398| 参数名 | 类型 | 必填 | 说明 | 5399| ------ | ------ | ---- | --------------------- | 5400| callback | Callback\<[OnFirstContentfulPaintEvent](#onfirstcontentfulpaintevent12)\> | 是 | 网页首次内容绘制回调函数。 | 5401 5402**示例：** 5403 5404 ```ts 5405 // xxx.ets 5406 import { webview } from '@kit.ArkWeb'; 5407 5408 @Entry 5409 @Component 5410 struct WebComponent { 5411 controller: webview.WebviewController = new webview.WebviewController(); 5412 5413 build() { 5414 Column() { 5415 Web({ src: 'www.example.com', controller: this.controller }) 5416 .onFirstContentfulPaint(event => { 5417 if (event) { 5418 console.log("onFirstContentfulPaint:" + "[navigationStartTick]:" + 5419 event.navigationStartTick + ", [firstContentfulPaintMs]:" + 5420 event.firstContentfulPaintMs); 5421 } 5422 }) 5423 } 5424 } 5425 } 5426 ``` 5427 5428### onFirstMeaningfulPaint<sup>12+</sup> 5429 5430onFirstMeaningfulPaint(callback: [OnFirstMeaningfulPaintCallback](#onfirstmeaningfulpaintcallback12)) 5431 5432设置网页绘制页面主要内容回调函数。 5433 5434**系统能力：** SystemCapability.Web.Webview.Core 5435 5436**参数：** 5437 5438| 参数名 | 类型 | 必填 | 说明 | 5439| ------ | ------ | ---- | --------------------- | 5440| callback | [OnFirstMeaningfulPaintCallback](#onfirstmeaningfulpaintcallback12) | 是 | 网页绘制页面主要内容度量信息的回调。 | 5441 5442**示例：** 5443 5444 ```ts 5445 // xxx.ets 5446 import { webview } from '@kit.ArkWeb'; 5447 5448 @Entry 5449 @Component 5450 struct WebComponent { 5451 controller: webview.WebviewController = new webview.WebviewController(); 5452 5453 build() { 5454 Column() { 5455 Web({ src: 'www.example.com', controller: this.controller }) 5456 .onFirstMeaningfulPaint((details) => { 5457 console.log("onFirstMeaningfulPaint: [navigationStartTime]= " + details.navigationStartTime + 5458 ", [firstMeaningfulPaintTime]=" + details.firstMeaningfulPaintTime); 5459 }) 5460 } 5461 } 5462 } 5463 ``` 5464 5465### onLargestContentfulPaint<sup>12+</sup> 5466 5467onLargestContentfulPaint(callback: [OnLargestContentfulPaintCallback](#onlargestcontentfulpaintcallback12)) 5468 5469设置网页绘制页面最大内容回调函数。 5470 5471**系统能力：** SystemCapability.Web.Webview.Core 5472 5473**参数：** 5474 5475| 参数名 | 类型 | 必填 | 说明 | 5476| ------ | ------ | ---- | --------------------- | 5477| callback | [OnLargestContentfulPaintCallback](#onlargestcontentfulpaintcallback12) | 是 | 网页绘制页面最大内容度量信息的回调。 | 5478 5479**示例：** 5480 5481 ```ts 5482 // xxx.ets 5483 import { webview } from '@kit.ArkWeb'; 5484 5485 @Entry 5486 @Component 5487 struct WebComponent { 5488 controller: webview.WebviewController = new webview.WebviewController(); 5489 5490 build() { 5491 Column() { 5492 Web({ src: 'www.example.com', controller: this.controller }) 5493 .onLargestContentfulPaint((details) => { 5494 console.log("onLargestContentfulPaint: [navigationStartTime]= " + details.navigationStartTime + 5495 ", [largestImagePaintTime]=" + details.largestImagePaintTime + 5496 ", [largestTextPaintTime]=" + details.largestTextPaintTime + 5497 ", [largestImageLoadStartTime]=" + details.largestImageLoadStartTime + 5498 ", [largestImageLoadEndTime]=" + details.largestImageLoadEndTime + 5499 ", [imageBPP]=" + details.imageBPP); 5500 }) 5501 } 5502 } 5503 } 5504 ``` 5505 5506### onLoadIntercept<sup>10+</sup> 5507 5508onLoadIntercept(callback: Callback\<OnLoadInterceptEvent, boolean\>) 5509 5510当Web组件加载url之前触发该回调，用于判断是否阻止此次访问。默认允许加载。 5511 5512**系统能力：** SystemCapability.Web.Webview.Core 5513 5514**参数：** 5515 5516| 参数名 | 类型 | 必填 | 说明 | 5517| ------ | ------ | ---- | --------------------- | 5518| callback | Callback\<[OnLoadInterceptEvent](#onloadinterceptevent12), boolean\> | 是 | 截获资源加载时触发的回调。<br>返回值boolean。返回true表示阻止此次加载，否则允许此次加载。 | 5519 5520**示例：** 5521 5522 ```ts 5523 // xxx.ets 5524 import { webview } from '@kit.ArkWeb'; 5525 5526 @Entry 5527 @Component 5528 struct WebComponent { 5529 controller: webview.WebviewController = new webview.WebviewController(); 5530 5531 build() { 5532 Column() { 5533 Web({ src: 'www.example.com', controller: this.controller }) 5534 .onLoadIntercept((event) => { 5535 console.log('url:' + event.data.getRequestUrl()); 5536 console.log('isMainFrame:' + event.data.isMainFrame()); 5537 console.log('isRedirect:' + event.data.isRedirect()); 5538 console.log('isRequestGesture:' + event.data.isRequestGesture()); 5539 return true; 5540 }) 5541 } 5542 } 5543 } 5544 ``` 5545 5546### onRequestSelected 5547 5548onRequestSelected(callback: () => void) 5549 5550当Web组件获得焦点时触发该回调。 5551 5552**系统能力：** SystemCapability.Web.Webview.Core 5553 5554**示例：** 5555 5556 ```ts 5557 // xxx.ets 5558 import { webview } from '@kit.ArkWeb'; 5559 5560 @Entry 5561 @Component 5562 struct WebComponent { 5563 controller: webview.WebviewController = new webview.WebviewController(); 5564 5565 build() { 5566 Column() { 5567 Web({ src: 'www.example.com', controller: this.controller }) 5568 .onRequestSelected(() => { 5569 console.log('onRequestSelected'); 5570 }) 5571 } 5572 } 5573 } 5574 ``` 5575### onScreenCaptureRequest<sup>10+</sup> 5576 5577onScreenCaptureRequest(callback: Callback\<OnScreenCaptureRequestEvent\>) 5578 5579通知收到屏幕捕获请求。 5580 5581**系统能力：** SystemCapability.Web.Webview.Core 5582 5583**参数：** 5584 5585| 参数名 | 类型 | 必填 | 说明 | 5586| ------ | ------ | ---- | --------------------- | 5587| callback | Callback\<[OnScreenCaptureRequestEvent](#onscreencapturerequestevent12)\> | 是 | 通知收到屏幕捕获请求。 | 5588 5589**示例：** 5590 5591 ```ts 5592 // xxx.ets 5593 import { webview } from '@kit.ArkWeb'; 5594 5595 @Entry 5596 @Component 5597 struct WebComponent { 5598 controller: webview.WebviewController = new webview.WebviewController(); 5599 5600 build() { 5601 Column() { 5602 Web({ src: 'www.example.com', controller: this.controller }) 5603 .onScreenCaptureRequest((event) => { 5604 if (event) { 5605 AlertDialog.show({ 5606 title: 'title: ' + event.handler.getOrigin(), 5607 message: 'text', 5608 primaryButton: { 5609 value: 'deny', 5610 action: () => { 5611 event.handler.deny(); 5612 } 5613 }, 5614 secondaryButton: { 5615 value: 'onConfirm', 5616 action: () => { 5617 event.handler.grant({ captureMode: WebCaptureMode.HOME_SCREEN }); 5618 } 5619 }, 5620 cancel: () => { 5621 event.handler.deny(); 5622 } 5623 }) 5624 } 5625 }) 5626 } 5627 } 5628 } 5629 ``` 5630 5631### onOverScroll<sup>10+</sup> 5632 5633onOverScroll(callback: Callback\<OnOverScrollEvent\>) 5634 5635该接口在网页过度滚动时触发，用于通知网页过度滚动的偏移量。 5636 5637**系统能力：** SystemCapability.Web.Webview.Core 5638 5639**参数：** 5640 5641| 参数名 | 类型 | 必填 | 说明 | 5642| ------ | ------ | ---- | --------------------- | 5643| callback | Callback\<[OnOverScrollEvent](#onoverscrollevent12)\> | 是 | 网页过度滚动时触发。 | 5644 5645**示例：** 5646 5647 ```ts 5648 // xxx.ets 5649 import { webview } from '@kit.ArkWeb'; 5650 5651 @Entry 5652 @Component 5653 struct WebComponent { 5654 controller: webview.WebviewController = new webview.WebviewController(); 5655 5656 build() { 5657 Column() { 5658 Web({ src: 'www.example.com', controller: this.controller }) 5659 .onOverScroll((event) => { 5660 console.info("x = " + event.xOffset); 5661 console.info("y = " + event.yOffset); 5662 }) 5663 } 5664 } 5665 } 5666 ``` 5667 5668### onControllerAttached<sup>10+</sup> 5669 5670onControllerAttached(callback: () => void) 5671 5672当Controller成功绑定到Web组件时触发该回调，并且该Controller必须为WebviewController，且禁止在该事件回调前调用Web组件相关的接口，否则会抛出js-error异常。 5673因该回调调用时网页还未加载，无法在回调中使用有关操作网页的接口，例如[zoomIn](js-apis-webview.md#zoomin)、[zoomOut](js-apis-webview.md#zoomout)等，可以使用[loadUrl](js-apis-webview.md#loadurl)、[getWebId](js-apis-webview.md#getwebid)等操作网页不相关的接口。 5674 5675组件生命周期详情可参考[Web组件的生命周期](../../web/web-event-sequence.md)。 5676 5677**系统能力：** SystemCapability.Web.Webview.Core 5678 5679**示例：** 5680 5681在该回调中使用loadUrl加载网页 5682 ```ts 5683 // xxx.ets 5684 import { webview } from '@kit.ArkWeb'; 5685 5686 @Entry 5687 @Component 5688 struct WebComponent { 5689 controller: webview.WebviewController = new webview.WebviewController(); 5690 5691 build() { 5692 Column() { 5693 Web({ src: '', controller: this.controller }) 5694 .onControllerAttached(() => { 5695 this.controller.loadUrl($rawfile("index.html")); 5696 }) 5697 } 5698 } 5699 } 5700 ``` 5701 5702在该回调中使用getWebId 5703 ```ts 5704 // xxx.ets 5705 import { webview } from '@kit.ArkWeb'; 5706 import { BusinessError } from '@kit.BasicServicesKit'; 5707 5708 @Entry 5709 @Component 5710 struct WebComponent { 5711 controller: webview.WebviewController = new webview.WebviewController(); 5712 5713 build() { 5714 Column() { 5715 Web({ src: $rawfile("index.html"), controller: this.controller }) 5716 .onControllerAttached(() => { 5717 try { 5718 let id = this.controller.getWebId(); 5719 console.log("id: " + id); 5720 } catch (error) { 5721 let code = (error as BusinessError).code; 5722 let message = (error as BusinessError).message; 5723 console.error(`ErrorCode: ${code}, Message: ${message}`); 5724 } 5725 }) 5726 } 5727 } 5728 } 5729 ``` 5730 加载的html文件。 5731 ```html 5732 <!-- index.html --> 5733 <!DOCTYPE html> 5734 <html> 5735 <body> 5736 <p>Hello World</p> 5737 </body> 5738 </html> 5739 ``` 5740 5741### onNavigationEntryCommitted<sup>11+</sup> 5742 5743onNavigationEntryCommitted(callback: [OnNavigationEntryCommittedCallback](#onnavigationentrycommittedcallback11)) 5744 5745当网页跳转提交时触发该回调。 5746 5747**系统能力：** SystemCapability.Web.Webview.Core 5748 5749**参数：** 5750 5751| 参数名 | 类型 | 必填 | 说明 | 5752| ------ | ------ | ---- | --------------------- | 5753| callback | [OnNavigationEntryCommittedCallback](#onnavigationentrycommittedcallback11) | 是 | 网页跳转提交时触发的回调。 | 5754 5755**示例：** 5756 5757 ```ts 5758 // xxx.ets 5759 import { webview } from '@kit.ArkWeb'; 5760 5761 @Entry 5762 @Component 5763 struct WebComponent { 5764 controller: webview.WebviewController = new webview.WebviewController(); 5765 5766 build() { 5767 Column() { 5768 Web({ src: 'www.example.com', controller: this.controller }) 5769 .onNavigationEntryCommitted((details) => { 5770 console.log("onNavigationEntryCommitted: [isMainFrame]= " + details.isMainFrame + 5771 ", [isSameDocument]=" + details.isSameDocument + 5772 ", [didReplaceEntry]=" + details.didReplaceEntry + 5773 ", [navigationType]=" + details.navigationType + 5774 ", [url]=" + details.url); 5775 }) 5776 } 5777 } 5778 } 5779 ``` 5780 5781### onSafeBrowsingCheckResult<sup>11+</sup> 5782 5783onSafeBrowsingCheckResult(callback: OnSafeBrowsingCheckResultCallback) 5784 5785收到网站安全风险检查结果时触发的回调。 5786 5787**系统能力：** SystemCapability.Web.Webview.Core 5788 5789**参数：** 5790 5791| 参数名 | 类型 | 必填 | 说明 | 5792| ------ | ------ | ---- | --------------------- | 5793| callback | [OnSafeBrowsingCheckResultCallback](#onsafebrowsingcheckresultcallback11) | 是 | 收到网站安全风险检查结果时触发的回调。| 5794 5795**示例：** 5796 5797 ```ts 5798 // xxx.ets 5799 import { webview } from '@kit.ArkWeb'; 5800 5801 export enum ThreatType { 5802 UNKNOWN = -1, 5803 THREAT_ILLEGAL = 0, 5804 THREAT_FRAUD = 1, 5805 THREAT_RISK = 2, 5806 THREAT_WARNING = 3, 5807 } 5808 5809 export class OnSafeBrowsingCheckResultCallback { 5810 threatType: ThreatType = ThreatType.UNKNOWN; 5811 } 5812 5813 @Entry 5814 @Component 5815 struct WebComponent { 5816 controller: webview.WebviewController = new webview.WebviewController(); 5817 5818 build() { 5819 Column() { 5820 Web({ src: 'www.example.com', controller: this.controller }) 5821 .onSafeBrowsingCheckResult((callback) => { 5822 let jsonData = JSON.stringify(callback); 5823 let json: OnSafeBrowsingCheckResultCallback = JSON.parse(jsonData); 5824 console.log("onSafeBrowsingCheckResult: [threatType]= " + json.threatType); 5825 }) 5826 } 5827 } 5828 } 5829 ``` 5830 5831### onNativeEmbedLifecycleChange<sup>11+</sup> 5832 5833onNativeEmbedLifecycleChange(callback: (event: NativeEmbedDataInfo) => void) 5834 5835当同层标签生命周期变化时触发该回调。 5836 5837**系统能力：** SystemCapability.Web.Webview.Core 5838 5839**参数：** 5840 5841| 参数名 | 类型 | 必填 | 说明 | 5842| ------ | ------ | ---- | --------------------- | 5843| callback | (event: [NativeEmbedDataInfo](#nativeembeddatainfo11)) => void | 是 | 同层标签生命周期变化时触发该回调。 | 5844 5845**示例：** 5846 5847```ts 5848// EntryAbility.ets 5849 5850import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 5851import { hilog } from '@kit.PerformanceAnalysisKit'; 5852import { window } from '@kit.ArkUI'; 5853import { webview } from '@kit.ArkWeb'; 5854 5855export default class EntryAbility extends UIAbility { 5856 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 5857 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 5858 // API12新增：开启同层渲染BFCache开关 5859 let features = new webview.BackForwardCacheSupportedFeatures(); 5860 features.nativeEmbed = true; 5861 features.mediaTakeOver = true; 5862 webview.WebviewController.enableBackForwardCache(features); 5863 webview.WebviewController.initializeWebEngine(); 5864 } 5865 5866 onDestroy(): void { 5867 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); 5868 } 5869 5870 onWindowStageCreate(windowStage: window.WindowStage): void { 5871 // Main window is created, set main page for this ability 5872 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 5873 5874 windowStage.loadContent('pages/Index', (err) => { 5875 if (err.code) { 5876 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 5877 return; 5878 } 5879 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.'); 5880 }); 5881 } 5882 5883 onWindowStageDestroy(): void { 5884 // Main window is destroyed, release UI related resources 5885 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy'); 5886 } 5887 5888 onForeground(): void { 5889 // Ability has brought to foreground 5890 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground'); 5891 } 5892 5893 onBackground(): void { 5894 // Ability has back to background 5895 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground'); 5896 } 5897} 5898``` 5899 5900 ```ts 5901 // xxx.ets 5902 import { webview } from '@kit.ArkWeb'; 5903 import { BusinessError } from '@kit.BasicServicesKit'; 5904 5905 @Entry 5906 @Component 5907 struct WebComponent { 5908 @State embedStatus: string = ''; 5909 controller: webview.WebviewController = new webview.WebviewController(); 5910 5911 build() { 5912 Column() { 5913 // 默认行为：点击按钮跳转页面，关闭index页面，使同层标签销毁。 5914 // API12新增：使能同层渲染所在的页面支持BFCache后，点击按钮跳转页面，关闭index页面，使同层标签进入BFCache。 5915 Button('Destroy') 5916 .onClick(() => { 5917 try { 5918 this.controller.loadUrl("www.example.com"); 5919 } catch (error) { 5920 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5921 } 5922 }) 5923 5924 // API12新增：使能同层渲染所在的页面支持BFCache后，点击按钮返回页面，使同层标签离开BFCache。 5925 Button('backward') 5926 .onClick(() => { 5927 try { 5928 this.controller.backward(); 5929 } catch (error) { 5930 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5931 } 5932 }) 5933 5934 // API12新增：使能同层渲染所在的页面支持BFCache后，点击按钮前进页面，使同层标签进入BFCache。 5935 Button('forward') 5936 .onClick(() => { 5937 try { 5938 this.controller.forward(); 5939 } catch (error) { 5940 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 5941 } 5942 }) 5943 5944 5945 // API12新增同层标签进入离开BFCache状态：非http与https协议加载的网页，Web内核不支持进入BFCache; 5946 // 因此如果要测试ENTER_BFCACHE/LEAVE_BFCACHE状态，需要将index.html放到Web服务器上，使用http或者https协议加载，如： 5947 // Web({ src: "http://xxxx/index.html", controller: this.controller }) 5948 Web({ src: $rawfile("index.html"), controller: this.controller }) 5949 .enableNativeEmbedMode(true) 5950 .onNativeEmbedLifecycleChange((event) => { 5951 // 当加载页面中有同层标签会触发Create。 5952 if (event.status == NativeEmbedStatus.CREATE) { 5953 this.embedStatus = 'Create'; 5954 } 5955 // 当页面中同层标签移动或者缩放时会触发Update。 5956 if (event.status == NativeEmbedStatus.UPDATE) { 5957 this.embedStatus = 'Update'; 5958 } 5959 // 退出页面时会触发Destroy。 5960 if (event.status == NativeEmbedStatus.DESTROY) { 5961 this.embedStatus = 'Destroy'; 5962 } 5963 // 同层标签所在的页面进入BFCache时，会触发Enter BFCache。 5964 if (event.status == NativeEmbedStatus.ENTER_BFCACHE) { 5965 this.embedStatus = 'Enter BFCache'; 5966 } 5967 // 同层标签所在的页面离开BFCache时，会触发Leave BFCache。 5968 if (event.status == NativeEmbedStatus.LEAVE_BFCACHE) { 5969 this.embedStatus = 'Leave BFCache'; 5970 } 5971 console.log("status = " + this.embedStatus); 5972 console.log("surfaceId = " + event.surfaceId); 5973 console.log("embedId = " + event.embedId); 5974 if (event.info) { 5975 console.log("id = " + event.info.id); 5976 console.log("type = " + event.info.type); 5977 console.log("src = " + event.info.src); 5978 console.log("width = " + event.info.width); 5979 console.log("height = " + event.info.height); 5980 console.log("url = " + event.info.url); 5981 } 5982 }) 5983 } 5984 } 5985 } 5986 ``` 5987 5988 加载的html文件 5989 ``` 5990 <!-- index.html --> 5991 <!Document> 5992 <html> 5993 <head> 5994 <title>同层渲染测试html</title> 5995 <meta name="viewport"> 5996 </head> 5997 <body> 5998 <div> 5999 <div id="bodyId"> 6000 <embed id="nativeButton" type = "native/button" width="800" height="800" src="test? params1=1?" style = "background-color:red"/> 6001 </div> 6002 </div> 6003 </body> 6004 </html> 6005 ``` 6006 6007### onNativeEmbedGestureEvent<sup>11+</sup> 6008 6009onNativeEmbedGestureEvent(callback: (event: NativeEmbedTouchInfo) => void) 6010 6011当手指触摸到同层标签时触发该回调。 6012 6013**系统能力：** SystemCapability.Web.Webview.Core 6014 6015**参数：** 6016 6017| 参数名 | 类型 | 必填 | 说明 | 6018| ------ | ------ | ---- | --------------------- | 6019| callback | (event: [NativeEmbedTouchInfo](#nativeembedtouchinfo11)) => void | 是 | 手指触摸到同层标签时触发该回调。 | 6020 6021**示例：** 6022 6023 ```ts 6024 // xxx.ets 6025 import { webview } from '@kit.ArkWeb'; 6026 import { NodeController, BuilderNode, NodeRenderType, FrameNode, UIContext } from "@kit.ArkUI"; 6027 6028 declare class Params { 6029 text: string; 6030 width: number; 6031 height: number; 6032 } 6033 6034 declare class NodeControllerParams { 6035 surfaceId: string; 6036 renderType: NodeRenderType; 6037 width: number; 6038 height: number; 6039 } 6040 6041 class MyNodeController extends NodeController { 6042 private rootNode: BuilderNode<[Params]> | undefined | null; 6043 private surfaceId_: string = ""; 6044 private renderType_: NodeRenderType = NodeRenderType.RENDER_TYPE_DISPLAY; 6045 private width_: number = 0; 6046 private height_: number = 0; 6047 6048 setRenderOption(params: NodeControllerParams) { 6049 this.surfaceId_ = params.surfaceId; 6050 this.renderType_ = params.renderType; 6051 this.width_ = params.width; 6052 this.height_ = params.height; 6053 } 6054 6055 makeNode(uiContext: UIContext): FrameNode | null { 6056 this.rootNode = new BuilderNode(uiContext, { surfaceId: this.surfaceId_, type: this.renderType_ }); 6057 this.rootNode.build(wrapBuilder(ButtonBuilder), { text: "myButton", width: this.width_, height: this.height_ }); 6058 return this.rootNode.getFrameNode(); 6059 } 6060 6061 postEvent(event: TouchEvent | undefined): boolean { 6062 return this.rootNode?.postTouchEvent(event) as boolean; 6063 } 6064 } 6065 6066 @Component 6067 struct ButtonComponent { 6068 @Prop params: Params; 6069 @State bkColor: Color = Color.Red; 6070 6071 build() { 6072 Column() { 6073 Button(this.params.text) 6074 .height(50) 6075 .width(200) 6076 .border({ width: 2, color: Color.Red }) 6077 .backgroundColor(this.bkColor) 6078 6079 } 6080 .width(this.params.width) 6081 .height(this.params.height) 6082 } 6083 } 6084 6085 @Builder 6086 function ButtonBuilder(params: Params) { 6087 ButtonComponent({ params: params }) 6088 .backgroundColor(Color.Green) 6089 } 6090 6091 @Entry 6092 @Component 6093 struct WebComponent { 6094 @State eventType: string = ''; 6095 controller: webview.WebviewController = new webview.WebviewController(); 6096 private nodeController: MyNodeController = new MyNodeController(); 6097 6098 build() { 6099 Column() { 6100 Stack() { 6101 NodeContainer(this.nodeController) 6102 Web({ src: $rawfile("index.html"), controller: this.controller }) 6103 .enableNativeEmbedMode(true) 6104 .onNativeEmbedLifecycleChange((embed) => { 6105 if (embed.status == NativeEmbedStatus.CREATE) { 6106 this.nodeController.setRenderOption({ 6107 surfaceId: embed.surfaceId as string, 6108 renderType: NodeRenderType.RENDER_TYPE_TEXTURE, 6109 width: px2vp(embed.info?.width), 6110 height: px2vp(embed.info?.height) 6111 }); 6112 this.nodeController.rebuild(); 6113 } 6114 }) 6115 .onNativeEmbedGestureEvent((event) => { 6116 if (event && event.touchEvent) { 6117 if (event.touchEvent.type == TouchType.Down) { 6118 this.eventType = 'Down' 6119 } 6120 if (event.touchEvent.type == TouchType.Up) { 6121 this.eventType = 'Up' 6122 } 6123 if (event.touchEvent.type == TouchType.Move) { 6124 this.eventType = 'Move' 6125 } 6126 if (event.touchEvent.type == TouchType.Cancel) { 6127 this.eventType = 'Cancel' 6128 } 6129 let ret = this.nodeController.postEvent(event.touchEvent) 6130 if (event.result) { 6131 event.result.setGestureEventResult(ret, true); 6132 } 6133 console.log("embedId = " + event.embedId); 6134 console.log("touchType = " + this.eventType); 6135 console.log("x = " + event.touchEvent.touches[0].x); 6136 console.log("y = " + event.touchEvent.touches[0].y); 6137 console.log("Component globalPos:(" + event.touchEvent.target.area.globalPosition.x + "," + event.touchEvent.target.area.globalPosition.y + ")"); 6138 console.log("width = " + event.touchEvent.target.area.width); 6139 console.log("height = " + event.touchEvent.target.area.height); 6140 } 6141 }) 6142 } 6143 } 6144 } 6145 } 6146 ``` 6147加载的html文件 6148 ``` 6149 <!-- index.html --> 6150 <!Document> 6151<html> 6152<head> 6153 <title>同层渲染测试html</title> 6154 <meta name="viewport"> 6155</head> 6156<body> 6157<div> 6158 <div id="bodyId"> 6159 <embed id="nativeButton" type = "native/button" width="800" height="800" src="test?params1=1?" style = "background-color:red"/> 6160 </div> 6161</div> 6162</body> 6163</html> 6164 ``` 6165 6166### onIntelligentTrackingPreventionResult<sup>12+</sup> 6167 6168onIntelligentTrackingPreventionResult(callback: OnIntelligentTrackingPreventionCallback) 6169 6170智能防跟踪功能使能时，当追踪者cookie被拦截时触发该回调。 6171 6172**系统能力：** SystemCapability.Web.Webview.Core 6173 6174**参数：** 6175 6176| 参数名 | 类型 | 必填 | 说明 | 6177| ------ | ------ | ---- | --------------------- | 6178| callback | [OnIntelligentTrackingPreventionCallback](#onintelligenttrackingpreventioncallback12) | 是 | 智能防跟踪功能使能时，当追踪者cookie被拦截时触发的回调。 | 6179 6180**示例：** 6181 6182 ```ts 6183 // xxx.ets 6184 import { webview } from '@kit.ArkWeb'; 6185 import { BusinessError } from '@kit.BasicServicesKit'; 6186 6187 @Entry 6188 @Component 6189 struct WebComponent { 6190 controller: webview.WebviewController = new webview.WebviewController(); 6191 6192 build() { 6193 Column() { 6194 // 需要打开智能防跟踪功能，才会触发onIntelligentTrackingPreventionResult回调 6195 Button('enableIntelligentTrackingPrevention') 6196 .onClick(() => { 6197 try { 6198 this.controller.enableIntelligentTrackingPrevention(true); 6199 } catch (error) { 6200 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 6201 } 6202 }) 6203 Web({ src: 'www.example.com', controller: this.controller }) 6204 .onIntelligentTrackingPreventionResult((details) => { 6205 console.log("onIntelligentTrackingPreventionResult: [websiteHost]= " + details.host + 6206 ", [trackerHost]=" + details.trackerHost); 6207 }) 6208 } 6209 } 6210 } 6211 ``` 6212 6213### onOverrideUrlLoading<sup>12+</sup> 6214 6215onOverrideUrlLoading(callback: OnOverrideUrlLoadingCallback) 6216 6217当URL将要加载到当前Web中时，让宿主应用程序有机会获得控制权，回调函数返回true将导致当前Web中止加载URL，而返回false则会导致Web继续照常加载URL。 6218 6219POST请求不会触发该回调。 6220 6221iframe加载HTTP(s)协议或about:blank时不会触发该回调，加载非HTTP(s)协议的跳转可以触发。调用loadUrl(String)主动触发的跳转不会触发该回调。 6222 6223不要使用相同的URL调用loadUrl(String)方法，然后返回true。这样做会不必要地取消当前的加载并重新使用相同的URL开始新的加载。继续加载给定URL的正确方式是直接返回false，而不是调用loadUrl(String)。 6224 6225**系统能力：** SystemCapability.Web.Webview.Core 6226 6227**参数：** 6228 6229| 参数名 | 类型 | 必填 | 说明 | 6230| ------ | ------ | ---- | --------------------- | 6231| callback | [OnOverrideUrlLoadingCallback](#onoverrideurlloadingcallback12) | 是 | onOverrideUrlLoading的回调。 | 6232 6233**示例：** 6234 6235 ```ts 6236 // xxx.ets 6237 import { webview } from '@kit.ArkWeb'; 6238 6239 @Entry 6240 @Component 6241 struct WebComponent { 6242 controller: webview.WebviewController = new webview.WebviewController(); 6243 6244 build() { 6245 Column() { 6246 Web({ src: $rawfile("index.html"), controller: this.controller }) 6247 .onOverrideUrlLoading((webResourceRequest: WebResourceRequest) => { 6248 if (webResourceRequest && webResourceRequest.getRequestUrl() == "about:blank") { 6249 return true; 6250 } 6251 return false; 6252 }) 6253 } 6254 } 6255 } 6256 ``` 6257 6258 加载的html文件。 6259 ```html 6260 <!--index.html--> 6261 <!DOCTYPE html> 6262 <html> 6263 <head> 6264 <title>测试网页</title> 6265 </head> 6266 <body> 6267 <h1>onOverrideUrlLoading Demo</h1> 6268 <a href="about:blank">Click here</a>// 访问about:blank。 6269 </body> 6270 </html> 6271 ``` 6272 6273### onViewportFitChanged<sup>12+</sup> 6274 6275onViewportFitChanged(callback: OnViewportFitChangedCallback) 6276 6277网页meta中viewport-fit配置项更改时触发该回调，应用可在此回调中自适应布局视口。 6278 6279**系统能力：** SystemCapability.Web.Webview.Core 6280 6281**参数：** 6282 6283| 参数名 | 类型 | 必填 | 说明 | 6284| ------ | ------ | ---- | --------------------- | 6285| callback | [OnViewportFitChangedCallback](#onviewportfitchangedcallback12) | 是 | 网页meta中viewport-fit配置项更改时触发的回调。 | 6286 6287**示例：** 6288 6289 ```ts 6290 // xxx.ets 6291 import { webview } from '@kit.ArkWeb'; 6292 6293 @Entry 6294 @Component 6295 struct WebComponent { 6296 controller: webview.WebviewController = new webview.WebviewController(); 6297 6298 build() { 6299 Column() { 6300 Web({ src: $rawfile('index.html'), controller: this.controller }) 6301 .onViewportFitChanged((data) => { 6302 let jsonData = JSON.stringify(data); 6303 let viewportFit: ViewportFit = JSON.parse(jsonData).viewportFit; 6304 if (viewportFit === ViewportFit.COVER) { 6305 // index.html网页支持沉浸式布局，可调用expandSafeArea调整web控件布局视口覆盖避让区域(状态栏或导航条)。 6306 } else if (viewportFit === ViewportFit.CONTAINS) { 6307 // index.html网页不支持沉浸式布局，可调用expandSafeArea调整web控件布局视口为安全区域。 6308 } else { 6309 // 默认值，可不作处理 6310 } 6311 }) 6312 } 6313 } 6314 } 6315 ``` 6316 6317 加载的html文件。 6318 ```html 6319 <!-- index.html --> 6320 <!DOCTYPE html> 6321 <html> 6322 <head> 6323 <meta name="viewport" content="width=device-width,viewport-fit=cover"> 6324 </head> 6325 <body> 6326 <div style="position: absolute; bottom: 0; margin-bottom: env(safe-area-inset-bottom)"></div> 6327 </body> 6328 </html> 6329 ``` 6330 6331### onInterceptKeyboardAttach<sup>12+</sup> 6332 6333onInterceptKeyboardAttach(callback: WebKeyboardCallback) 6334 6335网页中可编辑元素（如input标签）拉起软键盘之前会回调该接口，应用可以使用该接口拦截系统软键盘的弹出，配置应用定制的软键盘（应用根据该接口可以决定使用系统默认软键盘/定制enter键的系统软键盘/全部由应用自定义的软键盘）。 6336 6337**系统能力：** SystemCapability.Web.Webview.Core 6338 6339**参数：** 6340 6341| 参数名 | 类型 | 必填 | 说明 | 6342| ------ | ------ | ---- | --------------------- | 6343| callback | [WebKeyboardCallback](#webkeyboardcallback12) | 是 | 拦截网页拉起软键盘回调。 | 6344 6345**示例：** 6346 6347 ```ts 6348 // xxx.ets 6349 import { webview } from '@kit.ArkWeb'; 6350 import { inputMethodEngine } from '@kit.IMEKit'; 6351 6352 @Entry 6353 @Component 6354 struct WebComponent { 6355 controller: webview.WebviewController = new webview.WebviewController(); 6356 webKeyboardController: WebKeyboardController = new WebKeyboardController() 6357 inputAttributeMap: Map<string, number> = new Map([ 6358 ['UNSPECIFIED', inputMethodEngine.ENTER_KEY_TYPE_UNSPECIFIED], 6359 ['GO', inputMethodEngine.ENTER_KEY_TYPE_GO], 6360 ['SEARCH', inputMethodEngine.ENTER_KEY_TYPE_SEARCH], 6361 ['SEND', inputMethodEngine.ENTER_KEY_TYPE_SEND], 6362 ['NEXT', inputMethodEngine.ENTER_KEY_TYPE_NEXT], 6363 ['DONE', inputMethodEngine.ENTER_KEY_TYPE_DONE], 6364 ['PREVIOUS', inputMethodEngine.ENTER_KEY_TYPE_PREVIOUS] 6365 ]) 6366 6367 /** 6368 * 自定义键盘组件Builder 6369 */ 6370 @Builder 6371 customKeyboardBuilder() { 6372 // 这里实现自定义键盘组件，对接WebKeyboardController实现输入、删除、关闭等操作。 6373 Row() { 6374 Text("完成") 6375 .fontSize(20) 6376 .fontColor(Color.Blue) 6377 .onClick(() => { 6378 this.webKeyboardController.close(); 6379 }) 6380 // 插入字符。 6381 Button("insertText").onClick(() => { 6382 this.webKeyboardController.insertText('insert '); 6383 }).margin({ 6384 bottom: 200, 6385 }) 6386 // 从后往前删除length参数指定长度的字符。 6387 Button("deleteForward").onClick(() => { 6388 this.webKeyboardController.deleteForward(1); 6389 }).margin({ 6390 bottom: 200, 6391 }) 6392 // 从前往后删除length参数指定长度的字符。 6393 Button("deleteBackward").onClick(() => { 6394 this.webKeyboardController.deleteBackward(1); 6395 }).margin({ 6396 left: -220, 6397 }) 6398 // 插入功能按键。 6399 Button("sendFunctionKey").onClick(() => { 6400 this.webKeyboardController.sendFunctionKey(6); 6401 }) 6402 } 6403 } 6404 6405 build() { 6406 Column() { 6407 Web({ src: $rawfile('index.html'), controller: this.controller }) 6408 .onInterceptKeyboardAttach((KeyboardCallbackInfo) => { 6409 // option初始化，默认使用系统默认键盘 6410 let option: WebKeyboardOptions = { 6411 useSystemKeyboard: true, 6412 }; 6413 if (!KeyboardCallbackInfo) { 6414 return option; 6415 } 6416 6417 // 保存WebKeyboardController，使用自定义键盘时候，需要使用该handler控制输入、删除、软键盘关闭等行为 6418 this.webKeyboardController = KeyboardCallbackInfo.controller 6419 let attributes: Record<string, string> = KeyboardCallbackInfo.attributes 6420 // 遍历attributes 6421 let attributeKeys = Object.keys(attributes) 6422 for (let i = 0; i < attributeKeys.length; i++) { 6423 console.log('WebCustomKeyboard key = ' + attributeKeys[i] + ', value = ' + attributes[attributeKeys[i]]) 6424 } 6425 6426 if (attributes) { 6427 if (attributes['data-keyboard'] == 'customKeyboard') { 6428 // 根据html可编辑元素的属性，判断使用不同的软键盘，例如这里如果属性包含有data-keyboard，且值为customKeyboard，则使用自定义键盘 6429 console.log('WebCustomKeyboard use custom keyboard') 6430 option.useSystemKeyboard = false; 6431 // 设置自定义键盘builder 6432 option.customKeyboard = () => { 6433 this.customKeyboardBuilder() 6434 } 6435 return option; 6436 } 6437 6438 if (attributes['keyboard-return'] != undefined) { 6439 // 根据html可编辑元素的属性，判断使用不同的软键盘，例如这里如果属性包含有keyboard-return，使用系统键盘，并且指定系统软键盘enterKey类型 6440 option.useSystemKeyboard = true; 6441 let enterKeyType: number | undefined = this.inputAttributeMap.get(attributes['keyboard-return']) 6442 if (enterKeyType != undefined) { 6443 option.enterKeyType = enterKeyType 6444 } 6445 return option; 6446 } 6447 } 6448 6449 return option; 6450 }) 6451 } 6452 } 6453 } 6454 ``` 6455 6456 加载的html文件。 6457 ```html 6458 <!-- index.html --> 6459 <!DOCTYPE html> 6460 <html> 6461 6462 <head> 6463 <meta charset="utf-8"> 6464 <meta name="viewport" content="width=device-width,minimum-scale=1.0,maximum-scale=1.0"> 6465 </head> 6466 6467 <body> 6468 6469 <p style="font-size:12px">input标签，原有默认行为：</p> 6470 <input type="text" style="width: 300px; height: 20px"><br> 6471 <hr style="height:2px;border-width:0;color:gray;background-color:gray"> 6472 6473 <p style="font-size:12px">input标签，系统键盘自定义enterKeyType属性 enter key UNSPECIFIED：</p> 6474 <input type="text" keyboard-return="UNSPECIFIED" style="width: 300px; height: 20px"><br> 6475 <hr style="height:2px;border-width:0;color:gray;background-color:gray"> 6476 6477 <p style="font-size:12px">input标签，系统键盘自定义enterKeyType属性 enter key GO：</p> 6478 <input type="text" keyboard-return="GO" style="width: 300px; height: 20px"><br> 6479 <hr style="height:2px;border-width:0;color:gray;background-color:gray"> 6480 6481 <p style="font-size:12px">input标签，系统键盘自定义enterKeyType属性 enter key SEARCH：</p> 6482 <input type="text" keyboard-return="SEARCH" style="width: 300px; height: 20px"><br> 6483 <hr style="height:2px;border-width:0;color:gray;background-color:gray"> 6484 6485 <p style="font-size:12px">input标签，系统键盘自定义enterKeyType属性 enter key SEND：</p> 6486 <input type="text" keyboard-return="SEND" style="width: 300px; height: 20px"><br> 6487 <hr style="height:2px;border-width:0;color:gray;background-color:gray"> 6488 6489 <p style="font-size:12px">input标签，系统键盘自定义enterKeyType属性 enter key NEXT：</p> 6490 <input type="text" keyboard-return="NEXT" style="width: 300px; height: 20px"><br> 6491 <hr style="height:2px;border-width:0;color:gray;background-color:gray"> 6492 6493 <p style="font-size:12px">input标签，系统键盘自定义enterKeyType属性 enter key DONE：</p> 6494 <input type="text" keyboard-return="DONE" style="width: 300px; height: 20px"><br> 6495 <hr style="height:2px;border-width:0;color:gray;background-color:gray"> 6496 6497 <p style="font-size:12px">input标签，系统键盘自定义enterKeyType属性 enter key PREVIOUS：</p> 6498 <input type="text" keyboard-return="PREVIOUS" style="width: 300px; height: 20px"><br> 6499 <hr style="height:2px;border-width:0;color:gray;background-color:gray"> 6500 6501 <p style="font-size:12px">input标签，应用自定义键盘：</p> 6502 <input type="text" data-keyboard="customKeyboard" style="width: 300px; height: 20px"><br> 6503 6504 </body> 6505 6506 </html> 6507 ``` 6508 6509### onNativeEmbedVisibilityChange<sup>12+</sup> 6510 6511onNativeEmbedVisibilityChange(callback: OnNativeEmbedVisibilityChangeCallback) 6512 6513网页中同层标签（如Embed标签或Object标签）在视口内的可见性发生变化时会触发该回调。同层标签默认不可见，如果首次进入页面可见则会上报，不可见则不会上报，当同层标签大小由非0值变为0 *0时，不会上报不可见，由0 *0变为非0值时会上报可见。同层标签全部不可见才算不可见，部分可见或全部可见算作可见。 6514 6515**系统能力：** SystemCapability.Web.Webview.Core 6516 6517**参数：** 6518 6519| 参数名 | 类型 | 必填 | 说明 | 6520| ------ | ------ | ---- | --------------------- | 6521| callback | [OnNativeEmbedVisibilityChangeCallback](#onnativeembedvisibilitychangecallback12) | 是 | 同层标签可见性变化时触发该回调。 | 6522 6523**示例：** 6524 6525 ```ts 6526 // xxx.ets 6527 import { webview } from '@kit.ArkWeb'; 6528 import { NodeController, BuilderNode, NodeRenderType, FrameNode, UIContext } from "@kit.ArkUI"; 6529 6530 declare class Params { 6531 text: string; 6532 width: number; 6533 height: number; 6534 } 6535 6536 declare class NodeControllerParams { 6537 surfaceId: string; 6538 renderType: NodeRenderType; 6539 width: number; 6540 height: number; 6541 } 6542 6543 class MyNodeController extends NodeController { 6544 private rootNode: BuilderNode<[Params]> | undefined | null; 6545 private surfaceId_: string = ""; 6546 private renderType_: NodeRenderType = NodeRenderType.RENDER_TYPE_DISPLAY; 6547 private width_: number = 0; 6548 private height_: number = 0; 6549 6550 setRenderOption(params: NodeControllerParams) { 6551 this.surfaceId_ = params.surfaceId; 6552 this.renderType_ = params.renderType; 6553 this.width_ = params.width; 6554 this.height_ = params.height; 6555 } 6556 6557 makeNode(uiContext: UIContext): FrameNode | null { 6558 this.rootNode = new BuilderNode(uiContext, { surfaceId: this.surfaceId_, type: this.renderType_ }); 6559 this.rootNode.build(wrapBuilder(ButtonBuilder), { text: "myButton", width: this.width_, height: this.height_ }); 6560 return this.rootNode.getFrameNode(); 6561 } 6562 6563 postEvent(event: TouchEvent | undefined): boolean { 6564 return this.rootNode?.postTouchEvent(event) as boolean; 6565 } 6566 } 6567 6568 @Component 6569 struct ButtonComponent { 6570 @Prop params: Params; 6571 @State bkColor: Color = Color.Red; 6572 6573 build() { 6574 Column() { 6575 Button(this.params.text) 6576 .height(50) 6577 .width(200) 6578 .border({ width: 2, color: Color.Red }) 6579 .backgroundColor(this.bkColor) 6580 6581 } 6582 .width(this.params.width) 6583 .height(this.params.height) 6584 } 6585 } 6586 6587 @Builder 6588 function ButtonBuilder(params: Params) { 6589 ButtonComponent({ params: params }) 6590 .backgroundColor(Color.Green) 6591 } 6592 6593 @Entry 6594 @Component 6595 struct WebComponent { 6596 @State embedVisibility: string = ''; 6597 controller: webview.WebviewController = new webview.WebviewController(); 6598 private nodeController: MyNodeController = new MyNodeController(); 6599 6600 build() { 6601 Column() { 6602 Stack() { 6603 NodeContainer(this.nodeController) 6604 Web({ src: $rawfile("index.html"), controller: this.controller }) 6605 .enableNativeEmbedMode(true) 6606 .onNativeEmbedLifecycleChange((embed) => { 6607 if (embed.status == NativeEmbedStatus.CREATE) { 6608 this.nodeController.setRenderOption({ 6609 surfaceId: embed.surfaceId as string, 6610 renderType: NodeRenderType.RENDER_TYPE_TEXTURE, 6611 width: px2vp(embed.info?.width), 6612 height: px2vp(embed.info?.height) 6613 }); 6614 this.nodeController.rebuild(); 6615 } 6616 }) 6617 .onNativeEmbedVisibilityChange((embed) => { 6618 if (embed.visibility) { 6619 this.embedVisibility = 'Visible'; 6620 } else { 6621 this.embedVisibility = 'Hidden'; 6622 } 6623 console.log("embedId = " + embed.embedId); 6624 console.log("visibility = " + embed.visibility); 6625 }) 6626 } 6627 } 6628 } 6629 } 6630 ``` 6631 6632 加载的html文件 6633 ```html 6634 <!-- index.html --> 6635 <!DOCTYPE html> 6636 <html> 6637 <head> 6638 <title>同层渲染测试html</title> 6639 <meta name="viewport"> 6640 </head> 6641 <body> 6642 <div> 6643 <div id="bodyId"> 6644 <embed id="nativeButton" type = "native/button" width="800" height="800" src="test?params1=1?" style = "background-color:red"/> 6645 </div> 6646 </div> 6647 </body> 6648 </html> 6649 ``` 6650 6651## WebKeyboardCallback<sup>12+</sup> 6652 6653type WebKeyboardCallback = (keyboardCallbackInfo: WebKeyboardCallbackInfo) => WebKeyboardOptions 6654 6655拦截网页可编辑元素拉起软键盘的回调，一般在点击网页input标签时触发。 6656 6657**系统能力：** SystemCapability.Web.Webview.Core 6658 6659**参数：** 6660 6661| 参数名 | 类型 | 必填 | 说明 | 6662| ------------- | ------ | ---- | ------------------ | 6663| keyboardCallbackInfo | [WebKeyboardCallbackInfo](#webkeyboardcallbackinfo12) | 是 | 拦截网页拉起软键盘回调通知的入参，其中包括[WebKeyboardController](#webkeyboardcontroller12)、可编辑元素的属性。 | 6664 6665**返回值：** 6666 6667| 类型 | 说明 | 6668| ------------------ | ------------------------------------------------------------ | 6669| [WebKeyboardOptions](#webkeyboardoptions12) | 回调函数通过返回[WebKeyboardOptions](#webkeyboardoptions12)来决定ArkWeb内核拉起不同类型的软键盘。 | 6670 6671## WebKeyboardCallbackInfo<sup>12+</sup> 6672 6673拦截网页可编辑元素拉起软键盘的回调入参，其中包括[WebKeyboardController](#webkeyboardcontroller12)、可编辑元素的属性。 6674 6675**系统能力：** SystemCapability.Web.Webview.Core 6676 6677| 名称 | 类型 | 必填 | 说明 | 6678| -------------- | ------- | ---- | ---------------------------------------- | 6679| controller | [WebKeyboardController](#webkeyboardcontroller12) | 是 | 提供控制自定义键盘的输入、删除、关闭等操作。 | 6680| attributes | Record<string, string> | 是 | 触发本次软键盘弹出的网页元素属性。 6681 6682## WebKeyboardOptions<sup>12+</sup> 6683 6684拦截网页可编辑元素拉起软键盘的回调返回值，可以指定使用的键盘类型，并返回给web内核，以控制拉起不同类型的软键盘； 6685 6686**系统能力：** SystemCapability.Web.Webview.Core 6687 6688| 名称 | 类型 | 必填 | 说明 | 6689| -------------- | ------- | ---- | ---------------------------------------- | 6690| useSystemKeyboard | boolean | 是 | 是否使用系统默认软键盘。 | 6691| enterKeyType | number | 否 | 指定系统软键盘enter键的类型，取值范围见输入框架的定义[EnterKeyType](../apis-ime-kit/js-apis-inputmethod.md#enterkeytype10)，该参数为可选参数，当useSystemKeyboard为true，并且设置了有效的enterKeyType时候，才有效。| 6692| customKeyboard | [CustomBuilder](../apis-arkui/arkui-ts/ts-types.md#custombuilder8) | 否 | 指定自定义键盘组件builder，可选参数，当useSystemKeyboard为false时，需要设置该参数，然后Web组件会拉起该自定义键盘。 6693 6694## WebKeyboardController<sup>12+</sup> 6695 6696控制自定义键盘的输入、删除、关闭等操作。示例代码参考[onInterceptKeyboardAttach](#oninterceptkeyboardattach12)。 6697 6698### constructor<sup>12+</sup> 6699 6700constructor() 6701 6702WebKeyboardController的构造函数。 6703 6704**系统能力：** SystemCapability.Web.Webview.Core 6705 6706### insertText<sup>12+</sup> 6707 6708insertText(text: string): void 6709 6710插入字符。 6711 6712**系统能力：** SystemCapability.Web.Webview.Core 6713 6714**参数：** 6715 6716| 参数名 | 类型 | 必填 | 说明 | 6717| ------ | -------- | ---- | --------------------- | 6718| text | string | 是 | 向Web输入框插入字符。 | 6719 6720### deleteForward<sup>12+</sup> 6721 6722deleteForward(length: number): void 6723 6724从后往前删除length参数指定长度的字符。 6725 6726**系统能力：** SystemCapability.Web.Webview.Core 6727 6728**参数：** 6729 6730| 参数名 | 类型 | 必填 | 说明 | 6731| ------ | -------- | ---- | ------------------------ | 6732| length | number | 是 | 从后往前删除字符的长度。 | 6733 6734### deleteBackward12+</sup> 6735 6736deleteBackward(length: number): void 6737 6738从前往后删除length参数指定长度的字符。 6739 6740**系统能力：** SystemCapability.Web.Webview.Core 6741 6742**参数：** 6743 6744| 参数名 | 类型 | 必填 | 说明 | 6745| ------ | -------- | ---- | ------------------------ | 6746| length | number | 是 | 从前往后删除字符的长度。 | 6747 6748### sendFunctionKey<sup>12+</sup> 6749 6750sendFunctionKey(key: number): void 6751 6752插入功能按键，目前仅支持enter键类型，取值见[EnterKeyType](../apis-ime-kit/js-apis-inputmethod.md#enterkeytype10)。 6753 6754**系统能力：** SystemCapability.Web.Webview.Core 6755 6756**参数：** 6757 6758| 参数名 | 类型 | 必填 | 说明 | 6759| ------ | -------- | ---- | ------------------------------------------ | 6760| key | number | 是 | 向Web输入框传递功能键，目前仅支持enter键。 | 6761 6762### close<sup>12+</sup> 6763 6764close(): void 6765 6766关闭自定义键盘。 6767 6768**系统能力：** SystemCapability.Web.Webview.Core 6769 6770## ConsoleMessage 6771 6772Web组件获取控制台信息对象。示例代码参考[onConsole事件](#onconsole)。 6773 6774### constructor<sup>9+</sup> 6775 6776constructor() 6777 6778ConsoleMessage的构造函数。 6779 6780**系统能力：** SystemCapability.Web.Webview.Core 6781 6782### getLineNumber 6783 6784getLineNumber(): number 6785 6786获取ConsoleMessage的行数。 6787 6788**系统能力：** SystemCapability.Web.Webview.Core 6789 6790**返回值：** 6791 6792| 类型 | 说明 | 6793| ------ | -------------------- | 6794| number | 返回ConsoleMessage的行数。 | 6795 6796### getMessage 6797 6798getMessage(): string 6799 6800获取ConsoleMessage的日志信息。 6801 6802**系统能力：** SystemCapability.Web.Webview.Core 6803 6804**返回值：** 6805 6806| 类型 | 说明 | 6807| ------ | ---------------------- | 6808| string | 返回ConsoleMessage的日志信息。 | 6809 6810### getMessageLevel 6811 6812getMessageLevel(): MessageLevel 6813 6814获取ConsoleMessage的信息级别。 6815 6816**系统能力：** SystemCapability.Web.Webview.Core 6817 6818**返回值：** 6819 6820| 类型 | 说明 | 6821| --------------------------------- | ---------------------- | 6822| [MessageLevel](#messagelevel枚举说明) | 返回ConsoleMessage的信息级别。 | 6823 6824### getSourceId 6825 6826getSourceId(): string 6827 6828获取网页源文件路径和名字。 6829 6830**系统能力：** SystemCapability.Web.Webview.Core 6831 6832**返回值：** 6833 6834| 类型 | 说明 | 6835| ------ | ------------- | 6836| string | 返回网页源文件路径和名字。 | 6837 6838## JsResult 6839 6840Web组件返回的弹窗确认或弹窗取消功能对象。示例代码参考[onAlert事件](#onalert)。 6841 6842### constructor 6843 6844constructor() 6845 6846JsResult的构造函数。 6847 6848**系统能力：** SystemCapability.Web.Webview.Core 6849 6850### handleCancel 6851 6852handleCancel(): void 6853 6854通知Web组件用户取消弹窗操作。 6855 6856**系统能力：** SystemCapability.Web.Webview.Core 6857 6858### handleConfirm 6859 6860handleConfirm(): void 6861 6862通知Web组件用户确认弹窗操作。 6863 6864**系统能力：** SystemCapability.Web.Webview.Core 6865 6866### handlePromptConfirm<sup>9+</sup> 6867 6868handlePromptConfirm(result: string): void 6869 6870通知Web组件用户确认弹窗操作及对话框内容。 6871 6872**系统能力：** SystemCapability.Web.Webview.Core 6873 6874**参数：** 6875 6876| 参数名 | 类型 | 必填 | 说明 | 6877| ------ | ------ | ---- | ----------- | 6878| result | string | 是 | 用户输入的对话框内容。 | 6879 6880## FullScreenExitHandler<sup>9+</sup> 6881 6882通知开发者Web组件退出全屏。示例代码参考[onFullScreenEnter事件](#onfullscreenenter9)。 6883 6884### constructor<sup>9+</sup> 6885 6886constructor() 6887 6888FullScreenExitHandler的构造函数。 6889 6890**系统能力：** SystemCapability.Web.Webview.Core 6891 6892### exitFullScreen<sup>9+</sup> 6893 6894exitFullScreen(): void 6895 6896通知开发者Web组件退出全屏。 6897 6898**系统能力：** SystemCapability.Web.Webview.Core 6899 6900## ControllerHandler<sup>9+</sup> 6901 6902设置用户新建Web组件的WebviewController对象。示例代码参考[onWindowNew事件](#onwindownew9)。 6903 6904**系统能力：** SystemCapability.Web.Webview.Core 6905 6906### constructor<sup>9+</sup> 6907 6908constructor() 6909 6910ControllerHandler的构造函数。 6911 6912**系统能力：** SystemCapability.Web.Webview.Core 6913 6914### setWebController<sup>9+</sup> 6915 6916setWebController(controller: WebviewController): void 6917 6918设置WebviewController对象，如果不需要打开新窗口请设置为null。 6919 6920**系统能力：** SystemCapability.Web.Webview.Core 6921 6922**参数：** 6923 6924| 参数名 | 类型 | 必填 | 说明 | 6925| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 6926| controller | [WebviewController](js-apis-webview.md#webviewcontroller) | 是 | 新建Web组件的WebviewController对象，如果不需要打开新窗口请设置为null。 | 6927 6928## WebResourceError 6929 6930Web组件资源管理错误信息对象。示例代码参考[onErrorReceive事件](#onerrorreceive)。 6931 6932### constructor<sup>9+</sup> 6933 6934constructor() 6935 6936WebResourceError的构造函数。 6937 6938**系统能力：** SystemCapability.Web.Webview.Core 6939 6940### getErrorCode 6941 6942getErrorCode(): number 6943 6944获取加载资源的错误码。 6945 6946**系统能力：** SystemCapability.Web.Webview.Core 6947 6948**返回值：** 6949 6950| 类型 | 说明 | 6951| ------ | ----------- | 6952| number | 返回加载资源的错误码。错误码的含义可以参考[WebNetErrorList](js-apis-netErrorList.md) | 6953 6954### getErrorInfo 6955 6956getErrorInfo(): string 6957 6958获取加载资源的错误信息。 6959 6960**系统能力：** SystemCapability.Web.Webview.Core 6961 6962**返回值：** 6963 6964| 类型 | 说明 | 6965| ------ | ------------ | 6966| string | 返回加载资源的错误信息。 | 6967 6968## WebResourceRequest 6969 6970Web组件获取资源请求对象。示例代码参考[onErrorReceive事件](#onerrorreceive)。 6971 6972### constructor 6973 6974constructor() 6975 6976WebResourceRequest的构造函数。 6977 6978**系统能力：** SystemCapability.Web.Webview.Core 6979 6980### getRequestHeader 6981 6982getRequestHeader(): Array\<Header\> 6983 6984获取资源请求头信息。 6985 6986**系统能力：** SystemCapability.Web.Webview.Core 6987 6988**返回值：** 6989 6990| 类型 | 说明 | 6991| -------------------------- | ---------- | 6992| Array\<[Header](#header)\> | 返回资源请求头信息。 | 6993 6994### getRequestUrl 6995 6996getRequestUrl(): string 6997 6998获取资源请求的URL信息。 6999 7000**系统能力：** SystemCapability.Web.Webview.Core 7001 7002**返回值：** 7003 7004| 类型 | 说明 | 7005| ------ | ------------- | 7006| string | 返回资源请求的URL信息。 | 7007 7008### isMainFrame 7009 7010isMainFrame(): boolean 7011 7012判断资源请求是否为主frame。 7013 7014**系统能力：** SystemCapability.Web.Webview.Core 7015 7016**返回值：** 7017 7018| 类型 | 说明 | 7019| ------- | ---------------- | 7020| boolean | 返回资源请求是否为主frame。 | 7021 7022### isRedirect 7023 7024isRedirect(): boolean 7025 7026判断资源请求是否被服务端重定向。 7027 7028**系统能力：** SystemCapability.Web.Webview.Core 7029 7030**返回值：** 7031 7032| 类型 | 说明 | 7033| ------- | ---------------- | 7034| boolean | 返回资源请求是否被服务端重定向。 | 7035 7036### isRequestGesture 7037 7038isRequestGesture(): boolean 7039 7040获取资源请求是否与手势（如点击）相关联。 7041 7042**系统能力：** SystemCapability.Web.Webview.Core 7043 7044**返回值：** 7045 7046| 类型 | 说明 | 7047| ------- | -------------------- | 7048| boolean | 返回资源请求是否与手势（如点击）相关联。 | 7049 7050### getRequestMethod<sup>9+</sup> 7051 7052getRequestMethod(): string 7053 7054获取请求方法。 7055 7056**系统能力：** SystemCapability.Web.Webview.Core 7057 7058**返回值：** 7059 7060| 类型 | 说明 | 7061| ------ | ------- | 7062| string | 返回请求方法。 | 7063 7064## Header 7065 7066Web组件返回的请求/响应头对象。 7067 7068**系统能力：** SystemCapability.Web.Webview.Core 7069 7070| 名称 | 类型 | 必填 | 说明 | 7071| ----------- | ------ | ---- | ------------- | 7072| headerKey | string | 是 | 请求/响应头的key。 | 7073| headerValue | string | 是 | 请求/响应头的value。 | 7074 7075## WebResourceResponse 7076 7077Web组件资源响应对象。示例代码参考[onHttpErrorReceive事件](#onhttperrorreceive)。 7078 7079### constructor 7080 7081constructor() 7082 7083WebResourceResponse的构造函数。 7084 7085**系统能力：** SystemCapability.Web.Webview.Core 7086 7087### getReasonMessage 7088 7089getReasonMessage(): string 7090 7091获取资源响应的状态码描述。 7092 7093**系统能力：** SystemCapability.Web.Webview.Core 7094 7095**返回值：** 7096 7097| 类型 | 说明 | 7098| ------ | ------------- | 7099| string | 返回资源响应的状态码描述。 | 7100 7101### getResponseCode 7102 7103getResponseCode(): number 7104 7105获取资源响应的状态码。 7106 7107**系统能力：** SystemCapability.Web.Webview.Core 7108 7109**返回值：** 7110 7111| 类型 | 说明 | 7112| ------ | ----------- | 7113| number | 返回资源响应的状态码。 | 7114 7115### getResponseData 7116 7117getResponseData(): string 7118 7119获取资源响应数据。 7120 7121**系统能力：** SystemCapability.Web.Webview.Core 7122 7123**返回值：** 7124 7125| 类型 | 说明 | 7126| ------ | --------- | 7127| string | 返回资源响应数据。 | 7128 7129### getResponseEncoding 7130 7131getResponseEncoding(): string 7132 7133获取资源响应的编码。 7134 7135**系统能力：** SystemCapability.Web.Webview.Core 7136 7137**返回值：** 7138 7139| 类型 | 说明 | 7140| ------ | ---------- | 7141| string | 返回资源响应的编码。 | 7142 7143### getResponseHeader 7144 7145getResponseHeader() : Array\<Header\> 7146 7147获取资源响应头。 7148 7149**系统能力：** SystemCapability.Web.Webview.Core 7150 7151**返回值：** 7152 7153| 类型 | 说明 | 7154| -------------------------- | -------- | 7155| Array\<[Header](#header)\> | 返回资源响应头。 | 7156 7157### getResponseMimeType 7158 7159getResponseMimeType(): string 7160 7161获取资源响应的媒体（MIME）类型。 7162 7163**系统能力：** SystemCapability.Web.Webview.Core 7164 7165**返回值：** 7166 7167| 类型 | 说明 | 7168| ------ | ------------------ | 7169| string | 返回资源响应的媒体（MIME）类型。 | 7170 7171### getResponseDataEx<sup>13+</sup> 7172 7173getResponseDataEx(): string | number | ArrayBuffer | Resource | undefined 7174 7175获取资源响应数据，支持多种数据类型。 7176 7177**系统能力：** SystemCapability.Web.Webview.Core 7178 7179**返回值：** 7180 7181|类型|说明| 7182|---|---| 7183|string|返回HTML格式的字符串。| 7184|number|返回文件句柄。| 7185|ArrayBuffer|返回二进制数据。| 7186|[Resource](../apis-arkui/arkui-ts/ts-types.md)|返回`$rawfile`资源。| 7187|undefined|如果没有可用数据，返回`undefined`。| 7188 7189### getResponseIsReady<sup>13+</sup> 7190 7191getResponseIsReady(): boolean 7192 7193获取响应数据是否已准备就绪。 7194 7195**系统能力：** SystemCapability.Web.Webview.Core 7196 7197**返回值：** 7198 7199|类型|说明| 7200|---|---| 7201|boolean|`true`表示响应数据已准备好，`false`表示未准备好。| 7202 7203### setResponseData<sup>9+</sup> 7204 7205setResponseData(data: string \| number \| Resource \| ArrayBuffer): void 7206 7207设置资源响应数据。 7208 7209**系统能力：** SystemCapability.Web.Webview.Core 7210 7211**参数：** 7212 7213| 参数名 | 类型 | 必填 | 说明 | 7214| ---- | ---------------------------------------- | ---- | ---------------------------------------- | 7215| data | string \| number \| [Resource](../apis-arkui/arkui-ts/ts-types.md)<sup>10+</sup> \| ArrayBuffer<sup>11+</sup> | 是 | 要设置的资源响应数据。string表示HTML格式的字符串。number表示文件句柄, 此句柄由系统的Web组件负责关闭。 Resource表示应用rawfile目录下文件资源。 ArrayBuffer表示资源的原始二进制数据。 | 7216 7217### setResponseEncoding<sup>9+</sup> 7218 7219setResponseEncoding(encoding: string): void 7220 7221设置资源响应的编码。 7222 7223**系统能力：** SystemCapability.Web.Webview.Core 7224 7225**参数：** 7226 7227| 参数名 | 类型 | 必填 | 说明 | 7228| -------- | ------ | ---- | ------------ | 7229| encoding | string | 是 | 要设置的资源响应的编码。 | 7230 7231### setResponseMimeType<sup>9+</sup> 7232 7233setResponseMimeType(mimeType: string): void 7234 7235设置资源响应的媒体（MIME）类型。 7236 7237**系统能力：** SystemCapability.Web.Webview.Core 7238 7239**参数：** 7240 7241| 参数名 | 类型 | 必填 | 说明 | 7242| -------- | ------ | ---- | -------------------- | 7243| mimeType | string | 是 | 要设置的资源响应的媒体（MIME）类型。 | 7244 7245### setReasonMessage<sup>9+</sup> 7246 7247setReasonMessage(reason: string): void 7248 7249设置资源响应的状态码描述。 7250 7251**系统能力：** SystemCapability.Web.Webview.Core 7252 7253**参数：** 7254 7255| 参数名 | 类型 | 必填 | 说明 | 7256| ------ | ------ | ---- | --------------- | 7257| reason | string | 是 | 要设置的资源响应的状态码描述。 | 7258 7259### setResponseHeader<sup>9+</sup> 7260 7261setResponseHeader(header: Array\<Header\>): void 7262 7263设置资源响应头。 7264 7265**系统能力：** SystemCapability.Web.Webview.Core 7266 7267**参数：** 7268 7269| 参数名 | 类型 | 必填 | 说明 | 7270| ------ | -------------------------- | ---- | ---------- | 7271| header | Array\<[Header](#header)\> | 是 | 要设置的资源响应头。 | 7272 7273### setResponseCode<sup>9+</sup> 7274 7275setResponseCode(code: number): void 7276 7277设置资源响应的状态码。 7278 7279**系统能力：** SystemCapability.Web.Webview.Core 7280 7281**参数：** 7282 7283| 参数名 | 类型 | 必填 | 说明 | 7284| ---- | ------ | ---- | ------------- | 7285| code | number | 是 | 要设置的资源响应的状态码。如果该资源以错误结束，请参考[@ohos.web.netErrorList](js-apis-netErrorList.md)设置相应错误码，避免设置错误码为 ERR_IO_PENDING，设置为该错误码可能会导致XMLHttpRequest同步请求阻塞。 | 7286 7287### setResponseIsReady<sup>9+</sup> 7288 7289setResponseIsReady(IsReady: boolean): void 7290 7291设置资源响应数据是否已经就绪。 7292 7293**系统能力：** SystemCapability.Web.Webview.Core 7294 7295**参数：** 7296 7297| 参数名 | 类型 | 必填 | 说明 | 7298| ------- | ------- | ---- | ------------- | 7299| IsReady | boolean | 是 | 资源响应数据是否已经就绪。默认值：true。 | 7300 7301## FileSelectorResult<sup>9+</sup> 7302 7303通知Web组件的文件选择结果。示例代码参考[onShowFileSelector事件](#onshowfileselector9)。 7304 7305### constructor<sup>9+</sup> 7306 7307constructor() 7308 7309FileSelectorResult的构造函数。 7310 7311**系统能力：** SystemCapability.Web.Webview.Core 7312 7313### handleFileList<sup>9+</sup> 7314 7315handleFileList(fileList: Array\<string\>): void 7316 7317通知Web组件进行文件选择操作。 7318 7319**系统能力：** SystemCapability.Web.Webview.Core 7320 7321**参数：** 7322 7323| 参数名 | 类型 | 必填 | 说明 | 7324| -------- | --------------- | ---- | ------------ | 7325| fileList | Array\<string\> | 是 | 需要进行操作的文件列表。 | 7326 7327## FileSelectorParam<sup>9+</sup> 7328 7329Web组件获取文件对象。示例代码参考[onShowFileSelector事件](#onshowfileselector9)。 7330 7331### constructor<sup>9+</sup> 7332 7333constructor() 7334 7335FileSelectorParam的构造函数。 7336 7337**系统能力：** SystemCapability.Web.Webview.Core 7338 7339### getTitle<sup>9+</sup> 7340 7341getTitle(): string 7342 7343获取文件选择器标题。 7344 7345**系统能力：** SystemCapability.Web.Webview.Core 7346 7347**返回值：** 7348 7349| 类型 | 说明 | 7350| ------ | ---------- | 7351| string | 返回文件选择器标题。 | 7352 7353### getMode<sup>9+</sup> 7354 7355getMode(): FileSelectorMode 7356 7357获取文件选择器的模式。 7358 7359**系统能力：** SystemCapability.Web.Webview.Core 7360 7361**返回值：** 7362 7363| 类型 | 说明 | 7364| ---------------------------------------- | ----------- | 7365| [FileSelectorMode](#fileselectormode9枚举说明) | 返回文件选择器的模式。 | 7366 7367### getAcceptType<sup>9+</sup> 7368 7369getAcceptType(): Array\<string\> 7370 7371获取文件过滤类型。 7372 7373**系统能力：** SystemCapability.Web.Webview.Core 7374 7375**返回值：** 7376 7377| 类型 | 说明 | 7378| --------------- | --------- | 7379| Array\<string\> | 返回文件过滤类型。 | 7380 7381### isCapture<sup>9+</sup> 7382 7383isCapture(): boolean 7384 7385获取是否调用多媒体能力。 7386 7387**系统能力：** SystemCapability.Web.Webview.Core 7388 7389**返回值：** 7390 7391| 类型 | 说明 | 7392| ------- | ------------ | 7393| boolean | 返回是否调用多媒体能力。 | 7394 7395## HttpAuthHandler<sup>9+</sup> 7396 7397Web组件返回的http auth认证请求确认或取消和使用缓存密码认证功能对象。示例代码参考[onHttpAuthRequest事件](#onhttpauthrequest9)。 7398 7399### constructor<sup>9+</sup> 7400 7401constructor() 7402 7403HttpAuthHandler的构造函数。 7404 7405**系统能力：** SystemCapability.Web.Webview.Core 7406 7407### cancel<sup>9+</sup> 7408 7409cancel(): void 7410 7411通知Web组件用户取消HTTP认证操作。 7412 7413**系统能力：** SystemCapability.Web.Webview.Core 7414 7415### confirm<sup>9+</sup> 7416 7417confirm(userName: string, password: string): boolean 7418 7419使用用户名和密码进行HTTP认证操作。 7420 7421**系统能力：** SystemCapability.Web.Webview.Core 7422 7423**参数：** 7424 7425| 参数名 | 类型 | 必填 | 说明 | 7426| -------- | ------ | ---- | ---------- | 7427| userName | string | 是 | HTTP认证用户名。 | 7428| password | string | 是 | HTTP认证密码。 | 7429 7430**返回值：** 7431 7432| 类型 | 说明 | 7433| ------- | --------------------- | 7434| boolean | 认证成功返回true，失败返回false。 | 7435 7436### isHttpAuthInfoSaved<sup>9+</sup> 7437 7438isHttpAuthInfoSaved(): boolean 7439 7440通知Web组件用户使用服务器缓存的账号密码认证。 7441 7442**系统能力：** SystemCapability.Web.Webview.Core 7443 7444**返回值：** 7445 7446| 类型 | 说明 | 7447| ------- | ------------------------- | 7448| boolean | 存在密码认证成功返回true，其他返回false。 | 7449 7450## SslErrorHandler<sup>9+</sup> 7451 7452Web组件返回的SSL错误通知事件用户处理功能对象。示例代码参考[onSslErrorEventReceive事件](#onsslerroreventreceive9)。 7453 7454### constructor<sup>9+</sup> 7455 7456constructor() 7457 7458SslErrorHandler的构造函数。 7459 7460**系统能力：** SystemCapability.Web.Webview.Core 7461 7462### handleCancel<sup>9+</sup> 7463 7464handleCancel(): void 7465 7466通知Web组件取消此请求。 7467 7468**系统能力：** SystemCapability.Web.Webview.Core 7469 7470### handleConfirm<sup>9+</sup> 7471 7472handleConfirm(): void 7473 7474通知Web组件继续使用SSL证书。 7475 7476**系统能力：** SystemCapability.Web.Webview.Core 7477 7478## ClientAuthenticationHandler<sup>9+</sup> 7479 7480Web组件返回的SSL客户端证书请求事件用户处理功能对象。示例代码参考[onClientAuthenticationRequest事件](#onclientauthenticationrequest9)。 7481 7482### constructor<sup>9+</sup> 7483 7484constructor() 7485 7486ClientAuthenticationHandler的构造函数。 7487 7488**系统能力：** SystemCapability.Web.Webview.Core 7489 7490### confirm<sup>9+</sup> 7491 7492confirm(priKeyFile : string, certChainFile : string): void 7493 7494通知Web组件使用指定的私钥和客户端证书链。 7495 7496**系统能力：** SystemCapability.Web.Webview.Core 7497 7498**参数：** 7499 7500| 参数名 | 类型 | 必填 | 说明 | 7501| ------------- | ------ | ---- | ------------------ | 7502| priKeyFile | string | 是 | 存放私钥的文件，包含路径和文件名。 | 7503| certChainFile | string | 是 | 存放证书链的文件，包含路径和文件名。 | 7504 7505### confirm<sup>10+</sup> 7506 7507confirm(authUri : string): void 7508 7509通知Web组件使用指定的凭据(从证书管理模块获得)。 7510 7511> **说明：** 7512> 7513> 需要配置权限：ohos.permission.ACCESS_CERT_MANAGER。 7514 7515**系统能力：** SystemCapability.Web.Webview.Core 7516 7517**参数：** 7518 7519| 参数名 | 类型 | 必填 | 说明 | 7520| ------- | ------ | ---- | ------- | 7521| authUri | string | 是 | 凭据的关键值。 | 7522 7523### cancel<sup>9+</sup> 7524 7525cancel(): void 7526 7527通知Web组件取消相同host和port服务器发送的客户端证书请求事件。同时，相同host和port服务器的请求，不重复上报该事件。 7528 7529**系统能力：** SystemCapability.Web.Webview.Core 7530 7531### ignore<sup>9+</sup> 7532 7533ignore(): void 7534 7535通知Web组件忽略本次请求。 7536 7537**系统能力：** SystemCapability.Web.Webview.Core 7538 7539## PermissionRequest<sup>9+</sup> 7540 7541Web组件返回授权或拒绝权限功能的对象。示例代码参考[onPermissionRequest事件](#onpermissionrequest9)。 7542 7543### constructor<sup>9+</sup> 7544 7545constructor() 7546 7547PermissionRequest的构造函数。 7548 7549**系统能力：** SystemCapability.Web.Webview.Core 7550 7551### deny<sup>9+</sup> 7552 7553deny(): void 7554 7555拒绝网页所请求的权限。 7556 7557**系统能力：** SystemCapability.Web.Webview.Core 7558 7559### getOrigin<sup>9+</sup> 7560 7561getOrigin(): string 7562 7563获取网页来源。 7564 7565**系统能力：** SystemCapability.Web.Webview.Core 7566 7567**返回值：** 7568 7569| 类型 | 说明 | 7570| ------ | ------------ | 7571| string | 当前请求权限网页的来源。 | 7572 7573### getAccessibleResource<sup>9+</sup> 7574 7575getAccessibleResource(): Array\<string\> 7576 7577获取网页所请求的权限资源列表，资源列表类型参考[ProtectedResourceType](#protectedresourcetype9枚举说明)。 7578 7579**系统能力：** SystemCapability.Web.Webview.Core 7580 7581**返回值：** 7582 7583| 类型 | 说明 | 7584| --------------- | ------------- | 7585| Array\<string\> | 网页所请求的权限资源列表。 | 7586 7587### grant<sup>9+</sup> 7588 7589grant(resources: Array\<string\>): void 7590 7591对网页访问的给定权限进行授权。 7592 7593**系统能力：** SystemCapability.Web.Webview.Core 7594 7595**参数：** 7596 7597| 参数名 | 类型 | 必填 | 说明 | 7598| --------- | --------------- | ---- | --------------- | 7599| resources | Array\<string\> | 是 | 授予网页请求的权限的资源列表。 | 7600 7601## ScreenCaptureHandler<sup>10+</sup> 7602 7603Web组件返回授权或拒绝屏幕捕获功能的对象。示例代码参考[onScreenCaptureRequest事件](#onscreencapturerequest10)。 7604 7605### constructor<sup>9+</sup> 7606 7607constructor() 7608 7609ScreenCaptureHandler的构造函数。 7610 7611**系统能力：** SystemCapability.Web.Webview.Core 7612 7613### deny<sup>10+</sup> 7614 7615deny(): void 7616 7617拒绝网页所请求的屏幕捕获操作。 7618 7619**系统能力：** SystemCapability.Web.Webview.Core 7620 7621### getOrigin<sup>10+</sup> 7622 7623getOrigin(): string 7624 7625获取网页来源。 7626 7627**系统能力：** SystemCapability.Web.Webview.Core 7628 7629**返回值：** 7630 7631| 类型 | 说明 | 7632| ------ | ------------ | 7633| string | 当前请求权限网页的来源。 | 7634 7635### grant<sup>10+</sup> 7636 7637grant(config: ScreenCaptureConfig): void 7638 7639对网页访问的屏幕捕获操作进行授权。 7640 7641> **说明：** 7642> 7643> 需要配置权限：ohos.permission.MICROPHONE。 7644 7645**系统能力：** SystemCapability.Web.Webview.Core 7646 7647**参数：** 7648 7649| 参数名 | 类型 | 必填 | 说明 | 7650| ------ | ---------------------------------------- | ---- | ------- | 7651| config | [ScreenCaptureConfig](#screencaptureconfig10) | 是 | 屏幕捕获配置。 | 7652 7653## EventResult<sup>12+</sup> 7654 7655通知Web组件事件消费结果，支持的事件参考[触摸事件的类型](../apis-arkui/arkui-ts/ts-appendix-enums.md#touchtype)。如果应用不消费该事件，则设置为false，事件被Web组件消费。应用消费了该事件，设置为true，Web组件不消费。示例代码参考[onNativeEmbedGestureEvent事件](#onnativeembedgestureevent11)。 7656 7657### constructor<sup>12+</sup> 7658 7659constructor() 7660 7661EventResult的构造函数。 7662 7663**系统能力：** SystemCapability.Web.Webview.Core 7664 7665### setGestureEventResult<sup>12+</sup> 7666 7667设置手势事件消费结果。 7668 7669setGestureEventResult(result: boolean): void 7670 7671**系统能力：** SystemCapability.Web.Webview.Core 7672 7673**参数：** 7674 7675| 参数名 | 类型 | 必填 | 说明 | 7676| --------------- | -------- | ---- |------- | 7677| result | boolean | 是 | 是否消费该手势事件。默认值为true。 | 7678 7679**示例：** 7680 7681请参考[onNativeEmbedGestureEvent事件](#onnativeembedgestureevent11)。 7682 7683### setGestureEventResult<sup>12+</sup> 7684 7685设置手势事件消费结果。 7686 7687setGestureEventResult(result: boolean, stopPropagation?: boolean): void 7688 7689**系统能力：** SystemCapability.Web.Webview.Core 7690 7691**参数：** 7692 7693| 参数名 | 类型 | 必填 | 说明 | 7694| --------------- | -------- | ---- |------- | 7695| result | boolean | 是 | 是否消费该手势事件。默认值为true。 | 7696| stopPropagation<sup>14+</sup>| boolean | 否 | 是否阻止冒泡，在result为true时生效。默认值为true。 | 7697 7698**示例：** 7699 7700请参考[onNativeEmbedGestureEvent事件](#onnativeembedgestureevent11)。 7701 7702## ContextMenuSourceType<sup>9+</sup>枚举说明 7703 7704**系统能力：** SystemCapability.Web.Webview.Core 7705 7706| 名称 | 值 | 说明 | 7707| --------- | -- |------------ | 7708| None | 0 | 其他事件来源。 | 7709| Mouse | 1 | 鼠标事件。 | 7710| LongPress | 2 | 长按事件。 | 7711 7712## ContextMenuMediaType<sup>9+</sup>枚举说明 7713 7714**系统能力：** SystemCapability.Web.Webview.Core 7715 7716| 名称 | 值 | 说明 | 7717| ----- | -- | ------------- | 7718| None | 0 | 非特殊媒体或其他媒体类型。 | 7719| Image | 1 | 图片。 | 7720 7721## ContextMenuInputFieldType<sup>9+</sup>枚举说明 7722 7723**系统能力：** SystemCapability.Web.Webview.Core 7724 7725| 名称 | 值 | 说明 | 7726| --------- | -- | --------------------------- | 7727| None | 0 | 非输入框。 | 7728| PlainText | 1 | 纯文本类型，包括text、search、email等。 | 7729| Password | 2 | 密码类型。 | 7730| Number | 3 | 数字类型。 | 7731| Telephone | 4 | 电话号码类型。 | 7732| Other | 5 | 其他类型。 | 7733 7734## ContextMenuEditStateFlags<sup>9+</sup>枚举说明 7735 7736支持以按位或的方式使用此枚举。例如，如果需要同时支持CAN_CUT、CAN_COPY和CAN_SELECT_ALL，可使用CAN_CUT | CAN_COPY | CAN_SELECT_ALL或11。 7737 7738**系统能力：** SystemCapability.Web.Webview.Core 7739 7740| 名称 | 值 | 说明 | 7741| -------------- | -- | -------- | 7742| NONE | 0 | 不可编辑。 | 7743| CAN_CUT | 1 | 支持剪切。 | 7744| CAN_COPY | 2 | 支持拷贝。 | 7745| CAN_PASTE | 4 | 支持粘贴。 | 7746| CAN_SELECT_ALL | 8 | 支持全选。 | 7747 7748## WebContextMenuParam<sup>9+</sup> 7749 7750实现长按页面元素或鼠标右键弹出来的菜单信息。示例代码参考[onContextMenuShow事件](#oncontextmenushow9)。 7751 7752### constructor<sup>9+</sup> 7753 7754constructor() 7755 7756WebContextMenuParam的构造函数。 7757 7758**系统能力：** SystemCapability.Web.Webview.Core 7759 7760### x<sup>9+</sup> 7761 7762x(): number 7763 7764弹出菜单的x坐标。 7765 7766**系统能力：** SystemCapability.Web.Webview.Core 7767 7768**返回值：** 7769 7770| 类型 | 说明 | 7771| ------ | ------------------ | 7772| number | 显示正常返回非负整数，否则返回-1。 | 7773 7774### y<sup>9+</sup> 7775 7776y(): number 7777 7778弹出菜单的y坐标。 7779 7780**系统能力：** SystemCapability.Web.Webview.Core 7781 7782**返回值：** 7783 7784| 类型 | 说明 | 7785| ------ | ------------------ | 7786| number | 显示正常返回非负整数，否则返回-1。 | 7787 7788### getLinkUrl<sup>9+</sup> 7789 7790getLinkUrl(): string 7791 7792获取链接地址。 7793 7794**系统能力：** SystemCapability.Web.Webview.Core 7795 7796**返回值：** 7797 7798| 类型 | 说明 | 7799| ------ | ------------------------- | 7800| string | 如果长按位置是链接，返回经过安全检查的url链接。 | 7801 7802### getUnfilteredLinkUrl<sup>9+</sup> 7803 7804getUnfilteredLinkUrl(): string 7805 7806获取链接地址。 7807 7808**系统能力：** SystemCapability.Web.Webview.Core 7809 7810**返回值：** 7811 7812| 类型 | 说明 | 7813| ------ | --------------------- | 7814| string | 如果长按位置是链接，返回原始的url链接。 | 7815 7816### getSourceUrl<sup>9+</sup> 7817 7818getSourceUrl(): string 7819 7820获取sourceUrl链接。 7821 7822**系统能力：** SystemCapability.Web.Webview.Core 7823 7824**返回值：** 7825 7826| 类型 | 说明 | 7827| ------ | ------------------------ | 7828| string | 如果选中的元素有src属性，返回src的url。 | 7829 7830### existsImageContents<sup>9+</sup> 7831 7832existsImageContents(): boolean 7833 7834是否存在图像内容。 7835 7836**系统能力：** SystemCapability.Web.Webview.Core 7837 7838**返回值：** 7839 7840| 类型 | 说明 | 7841| ------- | ------------------------- | 7842| boolean | 长按位置中有图片返回true，否则返回false。 | 7843 7844### getMediaType<sup>9+</sup> 7845 7846getMediaType(): ContextMenuMediaType 7847 7848获取网页元素媒体类型。 7849 7850**系统能力：** SystemCapability.Web.Webview.Core 7851 7852**返回值：** 7853 7854| 类型 | 说明 | 7855| ---------------------------------------- | --------- | 7856| [ContextMenuMediaType](#contextmenumediatype9枚举说明) | 网页元素媒体类型。 | 7857 7858### getSelectionText<sup>9+</sup> 7859 7860getSelectionText(): string 7861 7862获取选中文本。 7863 7864**系统能力：** SystemCapability.Web.Webview.Core 7865 7866**返回值：** 7867 7868| 类型 | 说明 | 7869| ------ | -------------------- | 7870| string | 菜单上下文选中文本内容，不存在则返回空。 | 7871 7872### getSourceType<sup>9+</sup> 7873 7874getSourceType(): ContextMenuSourceType 7875 7876获取菜单事件来源。 7877 7878**系统能力：** SystemCapability.Web.Webview.Core 7879 7880**返回值：** 7881 7882| 类型 | 说明 | 7883| ---------------------------------------- | ------- | 7884| [ContextMenuSourceType](#contextmenusourcetype9枚举说明) | 菜单事件来源。 | 7885 7886### getInputFieldType<sup>9+</sup> 7887 7888getInputFieldType(): ContextMenuInputFieldType 7889 7890获取网页元素输入框类型。 7891 7892**系统能力：** SystemCapability.Web.Webview.Core 7893 7894**返回值：** 7895 7896| 类型 | 说明 | 7897| ---------------------------------------- | ------ | 7898| [ContextMenuInputFieldType](#contextmenuinputfieldtype9枚举说明) | 输入框类型。 | 7899 7900### isEditable<sup>9+</sup> 7901 7902isEditable(): boolean 7903 7904获取网页元素是否可编辑标识。 7905 7906**系统能力：** SystemCapability.Web.Webview.Core 7907 7908**返回值：** 7909 7910| 类型 | 说明 | 7911| ------- | -------------------------- | 7912| boolean | 网页元素可编辑返回true，不可编辑返回false。 | 7913 7914### getEditStateFlags<sup>9+</sup> 7915 7916getEditStateFlags(): number 7917 7918获取网页元素可编辑标识。 7919 7920**系统能力：** SystemCapability.Web.Webview.Core 7921 7922**返回值：** 7923 7924| 类型 | 说明 | 7925| ------ | ---------------------------------------- | 7926| number | 网页元素可编辑标识，参照[ContextMenuEditStateFlags](#contextmenueditstateflags9枚举说明)。 | 7927 7928### getPreviewWidth<sup>13+</sup> 7929 7930getPreviewWidth(): number 7931 7932获取预览图的宽。 7933 7934**系统能力：** SystemCapability.Web.Webview.Core 7935 7936**返回值：** 7937 7938| 类型 | 说明 | 7939| ------ | ----------- | 7940| number | 预览图的宽。 | 7941 7942### getPreviewHeight<sup>13+</sup> 7943 7944getPreviewHeight(): number 7945 7946获取预览图的高。 7947 7948**系统能力：** SystemCapability.Web.Webview.Core 7949 7950**返回值：** 7951 7952| 类型 | 说明 | 7953| ------ | ---------- | 7954| number | 预览图的高。 | 7955 7956## WebContextMenuResult<sup>9+</sup> 7957 7958实现长按页面元素或鼠标右键弹出来的菜单所执行的响应事件。示例代码参考[onContextMenuShow事件](#oncontextmenushow9)。 7959 7960### constructor<sup>9+</sup> 7961 7962constructor() 7963 7964WebContextMenuResult的构造函数。 7965 7966**系统能力：** SystemCapability.Web.Webview.Core 7967 7968### closeContextMenu<sup>9+</sup> 7969 7970closeContextMenu(): void 7971 7972不执行WebContextMenuResult其他接口操作时，需要调用此接口关闭菜单。 7973 7974**系统能力：** SystemCapability.Web.Webview.Core 7975 7976### copyImage<sup>9+</sup> 7977 7978copyImage(): void 7979 7980WebContextMenuParam有图片内容则复制图片。 7981 7982**系统能力：** SystemCapability.Web.Webview.Core 7983 7984### copy<sup>9+</sup> 7985 7986copy(): void 7987 7988执行与此上下文菜单相关的拷贝文本操作。 7989 7990**系统能力：** SystemCapability.Web.Webview.Core 7991 7992### paste<sup>9+</sup> 7993 7994paste(): void 7995 7996执行与此上下文菜单相关的粘贴操作。 7997 7998> **说明：** 7999> 8000> 需要配置权限：ohos.permission.READ_PASTEBOARD。 8001 8002**系统能力：** SystemCapability.Web.Webview.Core 8003 8004### cut<sup>9+</sup> 8005 8006cut(): void 8007 8008执行与此上下文菜单相关的剪切操作。 8009 8010**系统能力：** SystemCapability.Web.Webview.Core 8011 8012### selectAll<sup>9+</sup> 8013 8014selectAll(): void 8015 8016执行与此上下文菜单相关的全选操作。 8017 8018**系统能力：** SystemCapability.Web.Webview.Core 8019 8020## JsGeolocation 8021 8022Web组件返回授权或拒绝权限功能的对象。示例代码参考[onGeolocationShow事件](#ongeolocationshow)。 8023 8024### constructor 8025 8026constructor() 8027 8028JsGeolocation的构造函数。 8029 8030**系统能力：** SystemCapability.Web.Webview.Core 8031 8032### invoke 8033 8034invoke(origin: string, allow: boolean, retain: boolean): void 8035 8036设置网页地理位置权限状态。 8037 8038**系统能力：** SystemCapability.Web.Webview.Core 8039 8040**参数：** 8041 8042| 参数名 | 类型 | 必填 | 说明 | 8043| ------ | ------- | ---- | ---------------------------------------- | 8044| origin | string | 是 | 指定源的字符串索引。 | 8045| allow | boolean | 是 | 设置的地理位置权限状态。 | 8046| retain | boolean | 是 | 是否允许将地理位置权限状态保存到系统中。可通过[GeolocationPermissions<sup>9+</sup>](js-apis-webview.md#geolocationpermissions)接口管理保存到系统的地理位置权限。 | 8047 8048## MessageLevel枚举说明 8049 8050**系统能力：** SystemCapability.Web.Webview.Core 8051 8052| 名称 | 值 | 说明 | 8053| ----- | -- | ---- | 8054| Debug | 1 | 调试级别。 | 8055| Error | 4 | 错误级别。 | 8056| Info | 2 | 消息级别。 | 8057| Log | 5 | 日志级别。 | 8058| Warn | 3 | 警告级别。 | 8059 8060## RenderExitReason<sup>9+</sup>枚举说明 8061 8062onRenderExited接口返回的渲染进程退出的具体原因。 8063 8064**系统能力：** SystemCapability.Web.Webview.Core 8065 8066| 名称 | 值 | 说明 | 8067| -------------------------- | -- | ----------------- | 8068| ProcessAbnormalTermination | 0 | 渲染进程异常退出。 | 8069| ProcessWasKilled | 1 | 收到SIGKILL，或被手动终止。 | 8070| ProcessCrashed | 2 | 渲染进程崩溃退出，如段错误。 | 8071| ProcessOom | 3 | 程序内存不足。 | 8072| ProcessExitUnknown | 4 | 其他原因。 | 8073 8074## MixedMode枚举说明 8075 8076**系统能力：** SystemCapability.Web.Webview.Core 8077 8078| 名称 | 值 | 说明 | 8079| ---------- | -- | ---------------------------------- | 8080| All | 0 | 允许加载HTTP和HTTPS混合内容。所有不安全的内容都可以被加载。 | 8081| Compatible | 1 | 混合内容兼容性模式，部分不安全的内容可能被加载。 | 8082| None | 2 | 不允许加载HTTP和HTTPS混合内容。 | 8083 8084## CacheMode枚举说明 8085 8086**系统能力：** SystemCapability.Web.Webview.Core 8087 8088| 名称 | 值 | 说明 | 8089| ------- | -- | ------------------------------------ | 8090| Default<sup>9+</sup> | 0 | 优先使用未过期cache加载资源，无效或无cache时从网络获取。 | 8091| None | 1 | 优先使用cache(含过期)加载资源，无cache时从网络获取。 | 8092| Online | 2 | 强制从网络获取最新资源，不使用任何cache。 | 8093| Only | 3 | 仅使用本地cache加载资源。 | 8094 8095## FileSelectorMode<sup>9+</sup>枚举说明 8096 8097**系统能力：** SystemCapability.Web.Webview.Core 8098 8099| 名称 | 值 | 说明 | 8100| -------------------- | -- | ---------- | 8101| FileOpenMode | 0 | 打开上传单个文件。 | 8102| FileOpenMultipleMode | 1 | 打开上传多个文件。 | 8103| FileOpenFolderMode | 2 | 打开上传文件夹模式。 | 8104| FileSaveMode | 3 | 文件保存模式。 | 8105 8106 ## HitTestType枚举说明 8107 8108 **系统能力：** SystemCapability.Web.Webview.Core 8109 8110| 名称 | 值 | 说明 | 8111| ------------- | -- | ------------------------ | 8112| EditText | 0 | 可编辑的区域。 | 8113| Email | 1 | 电子邮件地址。 | 8114| HttpAnchor | 2 | 超链接，其src为http。 | 8115| HttpAnchorImg | 3 | 带有超链接的图片，其中超链接的src为http。 | 8116| Img | 4 | HTML::img标签。 | 8117| Map | 5 | 地理地址。 | 8118| Phone | 6 | 电话号码。 | 8119| Unknown | 7 | 未知内容。 | 8120 8121 ## OverScrollMode<sup>11+</sup>枚举说明 8122 8123 **系统能力：** SystemCapability.Web.Webview.Core 8124 8125| 名称 | 值 | 说明 | 8126| ------ | -- | ----------- | 8127| NEVER | 0 | Web过滚动模式关闭。 | 8128| ALWAYS | 1 | Web过滚动模式开启。 | 8129 8130## OnContextMenuHideCallback<sup>11+</sup> 8131 8132type OnContextMenuHideCallback = () => void 8133 8134上下文菜单自定义隐藏的回调。 8135 8136**系统能力：** SystemCapability.Web.Webview.Core 8137 8138## SslError<sup>9+</sup>枚举说明 8139 8140onSslErrorEventReceive接口返回的SSL错误的具体原因。 8141 8142**系统能力：** SystemCapability.Web.Webview.Core 8143 8144| 名称 | 值 | 说明 | 8145| ------------ | -- | ----------- | 8146| Invalid | 0 | 一般错误。 | 8147| HostMismatch | 1 | 主机名不匹配。 | 8148| DateInvalid | 2 | 证书日期无效。 | 8149| Untrusted | 3 | 证书颁发机构不受信任。 | 8150 8151## ProtectedResourceType<sup>9+</sup>枚举说明 8152 8153**系统能力：** SystemCapability.Web.Webview.Core 8154 8155| 名称 | 值 | 说明 | 备注 | 8156| --------------------------- | --------------- | ------------- | -------------------------- | 8157| MidiSysex | TYPE_MIDI_SYSEX | MIDI SYSEX资源。 | 目前仅支持权限事件上报，MIDI设备的使用还未支持。 | 8158| VIDEO_CAPTURE<sup>10+</sup> | TYPE_VIDEO_CAPTURE | 视频捕获资源，例如相机。 | | 8159| AUDIO_CAPTURE<sup>10+</sup> | TYPE_AUDIO_CAPTURE | 音频捕获资源，例如麦克风。 | | 8160| SENSOR<sup>12+</sup> | TYPE_SENSOR | 传感器资源，例如加速度传感器。 | | 8161 8162## WebDarkMode<sup>9+</sup>枚举说明 8163 8164**系统能力：** SystemCapability.Web.Webview.Core 8165 8166| 名称 | 值 | 说明 | 8167| ---- | -- | ------------ | 8168| Off | 0 | Web深色模式关闭。 | 8169| On | 1 | Web深色模式开启。 | 8170| Auto | 2 | Web深色模式跟随系统。 | 8171 8172## WebCaptureMode<sup>10+</sup>枚举说明 8173 8174**系统能力：** SystemCapability.Web.Webview.Core 8175 8176| 名称 | 值 | 说明 | 8177| ----------- | -- | ------- | 8178| HOME_SCREEN | 0 | 主屏捕获模式。 | 8179 8180## WebMediaOptions<sup>10+</sup> 8181 8182Web媒体策略的配置。 8183 8184**系统能力：** SystemCapability.Web.Webview.Core 8185 8186| 名称 | 类型 | 必填 | 说明 | 8187| -------------- | ------- | ---- | ---------------------------------------- | 8188| resumeInterval | number | 否 | 被暂停的Web音频能够自动续播的有效期，单位：秒。最长有效期为60秒，由于近似值原因，该有效期可能存在一秒内的误差。 | 8189| audioExclusive | boolean | 否 | 应用内多个Web实例的音频是否独占。 | 8190 8191## ScreenCaptureConfig<sup>10+</sup> 8192 8193Web屏幕捕获的配置。 8194 8195**系统能力：** SystemCapability.Web.Webview.Core 8196 8197| 名称 | 类型 | 必填 | 说明 | 8198| ----------- | --------------------------------------- | ---- | ---------- | 8199| captureMode | [WebCaptureMode](#webcapturemode10枚举说明) | 是 | Web屏幕捕获模式。 | 8200 8201## WebLayoutMode<sup>11+</sup>枚举说明 8202 8203**系统能力：** SystemCapability.Web.Webview.Core 8204 8205| 名称 | 值 | 说明 | 8206| ----------- | -- | ------------------ | 8207| NONE | 0 | Web布局跟随系统。 | 8208| FIT_CONTENT | 1 | Web基于页面大小的自适应网页布局。 | 8209 8210## NestedScrollOptionsExt<sup>14+</sup>对象说明 8211 8212通过NestedScrollOptionsExt可以设置上下左右四个方向的嵌套滚动规则。 8213 8214**系统能力：** SystemCapability.Web.Webview.Core 8215 8216| 名称 | 类型 | 必填 | 说明 | 8217| -------------- | ---------------- | ---- | -------------------- | 8218| scrollUp | [NestedScrollMode](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10) | 否 | 可滚动组件往上滚动时的嵌套滚动选项。 | 8219| scrollDown | [NestedScrollMode](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10) | 否 | 可滚动组件往下滚动时的嵌套滚动选项。 | 8220| scrollLeft | [NestedScrollMode](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10) | 否 | 可滚动组件往左滚动时的嵌套滚动选项。 | 8221| scrollRight | [NestedScrollMode](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10) | 否 | 可滚动组件往右滚动时的嵌套滚动选项。 | 8222 8223## DataResubmissionHandler<sup>9+</sup> 8224 8225通过DataResubmissionHandler可以重新提交表单数据或取消提交表单数据。 8226 8227### constructor<sup>9+</sup> 8228 8229constructor() 8230 8231DataResubmissionHandler的构造函数。 8232 8233**系统能力：** SystemCapability.Web.Webview.Core 8234 8235### resend<sup>9+</sup> 8236 8237resend(): void 8238 8239重新发送表单数据。 8240 8241**系统能力：** SystemCapability.Web.Webview.Core 8242 8243**示例：** 8244 8245 ```ts 8246 // xxx.ets 8247 import { webview } from '@kit.ArkWeb'; 8248 8249 @Entry 8250 @Component 8251 struct WebComponent { 8252 controller: webview.WebviewController = new webview.WebviewController(); 8253 8254 build() { 8255 Column() { 8256 Web({ src: 'www.example.com', controller: this.controller }) 8257 .onDataResubmitted((event) => { 8258 console.log('onDataResubmitted'); 8259 event.handler.resend(); 8260 }) 8261 } 8262 } 8263 } 8264 ``` 8265 8266### cancel<sup>9+</sup> 8267 8268cancel(): void 8269 8270取消重新发送表单数据。 8271 8272**系统能力：** SystemCapability.Web.Webview.Core 8273 8274**示例：** 8275 8276 ```ts 8277 // xxx.ets 8278 import { webview } from '@kit.ArkWeb'; 8279 8280 @Entry 8281 @Component 8282 struct WebComponent { 8283 controller: webview.WebviewController = new webview.WebviewController(); 8284 8285 build() { 8286 Column() { 8287 Web({ src: 'www.example.com', controller: this.controller }) 8288 .onDataResubmitted((event) => { 8289 console.log('onDataResubmitted'); 8290 event.handler.cancel(); 8291 }) 8292 } 8293 } 8294 } 8295 ``` 8296 8297 ## WebController 8298 8299通过WebController可以控制Web组件各种行为。一个WebController对象只能控制一个Web组件，且必须在Web组件和WebController绑定后，才能调用WebController上的方法。 8300 8301从API version 9开始不再维护，建议使用[WebviewController<sup>9+</sup>](js-apis-webview.md#webviewcontroller)代替。 8302 8303### 创建对象 8304 8305<!--code_no_check--> 8306```ts 8307let webController: WebController = new WebController() 8308``` 8309 8310### getCookieManager<sup>(deprecated)</sup> 8311 8312getCookieManager(): WebCookie 8313 8314获取Web组件cookie管理对象。 8315 8316从API version 9开始不再维护，建议使用[getCookie](js-apis-webview.md#getcookiedeprecated)代替。 8317 8318**系统能力：** SystemCapability.Web.Webview.Core 8319 8320**返回值：** 8321 8322| 类型 | 说明 | 8323| --------- | ---------------------------------------- | 8324| WebCookie | Web组件cookie管理对象，参考[WebCookie](#webcookie)定义。 | 8325 8326**示例：** 8327 8328 ```ts 8329 // xxx.ets 8330 @Entry 8331 @Component 8332 struct WebComponent { 8333 controller: WebController = new WebController() 8334 8335 build() { 8336 Column() { 8337 Button('getCookieManager') 8338 .onClick(() => { 8339 let cookieManager = this.controller.getCookieManager() 8340 }) 8341 Web({ src: 'www.example.com', controller: this.controller }) 8342 } 8343 } 8344 } 8345 ``` 8346 8347### requestFocus<sup>(deprecated)</sup> 8348 8349requestFocus() 8350 8351使当前web页面获取焦点。 8352 8353从API version 9开始不再维护，建议使用[requestFocus<sup>9+</sup>](js-apis-webview.md#requestfocus)代替。 8354 8355**系统能力：** SystemCapability.Web.Webview.Core 8356 8357**示例：** 8358 8359 ```ts 8360 // xxx.ets 8361 @Entry 8362 @Component 8363 struct WebComponent { 8364 controller: WebController = new WebController() 8365 8366 build() { 8367 Column() { 8368 Button('requestFocus') 8369 .onClick(() => { 8370 this.controller.requestFocus() 8371 }) 8372 Web({ src: 'www.example.com', controller: this.controller }) 8373 } 8374 } 8375 } 8376 ``` 8377 8378### accessBackward<sup>(deprecated)</sup> 8379 8380accessBackward(): boolean 8381 8382当前页面是否可后退，即当前页面是否有返回历史记录。 8383 8384从API version 9开始不再维护，建议使用[accessBackward<sup>9+</sup>](js-apis-webview.md#accessbackward)代替。 8385 8386**系统能力：** SystemCapability.Web.Webview.Core 8387 8388**返回值：** 8389 8390| 类型 | 说明 | 8391| ------- | --------------------- | 8392| boolean | 可以后退返回true,否则返回false。 | 8393 8394**示例：** 8395 8396 ```ts 8397 // xxx.ets 8398 @Entry 8399 @Component 8400 struct WebComponent { 8401 controller: WebController = new WebController() 8402 8403 build() { 8404 Column() { 8405 Button('accessBackward') 8406 .onClick(() => { 8407 let result = this.controller.accessBackward() 8408 console.log('result:' + result) 8409 }) 8410 Web({ src: 'www.example.com', controller: this.controller }) 8411 } 8412 } 8413 } 8414 ``` 8415 8416### accessForward<sup>(deprecated)</sup> 8417 8418accessForward(): boolean 8419 8420当前页面是否可前进，即当前页面是否有前进历史记录。 8421 8422从API version 9开始不再维护，建议使用[accessForward<sup>9+</sup>](js-apis-webview.md#accessforward)代替。 8423 8424**系统能力：** SystemCapability.Web.Webview.Core 8425 8426**返回值：** 8427 8428| 类型 | 说明 | 8429| ------- | --------------------- | 8430| boolean | 可以前进返回true,否则返回false。 | 8431 8432**示例：** 8433 8434 ```ts 8435 // xxx.ets 8436 @Entry 8437 @Component 8438 struct WebComponent { 8439 controller: WebController = new WebController() 8440 8441 build() { 8442 Column() { 8443 Button('accessForward') 8444 .onClick(() => { 8445 let result = this.controller.accessForward() 8446 console.log('result:' + result) 8447 }) 8448 Web({ src: 'www.example.com', controller: this.controller }) 8449 } 8450 } 8451 } 8452 ``` 8453 8454### accessStep<sup>(deprecated)</sup> 8455 8456accessStep(step: number): boolean 8457 8458当前页面是否可前进或者后退给定的step步。 8459 8460从API version 9开始不再维护，建议使用[accessStep<sup>9+</sup>](js-apis-webview.md#accessstep)代替。 8461 8462**系统能力：** SystemCapability.Web.Webview.Core 8463 8464**参数：** 8465 8466| 参数名 | 类型 | 必填 | 说明 | 8467| ---- | ------ | ---- | --------------------- | 8468| step | number | 是 | 要跳转的步数，正数代表前进，负数代表后退。 | 8469 8470**返回值：** 8471 8472| 类型 | 说明 | 8473| ------- | --------- | 8474| boolean | 页面是否前进或后退 | 8475 8476**示例：** 8477 8478 ```ts 8479 // xxx.ets 8480 @Entry 8481 @Component 8482 struct WebComponent { 8483 controller: WebController = new WebController() 8484 @State steps: number = 2 8485 8486 build() { 8487 Column() { 8488 Button('accessStep') 8489 .onClick(() => { 8490 let result = this.controller.accessStep(this.steps) 8491 console.log('result:' + result) 8492 }) 8493 Web({ src: 'www.example.com', controller: this.controller }) 8494 } 8495 } 8496 } 8497 ``` 8498 8499### backward<sup>(deprecated)</sup> 8500 8501backward() 8502 8503按照历史栈，后退一个页面。一般结合accessBackward一起使用。 8504 8505从API version 9开始不再维护，建议使用[backward<sup>9+</sup>](js-apis-webview.md#backward)代替。 8506 8507**系统能力：** SystemCapability.Web.Webview.Core 8508 8509**示例：** 8510 8511 ```ts 8512 // xxx.ets 8513 @Entry 8514 @Component 8515 struct WebComponent { 8516 controller: WebController = new WebController() 8517 8518 build() { 8519 Column() { 8520 Button('backward') 8521 .onClick(() => { 8522 this.controller.backward() 8523 }) 8524 Web({ src: 'www.example.com', controller: this.controller }) 8525 } 8526 } 8527 } 8528 ``` 8529 8530### forward<sup>(deprecated)</sup> 8531 8532forward() 8533 8534按照历史栈，前进一个页面。一般结合accessForward一起使用。 8535 8536从API version 9开始不再维护，建议使用[forward<sup>9+</sup>](js-apis-webview.md#forward)代替。 8537 8538**系统能力：** SystemCapability.Web.Webview.Core 8539 8540**示例：** 8541 8542 ```ts 8543 // xxx.ets 8544 @Entry 8545 @Component 8546 struct WebComponent { 8547 controller: WebController = new WebController() 8548 8549 build() { 8550 Column() { 8551 Button('forward') 8552 .onClick(() => { 8553 this.controller.forward() 8554 }) 8555 Web({ src: 'www.example.com', controller: this.controller }) 8556 } 8557 } 8558 } 8559 ``` 8560 8561### deleteJavaScriptRegister<sup>(deprecated)</sup> 8562 8563deleteJavaScriptRegister(name: string) 8564 8565删除通过registerJavaScriptProxy注册到window上的指定name的应用侧JavaScript对象。删除后立即生效，无须调用[refresh](#refreshdeprecated)接口。 8566 8567从API version 9开始不再维护，建议使用[deleteJavaScriptRegister<sup>9+</sup>](js-apis-webview.md#deletejavascriptregister)代替。 8568 8569**系统能力：** SystemCapability.Web.Webview.Core 8570 8571**参数：** 8572 8573| 参数名 | 类型 | 必填 | 说明 | 8574| ---- | ------ | ---- | ---------------------------------------- | 8575| name | string | 是 | 注册对象的名称，可在网页侧JavaScript中通过此名称调用应用侧JavaScript对象。 | 8576 8577**示例：** 8578 8579 ```ts 8580 // xxx.ets 8581 @Entry 8582 @Component 8583 struct WebComponent { 8584 controller: WebController = new WebController() 8585 @State name: string = 'Object' 8586 8587 build() { 8588 Column() { 8589 Button('deleteJavaScriptRegister') 8590 .onClick(() => { 8591 this.controller.deleteJavaScriptRegister(this.name) 8592 }) 8593 Web({ src: 'www.example.com', controller: this.controller }) 8594 } 8595 } 8596 } 8597 ``` 8598 8599### getHitTest<sup>(deprecated)</sup> 8600 8601getHitTest(): HitTestType 8602 8603获取当前被点击区域的元素类型。 8604 8605从API version 9开始不再维护，建议使用[getHitTest<sup>9+</sup>](js-apis-webview.md#gethittest)代替。 8606 8607**系统能力：** SystemCapability.Web.Webview.Core 8608 8609**返回值：** 8610 8611| 类型 | 说明 | 8612| ------------------------------- | ----------- | 8613| [HitTestType](#hittesttype枚举说明) | 被点击区域的元素类型。 | 8614 8615**示例：** 8616 8617 ```ts 8618 // xxx.ets 8619 @Entry 8620 @Component 8621 struct WebComponent { 8622 controller: WebController = new WebController() 8623 8624 build() { 8625 Column() { 8626 Button('getHitTest') 8627 .onClick(() => { 8628 let hitType = this.controller.getHitTest() 8629 console.log("hitType: " + hitType) 8630 }) 8631 Web({ src: 'www.example.com', controller: this.controller }) 8632 } 8633 } 8634 } 8635 ``` 8636 8637### loadData<sup>(deprecated)</sup> 8638 8639loadData(options: { data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string }) 8640 8641baseUrl为空时，通过”data“协议加载指定的一段字符串。 8642 8643当baseUrl为”data“协议时，编码后的data字符串将被Web组件作为”data"协议加载。 8644 8645当baseUrl为“http/https"协议时，编码后的data字符串将被Web组件以类似loadUrl的方式以非编码字符串处理。 8646 8647从API version 9开始不再维护，建议使用[loadData<sup>9+</sup>](js-apis-webview.md#loaddata)代替。 8648 8649**系统能力：** SystemCapability.Web.Webview.Core 8650 8651**参数：** 8652 8653| 参数名 | 类型 | 必填 | 说明 | 8654| ---------- | ------ | ---- | ---------------------------------------- | 8655| data | string | 是 | 按照”Base64“或者”URL"编码后的一段字符串。 | 8656| mimeType | string | 是 | 媒体类型（MIME）。 | 8657| encoding | string | 是 | 编码类型，具体为“Base64"或者”URL编码。 | 8658| baseUrl | string | 否 | 指定的一个URL路径（“http”/“https”/"data"协议），并由Web组件赋值给window.origin。 | 8659| historyUrl | string | 否 | 历史记录URL。非空时，可被历史记录管理，实现前后后退功能。当baseUrl为空时，此属性无效。 | 8660 8661**示例：** 8662 8663 ```ts 8664 // xxx.ets 8665 @Entry 8666 @Component 8667 struct WebComponent { 8668 controller: WebController = new WebController() 8669 8670 build() { 8671 Column() { 8672 Button('loadData') 8673 .onClick(() => { 8674 this.controller.loadData({ 8675 data: "<html><body bgcolor=\"white\">Source:<pre>source</pre></body></html>", 8676 mimeType: "text/html", 8677 encoding: "UTF-8" 8678 }) 8679 }) 8680 Web({ src: 'www.example.com', controller: this.controller }) 8681 } 8682 } 8683 } 8684 ``` 8685 8686### loadUrl<sup>(deprecated)</sup> 8687 8688loadUrl(options: { url: string | Resource, headers?: Array\<Header\> }) 8689 8690使用指定的http头加载指定的URL。 8691 8692通过loadUrl注入的对象只在当前document有效，即通过loadUrl导航到新的页面会无效。 8693 8694而通过registerJavaScriptProxy注入的对象，在loadUrl导航到新的页面也会有效。 8695 8696从API version 9开始不再维护，建议使用[loadUrl<sup>9+</sup>](js-apis-webview.md#loadurl)代替。 8697 8698**系统能力：** SystemCapability.Web.Webview.Core 8699 8700**参数：** 8701 8702| 参数名 | 类型 | 必填 | 说明 | 8703| ------- | -------------------------- | ---- | -------------- | 8704| url | string \| Resource | 是 | 需要加载的 URL。 | 8705| headers | Array\<[Header](#header)\> | 否 | URL的附加HTTP请求头。默认值：[]。 | 8706 8707**示例：** 8708 8709 ```ts 8710 // xxx.ets 8711 @Entry 8712 @Component 8713 struct WebComponent { 8714 controller: WebController = new WebController() 8715 8716 build() { 8717 Column() { 8718 Button('loadUrl') 8719 .onClick(() => { 8720 this.controller.loadUrl({ url: 'www.example.com' }) 8721 }) 8722 Web({ src: 'www.example.com', controller: this.controller }) 8723 } 8724 } 8725 } 8726 ``` 8727 8728### onActive<sup>(deprecated)</sup> 8729 8730onActive(): void 8731 8732调用此接口通知Web组件进入前台激活状态。 8733 8734从API version 9开始不再维护，建议使用[onActive<sup>9+</sup>](js-apis-webview.md#onactive)代替。 8735 8736**系统能力：** SystemCapability.Web.Webview.Core 8737 8738**示例：** 8739 8740 ```ts 8741 // xxx.ets 8742 @Entry 8743 @Component 8744 struct WebComponent { 8745 controller: WebController = new WebController() 8746 8747 build() { 8748 Column() { 8749 Button('onActive') 8750 .onClick(() => { 8751 this.controller.onActive() 8752 }) 8753 Web({ src: 'www.example.com', controller: this.controller }) 8754 } 8755 } 8756 } 8757 ``` 8758 8759### onInactive<sup>(deprecated)</sup> 8760 8761onInactive(): void 8762 8763调用此接口通知Web组件进入未激活状态。 8764 8765从API version 9开始不再维护，建议使用[onInactive<sup>9+</sup>](js-apis-webview.md#oninactive)代替。 8766 8767**系统能力：** SystemCapability.Web.Webview.Core 8768 8769**示例：** 8770 8771 ```ts 8772 // xxx.ets 8773 @Entry 8774 @Component 8775 struct WebComponent { 8776 controller: WebController = new WebController() 8777 8778 build() { 8779 Column() { 8780 Button('onInactive') 8781 .onClick(() => { 8782 this.controller.onInactive() 8783 }) 8784 Web({ src: 'www.example.com', controller: this.controller }) 8785 } 8786 } 8787 } 8788 ``` 8789 8790### zoom<sup>(deprecated)</sup> 8791 8792zoom(factor: number): void 8793 8794调整当前网页的缩放比例。 8795 8796从API version 9开始不再维护，建议使用[zoom<sup>9+</sup>](js-apis-webview.md#zoom)代替。 8797 8798**系统能力：** SystemCapability.Web.Webview.Core 8799 8800**参数：** 8801 8802| 参数名 | 类型 | 必填 | 说明 | 8803| ------ | ------ | ---- | ------------------------------ | 8804| factor | number | 是 | 基于当前网页所需调整的相对缩放比例，正值为放大，负值为缩小。 | 8805 8806**示例：** 8807 8808 ```ts 8809 // xxx.ets 8810 @Entry 8811 @Component 8812 struct WebComponent { 8813 controller: WebController = new WebController() 8814 @State factor: number = 1 8815 8816 build() { 8817 Column() { 8818 Button('zoom') 8819 .onClick(() => { 8820 this.controller.zoom(this.factor) 8821 }) 8822 Web({ src: 'www.example.com', controller: this.controller }) 8823 } 8824 } 8825 } 8826 ``` 8827 8828### refresh<sup>(deprecated)</sup> 8829 8830refresh() 8831 8832调用此接口通知Web组件刷新网页。 8833 8834从API version 9开始不再维护，建议使用[refresh<sup>9+</sup>](js-apis-webview.md#refresh)代替。 8835 8836**系统能力：** SystemCapability.Web.Webview.Core 8837 8838**示例：** 8839 8840 ```ts 8841 // xxx.ets 8842 @Entry 8843 @Component 8844 struct WebComponent { 8845 controller: WebController = new WebController() 8846 8847 build() { 8848 Column() { 8849 Button('refresh') 8850 .onClick(() => { 8851 this.controller.refresh() 8852 }) 8853 Web({ src: 'www.example.com', controller: this.controller }) 8854 } 8855 } 8856 } 8857 ``` 8858 8859### registerJavaScriptProxy<sup>(deprecated)</sup> 8860 8861registerJavaScriptProxy(options: { object: object, name: string, methodList: Array\<string\> }) 8862 8863注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。注册后，须调用[refresh](#refreshdeprecated)接口生效。 8864 8865从API version 9开始不再维护，建议使用[registerJavaScriptProxy<sup>9+</sup>](js-apis-webview.md#registerjavascriptproxy)代替。 8866 8867**系统能力：** SystemCapability.Web.Webview.Core 8868 8869**参数：** 8870 8871| 参数名 | 类型 | 必填 | 说明 | 8872| ---------- | --------------- | ---- | ---------------------------------------- | 8873| object | object | 是 | 参与注册的应用侧JavaScript对象。可以声明方法，也可以声明属性，但是不支持h5直接调用。其中方法的参数和返回类型只能为string，number，boolean | 8874| name | string | 是 | 注册对象的名称，与window中调用的对象名一致。注册后window对象可以通过此名字访问应用侧JavaScript对象。 | 8875| methodList | Array\<string\> | 是 | 参与注册的应用侧JavaScript对象的方法。 | 8876 8877**示例：** 8878 8879 ```ts 8880 // xxx.ets 8881 class TestObj { 8882 constructor() { 8883 } 8884 8885 test(): string { 8886 return "ArkUI Web Component" 8887 } 8888 8889 toString(): void { 8890 console.log('Web Component toString') 8891 } 8892 } 8893 8894 @Entry 8895 @Component 8896 struct Index { 8897 controller: WebController = new WebController() 8898 testObj = new TestObj(); 8899 build() { 8900 Column() { 8901 Row() { 8902 Button('Register JavaScript To Window').onClick(() => { 8903 this.controller.registerJavaScriptProxy({ 8904 object: this.testObj, 8905 name: "objName", 8906 methodList: ["test", "toString"], 8907 }) 8908 }) 8909 } 8910 Web({ src: $rawfile('index.html'), controller: this.controller }) 8911 .javaScriptAccess(true) 8912 } 8913 } 8914 } 8915 ``` 8916 8917 加载的html文件。 8918 ```html 8919 <!-- index.html --> 8920 <!DOCTYPE html> 8921 <html> 8922 <meta charset="utf-8"> 8923 <body> 8924 Hello world! 8925 </body> 8926 <script type="text/javascript"> 8927 function htmlTest() { 8928 str = objName.test("test function") 8929 console.log('objName.test result:'+ str) 8930 } 8931 </script> 8932 </html> 8933 8934 ``` 8935 8936### runJavaScript<sup>(deprecated)</sup> 8937 8938runJavaScript(options: { script: string, callback?: (result: string) => void }) 8939 8940异步执行JavaScript脚本，并通过回调方式返回脚本执行的结果。runJavaScript需要在loadUrl完成后，比如onPageEnd中调用。 8941 8942从API version 9开始不再维护，建议使用[runJavaScript<sup>9+</sup>](js-apis-webview.md#runjavascript)代替。 8943 8944**系统能力：** SystemCapability.Web.Webview.Core 8945 8946**参数：** 8947 8948| 参数名 | 类型 | 必填 | 说明 | 8949| -------- | ------------------------ | ---- | ---------------------------------------- | 8950| script | string | 是 | JavaScript脚本。 | 8951| callback | (result: string) => void | 否 | 回调执行JavaScript脚本结果。JavaScript脚本若执行失败或无返回值时，返回null。 | 8952 8953**示例：** 8954 8955 ```ts 8956 // xxx.ets 8957 @Entry 8958 @Component 8959 struct WebComponent { 8960 controller: WebController = new WebController() 8961 @State webResult: string = '' 8962 build() { 8963 Column() { 8964 Text(this.webResult).fontSize(20) 8965 Web({ src: $rawfile('index.html'), controller: this.controller }) 8966 .javaScriptAccess(true) 8967 .onPageEnd((event) => { 8968 this.controller.runJavaScript({ 8969 script: 'test()', 8970 callback: (result: string)=> { 8971 this.webResult = result 8972 console.info(`The test() return value is: ${result}`) 8973 }}) 8974 if (event) { 8975 console.info('url: ', event.url) 8976 } 8977 }) 8978 } 8979 } 8980 } 8981 ``` 8982 加载的html文件。 8983 ```html 8984 <!-- index.html --> 8985 <!DOCTYPE html> 8986 <html> 8987 <meta charset="utf-8"> 8988 <body> 8989 Hello world! 8990 </body> 8991 <script type="text/javascript"> 8992 function test() { 8993 console.log('Ark WebComponent') 8994 return "This value is from index.html" 8995 } 8996 </script> 8997 </html> 8998 ``` 8999 9000### stop<sup>(deprecated)</sup> 9001 9002stop() 9003 9004停止页面加载。 9005 9006从API version 9开始不再维护，建议使用[stop<sup>9+</sup>](js-apis-webview.md#stop)代替。 9007 9008**系统能力：** SystemCapability.Web.Webview.Core 9009 9010**示例：** 9011 9012 ```ts 9013 // xxx.ets 9014 @Entry 9015 @Component 9016 struct WebComponent { 9017 controller: WebController = new WebController() 9018 9019 build() { 9020 Column() { 9021 Button('stop') 9022 .onClick(() => { 9023 this.controller.stop() 9024 }) 9025 Web({ src: 'www.example.com', controller: this.controller }) 9026 } 9027 } 9028 } 9029 ``` 9030 9031### clearHistory<sup>(deprecated)</sup> 9032 9033clearHistory(): void 9034 9035删除所有前进后退记录。 9036 9037从API version 9开始不再维护，建议使用[clearHistory<sup>9+</sup>](js-apis-webview.md#clearhistory)代替。 9038 9039**系统能力：** SystemCapability.Web.Webview.Core 9040 9041**示例：** 9042 9043 ```ts 9044 // xxx.ets 9045 @Entry 9046 @Component 9047 struct WebComponent { 9048 controller: WebController = new WebController() 9049 9050 build() { 9051 Column() { 9052 Button('clearHistory') 9053 .onClick(() => { 9054 this.controller.clearHistory() 9055 }) 9056 Web({ src: 'www.example.com', controller: this.controller }) 9057 } 9058 } 9059 } 9060 ``` 9061 9062## WebCookie 9063 9064通过WebCookie可以控制Web组件中的cookie的各种行为，其中每个应用中的所有Web组件共享一个WebCookie。通过controller方法中的getCookieManager方法可以获取WebCookie对象，进行后续的cookie管理操作。 9065 9066### constructor<sup>9+</sup> 9067 9068constructor() 9069 9070WebCookie的构造函数。 9071 9072**系统能力：** SystemCapability.Web.Webview.Core 9073 9074### setCookie<sup>(deprecated)</sup> 9075 9076setCookie() 9077 9078设置cookie，该方法为同步方法。设置成功返回true，否则返回false。 9079 9080从API version 9开始不再维护，建议使用[setCookie<sup>9+</sup>](js-apis-webview.md#setcookie)代替。 9081 9082**系统能力：** SystemCapability.Web.Webview.Core 9083 9084### saveCookie<sup>(deprecated)</sup> 9085 9086saveCookie() 9087 9088将当前存在内存中的cookie同步到磁盘中，该方法为同步方法。 9089 9090从API version 9开始不再维护，建议使用[saveCookieAsync<sup>9+</sup>](js-apis-webview.md#savecookieasync)代替。 9091 9092**系统能力：** SystemCapability.Web.Webview.Core 9093 9094## ScriptItem<sup>11+</sup> 9095 9096通过[javaScriptOnDocumentStart](#javascriptondocumentstart11)属性注入到Web组件的ScriptItem对象。 9097 9098**系统能力：** SystemCapability.Web.Webview.Core 9099 9100| 名称 | 类型 | 必填 | 说明 | 9101| ----------- | -------------- | ---- | --------------------- | 9102| script | string | 是 | 需要注入、执行的JavaScript脚本。 | 9103| scriptRules | Array\<string> | 是 | 一组允许来源的匹配规则。<br>1.如果需要允许所有来源的网址，使用通配符“ * ”。<br>2.如果需要精确匹配，则描述网站地址，如"https:\//www\.example.com"。<br>3.如果模糊匹配网址，可以使用“ * ”通配符替代，如"https://*.example.com"。不允许使用"x. * .y.com"、" * foobar.com"等。<br>4.如果来源是ip地址，则使用规则2。<br>5.对于http/https以外的协议(自定义协议)，不支持使用精确匹配和模糊匹配，且必须以"://"结尾，例如"resource://"。<br>6.一组scriptRule中，如果其中一条不满足以上规则，则整组scriptRule都不生效。 | 9104 9105## WebNavigationType<sup>11+</sup> 9106 9107定义navigation类型。 9108 9109**系统能力：** SystemCapability.Web.Webview.Core 9110 9111| 名称 | 值 | 说明 | 9112| ----------------------------- | -- | ------------ | 9113| UNKNOWN | 0 | 未知类型。 | 9114| MAIN_FRAME_NEW_ENTRY | 1 | 主文档上产生的新的历史节点跳转。 | 9115| MAIN_FRAME_EXISTING_ENTRY | 2 | 主文档上产生的到已有的历史节点的跳转。 | 9116| NAVIGATION_TYPE_NEW_SUBFRAME | 4 | 子文档上产生的用户触发的跳转。 | 9117| NAVIGATION_TYPE_AUTO_SUBFRAME | 5 | 子文档上产生的非用户触发的跳转。 | 9118 9119## LoadCommittedDetails<sup>11+</sup> 9120 9121提供已提交跳转的网页的详细信息。 9122 9123**系统能力：** SystemCapability.Web.Webview.Core 9124 9125| 名称 | 类型 | 必填 | 说明 | 9126| ----------- | ------------------------------------ | ---- | --------------------- | 9127| isMainFrame | boolean | 是 | 是否是主文档。 | 9128| isSameDocument | boolean | 是 | 是否在不更改文档的情况下进行的网页跳转。在同文档跳转的示例：1.参考片段跳转；2.pushState或replaceState触发的跳转；3.同一页面历史跳转。 | 9129| didReplaceEntry | boolean | 是 | 是否提交的新节点替换了已有的节点。另外在一些子文档跳转的场景，虽然没有实际替换已有节点，但是有一些属性发生了变更。 | 9130| navigationType | [WebNavigationType](#webnavigationtype11) | 是 | 网页跳转的类型。 | 9131| url | string | 是 | 当前跳转网页的URL。 | 9132 9133## ThreatType<sup>11+</sup> 9134 9135定义网站风险类型。 9136 9137**系统能力：** SystemCapability.Web.Webview.Core 9138 9139| 名称 | 值 | 说明 | 9140| ---------------- | -- | ----------------------| 9141| THREAT_ILLEGAL | 0 | 非法网站。 | 9142| THREAT_FRAUD | 1 | 欺诈网站。 | 9143| THREAT_RISK | 2 | 存在安全风险的网站。 | 9144| THREAT_WARNING | 3 | 涉嫌包含不健康内容的网站。 | 9145 9146## OnNavigationEntryCommittedCallback<sup>11+</sup> 9147 9148type OnNavigationEntryCommittedCallback = (loadCommittedDetails: [LoadCommittedDetails](#loadcommitteddetails11)) => void 9149 9150导航条目提交时触发的回调。 9151 9152**系统能力：** SystemCapability.Web.Webview.Core 9153 9154**参数：** 9155 9156| 参数名 | 类型 | 必填 | 说明 | 9157| ------ | ------ | ---- | --------------------- | 9158| loadCommittedDetails | [LoadCommittedDetails](#loadcommitteddetails11) | 是 | 提供已提交跳转的网页的详细信息。 | 9159 9160## OnSafeBrowsingCheckResultCallback<sup>11+</sup> 9161 9162type OnSafeBrowsingCheckResultCallback = (threatType: ThreatType) => void 9163 9164网站安全风险检查触发的回调。 9165 9166**系统能力：** SystemCapability.Web.Webview.Core 9167 9168**参数：** 9169 9170| 参数名 | 类型 | 必填 | 说明 | 9171| ------ | ------ | ---- | --------------------- | 9172| threatType | [ThreatType](#threattype11) | 是 | 定义网站threat类型。 | 9173 9174## FullScreenEnterEvent<sup>12+</sup> 9175 9176Web组件进入全屏回调事件的详情。 9177 9178**系统能力：** SystemCapability.Web.Webview.Core 9179 9180| 名称 | 类型 | 必填 | 说明 | 9181| ----------- | ------------------------------------ | ---- | --------------------- | 9182| handler | [FullScreenExitHandler](#fullscreenexithandler9) | 是 | 用于退出全屏模式的函数句柄。 | 9183| videoWidth | number | 否 | 视频的宽度，单位：px。如果进入全屏的是 `<video>` 元素，表示其宽度；如果进入全屏的子元素中包含 `<video>` 元素，表示第一个子视频元素的宽度；其他情况下，为0。 | 9184| videoHeight | number | 否 | 视频的高度，单位：px。如果进入全屏的是 `<video>` 元素，表示其高度；如果进入全屏的子元素中包含 `<video>` 元素，表示第一个子视频元素的高度；其他情况下，为0。 | 9185 9186## OnFullScreenEnterCallback<sup>12+</sup> 9187 9188type OnFullScreenEnterCallback = (event: FullScreenEnterEvent) => void 9189 9190Web组件进入全屏时触发的回调。 9191 9192**系统能力：** SystemCapability.Web.Webview.Core 9193 9194**参数：** 9195 9196| 参数名 | 类型 | 必填 | 说明 | 9197| ------ | ------ | ---- | --------------------- | 9198| event | [FullScreenEnterEvent](#fullscreenenterevent12) | 是 | Web组件进入全屏的回调事件详情。 | 9199 9200## SslErrorEvent<sup>12+</sup> 9201 9202用户加载资源时发生SSL错误时触发的回调详情。 9203 9204**系统能力：** SystemCapability.Web.Webview.Core 9205 9206| 名称 | 类型 | 必填 | 说明 | 9207| ------- | ------------------------------------ | ---- | -------------- | 9208| handler | [SslErrorHandler](#sslerrorhandler9) | 是 | 通知Web组件用户操作行为。 | 9209| error | [SslError](#sslerror9枚举说明) | 是 | 错误码。 | 9210| url | string | 是 | url地址。 | 9211| originalUrl | string | 是 | 请求的原始url地址。 | 9212| referrer | string | 是 | referrer url地址。 | 9213| isFatalError | boolean | 是 | 是否是致命错误。 | 9214| isMainFrame | boolean | 是 | 是否是主资源。 | 9215 9216 9217## OnSslErrorEventCallback<sup>12+</sup> 9218 9219type OnSslErrorEventCallback = (sslErrorEvent: SslErrorEvent) => void 9220 9221用户加载资源时发生SSL错误时触发的回调。 9222 9223**系统能力：** SystemCapability.Web.Webview.Core 9224 9225**参数：** 9226 9227| 参数名 | 类型 | 必填 | 说明 | 9228| ------ | ------ | ---- | --------------------- | 9229| sslErrorEvent | [SslErrorEvent](#sslerrorevent12) | 是 | 用户加载资源时发生SSL错误时触发的回调详情。 | 9230 9231## NativeEmbedStatus<sup>11+</sup> 9232 9233定义同层标签生命周期，当加载页面中有同层标签会触发CREATE，同层标签移动或者放大会触发UPDATE，退出页面会触发DESTROY。 9234 9235**系统能力：** SystemCapability.Web.Webview.Core 9236 9237| 名称 | 值 | 说明 | 9238| ----------------------------- | -- | ------------ | 9239| CREATE | 0 | 同层标签创建。 | 9240| UPDATE | 1 | 同层标签更新。 | 9241| DESTROY | 2 | 同层标签销毁。 | 9242| ENTER_BFCACHE<sup>12+</sup> | 3 | 同层标签进入BFCache。 | 9243| LEAVE_BFCACHE<sup>12+</sup> | 4 | 同层标签离开BFCache。 | 9244 9245## NativeEmbedInfo<sup>11+</sup> 9246 9247提供同层标签的详细信息。 9248 9249**系统能力：** SystemCapability.Web.Webview.Core 9250 9251| 名称 | 类型 | 必填 | 说明 | 9252|-------------------| ------------------------------------ | ---- |---------------------------| 9253| id | string | 否 | 同层标签的id信息。 | 9254| type | string | 否 | 同层标签的type信息，统一为小写字符。 | 9255| src | string | 否 | 同层标签的src信息。 | 9256| width | number | 否 | 同层标签的宽，单位为px。 | 9257| height | number | 否 | 同层标签的高，单位为px。 | 9258| url | string | 否 | 同层标签的url信息。 | 9259| tag<sup>12+</sup> | string | 否 | 标签名，统一为大写字符。 | 9260| params<sup>12+</sup> | Map<string, string> | 否 | object标签包含的param标签键值对列表，该map本质为Object类型，请使用Object提供的方法操作该对象。 | 9261| position<sup>12+</sup> | Position | 否 | 同层标签在屏幕坐标系中相对于Web组件的位置信息，此处区别于标准Position，单位为px。 | 9262 9263## NativeEmbedDataInfo<sup>11+</sup> 9264 9265提供同层标签生命周期变化的详细信息。 9266 9267**系统能力：** SystemCapability.Web.Webview.Core 9268 9269| 名称 | 类型 | 必填 | 说明 | 9270| ----------- | ------------------------------------ | ---- | --------------------- | 9271| status | [NativeEmbedStatus](#nativeembedstatus11) | 否 | 同层标签生命周期状态。 | 9272| surfaceId | string | 否 | NativeImage的psurfaceid。 | 9273| embedId | string | 否 | 同层标签的唯一id。 | 9274| info | [NativeEmbedInfo](#nativeembedinfo11) | 否 | 同层标签的详细信息。 | 9275 9276## NativeEmbedTouchInfo<sup>11+</sup> 9277 9278提供手指触摸到同层标签的详细信息。 9279 9280**系统能力：** SystemCapability.Web.Webview.Core 9281 9282| 名称 | 类型 | 必填 | 说明 | 9283| ----------- | ------------------------------------ | ---- | --------------------- | 9284| embedId | string | 否 | 同层标签的唯一id。 | 9285| touchEvent | [TouchEvent](../apis-arkui/arkui-ts/ts-universal-events-touch.md#touchevent对象说明) | 否 | 手指触摸动作信息。 | 9286| result<sup>12+</sup> | [EventResult](#eventresult12) | 否 | 通知Web组件手势事件的消费结果。 | 9287 9288## FirstMeaningfulPaint<sup>12+</sup> 9289 9290提供网页绘制页面主要内容的详细信息。 9291 9292**系统能力：** SystemCapability.Web.Webview.Core 9293 9294| 名称 | 类型 | 必填 | 说明 | 9295| ------------------------ | ------ | ---- | -------------------------------------- | 9296| navigationStartTime | number | 否 | 导航条加载时间，单位以微秒表示。 | 9297| firstMeaningfulPaintTime | number | 否 | 绘制页面主要内容时间，单位以毫秒表示。 | 9298 9299## OnFirstMeaningfulPaintCallback<sup>12+</sup> 9300 9301type OnFirstMeaningfulPaintCallback = (firstMeaningfulPaint: [FirstMeaningfulPaint](#firstmeaningfulpaint12)) => void 9302 9303网页绘制页面度量信息的回调，当网页加载完页面主要内容时会触发该回调。 9304 9305**系统能力：** SystemCapability.Web.Webview.Core 9306 9307**参数：** 9308 9309| 参数名 | 类型 | 必填 | 说明 | 9310| ------ | ------ | ---- | --------------------- | 9311| firstMeaningfulPaint | [FirstMeaningfulPaint](#firstmeaningfulpaint12) | 是 | 绘制页面主要内容度量的详细信息。 | 9312 9313## LargestContentfulPaint<sup>12+</sup> 9314 9315提供网页绘制页面主要内容的详细信息。 9316 9317**系统能力：** SystemCapability.Web.Webview.Core 9318 9319| 名称 | 类型 | 必填 | 说明 | 9320| ------------------------- | ------ | ---- | ---------------------------------------- | 9321| navigationStartTime | number | 否 | 导航条加载时间，单位以微秒表示。 | 9322| largestImagePaintTime | number | 否 | 最大图片加载的时间，单位是以毫秒表示。 | 9323| largestTextPaintTime | number | 否 | 最大文本加载时间，单位是以毫秒表示。 | 9324| largestImageLoadStartTime | number | 否 | 最大图片开始加载时间，单位是以毫秒表示。 | 9325| largestImageLoadEndTime | number | 否 | 最大图片结束记载时间，单位是以毫秒表示。 | 9326| imageBPP | number | 否 | 最大图片像素位数。 | 9327 9328## OnLargestContentfulPaintCallback<sup>12+</sup> 9329 9330type OnLargestContentfulPaintCallback = (largestContentfulPaint: [LargestContentfulPaint](#largestcontentfulpaint12 9331)) => void 9332 9333网页绘制页面最大内容度量信息的回调。 9334 9335**系统能力：** SystemCapability.Web.Webview.Core 9336 9337**参数：** 9338 9339| 参数名 | 类型 | 必填 | 说明 | 9340| ------ | ------ | ---- | --------------------- | 9341| largestContentfulPaint | [LargestContentfulPaint](#largestcontentfulpaint12) | 是 | 网页绘制页面最大内容度量的详细信息。 | 9342 9343## IntelligentTrackingPreventionDetails<sup>12+</sup> 9344 9345提供智能防跟踪拦截的详细信息。 9346 9347**系统能力：** SystemCapability.Web.Webview.Core 9348 9349| 名称 | 类型 | 必填 | 说明 | 9350| ------------- | ------------------------------------| ----- | ------------ | 9351| host | string | 是 | 网站域名。 | 9352| trackerHost | string | 是 | 追踪者域名。 | 9353 9354## OnIntelligentTrackingPreventionCallback<sup>12+</sup> 9355 9356type OnIntelligentTrackingPreventionCallback = (details: IntelligentTrackingPreventionDetails) => void 9357 9358当跟踪者cookie被拦截时触发的回调。 9359 9360**系统能力：** SystemCapability.Web.Webview.Core 9361 9362**参数：** 9363 9364| 参数名 | 类型 | 必填 | 说明 | 9365| ------ | ------ | ---- | --------------------- | 9366| details | [IntelligentTrackingPreventionDetails](#intelligenttrackingpreventiondetails12) | 是 | 提供智能防跟踪拦截的详细信息。 | 9367 9368## OnOverrideUrlLoadingCallback<sup>12+</sup> 9369 9370type OnOverrideUrlLoadingCallback = (webResourceRequest: WebResourceRequest) => boolean 9371 9372onOverrideUrlLoading的回调。 9373 9374**系统能力：** SystemCapability.Web.Webview.Core 9375 9376**参数：** 9377 9378| 参数名 | 类型 | 必填 | 说明 | 9379| ------------------ | ------- | ---- | ------------- | 9380| webResourceRequest | [WebResourceRequest](#webresourcerequest) | 是 | url请求的相关信息。| 9381 9382**返回值：** 9383 9384| 类型 | 说明 | 9385| ------- | ------------------------ | 9386| boolean | 返回true表示阻止此次加载，否则允许此次加载。 | 9387 9388## RenderMode<sup>12+</sup>枚举说明 9389 9390定义Web组件的渲染方式，默认为异步渲染模式。 9391 9392建议使用异步渲染模式，异步渲染模式有更好的性能和更低的功耗。 9393 9394**系统能力：** SystemCapability.Web.Webview.Core 9395 9396| 名称 | 值 | 说明 | 9397| ----------------------------- | -- | ------------ | 9398| ASYNC_RENDER | 0 | Web组件异步渲染模式，ArkWeb组件作为图形surface节点，独立送显，Web组件的宽度最大规格不超过7,680 px（物理像素）。 | 9399| SYNC_RENDER | 1 | Web组件同步渲染模式，ArkWeb组件作为图形canvas节点，跟随系统组件一起送显，可以渲染更长的Web组件内容，Web组件的宽度最大规格不超过500,000 px（物理像素）。 | 9400 9401## NativeMediaPlayerConfig<sup>12+</sup> 9402 9403用于[开启应用接管网页媒体播放功能](#enablenativemediaplayer12)的配置信息。 9404 9405**系统能力：** SystemCapability.Web.Webview.Core 9406 9407| 名称 | 类型 | 必填 | 说明 | 9408|------|------|------|------| 9409| enable | boolean | 是 | 是否开启该功能。<br/> `true` : 开启 <br/> `false` : 关闭(默认值) | 9410| shouldOverlay | boolean | 是 | 开启该功能后， 应用接管网页视频的播放器画面是否覆盖网页内容。<br/> `true` : 是，改变视频图层的高度，使其覆盖网页内容 <br/> `false` : 否(默认值), 不覆盖，跟原视频图层高度一样，嵌入在网页中。 | 9411 9412## RenderProcessNotRespondingReason<sup>12+</sup> 9413 9414触发渲染进程无响应回调的原因。 9415 9416**系统能力：** SystemCapability.Web.Webview.Core 9417 9418| 名称 | 值 | 说明 | 9419| ----------------------------- | -- | ------------ | 9420| INPUT_TIMEOUT | 0 | 发送给渲染进程的input事件响应超时。 | 9421| NAVIGATION_COMMIT_TIMEOUT | 1 | 新的网页加载导航响应超时。 | 9422 9423## RenderProcessNotRespondingData<sup>12+</sup> 9424 9425提供渲染进程无响应的详细信息。 9426 9427**系统能力：** SystemCapability.Web.Webview.Core 9428 9429| 名称 | 类型 | 必填 | 说明 | 9430| ------------------------ | ------ | ---- | -------------------------------------- | 9431| jsStack | string | 是 | 网页的javaScript调用栈信息。 | 9432| pid | number | 是 | 网页的进程id。 | 9433| reason | [RenderProcessNotRespondingReason](#renderprocessnotrespondingreason12) | 是 | 触发渲染进程无响应回调的原因。 | 9434 9435## OnRenderProcessNotRespondingCallback<sup>12+</sup> 9436 9437type OnRenderProcessNotRespondingCallback = (data : RenderProcessNotRespondingData) => void 9438 9439渲染进程无响应时触发的回调。 9440 9441**系统能力：** SystemCapability.Web.Webview.Core 9442 9443**参数：** 9444 9445| 参数名 | 类型 | 必填 | 说明 | 9446| ------ | ------ | ---- | --------------------- | 9447| data | [RenderProcessNotRespondingData](#renderprocessnotrespondingdata12) | 是 | 渲染进程无响应的详细信息。 | 9448 9449## OnRenderProcessRespondingCallback<sup>12+</sup> 9450 9451type OnRenderProcessRespondingCallback = () => void 9452 9453渲染进程由无响应状态变回正常运行状态时触发该回调。 9454 9455**系统能力：** SystemCapability.Web.Webview.Core 9456 9457## ViewportFit<sup>12+</sup> 9458 9459网页meta中viewport-fit配置的视口类型。 9460 9461**系统能力：** SystemCapability.Web.Webview.Core 9462 9463| 名称 | 值 | 说明 | 9464| ----------------------------- | -- | ------------ | 9465| AUTO | 0 | 默认值，整个网页可见。 | 9466| CONTAINS | 1 | 初始布局视口和视觉视口为适应设备显示屏的最大矩形内。 | 9467| COVER | 2| 初始布局视口和视觉视口为设备物理屏幕的外接矩形内。 | 9468 9469## OnViewportFitChangedCallback<sup>12+</sup> 9470 9471type OnViewportFitChangedCallback = (viewportFit: ViewportFit) => void 9472 9473网页meta中viewport-fit配置项更改时触发的回调。 9474 9475**系统能力：** SystemCapability.Web.Webview.Core 9476 9477**参数：** 9478 9479| 参数名 | 类型 | 必填 | 说明 | 9480| ------ | ------ | ---- | --------------------- | 9481| viewportFit | [ViewportFit](#viewportfit12) | 是 | 网页meta中viewport-fit配置的视口类型。 | 9482 9483## ExpandedMenuItemOptions<sup>12+</sup> 9484 9485自定义菜单扩展项。 9486 9487**系统能力：** SystemCapability.Web.Webview.Core 9488 9489| 名称 | 类型 | 必填 | 说明 | 9490| ---------- | -----------------------------------------------------| ------ | ---------------- | 9491| content | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | 是 | 显示内容。 | 9492| startIcon | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | 否 | 显示图标。 | 9493| action | (selectedText: {plainText: string}) => void | 是 | 选中的文本信息。| 9494 9495## WebKeyboardAvoidMode<sup>12+</sup> 9496 9497软键盘避让的模式。 9498 9499**系统能力：** SystemCapability.Web.Webview.Core 9500 9501| 名称 | 值 | 说明 | 9502| ------------------ | -- | ------------ | 9503| RESIZE_VISUAL | 0 | 软键盘避让时，仅调整可视视口大小，不调整布局视口大小。 | 9504| RESIZE_CONTENT | 1 | 默认值，软键盘避让时，同时调整可视视口和布局视口的大小。 | 9505| OVERLAYS_CONTENT | 2 | 不调整任何视口大小，不会触发软键盘避让。 | 9506 9507## OnPageEndEvent<sup>12+</sup> 9508 9509定义网页加载结束时触发的函数。 9510 9511**系统能力：** SystemCapability.Web.Webview.Core 9512 9513| 名称 | 类型 | 必填 | 说明 | 9514| -------------- | ---- | ---- | ---------------------------------------- | 9515| url | string | 是 | 页面的URL地址。 | 9516 9517## OnPageBeginEvent<sup>12+</sup> 9518 9519定义网页加载开始时触发的函数。 9520 9521**系统能力：** SystemCapability.Web.Webview.Core 9522 9523| 名称 | 类型 | 必填 | 说明 | 9524| -------------- | ---- | ---- | ---------------------------------------- | 9525| url | string | 是 | 页面的URL地址。 | 9526 9527## OnProgressChangeEvent<sup>12+</sup> 9528 9529定义网页加载进度变化时触发该回调。 9530 9531**系统能力：** SystemCapability.Web.Webview.Core 9532 9533| 名称 | 类型 | 必填 | 说明 | 9534| -------------- | ---- | ---- | ---------------------------------------- | 9535| newProgress | number | 是 | 新的加载进度，取值范围为0到100的整数。 | 9536 9537## OnTitleReceiveEvent<sup>12+</sup> 9538 9539定义网页document标题更改时触发该回调。 9540 9541**系统能力：** SystemCapability.Web.Webview.Core 9542 9543| 名称 | 类型 | 必填 | 说明 | 9544| -------------- | ---- | ---- | ---------------------------------------- | 9545| title | string | 是 | document标题内容。 | 9546 9547## OnGeolocationShowEvent<sup>12+</sup> 9548 9549定义通知用户收到地理位置信息获取请求。 9550 9551**系统能力：** SystemCapability.Web.Webview.Core 9552 9553| 名称 | 类型 | 必填 | 说明 | 9554| -------------- | ---- | ---- | ---------------------------------------- | 9555| origin | string | 是 | 指定源的字符串索引。 | 9556| geolocation | [JsGeolocation](#jsgeolocation) | 是 | 通知Web组件用户操作行为。 | 9557 9558## OnAlertEvent<sup>12+</sup> 9559 9560定义网页触发alert()告警弹窗时触发回调。 9561 9562**系统能力：** SystemCapability.Web.Webview.Core 9563 9564| 名称 | 类型 | 必填 | 说明 | 9565| -------------- | ---- | ---- | ---------------------------------------- | 9566| url | string | 是 | 当前显示弹窗所在网页的URL。 | 9567| message | string | 是 | 弹窗中显示的信息。 | 9568| result | [JsResult](#jsresult) | 是 | 通知Web组件用户操作行为。 | 9569 9570## OnBeforeUnloadEvent<sup>12+</sup> 9571 9572定义刷新或关闭场景下，在即将离开当前页面时触发此回调。 9573 9574**系统能力：** SystemCapability.Web.Webview.Core 9575 9576| 名称 | 类型 | 必填 | 说明 | 9577| -------------- | ---- | ---- | ---------------------------------------- | 9578| url | string | 是 | 当前显示弹窗所在网页的URL。 | 9579| message | string | 是 | 弹窗中显示的信息。 | 9580| result | [JsResult](#jsresult) | 是 | 通知Web组件用户操作行为。 | 9581 9582## OnConfirmEvent<sup>12+</sup> 9583 9584定义网页调用confirm()告警时触发此回调。 9585 9586**系统能力：** SystemCapability.Web.Webview.Core 9587 9588| 名称 | 类型 | 必填 | 说明 | 9589| -------------- | ---- | ---- | ---------------------------------------- | 9590| url | string | 是 | 当前显示弹窗所在网页的URL。 | 9591| message | string | 是 | 弹窗中显示的信息。 | 9592| result | [JsResult](#jsresult) | 是 | 通知Web组件用户操作行为。 | 9593 9594## OnPromptEvent<sup>12+</sup> 9595 9596定义网页调用prompt()告警时触发此回调。 9597 9598**系统能力：** SystemCapability.Web.Webview.Core 9599 9600| 名称 | 类型 | 必填 | 说明 | 9601| -------------- | ---- | ---- | ---------------------------------------- | 9602| url | string | 是 | 当前显示弹窗所在网页的URL。 | 9603| message | string | 是 | 弹窗中显示的信息。 | 9604| value | string | 是 | 提示对话框的信息。 | 9605| result | [JsResult](#jsresult) | 是 | 通知Web组件用户操作行为。 | 9606 9607## OnConsoleEvent<sup>12+</sup> 9608 9609定义通知宿主应用JavaScript console消息。 9610 9611**系统能力：** SystemCapability.Web.Webview.Core 9612 9613| 名称 | 类型 | 必填 | 说明 | 9614| -------------- | ---- | ---- | ---------------------------------------- | 9615| message | [ConsoleMessage](#consolemessage) | 是 | 触发的控制台信息。 | 9616 9617## OnErrorReceiveEvent<sup>12+</sup> 9618 9619定义网页加载遇到错误时触发该回调。 9620 9621**系统能力：** SystemCapability.Web.Webview.Core 9622 9623| 名称 | 类型 | 必填 | 说明 | 9624| -------------- | ---- | ---- | ---------------------------------------- | 9625| request | [WebResourceRequest](#webresourcerequest) | 是 | 网页请求的封装信息。 | 9626| error | [WebResourceError](#webresourceerror) | 是 | 网页加载资源错误的封装信息 。 | 9627 9628## OnHttpErrorReceiveEvent<sup>12+</sup> 9629 9630定义网页收到加载资源加载HTTP错误时触发。 9631 9632**系统能力：** SystemCapability.Web.Webview.Core 9633 9634| 名称 | 类型 | 必填 | 说明 | 9635| -------------- | ---- | ---- | ---------------------------------------- | 9636| request | [WebResourceRequest](#webresourcerequest) | 是 | 网页请求的封装信息。 | 9637| response | [WebResourceResponse](#webresourceresponse) | 是 | 资源响应的封装信息。 | 9638 9639## OnDownloadStartEvent<sup>12+</sup> 9640 9641定义通知主应用开始下载一个文件。 9642 9643**系统能力：** SystemCapability.Web.Webview.Core 9644 9645| 名称 | 类型 | 必填 | 说明 | 9646| -------------- | ---- | ---- | ---------------------------------------- | 9647| url | string | 是 | 文件下载的URL。 | 9648| userAgent | string | 是 | 用于下载的用户代理。 | 9649| contentDisposition | string | 是 | 服务器返回的 Content-Disposition响应头，可能为空。 | 9650| mimetype | string | 是 | 服务器返回内容媒体类型（MIME）信息。 | 9651| contentLength | number | 是 | 服务器返回文件的长度。 | 9652 9653## OnRefreshAccessedHistoryEvent<sup>12+</sup> 9654 9655定义网页刷新访问历史记录时触发。 9656 9657**系统能力：** SystemCapability.Web.Webview.Core 9658 9659| 名称 | 类型 | 必填 | 说明 | 9660| -------------- | ---- | ---- | ---------------------------------------- | 9661| url | string | 是 | 访问的url。 | 9662| isRefreshed | boolean | 是 | true表示该页面是被重新加载的（调用[refresh<sup>9+</sup>](js-apis-webview.md#refresh)接口），false表示该页面是新加载的。 | 9663 9664## OnRenderExitedEvent<sup>12+</sup> 9665 9666定义渲染过程退出时触发。 9667 9668**系统能力：** SystemCapability.Web.Webview.Core 9669 9670| 名称 | 类型 | 必填 | 说明 | 9671| -------------- | ---- | ---- | ---------------------------------------- | 9672| renderExitReason | [RenderExitReason](#renderexitreason9枚举说明) | 是 | 渲染进程异常退出的具体原因。 | 9673 9674## OnShowFileSelectorEvent<sup>12+</sup> 9675 9676定义文件选择器结果。 9677 9678**系统能力：** SystemCapability.Web.Webview.Core 9679 9680| 名称 | 类型 | 必填 | 说明 | 9681| -------------- | ---- | ---- | ---------------------------------------- | 9682| result | [FileSelectorResult](#fileselectorresult9) | 是 | 用于通知Web组件文件选择的结果。 | 9683| fileSelector | [FileSelectorParam](#fileselectorparam9) | 是 | 文件选择器的相关信息。 | 9684 9685## OnResourceLoadEvent<sup>12+</sup> 9686 9687定义加载url时触发。 9688 9689**系统能力：** SystemCapability.Web.Webview.Core 9690 9691| 名称 | 类型 | 必填 | 说明 | 9692| -------------- | ---- | ---- | ---------------------------------------- | 9693| url | string | 是 | 所加载的资源文件url信息。 | 9694 9695## OnScaleChangeEvent<sup>12+</sup> 9696 9697定义当前页面显示比例的变化时触发。 9698 9699**系统能力：** SystemCapability.Web.Webview.Core 9700 9701| 名称 | 类型 | 必填 | 说明 | 9702| -------------- | ---- | ---- | ---------------------------------------- | 9703| oldScale | number | 是 | 变化前的显示比例百分比。 | 9704| newScale | number | 是 | 变化后的显示比例百分比。 | 9705 9706## OnHttpAuthRequestEvent<sup>12+</sup> 9707 9708定义通知收到http auth认证请求。 9709 9710**系统能力：** SystemCapability.Web.Webview.Core 9711 9712| 名称 | 类型 | 必填 | 说明 | 9713| -------------- | ---- | ---- | ---------------------------------------- | 9714| handler | [HttpAuthHandler](#httpauthhandler9) | 是 | 通知Web组件用户操作行为。 | 9715| host | string | 是 | HTTP身份验证凭据应用的主机。 | 9716| realm | string | 是 | HTTP身份验证凭据应用的域。 | 9717 9718## OnInterceptRequestEvent<sup>12+</sup> 9719 9720定义当Web组件加载url之前触发。 9721 9722**系统能力：** SystemCapability.Web.Webview.Core 9723 9724| 名称 | 类型 | 必填 | 说明 | 9725| -------------- | ---- | ---- | ---------------------------------------- | 9726| request | [WebResourceRequest](#webresourcerequest) | 是 | url请求的相关信息。 | 9727 9728## OnPermissionRequestEvent<sup>12+</sup> 9729 9730定义通知收到获取权限请求。 9731 9732**系统能力：** SystemCapability.Web.Webview.Core 9733 9734| 名称 | 类型 | 必填 | 说明 | 9735| -------------- | ---- | ---- | ---------------------------------------- | 9736| request | [PermissionRequest](#permissionrequest9) | 是 | 通知Web组件用户操作行为。 | 9737 9738## OnScreenCaptureRequestEvent<sup>12+</sup> 9739 9740定义通知收到屏幕捕获请求。 9741 9742**系统能力：** SystemCapability.Web.Webview.Core 9743 9744| 名称 | 类型 | 必填 | 说明 | 9745| -------------- | ---- | ---- | ---------------------------------------- | 9746| handler | [ScreenCaptureHandler](#screencapturehandler10) | 是 | 通知Web组件用户操作行为。 | 9747 9748## OnContextMenuShowEvent<sup>12+</sup> 9749 9750定义调用时触发的回调，以允许自定义显示上下文菜单。 9751 9752**系统能力：** SystemCapability.Web.Webview.Core 9753 9754| 名称 | 类型 | 必填 | 说明 | 9755| -------------- | ---- | ---- | ---------------------------------------- | 9756| param | [WebContextMenuParam](#webcontextmenuparam9) | 是 | 菜单相关参数。 | 9757| result | [WebContextMenuResult](#webcontextmenuresult9) | 是 | 菜单相应事件传入内核。 | 9758 9759## OnSearchResultReceiveEvent<sup>12+</sup> 9760 9761定义通知调用方网页页内查找的结果。 9762 9763**系统能力：** SystemCapability.Web.Webview.Core 9764 9765| 名称 | 类型 | 必填 | 说明 | 9766| -------------- | ---- | ---- | ---------------------------------------- | 9767| activeMatchOrdinal | number | 是 | 当前匹配的查找项的序号（从0开始）。 | 9768| numberOfMatches | number | 是 | 所有匹配到的关键词的个数。 | 9769| isDoneCounting | boolean | 是 | 当次页内查找操作是否结束。该方法可能会回调多次，直到isDoneCounting为true为止。 | 9770 9771## OnScrollEvent<sup>12+</sup> 9772 9773定义滚动条滑动到指定位置时触发。 9774 9775**系统能力：** SystemCapability.Web.Webview.Core 9776 9777| 名称 | 类型 | 必填 | 说明 | 9778| -------------- | ---- | ---- | ---------------------------------------- | 9779| xOffset | number | 是 | 以网页最左端为基准，水平滚动条滚动所在位置。 | 9780| yOffset | number | 是 | 以网页最上端为基准，竖直滚动条滚动所在位置。 | 9781 9782## OnSslErrorEventReceiveEvent<sup>12+</sup> 9783 9784定义网页收到SSL错误时触发。 9785 9786**系统能力：** SystemCapability.Web.Webview.Core 9787 9788| 名称 | 类型 | 必填 | 说明 | 9789| -------------- | ---- | ---- | ---------------------------------------- | 9790| handler | [SslErrorHandler](#sslerrorhandler9) | 是 | 通知Web组件用户操作行为。 | 9791| error | [SslError](#sslerror9枚举说明) | 是 | 错误码。 | 9792 9793## OnClientAuthenticationEvent<sup>12+</sup> 9794 9795定义当需要用户提供SSL客户端证书时触发回调。 9796 9797**系统能力：** SystemCapability.Web.Webview.Core 9798 9799| 名称 | 类型 | 必填 | 说明 | 9800| -------------- | ---- | ---- | ---------------------------------------- | 9801| handler | [ClientAuthenticationHandler](#clientauthenticationhandler9) | 是 | 通知Web组件用户操作行为。 | 9802| host | string | 是 | 请求证书服务器的主机名。 | 9803| port | number | 是 | 请求证书服务器的端口号。 | 9804| keyTypes | Array<string\> | 是 | 可接受的非对称秘钥类型。 | 9805| issuers | Array<string\> | 是 | 与私钥匹配的证书可接受颁发者。 | 9806 9807## OnWindowNewEvent<sup>12+</sup> 9808 9809定义网页要求用户创建窗口时触发的回调。 9810 9811**系统能力：** SystemCapability.Web.Webview.Core 9812 9813| 名称 | 类型 | 必填 | 说明 | 9814| -------------- | ---- | ---- | ---------------------------------------- | 9815| isAlert | boolean | 是 | true代表请求创建对话框，false代表新标签页。 | 9816| isUserTrigger | boolean | 是 | true代表用户触发，false代表非用户触发。 | 9817| targetUrl | string | 是 | 目标url。 | 9818| handler | [ControllerHandler](#controllerhandler9) | 是 | 用于设置新建窗口的WebviewController实例。 | 9819 9820## OnTouchIconUrlReceivedEvent<sup>12+</sup> 9821 9822定义设置接收到apple-touch-icon url地址时的回调函数。 9823 9824**系统能力：** SystemCapability.Web.Webview.Core 9825 9826| 名称 | 类型 | 必填 | 说明 | 9827| -------------- | ---- | ---- | ---------------------------------------- | 9828| url | string | 是 | 接收到的apple-touch-icon url地址。 | 9829| precomposed | boolean | 是 | 对应apple-touch-icon是否为预合成。 | 9830 9831## OnFaviconReceivedEvent<sup>12+</sup> 9832 9833定义应用为当前页面接收到新的favicon时的回调函数。 9834 9835**系统能力：** SystemCapability.Web.Webview.Core 9836 9837| 名称 | 类型 | 必填 | 说明 | 9838| -------------- | ---- | ---- | ---------------------------------------- | 9839| favicon | [PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | 是 | 接收到的favicon图标的PixelMap对象。 | 9840 9841## OnPageVisibleEvent<sup>12+</sup> 9842 9843定义旧页面不再呈现，新页面即将可见时触发的回调函数。 9844 9845**系统能力：** SystemCapability.Web.Webview.Core 9846 9847| 名称 | 类型 | 必填 | 说明 | 9848| -------------- | ---- | ---- | ---------------------------------------- | 9849| url | string | 是 | 旧页面不再呈现，新页面即将可见时新页面的url地址。 | 9850 9851## OnDataResubmittedEvent<sup>12+</sup> 9852 9853定义网页表单可以重新提交时触发的回调函数。 9854 9855**系统能力：** SystemCapability.Web.Webview.Core 9856 9857| 名称 | 类型 | 必填 | 说明 | 9858| -------------- | ---- | ---- | ---------------------------------------- | 9859| handler | [DataResubmissionHandler](#dataresubmissionhandler9) | 是 | 表单数据重新提交句柄。 | 9860 9861## OnAudioStateChangedEvent<sup>12+</sup> 9862 9863定义网页上的音频播放状态发生改变时的回调函数。 9864 9865**系统能力：** SystemCapability.Web.Webview.Core 9866 9867| 名称 | 类型 | 必填 | 说明 | 9868| -------------- | ---- | ---- | ---------------------------------------- | 9869| playing | boolean | 是 | 当前页面的音频播放状态，true表示正在播放，false表示未播放。 | 9870 9871## OnFirstContentfulPaintEvent<sup>12+</sup> 9872 9873定义网页首次内容绘制回调函数。 9874 9875**系统能力：** SystemCapability.Web.Webview.Core 9876 9877| 名称 | 类型 | 必填 | 说明 | 9878| -------------- | ---- | ---- | ---------------------------------------- | 9879| navigationStartTick | number | 是 | navigation开始的时间，单位以微秒表示。 | 9880| firstContentfulPaintMs | number | 是 | 从navigation开始第一次绘制内容的时间，单位是以毫秒表示。 | 9881 9882## OnLoadInterceptEvent<sup>12+</sup> 9883 9884定义截获资源加载时触发的回调。 9885 9886**系统能力：** SystemCapability.Web.Webview.Core 9887 9888| 名称 | 类型 | 必填 | 说明 | 9889| -------------- | ---- | ---- | ---------------------------------------- | 9890| data | [WebResourceRequest](#webresourcerequest) | 是 | url请求的相关信息。 | 9891 9892## OnOverScrollEvent<sup>12+</sup> 9893 9894定义网页过度滚动时触发的回调。 9895 9896**系统能力：** SystemCapability.Web.Webview.Core 9897 9898| 名称 | 类型 | 必填 | 说明 | 9899| -------------- | ---- | ---- | ---------------------------------------- | 9900| xOffset | number | 是 | 以网页最左端为基准，水平过度滚动的偏移量。 | 9901| yOffset | number | 是 | 以网页最上端为基准，竖直过度滚动的偏移量。 | 9902 9903## JavaScriptProxy<sup>12+</sup> 9904 9905定义要注入的JavaScript对象。 9906 9907**系统能力：** SystemCapability.Web.Webview.Core 9908 9909| 名称 | 类型 | 必填 | 说明 | 9910| -------------- | ---- | ---- | ---------------------------------------- | 9911| object | object | 是 | 参与注册的对象。只能声明方法，不能声明属性。 | 9912| name | string | 是 | 注册对象的名称，与window中调用的对象名一致。 | 9913| methodList | Array\<string\> | 是 | 参与注册的应用侧JavaScript对象的同步方法。 | 9914| controller | [WebController](#webcontroller) \| [WebviewController<sup>9+</sup>](#webviewcontroller9) | 是 | - | 控制器。从API Version 9开始，WebController不再维护，建议使用WebviewController替代。 | 9915| asyncMethodList<sup>12+</sup> | Array\<string\> | 否 | 参与注册的应用侧JavaScript对象的异步方法。异步方法无法获取返回值。 | 9916| permission<sup>12+</sup> | string | 否 | json字符串，默认为空，通过该字符串配置JSBridge的权限管控，可以定义object、method一级的url白名单。<br>示例请参考[前端页面调用应用侧函数](../../web/web-in-page-app-function-invoking.md)。 | 9917 9918## AdsBlockedDetails<sup>12+</sup> 9919 9920发生广告拦截时，广告资源信息。 9921 9922**系统能力：** SystemCapability.Web.Webview.Core 9923 9924| 名称 | 类型 | 必填 | 说明 | 9925| ------- | -------------------------------------------------------------------------------- | ---- | ------------------------- | 9926| url | string | 是 | 发生广告过滤的页面url。 | 9927| adsBlocked | Array\<string\> | 是 | 被过滤的资源的url或dompath标识，被过滤的多个对象url相同则可能出现重复元素。 | 9928 9929## OnAdsBlockedCallback<sup>12+</sup> 9930 9931type OnAdsBlockedCallback = (details: AdsBlockedDetails) => void 9932 9933当页面发生广告过滤时触发此回调。 9934 9935**系统能力：** SystemCapability.Web.Webview.Core 9936 9937**参数：** 9938 9939| 参数名 | 类型 | 必填 | 说明 | 9940| -------------------- | ----------------------------------------------- | ---- | -------------------------------- | 9941| details | [AdsBlockedDetails](#adsblockeddetails12) | 是 | 发生广告拦截时，广告资源信息。 | 9942 9943## NativeEmbedVisibilityInfo<sup>12+</sup> 9944 9945提供同层标签的可见性信息。 9946 9947**系统能力：** SystemCapability.Web.Webview.Core 9948 9949| 名称 | 类型 | 必填 | 说明 | 9950| ------------- | ------------------------------------| ----- | ------------------ | 9951| visibility | boolean | 是 | 可见性。 | 9952| embedId | string | 是 | 同层渲染标签的唯一id。 | 9953 9954## OnNativeEmbedVisibilityChangeCallback<sup>12+</sup> 9955 9956type OnNativeEmbedVisibilityChangeCallback = (nativeEmbedVisibilityInfo: NativeEmbedVisibilityInfo) => void 9957 9958当同层标签可见性变化时触发该回调。 9959 9960**系统能力：** SystemCapability.Web.Webview.Core 9961 9962**参数：** 9963 9964| 参数名 | 类型 | 必填 | 说明 | 9965| ------ | ------ | ---- | --------------------- | 9966| nativeEmbedVisibilityInfo | [NativeEmbedVisibilityInfo](#nativeembedvisibilityinfo12) | 是 | 提供同层标签的可见性信息。 | 9967 9968## WebElementType<sup>13+</sup>枚举说明 9969 9970网页元素信息。 9971 9972**系统能力：** SystemCapability.Web.Webview.Core 9973 9974**参数：** 9975 9976| 名称 | 值 | 说明 | 9977| --------- | -- | ----------------- | 9978| IMAGE | 1 | 网页元素为图像类型。 | 9979 9980## WebResponseType<sup>13+</sup>枚举说明 9981 9982菜单的响应类型。 9983 9984**系统能力：** SystemCapability.Web.Webview.Core 9985 9986**参数：** 9987 9988| 名称 | 值 | 说明 | 9989| -------------- | -- | ------------------ | 9990| LONG_PRESS | 1 | 通过长按触发菜单弹出。 | 9991 9992## SelectionMenuOptionsExt<sup>13+</sup> 9993 9994自定义菜单扩展项。 9995 9996**系统能力：** SystemCapability.Web.Webview.Core 9997 9998| 名称 | 类型 | 必填 | 说明 | 9999| ---------- | -----------------------------------------------------| ------ | ---------------- | 10000| onAppear | Callback\<void\> | 否 | 自定义选择菜单弹出时回调。 | 10001| onDisappear | Callback\<void\> | 否 | 自定义选择菜单关闭时回调。 | 10002| preview | [CustomBuilder](../apis-arkui/arkui-ts/ts-types.md#custombuilder8) | 否 | 自定义选择菜单的预览内容样式, 未配置时无预览内容。| 10003| menuType | [MenuType](../apis-arkui/arkui-ts/ts-text-common.md#menutype13枚举说明) | 否 | 自定义选择菜单类型。<br>默认值：MenuType.SELECTION_MENU | 10004 10005## BlurOnKeyboardHideMode<sup>14+</sup>枚举说明 10006 10007设置手动收起软键盘时Web元素是否失焦。 10008 10009**系统能力：** SystemCapability.Web.Webview.Core 10010 10011**参数：** 10012 10013| 名称 | 值 | 说明 | 10014| ------ | -- | ----------- | 10015| SILENT | 0 | 软键盘收起时web组件失焦功能关闭。 | 10016| BLUR | 1 | 软键盘收起时web组件失焦功能开启。 |
