1# Attributes 2 3Supported common attributes: [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#clip12), [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#id), [gridOffset](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md#attributes), [gridSpan](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md#attributes), [useSizeType](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md#attributes), [height](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#height), [touchable](../apis-arkui/arkui-ts/ts-universal-attributes-click.md#attributes), [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), and [position](../apis-arkui/arkui-ts/ts-universal-attributes-location.md#position). 4 5> **NOTE** 6> 7> - The initial APIs of this component are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> - You can preview how this component looks on a real device, but not in DevEco Studio Previewer. 10 11## domStorageAccess 12 13domStorageAccess(domStorageAccess: boolean) 14 15Sets whether to enable the DOM Storage API. By default, this feature is disabled. 16 17**System capability**: SystemCapability.Web.Webview.Core 18 19**Parameters** 20 21| Name | Type | Mandatory | Description | 22| ---------------- | ------- | ---- | ------------------------------------ | 23| domStorageAccess | boolean | Yes | Whether to enable the DOM Storage API.<br>The value **true** means to the DOM Storage API, and **false** means the opposite.<br>The default value is **false**.| 24 25> **NOTE** 26> 27> - A web page can be loaded only when its DOM Storage API is set to **true**. 28 29**Example** 30 31 ```ts 32 // xxx.ets 33 import { webview } from '@kit.ArkWeb'; 34 35 @Entry 36 @Component 37 struct WebComponent { 38 controller: webview.WebviewController = new webview.WebviewController(); 39 40 build() { 41 Column() { 42 Web({ src: 'www.example.com', controller: this.controller }) 43 .domStorageAccess(true) 44 } 45 } 46 } 47 ``` 48 49## fileAccess 50 51fileAccess(fileAccess: boolean) 52 53Sets whether to enable access to the file system in the application. This setting does not affect the access to the files specified through [$rawfile(filepath/filename)](../../quick-start/resource-categories-and-access.md). 54 55**System capability**: SystemCapability.Web.Webview.Core 56 57**Parameters** 58 59| Name | Type | Mandatory | Description | 60| ---------- | ------- | ---- | ---------------------- | 61| fileAccess | boolean | Yes | Whether to enable access to the file system in the application.<br>The value **true** means to enable access to the file system in the application, and **false** means the opposite.<br>For API versions 11 and earlier, the default value is **true**.<br>Since API version 12, the default value is **false**. When this parameter is set to **false**, only file protocol resources in the read-only resource directory **/data/storage/el1/bundle/entry/resources/resfile** can be accessed.| 62 63**Example** 64 65 ```ts 66 // xxx.ets 67 import { webview } from '@kit.ArkWeb'; 68 69 @Entry 70 @Component 71 struct WebComponent { 72 controller: webview.WebviewController = new webview.WebviewController(); 73 74 build() { 75 Column() { 76 Web({ src: 'www.example.com', controller: this.controller }) 77 .fileAccess(true) 78 } 79 } 80 } 81 ``` 82 83## imageAccess 84 85imageAccess(imageAccess: boolean) 86 87Sets whether to enable automatic image loading. 88 89**System capability**: SystemCapability.Web.Webview.Core 90 91**Parameters** 92 93| Name | Type | Mandatory | Description | 94| ----------- | ------- | ---- | --------------- | 95| imageAccess | boolean | Yes | Whether to enable automatic image loading.<br>The value **true** means to enable automatic image loading, and **false** means the opposite.<br>Default value: **true**| 96 97**Example** 98 ```ts 99 // xxx.ets 100 import { webview } from '@kit.ArkWeb'; 101 102 @Entry 103 @Component 104 struct WebComponent { 105 controller: webview.WebviewController = new webview.WebviewController(); 106 107 build() { 108 Column() { 109 Web({ src: 'www.example.com', controller: this.controller }) 110 .imageAccess(true) 111 } 112 } 113 } 114 ``` 115 116## javaScriptProxy 117 118javaScriptProxy(javaScriptProxy: JavaScriptProxy) 119 120Registers an ArkTS object in **javaScriptProxy** with the **Web** component. The object is registered with all frameworks of the web page, including all iframes, using the name specified in **JavaScriptProxy**. This enables JavaScript to invoke methods of the ArkTS object in **javaScriptProxy**. 121 122> **NOTE** 123> 124> The **javaScriptProxy** API must be used in pair with the **deleteJavaScriptRegister** API to prevent memory leaks. 125> All parameters of the **javaScriptProxy** object cannot be updated. 126> When registering a **javaScriptProxy** object, select at least one of the synchronous and asynchronous method lists, or both. 127> Only one object can be registered through this API. To register multiple objects, use [registerJavaScriptProxy<sup>9+</sup>](./arkts-apis-webview-WebviewController.md#registerjavascriptproxy). 128 129**System capability**: SystemCapability.Web.Webview.Core 130 131**Parameters** 132 133| Name | Type | Mandatory | Description | 134| ---------- | ---------------------------------------- | ---- |---------------------------------------- | 135| javaScriptProxy | [JavaScriptProxy](./arkts-basic-components-web-i.md#javascriptproxy12) | Yes | Object to be registered. Methods can be declared, but attributes cannot. | 136 137**Example** 138 139 ```ts 140 // xxx.ets 141 import { webview } from '@kit.ArkWeb'; 142 143 class TestObj { 144 constructor() { 145 } 146 147 test(data1: string, data2: string, data3: string): string { 148 console.log("data1:" + data1); 149 console.log("data2:" + data2); 150 console.log("data3:" + data3); 151 return "AceString"; 152 } 153 154 asyncTest(data: string): void { 155 console.log("async data:" + data); 156 } 157 158 toString(): void { 159 console.log('toString' + "interface instead."); 160 } 161 } 162 163 @Entry 164 @Component 165 struct WebComponent { 166 controller: webview.WebviewController = new webview.WebviewController(); 167 testObj = new TestObj(); 168 build() { 169 Column() { 170 Button('deleteJavaScriptRegister') 171 .onClick(() => { 172 try { 173 this.controller.deleteJavaScriptRegister("objName"); 174 } catch (error) { 175 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 176 } 177 }) 178 Web({ src: 'www.example.com', controller: this.controller }) 179 .javaScriptAccess(true) 180 .javaScriptProxy({ 181 object: this.testObj, 182 name: "objName", 183 methodList: ["test", "toString"], 184 asyncMethodList: ["asyncTest"], 185 controller: this.controller, 186 }) 187 } 188 } 189 } 190 ``` 191 192## javaScriptAccess 193 194javaScriptAccess(javaScriptAccess: boolean) 195 196Sets whether JavaScript scripts can be executed. 197 198**System capability**: SystemCapability.Web.Webview.Core 199 200**Parameters** 201 202| Name | Type | Mandatory | Description | 203| ---------------- | ------- | ---- | ------------------- | 204| javaScriptAccess | boolean | Yes | Whether JavaScript scripts can be executed.<br>The value **true** indicates that JavaScript scripts can be executed, and **false** indicates the opposite.<br>Default value: **true**| 205 206**Example** 207 208 ```ts 209 // xxx.ets 210 import { webview } from '@kit.ArkWeb'; 211 212 @Entry 213 @Component 214 struct WebComponent { 215 controller: webview.WebviewController = new webview.WebviewController(); 216 build() { 217 Column() { 218 Web({ src: 'www.example.com', controller: this.controller }) 219 .javaScriptAccess(true) 220 } 221 } 222 } 223 ``` 224 225## overScrollMode<sup>11+</sup> 226 227overScrollMode(mode: OverScrollMode) 228 229Sets whether to enable overscroll mode. When overscroll mode is enabled and the boundary of the web page is reached, the **Web** component plays a bounce effect animation and return to the page. The internal page on the root page does not trigger bounce. 230 231**System capability**: SystemCapability.Web.Webview.Core 232 233**Parameters** 234 235| Name | Type | Mandatory | Description | 236| ---- | --------------------------------------- | ---- | ------------------ | 237| mode | [OverScrollMode](./arkts-basic-components-web-e.md#overscrollmode11) | Yes | Whether to enable the overscroll mode.<br>The default value is **OverScrollMode.NEVER**, meaning to disable overscroll mode.| 238 239**Example** 240 241 ```ts 242 // xxx.ets 243 import { webview } from '@kit.ArkWeb'; 244 245 @Entry 246 @Component 247 struct WebComponent { 248 controller: webview.WebviewController = new webview.WebviewController(); 249 @State mode: OverScrollMode = OverScrollMode.ALWAYS; 250 build() { 251 Column() { 252 Web({ src: 'www.example.com', controller: this.controller }) 253 .overScrollMode(this.mode) 254 } 255 } 256 } 257 ``` 258 259## mixedMode 260 261mixedMode(mixedMode: MixedMode) 262 263Sets whether a secure source can load resources from a non-secure source. The default value is **MixedMode.None**, indicating that the secure origin cannot load resources from an insecure origin. 264 265**System capability**: SystemCapability.Web.Webview.Core 266 267**Parameters** 268 269| Name | Type | Mandatory | Description | 270| --------- | --------------------------- | ---- | --------- | 271| mixedMode | [MixedMode](./arkts-basic-components-web-e.md#mixedmode) | Yes | Mixed content to load.<br>The default value is **MixedMode.None**, indicating that the secure origin cannot load resources from an insecure origin.| 272 273**Example** 274 275 ```ts 276 // xxx.ets 277 import { webview } from '@kit.ArkWeb'; 278 279 @Entry 280 @Component 281 struct WebComponent { 282 controller: webview.WebviewController = new webview.WebviewController(); 283 @State mode: MixedMode = MixedMode.All; 284 build() { 285 Column() { 286 Web({ src: 'www.example.com', controller: this.controller }) 287 .mixedMode(this.mode) 288 } 289 } 290 } 291 ``` 292 293## onlineImageAccess 294 295onlineImageAccess(onlineImageAccess: boolean) 296 297Sets whether to enable access to online images through HTTP and HTTPS. 298 299**System capability**: SystemCapability.Web.Webview.Core 300 301**Parameters** 302 303| Name | Type | Mandatory | Description | 304| ----------------- | ------- | ---- | ---------------- | 305| onlineImageAccess | boolean | Yes | Whether to enable access to online images through HTTP and HTTPS.<br>The value **true** means to enable access to online images through HTTP and HTTPS, and **false** means the opposite.<br>Default value: **true**| 306 307**Example** 308 309 ```ts 310 // xxx.ets 311 import { webview } from '@kit.ArkWeb'; 312 313 @Entry 314 @Component 315 struct WebComponent { 316 controller: webview.WebviewController = new webview.WebviewController(); 317 318 build() { 319 Column() { 320 Web({ src: 'www.example.com', controller: this.controller }) 321 .onlineImageAccess(true) 322 } 323 } 324 } 325 ``` 326 327## zoomAccess 328 329zoomAccess(zoomAccess: boolean) 330 331Sets whether to enable zoom gestures. 332 333**System capability**: SystemCapability.Web.Webview.Core 334 335**Parameters** 336 337| Name | Type | Mandatory | Description | 338| ---------- | ------- | ---- | ------------- | 339| zoomAccess | boolean | Yes | Whether to enable zoom gestures.<br>The value **true** means to enable zoom gestures, and **false** means the opposite.<br>Default value: **true**| 340 341**Example** 342 343 ```ts 344 // xxx.ets 345 import { webview } from '@kit.ArkWeb'; 346 347 @Entry 348 @Component 349 struct WebComponent { 350 controller: webview.WebviewController = new webview.WebviewController(); 351 352 build() { 353 Column() { 354 Web({ src: 'www.example.com', controller: this.controller }) 355 .zoomAccess(true) 356 } 357 } 358 } 359 ``` 360 361## overviewModeAccess 362 363overviewModeAccess(overviewModeAccess: boolean) 364 365Sets whether to load web pages by using the overview mode. That is, zoom out the content to fit the screen width. Currently, only mobile devices are supported. 366 367**System capability**: SystemCapability.Web.Webview.Core 368 369**Parameters** 370 371| Name | Type | Mandatory | Description | 372| ------------------ | ------- | ---- | --------------- | 373| overviewModeAccess | boolean | Yes | Whether to load web pages by using the overview mode.<br>The value **true** means to load web pages by using the overview mode, and **false** means the opposite.<br>Default value: **true**| 374 375**Example** 376 377 ```ts 378 // xxx.ets 379 import { webview } from '@kit.ArkWeb'; 380 381 @Entry 382 @Component 383 struct WebComponent { 384 controller: webview.WebviewController = new webview.WebviewController(); 385 386 build() { 387 Column() { 388 Web({ src: 'www.example.com', controller: this.controller }) 389 .overviewModeAccess(true) 390 } 391 } 392 } 393 ``` 394 395## databaseAccess 396 397databaseAccess(databaseAccess: boolean) 398 399Sets whether to enable database access. 400 401**System capability**: SystemCapability.Web.Webview.Core 402 403**Parameters** 404 405| Name | Type | Mandatory | Description | 406| -------------- | ------- | ---- | ----------------- | 407| databaseAccess | boolean | Yes | Whether to enable database access.<br>The value **true** means to enable database access, and the value **false** means the opposite.<br>The default value is **false**.| 408 409**Example** 410 411 ```ts 412 // xxx.ets 413 import { webview } from '@kit.ArkWeb'; 414 415 @Entry 416 @Component 417 struct WebComponent { 418 controller: webview.WebviewController = new webview.WebviewController(); 419 420 build() { 421 Column() { 422 Web({ src: 'www.example.com', controller: this.controller }) 423 .databaseAccess(true) 424 } 425 } 426 } 427 ``` 428 429## geolocationAccess 430 431geolocationAccess(geolocationAccess: boolean) 432 433Sets whether to enable geolocation access. For details, see [Managing Location Permissions](../../web/web-geolocation-permission.md). 434 435**System capability**: SystemCapability.Web.Webview.Core 436 437**Parameters** 438 439| Name | Type | Mandatory | Description | 440| ----------------- | ------- | ---- | --------------- | 441| geolocationAccess | boolean | Yes | Whether to enable geolocation access.<br>The value **true** means to enable geolocation access, and **false** means the opposite.<br>Default value: **true**| 442 443**Example** 444 445 ```ts 446 // xxx.ets 447 import { webview } from '@kit.ArkWeb'; 448 449 @Entry 450 @Component 451 struct WebComponent { 452 controller: webview.WebviewController = new webview.WebviewController(); 453 454 build() { 455 Column() { 456 Web({ src: 'www.example.com', controller: this.controller }) 457 .geolocationAccess(true) 458 } 459 } 460 } 461 ``` 462 463## mediaPlayGestureAccess<sup>9+</sup> 464 465mediaPlayGestureAccess(access: boolean) 466 467Sets whether video playback must be started by user gestures. This API is not applicable to muted videos. 468 469**System capability**: SystemCapability.Web.Webview.Core 470 471**Parameters** 472 473| Name | Type | Mandatory | Description | 474| ------ | ------- | ---- | ------------------- | 475| access | boolean | Yes | Whether video playback must be started by user gestures.<br>The value **true** indicates that video playback must be started by user gestures, and **false** indicates the opposite.<br>Default value: **true**| 476 477**Example** 478 479 ```ts 480 // xxx.ets 481 import { webview } from '@kit.ArkWeb'; 482 483 @Entry 484 @Component 485 struct WebComponent { 486 controller: webview.WebviewController = new webview.WebviewController(); 487 @State access: boolean = true; 488 489 build() { 490 Column() { 491 Web({ src: $rawfile('index.html'), controller: this.controller }) 492 .mediaPlayGestureAccess(this.access) 493 } 494 } 495 } 496 ``` 497 498HTML file to be loaded: 499 ```html 500 <!--index.html--> 501 <!DOCTYPE html> 502 <html> 503 <head> 504 <title>Video Playback Page</title> 505 </head> 506 <body> 507 <h1>Video Playback</h1> 508 <video id="testVideo" controls autoplay> 509 // Configure the autoplay attribute in the video tag to allow automatic video playback. 510 // Save an MP4 media file in the rawfile directory of resources and name it example.mp4. 511 <source src="example.mp4" type="video/mp4"> 512 </video> 513 </body> 514 </html> 515 ``` 516 517## multiWindowAccess<sup>9+</sup> 518 519multiWindowAccess(multiWindow: boolean) 520 521Sets whether to enable the multi-window permission. 522Enabling the multi-window permission requires implementation of the **onWindowNew** event. For the sample code, see [onWindowNew](./arkts-basic-components-web-events.md#onwindownew9). 523 524**System capability**: SystemCapability.Web.Webview.Core 525 526**Parameters** 527 528| Name | Type | Mandatory | Description | 529| ----------- | ------- | ---- | ------------ | 530| multiWindow | boolean | Yes | Whether to enable the multi-window permission.<br>The value **true** means to enable the multi-window permission, and **false** means the opposite.<br>The default value is **false**.| 531 532## horizontalScrollBarAccess<sup>9+</sup> 533 534horizontalScrollBarAccess(horizontalScrollBar: boolean) 535 536Sets whether to display the horizontal scrollbar, including the default system scrollbar and custom scrollbar. 537 538> **NOTE** 539> 540> - If an @State decorated variable is used to control the horizontal scrollbar visibility, [controller.refresh()](./arkts-apis-webview-WebviewController.md#refresh) must be called for the settings to take effect. 541> - If the vertical scrollbar visibility changes frequently through an @State decorated variable, it is recommended that the variable correspond to the **Web** component one by one. 542 543**System capability**: SystemCapability.Web.Webview.Core 544 545**Parameters** 546 547| Name | Type | Mandatory | Description | 548| ------------------- | ------- | ---- | ------------ | 549| horizontalScrollBar | boolean | Yes | Whether to display the horizontal scrollbar.<br>The value **true** means to display the horizontal scrollbar, and **false** means the opposite.<br>Default value: **true**| 550 551**Example** 552 553 ```ts 554 // xxx.ets 555 import { webview } from '@kit.ArkWeb'; 556 import { BusinessError } from '@kit.BasicServicesKit'; 557 558 @Entry 559 @Component 560 struct WebComponent { 561 controller: webview.WebviewController = new webview.WebviewController(); 562 @State isShow: boolean = true; 563 @State btnMsg: string ="Hide the scrollbar"; 564 565 build() { 566 Column() { 567 // If an @State decorated variable is used to control the horizontal scrollbar visibility, controller.refresh() must be called for the settings to take effect. 568 Button('refresh') 569 .onClick(() => { 570 if(this.isShow){ 571 this.isShow = false; 572 this.btnMsg="Display the scrollbar"; 573 }else{ 574 this.isShow = true; 575 this.btnMsg="Hide the scrollbar"; 576 } 577 try { 578 this.controller.refresh(); 579 } catch (error) { 580 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 581 } 582 }).height("10%").width("40%") 583 Web({ src: $rawfile('index.html'), controller: this.controller }).height("90%") 584 .horizontalScrollBarAccess(this.isShow) 585 } 586 } 587 } 588 ``` 589 590 HTML file to be loaded: 591 ```html 592 <!--index.html--> 593 <!DOCTYPE html> 594 <html> 595 <head> 596 <meta name="viewport" id="viewport" content="width=device-width,initial-scale=1.0"> 597 <title>Demo</title> 598 <style> 599 body { 600 width:3000px; 601 height:6000px; 602 padding-right:170px; 603 padding-left:170px; 604 border:5px solid blueviolet 605 } 606 </style> 607 </head> 608 <body> 609 Scroll Test 610 </body> 611 </html> 612 ``` 613 614## verticalScrollBarAccess<sup>9+</sup> 615 616verticalScrollBarAccess(verticalScrollBar: boolean) 617 618Sets whether to display the vertical scrollbar, including the default system scrollbar and custom scrollbar. 619 620> **NOTE** 621> 622> - If an @State decorated variable is used to control the vertical scrollbar visibility, **controller.refresh()** must be called for the settings to take effect. 623> - If the vertical scrollbar visibility changes frequently through an @State decorated variable, it is recommended that the variable correspond to the **Web** component one by one. 624 625**System capability**: SystemCapability.Web.Webview.Core 626 627**Parameters** 628 629| Name | Type | Mandatory | Description | 630| ----------------- | ------- | ---- | ------------ | 631| verticalScrollBar | boolean | Yes | Whether to display the vertical scrollbar.<br>The value **true** means to display the vertical scrollbar, and **false** means the opposite.<br>Default value: **true**| 632 633**Example** 634 635 ```ts 636 // xxx.ets 637 import { webview } from '@kit.ArkWeb'; 638 import { BusinessError } from '@kit.BasicServicesKit'; 639 640 @Entry 641 @Component 642 struct WebComponent { 643 controller: webview.WebviewController = new webview.WebviewController(); 644 @State isShow: boolean = true; 645 @State btnMsg: string ="Hide the scrollbar"; 646 647 build() { 648 Column() { 649 // If an @State decorated variable is used to control the horizontal scrollbar visibility, controller.refresh() must be called for the settings to take effect. 650 Button(this.btnMsg) 651 .onClick(() => { 652 if(this.isShow){ 653 this.isShow = false; 654 this.btnMsg="Display the scrollbar"; 655 }else{ 656 this.isShow = true; 657 this.btnMsg="Hide the scrollbar"; 658 } 659 try { 660 this.controller.refresh(); 661 } catch (error) { 662 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 663 } 664 }).height("10%").width("40%") 665 Web({ src: $rawfile('index.html'), controller: this.controller }).height("90%") 666 .verticalScrollBarAccess(this.isShow) 667 } 668 } 669 } 670 ``` 671 672 HTML file to be loaded: 673 ```html 674 <!--index.html--> 675 <!DOCTYPE html> 676 <html> 677 <head> 678 <meta name="viewport" id="viewport" content="width=device-width,initial-scale=1.0"> 679 <title>Demo</title> 680 <style> 681 body { 682 width:3000px; 683 height:6000px; 684 padding-right:170px; 685 padding-left:170px; 686 border:5px solid blueviolet 687 } 688 </style> 689 </head> 690 <body> 691 Scroll Test 692 </body> 693 </html> 694 ``` 695 696## cacheMode 697 698cacheMode(cacheMode: CacheMode) 699 700Sets the cache mode. 701 702**System capability**: SystemCapability.Web.Webview.Core 703 704**Parameters** 705 706| Name | Type | Mandatory | Description | 707| --------- | --------------------------- | ---- | --------- | 708| cacheMode | [CacheMode](./arkts-basic-components-web-e.md#cachemode) | Yes | Cache mode to set.<br>Default value: **CacheMode.Default**| 709 710**Example** 711 712 ```ts 713 // xxx.ets 714 import { webview } from '@kit.ArkWeb'; 715 716 @Entry 717 @Component 718 struct WebComponent { 719 controller: webview.WebviewController = new webview.WebviewController(); 720 @State mode: CacheMode = CacheMode.None; 721 722 build() { 723 Column() { 724 Web({ src: 'www.example.com', controller: this.controller }) 725 .cacheMode(this.mode) 726 } 727 } 728 } 729 ``` 730 731## copyOptions<sup>11+</sup> 732 733copyOptions(value: CopyOptions) 734 735Sets the pasteboard copy options. 736 737**System capability**: SystemCapability.Web.Webview.Core 738 739**Parameters** 740 741| Name | Type | Mandatory | Description | 742| --------- | --------------------------- | ---- | --------- | 743| value | [CopyOptions](../apis-arkui/arkui-ts/ts-appendix-enums.md#copyoptions9) | Yes | Pasteboard copy options.<br>Default value: **CopyOptions.LocalDevice**| 744 745**Example** 746 747 ```ts 748import { webview } from '@kit.ArkWeb'; 749 750@Entry 751@Component 752struct WebComponent { 753 controller: webview.WebviewController = new webview.WebviewController(); 754 755 build() { 756 Column() { 757 Web({ src: 'www.example.com', controller: this.controller }) 758 .copyOptions(CopyOptions.None) 759 } 760 } 761} 762 ``` 763 764## textZoomRatio<sup>9+</sup> 765 766textZoomRatio(textZoomRatio: number) 767 768Sets the text zoom ratio of the page. 769 770**System capability**: SystemCapability.Web.Webview.Core 771 772**Parameters** 773 774| Name | Type | Mandatory | Description | 775| ------------- | ------ | ---- | -------------------------------- | 776| textZoomRatio | number | Yes | Text zoom ratio to set.<br>The value is an integer. The value range is (0, 2147483647].<br>Default value: **100**| 777 778**Example** 779 780 ```ts 781 // xxx.ets 782 import { webview } from '@kit.ArkWeb'; 783 784 @Entry 785 @Component 786 struct WebComponent { 787 controller: webview.WebviewController = new webview.WebviewController(); 788 @State ratio: number = 150; 789 790 build() { 791 Column() { 792 Web({ src: 'www.example.com', controller: this.controller }) 793 .textZoomRatio(this.ratio) 794 } 795 } 796 } 797 ``` 798 799## initialScale<sup>9+</sup> 800 801initialScale(percent: number) 802 803Sets the scale factor of the entire page. 804 805**System capability**: SystemCapability.Web.Webview.Core 806 807**Parameters** 808 809| Name | Type | Mandatory | Description | 810| ------- | ------ | ---- | ----------------------------- | 811| percent | number | Yes | Scale factor of the entire page.<br>Value range: (0, 1000]<br>Default value: **100**| 812 813**Example** 814 815 ```ts 816 // xxx.ets 817 import { webview } from '@kit.ArkWeb'; 818 819 @Entry 820 @Component 821 struct WebComponent { 822 controller: webview.WebviewController = new webview.WebviewController(); 823 @State percent: number = 100; 824 825 build() { 826 Column() { 827 Web({ src: 'www.example.com', controller: this.controller }) 828 .initialScale(this.percent) 829 } 830 } 831 } 832 ``` 833 834## blockNetwork<sup>9+</sup> 835 836blockNetwork(block: boolean) 837 838Sets whether to block online downloads. 839 840**System capability**: SystemCapability.Web.Webview.Core 841 842**Parameters** 843 844| Name | Type | Mandatory | Description | 845| ----- | ------- | ---- | ------------------- | 846| block | boolean | Yes | Whether to block online downloads.<br>The value **true** means to block online downloads, and **false** means the opposite.<br>The default value is **false**.| 847 848**Example** 849 850 ```ts 851 // xxx.ets 852 import { webview } from '@kit.ArkWeb'; 853 854 @Entry 855 @Component 856 struct WebComponent { 857 controller: webview.WebviewController = new webview.WebviewController(); 858 @State block: boolean = true; 859 860 build() { 861 Column() { 862 Web({ src: 'www.example.com', controller: this.controller }) 863 .blockNetwork(this.block) 864 } 865 } 866 } 867 ``` 868 869## defaultFixedFontSize<sup>9+</sup> 870 871defaultFixedFontSize(size: number) 872 873Sets the default fixed font size for the web page. 874 875**System capability**: SystemCapability.Web.Webview.Core 876 877**Parameters** 878 879| Name | Type | Mandatory | Description | 880| ---- | ------ | ---- | ---------------------------------------- | 881| size | number | Yes | Default fixed font size to set, in px.<br>The value ranges from -2^31 to 2^31-1. In actual rendering, values greater than 72 px are handled as 72 px, and values less than 1 px are handled as 1 px.<br>Default value: **13**| 882 883**Example** 884 885 ```ts 886 // xxx.ets 887 import { webview } from '@kit.ArkWeb'; 888 889 @Entry 890 @Component 891 struct WebComponent { 892 controller: webview.WebviewController = new webview.WebviewController(); 893 @State fontSize: number = 16; 894 895 build() { 896 Column() { 897 Web({ src: 'www.example.com', controller: this.controller }) 898 .defaultFixedFontSize(this.fontSize) 899 } 900 } 901 } 902 ``` 903 904## defaultFontSize<sup>9+</sup> 905 906defaultFontSize(size: number) 907 908Sets the default font size for the web page. 909 910**System capability**: SystemCapability.Web.Webview.Core 911 912**Parameters** 913 914| Name | Type | Mandatory | Description | 915| ---- | ------ | ---- | ---------------------------------------- | 916| size | number | Yes | Default font size to set, in px.<br>The value ranges from -2^31 to 2^31-1. In actual rendering, values greater than 72 px are handled as 72 px, and values less than 1 px are handled as 1 px.<br>Default value: **16**| 917 918**Example** 919 920 ```ts 921 // xxx.ets 922 import { webview } from '@kit.ArkWeb'; 923 924 @Entry 925 @Component 926 struct WebComponent { 927 controller: webview.WebviewController = new webview.WebviewController(); 928 @State fontSize: number = 13; 929 930 build() { 931 Column() { 932 Web({ src: 'www.example.com', controller: this.controller }) 933 .defaultFontSize(this.fontSize) 934 } 935 } 936 } 937 ``` 938 939## minFontSize<sup>9+</sup> 940 941minFontSize(size: number) 942 943Sets the minimum font size for the web page. 944 945**System capability**: SystemCapability.Web.Webview.Core 946 947**Parameters** 948 949| Name | Type | Mandatory | Description | 950| ---- | ------ | ---- | ---------------------------------------- | 951| size | number | Yes | Minimum font size to set, in px.<br>The value ranges from -2^31 to 2^31-1. In actual rendering, values greater than 72 px are handled as 72 px, and values less than 1 px are handled as 1 px.<br>Default value: **8**| 952 953**Example** 954 955 ```ts 956 // xxx.ets 957 import { webview } from '@kit.ArkWeb'; 958 959 @Entry 960 @Component 961 struct WebComponent { 962 controller: webview.WebviewController = new webview.WebviewController(); 963 @State fontSize: number = 13; 964 965 build() { 966 Column() { 967 Web({ src: 'www.example.com', controller: this.controller }) 968 .minFontSize(this.fontSize) 969 } 970 } 971 } 972 ``` 973 974## minLogicalFontSize<sup>9+</sup> 975 976minLogicalFontSize(size: number) 977 978Sets the minimum logical font size for the web page. 979 980**System capability**: SystemCapability.Web.Webview.Core 981 982**Parameters** 983 984| Name | Type | Mandatory | Description | 985| ---- | ------ | ---- | ---------------------------------------- | 986| size | number | Yes | Minimum logical font size to set, in px.<br>The value ranges from -2^31 to 2^31-1. In actual rendering, values greater than 72 px are handled as 72 px, and values less than 1 px are handled as 1 px.<br>Default value: **8**| 987 988**Example** 989 990 ```ts 991 // xxx.ets 992 import { webview } from '@kit.ArkWeb'; 993 994 @Entry 995 @Component 996 struct WebComponent { 997 controller: webview.WebviewController = new webview.WebviewController(); 998 @State fontSize: number = 13; 999 1000 build() { 1001 Column() { 1002 Web({ src: 'www.example.com', controller: this.controller }) 1003 .minLogicalFontSize(this.fontSize) 1004 } 1005 } 1006 } 1007 ``` 1008 1009## webFixedFont<sup>9+</sup> 1010 1011webFixedFont(family: string) 1012 1013Sets a fixed font family for the web page. 1014 1015**System capability**: SystemCapability.Web.Webview.Core 1016 1017**Parameters** 1018 1019| Name | Type | Mandatory | Description | 1020| ------ | ------ | ---- | ------------------------ | 1021| family | string | Yes | Fixed font family to set.<br>Default value: **monospace**| 1022 1023**Example** 1024 1025 ```ts 1026 // xxx.ets 1027 import { webview } from '@kit.ArkWeb'; 1028 1029 @Entry 1030 @Component 1031 struct WebComponent { 1032 controller: webview.WebviewController = new webview.WebviewController(); 1033 @State family: string = "monospace"; 1034 1035 build() { 1036 Column() { 1037 Web({ src: 'www.example.com', controller: this.controller }) 1038 .webFixedFont(this.family) 1039 } 1040 } 1041 } 1042 ``` 1043 1044## webSansSerifFont<sup>9+</sup> 1045 1046webSansSerifFont(family: string) 1047 1048Sets a sans serif font family for the web page. 1049 1050**System capability**: SystemCapability.Web.Webview.Core 1051 1052**Parameters** 1053 1054| Name | Type | Mandatory | Description | 1055| ------ | ------ | ---- | ------------------------ | 1056| family | string | Yes | Sans serif font family to set.<br>Default value: **sans-serif**| 1057 1058**Example** 1059 1060 ```ts 1061 // xxx.ets 1062 import { webview } from '@kit.ArkWeb'; 1063 1064 @Entry 1065 @Component 1066 struct WebComponent { 1067 controller: webview.WebviewController = new webview.WebviewController(); 1068 @State family: string = "sans-serif"; 1069 1070 build() { 1071 Column() { 1072 Web({ src: 'www.example.com', controller: this.controller }) 1073 .webSansSerifFont(this.family) 1074 } 1075 } 1076 } 1077 ``` 1078 1079## webSerifFont<sup>9+</sup> 1080 1081webSerifFont(family: string) 1082 1083Sets a serif font family for the web page. 1084 1085**System capability**: SystemCapability.Web.Webview.Core 1086 1087**Parameters** 1088 1089| Name | Type | Mandatory | Description | 1090| ------ | ------ | ---- | ------------------------ | 1091| family | string | Yes | Serif font family to set.<br>Default value: **serif**| 1092 1093**Example** 1094 1095 ```ts 1096 // xxx.ets 1097 import { webview } from '@kit.ArkWeb'; 1098 1099 @Entry 1100 @Component 1101 struct WebComponent { 1102 controller: webview.WebviewController = new webview.WebviewController(); 1103 @State family: string = "serif"; 1104 1105 build() { 1106 Column() { 1107 Web({ src: 'www.example.com', controller: this.controller }) 1108 .webSerifFont(this.family) 1109 } 1110 } 1111 } 1112 ``` 1113 1114## webStandardFont<sup>9+</sup> 1115 1116webStandardFont(family: string) 1117 1118Sets a standard font family for the web page. 1119 1120**System capability**: SystemCapability.Web.Webview.Core 1121 1122**Parameters** 1123 1124| Name | Type | Mandatory | Description | 1125| ------ | ------ | ---- | ---------------------- | 1126| family | string | Yes | Standard font family to set.<br>Default value: **sans-serif**| 1127 1128**Example** 1129 1130 ```ts 1131 // xxx.ets 1132 import { webview } from '@kit.ArkWeb'; 1133 1134 @Entry 1135 @Component 1136 struct WebComponent { 1137 controller: webview.WebviewController = new webview.WebviewController(); 1138 @State family: string = "sans-serif"; 1139 1140 build() { 1141 Column() { 1142 Web({ src: 'www.example.com', controller: this.controller }) 1143 .webStandardFont(this.family) 1144 } 1145 } 1146 } 1147 ``` 1148 1149## webFantasyFont<sup>9+</sup> 1150 1151webFantasyFont(family: string) 1152 1153Sets a fantasy font family for the web page. 1154 1155**System capability**: SystemCapability.Web.Webview.Core 1156 1157**Parameters** 1158 1159| Name | Type | Mandatory | Description | 1160| ------ | ------ | ---- | ------------------------ | 1161| family | string | Yes | Fantasy font family to set.<br>Default value: **fantasy**| 1162 1163**Example** 1164 1165 ```ts 1166 // xxx.ets 1167 import { webview } from '@kit.ArkWeb'; 1168 @Entry 1169 @Component 1170 struct WebComponent { 1171 controller: webview.WebviewController = new webview.WebviewController(); 1172 @State family: string = "fantasy"; 1173 1174 build() { 1175 Column() { 1176 Web({ src: 'www.example.com', controller: this.controller }) 1177 .webFantasyFont(this.family) 1178 } 1179 } 1180 } 1181 ``` 1182 1183## webCursiveFont<sup>9+</sup> 1184 1185webCursiveFont(family: string) 1186 1187Sets a cursive font family for the web page. 1188 1189**System capability**: SystemCapability.Web.Webview.Core 1190 1191**Parameters** 1192 1193| Name | Type | Mandatory | Description | 1194| ------ | ------ | ---- | ------------------------ | 1195| family | string | Yes | Cursive font family to set.<br>Default value: **cursive**| 1196 1197**Example** 1198 1199 ```ts 1200 // xxx.ets 1201 import { webview } from '@kit.ArkWeb'; 1202 1203 @Entry 1204 @Component 1205 struct WebComponent { 1206 controller: webview.WebviewController = new webview.WebviewController(); 1207 @State family: string = "cursive"; 1208 1209 build() { 1210 Column() { 1211 Web({ src: 'www.example.com', controller: this.controller }) 1212 .webCursiveFont(this.family) 1213 } 1214 } 1215 } 1216 ``` 1217 1218## darkMode<sup>9+</sup> 1219 1220darkMode(mode: WebDarkMode) 1221 1222Sets dark mode for the web page. When dark mode is enabled, the **Web** component enables the dark style defined in the media query **prefers-color-scheme** of the web page. If it is not defined, the web page remains unchanged. To enable forcible dark mode, use this API with [forceDarkAccess](#forcedarkaccess9). For details about how to use dark mode, see [Setting Dark Mode](../../web/web-set-dark-mode.md). 1223 1224**System capability**: SystemCapability.Web.Webview.Core 1225 1226**Parameters** 1227 1228| Name | Type | Mandatory | Description | 1229| ---- | -------------------------------- | ---- | ------------------------ | 1230| mode | [WebDarkMode](./arkts-basic-components-web-e.md#webdarkmode9) | Yes | Dark mode for the web page, which can be set to **Off**, **On**, or **Auto**.<br>Default value: **WebDarkMode.Off**| 1231 1232**Example** 1233 1234 ```ts 1235 // xxx.ets 1236 import { webview } from '@kit.ArkWeb'; 1237 1238 @Entry 1239 @Component 1240 struct WebComponent { 1241 controller: webview.WebviewController = new webview.WebviewController(); 1242 @State mode: WebDarkMode = WebDarkMode.On; 1243 1244 build() { 1245 Column() { 1246 Web({ src: 'www.example.com', controller: this.controller }) 1247 .darkMode(this.mode) 1248 } 1249 } 1250 } 1251 ``` 1252 1253## forceDarkAccess<sup>9+</sup> 1254 1255forceDarkAccess(access: boolean) 1256 1257Sets whether to enable forcible dark mode for the web page. This API is applicable only when [darkMode](#darkmode9) is enabled. 1258 1259**System capability**: SystemCapability.Web.Webview.Core 1260 1261**Parameters** 1262 1263| Name | Type | Mandatory | Description | 1264| ------ | ------- | ---- | --------------- | 1265| access | boolean | Yes | Whether to enable forcible dark mode for the web page.<br>The value **true** means to enable forcible dark mode for the web page, and **false** means the opposite.<br>The default value is **false**.| 1266 1267**Example** 1268 1269 ```ts 1270 // xxx.ets 1271 import { webview } from '@kit.ArkWeb'; 1272 1273 @Entry 1274 @Component 1275 struct WebComponent { 1276 controller: webview.WebviewController = new webview.WebviewController(); 1277 @State mode: WebDarkMode = WebDarkMode.On; 1278 @State access: boolean = true; 1279 1280 build() { 1281 Column() { 1282 Web({ src: 'www.example.com', controller: this.controller }) 1283 .darkMode(this.mode) 1284 .forceDarkAccess(this.access) 1285 } 1286 } 1287 } 1288 ``` 1289 1290## pinchSmooth<sup>9+</sup> 1291 1292pinchSmooth(isEnabled: boolean) 1293 1294Sets whether to enable pinch smooth mode for the web page. 1295 1296**System capability**: SystemCapability.Web.Webview.Core 1297 1298**Parameters** 1299 1300| Name | Type | Mandatory | Description | 1301| --------- | ------- | ---- | ------------- | 1302| isEnabled | boolean | Yes | Whether to enable pinch smooth mode for the web page.<br>The value **true** means to enable pinch smooth mode, and **false** means the opposite.<br>The default value is **false**.| 1303 1304**Example** 1305 1306 ```ts 1307 // xxx.ets 1308 import { webview } from '@kit.ArkWeb'; 1309 1310 @Entry 1311 @Component 1312 struct WebComponent { 1313 controller: webview.WebviewController = new webview.WebviewController(); 1314 1315 build() { 1316 Column() { 1317 Web({ src: 'www.example.com', controller: this.controller }) 1318 .pinchSmooth(true) 1319 } 1320 } 1321 } 1322 ``` 1323 1324## allowWindowOpenMethod<sup>10+</sup> 1325 1326allowWindowOpenMethod(flag: boolean) 1327 1328Sets whether to allow a new window to automatically open through JavaScript. 1329 1330> **NOTE** 1331> 1332> - This API takes effect only when [javaScriptAccess](#javascriptaccess) is enabled. 1333> - This API opens a new window when [multiWindowAccess](#multiwindowaccess9) is enabled, and a local window when it is disabled. 1334> - The default value of **flag** is subject to the settings of the **persist.web.allowWindowOpenMethod.enabled** system attribute. If this attribute is not set, the default value of **flag** is **false**. 1335> - Run the **hdc shell param get persist.web.allowWindowOpenMethod.enabled** command to check whether the system attribute **persist.web.allowWindowOpenMethod.enabled** is enabled. If the attribute value is **1**, the system attribute is enabled. If the attribute value is **0** or does not exist, the system attribute is disabled. You can run the **hdc shell param set persist.web.allowWindowOpenMethod.enabled 1** command to enable the system attribute. 1336 1337**System capability**: SystemCapability.Web.Webview.Core 1338 1339**Parameters** 1340 1341| Name | Type | Mandatory | Description | 1342| ---- | ------- | ---- | ------------------------- | 1343| flag | boolean | Yes | <br>Whether to allow a new window to automatically open through JavaScript. The value **true** means to allow a new window to automatically open through JavaScript, and **false** means only to allow a new window to automatically open through JavaScript using user behaviors.<br>The user behavior here refers to a user requests to open a new window (**window.open**) within 5 seconds after operating the **Web** component.<br>The default value of **flag** is subject to the settings of the **persist.web.allowWindowOpenMethod.enabled** system attribute. If this attribute is set to **true**, the default value of **flag** is **true**. If this attribute is not set, the default value of **flag** is **false**.| 1344 1345**Example** 1346 1347 ```ts 1348 // xxx.ets 1349 import { webview } from '@kit.ArkWeb'; 1350 1351 // There are two Web components on the same page. When the WebComponent object opens a new window, the NewWebViewComp object is displayed. 1352 @CustomDialog 1353 struct NewWebViewComp { 1354 controller?: CustomDialogController; 1355 webviewController1: webview.WebviewController = new webview.WebviewController(); 1356 1357 build() { 1358 Column() { 1359 Web({ src: "", controller: this.webviewController1 }) 1360 .javaScriptAccess(true) 1361 .multiWindowAccess(false) 1362 .onWindowExit(() => { 1363 console.info("NewWebViewComp onWindowExit"); 1364 if (this.controller) { 1365 this.controller.close(); 1366 } 1367 }) 1368 } 1369 } 1370 } 1371 1372 @Entry 1373 @Component 1374 struct WebComponent { 1375 controller: webview.WebviewController = new webview.WebviewController(); 1376 dialogController: CustomDialogController | null = null; 1377 1378 build() { 1379 Column() { 1380 Web({ src: 'www.example.com', controller: this.controller }) 1381 .javaScriptAccess(true) 1382 // MultiWindowAccess needs to be enabled. 1383 .multiWindowAccess(true) 1384 .allowWindowOpenMethod(true) 1385 .onWindowNew((event) => { 1386 if (this.dialogController) { 1387 this.dialogController.close(); 1388 } 1389 let popController: webview.WebviewController = new webview.WebviewController(); 1390 this.dialogController = new CustomDialogController({ 1391 builder: NewWebViewComp({ webviewController1: popController }) 1392 }) 1393 this.dialogController.open(); 1394 // Return the WebviewController object corresponding to the new window to the web kernel. 1395 // If the event.handler.setWebController API is not called, the render process will be blocked. 1396 // If no new window is created, set the value of event.handler.setWebController to null to notify the Web component that no new window is created. 1397 event.handler.setWebController(popController); 1398 }) 1399 } 1400 } 1401 } 1402 ``` 1403 1404## mediaOptions<sup>10+</sup> 1405 1406mediaOptions(options: WebMediaOptions) 1407 1408Sets the web-based media playback policy, including the validity period for automatically resuming a paused web audio, and whether the audio of multiple **Web** instances in an application is exclusive. 1409 1410> **NOTE** 1411> 1412> - Audios in the same **Web** instance are considered as the same audio. 1413> - The media playback policy controls videos with an audio track. 1414> - You are advised to set [audioExclusive](./arkts-basic-components-web-i.md#webmediaoptions10) to the same value for all **Web** components. 1415> - Audio and video interruption takes effect within an application and between applications, and playback resumption takes effect only between applications. 1416 1417**System capability**: SystemCapability.Web.Webview.Core 1418 1419**Parameters** 1420 1421| Name | Type | Mandatory | Description | 1422| ------- | ------------------------------------- | ---- | ---------------------------------------- | 1423| options | [WebMediaOptions](./arkts-basic-components-web-i.md#webmediaoptions10) | Yes | Web-based media playback policy.<br>After the parameter settings are updated, the playback must be started again for the settings to take effect.<br>Default value: **{resumeInterval: 0, audioExclusive: true}**| 1424 1425**Example** 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 options: WebMediaOptions = {resumeInterval: 10, audioExclusive: true}; 1436 1437 build() { 1438 Column() { 1439 Web({ src: 'www.example.com', controller: this.controller }) 1440 .mediaOptions(this.options) 1441 } 1442 } 1443 } 1444 ``` 1445 1446## javaScriptOnDocumentStart<sup>11+</sup> 1447 1448javaScriptOnDocumentStart(scripts: Array\<ScriptItem>) 1449 1450Injects a JavaScript script into the **Web** component. When the specified page or document starts to be loaded, the script is executed on any page whose source matches **scriptRules**. 1451 1452> **NOTE** 1453> 1454> - The script runs before any JavaScript code of the page, when the DOM tree may not have been loaded or rendered. 1455> 1456> - This script is executed in lexicographical order in this API. To execute the script in array order, you are advised to use the [runJavaScriptOnDocumentStart](#runjavascriptondocumentstart15) API. 1457> 1458> - You are not advised to use this API together with [runJavaScriptOnDocumentStart](#runjavascriptondocumentstart15). 1459> 1460> - If a script with the same content is injected for multiple times, the script is silently deduplicated, not displayed, and no notification is displayed. The **scriptRules** of the first injection is used. 1461 1462**System capability**: SystemCapability.Web.Webview.Core 1463 1464**Parameters** 1465 1466| Name | Type | Mandatory | Description | 1467| ------- | ----------------------------------- | ---- | ------------------ | 1468| scripts | Array\<[ScriptItem](./arkts-basic-components-web-i.md#scriptitem11)> | Yes | Script item array to be injected.| 1469 1470**Example of the .ets file** 1471 1472 ```ts 1473 // xxx.ets 1474 import { webview } from '@kit.ArkWeb'; 1475 1476 @Entry 1477 @Component 1478 struct Index { 1479 controller: webview.WebviewController = new webview.WebviewController(); 1480 private localStorage: string = 1481 "if (typeof(Storage) !== 'undefined') {" + 1482 " localStorage.setItem('color', 'Red');" + 1483 "}"; 1484 @State scripts: Array<ScriptItem> = [ 1485 { script: this.localStorage, scriptRules: ["*"] } 1486 ]; 1487 1488 build() { 1489 Column({ space: 20 }) { 1490 Web({ src: $rawfile('index.html'), controller: this.controller }) 1491 .javaScriptAccess(true) 1492 .domStorageAccess(true) 1493 .backgroundColor(Color.Grey) 1494 .javaScriptOnDocumentStart(this.scripts) 1495 .width('100%') 1496 .height('100%') 1497 } 1498 } 1499 } 1500 ``` 1501**Example of the HTML file** 1502 1503```html 1504<!-- index.html --> 1505<!DOCTYPE html> 1506<html> 1507 <head> 1508 <meta charset="utf-8"> 1509 </head> 1510 <body style="font-size: 30px;" onload='bodyOnLoadLocalStorage()'> 1511 Hello world! 1512 <div id="result"></div> 1513 </body> 1514 <script type="text/javascript"> 1515 function bodyOnLoadLocalStorage() { 1516 if (typeof(Storage) !== 'undefined') { 1517 document.getElementById('result').innerHTML = localStorage.getItem('color'); 1518 } else { 1519 document.getElementById('result').innerHTML = 'Your browser does not support localStorage.'; 1520 } 1521 } 1522 </script> 1523</html> 1524``` 1525 1526## javaScriptOnDocumentEnd<sup>11+</sup> 1527 1528javaScriptOnDocumentEnd(scripts: Array\<ScriptItem>) 1529 1530Injects a JavaScript script into the **Web** component. When the specified page or document has been loaded, the script is executed on any page whose source matches **scriptRules**. 1531 1532> **NOTE** 1533> 1534> - The script runs before any JavaScript code of the page, when the DOM tree has been loaded and rendered. 1535> 1536> - The script is executed in the lexicographical order, not the array order. 1537> 1538> - You are not advised to use this API together with [runJavaScriptOnDocumentEnd](#runjavascriptondocumentend15). 1539> 1540> - If a script with the same content is injected for multiple times, the script is silently deduplicated, not displayed, and no notification is displayed. The **scriptRules** of the first injection is used. 1541 1542**System capability**: SystemCapability.Web.Webview.Core 1543 1544**Parameters** 1545 1546| Name | Type | Mandatory | Description | 1547| ------- | ----------------------------------- | ---- | ------------------ | 1548| scripts | Array\<[ScriptItem](./arkts-basic-components-web-i.md#scriptitem11)> | Yes | Script item array to be injected.| 1549 1550**Example** 1551 1552 ```ts 1553// xxx.ets 1554import { webview } from '@kit.ArkWeb'; 1555 1556@Entry 1557@Component 1558struct Index { 1559 controller: webview.WebviewController = new webview.WebviewController(); 1560 private jsStr: string = 1561 "window.document.getElementById(\"result\").innerHTML = 'this is msg from javaScriptOnDocumentEnd'"; 1562 @State scripts: Array<ScriptItem> = [ 1563 { script: this.jsStr, scriptRules: ["*"] } 1564 ]; 1565 1566 build() { 1567 Column({ space: 20 }) { 1568 Web({ src: $rawfile('index.html'), controller: this.controller }) 1569 .javaScriptAccess(true) 1570 .domStorageAccess(true) 1571 .backgroundColor(Color.Grey) 1572 .javaScriptOnDocumentEnd(this.scripts) 1573 .width('100%') 1574 .height('100%') 1575 } 1576 } 1577} 1578 ``` 1579 1580```html 1581<!DOCTYPE html> 1582<html> 1583<head> 1584 <meta charset="utf-8"> 1585</head> 1586<body style="font-size: 30px;"> 1587Hello world! 1588<div id="result">test msg</div> 1589</body> 1590</html> 1591``` 1592 1593## runJavaScriptOnDocumentStart<sup>15+</sup> 1594 1595runJavaScriptOnDocumentStart(scripts: Array\<ScriptItem>) 1596 1597Injects a JavaScript script into the **Web** component. When the specified page or document starts to be loaded, the script is executed on any page whose source matches **scriptRules**. 1598 1599> **NOTE** 1600> 1601> - The script runs before any JavaScript code of the page, when the DOM tree may not have been loaded or rendered. 1602> 1603> - This script is executed in the array order. 1604> 1605> - You are advised not to use this API together with [javaScriptOnDocumentStart](#javascriptondocumentstart11). 1606> 1607> - If a script with the same content is injected for multiple times, the script is silently deduplicated, not displayed, and no notification is displayed. The **scriptRules** of the first injection is used. 1608 1609**System capability**: SystemCapability.Web.Webview.Core 1610 1611**Parameters** 1612 1613| Name | Type | Mandatory | Description | 1614| ------- | ----------------------------------- | ---- | ------------------ | 1615| scripts | Array\<[ScriptItem](./arkts-basic-components-web-i.md#scriptitem11)> | Yes | Script item array to be injected.| 1616 1617**Example of the .ets file** 1618 1619 ```ts 1620 // xxx.ets 1621 import { webview } from '@kit.ArkWeb'; 1622 1623 @Entry 1624 @Component 1625 struct Index { 1626 controller: webview.WebviewController = new webview.WebviewController(); 1627 private localStorage: string = 1628 "if (typeof(Storage) !== 'undefined') {" + 1629 " localStorage.setItem('color', 'Red');" + 1630 "}"; 1631 @State scripts: Array<ScriptItem> = [ 1632 { script: this.localStorage, scriptRules: ["*"] } 1633 ]; 1634 1635 build() { 1636 Column({ space: 20 }) { 1637 Web({ src: $rawfile('index.html'), controller: this.controller }) 1638 .javaScriptAccess(true) 1639 .domStorageAccess(true) 1640 .backgroundColor(Color.Grey) 1641 .runJavaScriptOnDocumentStart(this.scripts) 1642 .width('100%') 1643 .height('100%') 1644 } 1645 } 1646 } 1647 ``` 1648**Example of the HTML file** 1649 1650```html 1651<!-- index.html --> 1652<!DOCTYPE html> 1653<html> 1654 <head> 1655 <meta charset="utf-8"> 1656 </head> 1657 <body style="font-size: 30px;" onload='bodyOnLoadLocalStorage()'> 1658 Hello world! 1659 <div id="result"></div> 1660 </body> 1661 <script type="text/javascript"> 1662 function bodyOnLoadLocalStorage() { 1663 if (typeof(Storage) !== 'undefined') { 1664 document.getElementById('result').innerHTML = localStorage.getItem('color'); 1665 } else { 1666 document.getElementById('result').innerHTML = 'Your browser does not support localStorage.'; 1667 } 1668 } 1669 </script> 1670</html> 1671``` 1672 1673## runJavaScriptOnDocumentEnd<sup>15+</sup> 1674 1675runJavaScriptOnDocumentEnd(scripts: Array\<ScriptItem>) 1676 1677Injects a JavaScript script into the **Web** component. When the specified page or document has been loaded, the script is executed on any page whose source matches **scriptRules**. 1678 1679> **NOTE** 1680> 1681> - The script runs before any JavaScript code of the page, when the DOM tree has been loaded and rendered. 1682> 1683> - This script is executed in the array order. 1684> 1685> - You are advised not to use this API together with [javaScriptOnDocumentEnd](#javascriptondocumentend11). 1686> 1687> - If a script with the same content is injected for multiple times, the script is silently deduplicated, not displayed, and no notification is displayed. The **scriptRules** of the first injection is used. 1688 1689**System capability**: SystemCapability.Web.Webview.Core 1690 1691**Parameters** 1692 1693| Name | Type | Mandatory | Description | 1694| ------- | ----------------------------------- | ---- | ------------------ | 1695| scripts | Array\<[ScriptItem](./arkts-basic-components-web-i.md#scriptitem11)> | Yes | Script item array to be injected.| 1696 1697**Example** 1698 1699 ```ts 1700// xxx.ets 1701import { webview } from '@kit.ArkWeb'; 1702 1703@Entry 1704@Component 1705struct Index { 1706 controller: webview.WebviewController = new webview.WebviewController(); 1707 private jsStr: string = 1708 "window.document.getElementById(\"result\").innerHTML = 'this is msg from runJavaScriptOnDocumentEnd'"; 1709 @State scripts: Array<ScriptItem> = [ 1710 { script: this.jsStr, scriptRules: ["*"] } 1711 ]; 1712 1713 build() { 1714 Column({ space: 20 }) { 1715 Web({ src: $rawfile('index.html'), controller: this.controller }) 1716 .javaScriptAccess(true) 1717 .domStorageAccess(true) 1718 .backgroundColor(Color.Grey) 1719 .runJavaScriptOnDocumentEnd(this.scripts) 1720 .width('100%') 1721 .height('100%') 1722 } 1723 } 1724} 1725 ``` 1726 1727```html 1728<!DOCTYPE html> 1729<html> 1730<head> 1731 <meta charset="utf-8"> 1732</head> 1733<body style="font-size: 30px;"> 1734Hello world! 1735<div id="result">test msg</div> 1736</body> 1737</html> 1738``` 1739 1740## runJavaScriptOnHeadEnd<sup>15+</sup> 1741 1742runJavaScriptOnHeadEnd(scripts: Array\<ScriptItem>) 1743 1744Injects a JavaScript script into the **Web** component. When the **head** tag of the DOM tree is parsed, the script is executed on any page whose source matches **scriptRules**. 1745 1746> **NOTE** 1747> 1748> - This script is executed in the array order. 1749> 1750> - If a script with the same content is injected for multiple times, the script is silently deduplicated, not displayed, and no notification is displayed. The **scriptRules** of the first injection is used. 1751 1752**System capability**: SystemCapability.Web.Webview.Core 1753 1754**Parameters** 1755 1756| Name | Type | Mandatory | Description | 1757| ------- | ----------------------------------- | ---- | ------------------ | 1758| scripts | Array\<[ScriptItem](./arkts-basic-components-web-i.md#scriptitem11)> | Yes | Script item array to be injected.| 1759 1760**Example** 1761 1762 ```ts 1763// xxx.ets 1764import { webview } from '@kit.ArkWeb'; 1765 1766@Entry 1767@Component 1768struct Index { 1769 controller: webview.WebviewController = new webview.WebviewController(); 1770 private jsStr: string = 1771 "window.document.getElementById(\"result\").innerHTML = 'this is msg from runJavaScriptOnHeadEnd'"; 1772 @State scripts: Array<ScriptItem> = [ 1773 { script: this.jsStr, scriptRules: ["*"] } 1774 ]; 1775 1776 build() { 1777 Column({ space: 20 }) { 1778 Web({ src: $rawfile('index.html'), controller: this.controller }) 1779 .javaScriptAccess(true) 1780 .domStorageAccess(true) 1781 .backgroundColor(Color.Grey) 1782 .runJavaScriptOnHeadEnd(this.scripts) 1783 .width('100%') 1784 .height('100%') 1785 } 1786 } 1787} 1788 ``` 1789 1790```html 1791<!DOCTYPE html> 1792<html> 1793<head> 1794 <meta charset="utf-8"> 1795</head> 1796<body style="font-size: 30px;"> 1797Hello world! 1798<div id="result">test msg</div> 1799</body> 1800</html> 1801``` 1802 1803## layoutMode<sup>11+</sup> 1804 1805layoutMode(mode: WebLayoutMode) 1806 1807Sets the web layout mode. For details, see [Fitting In the Page Content Layout](../../web/web-fit-content.md). 1808 1809> **NOTE** 1810> 1811> Currently, only two web layout modes are supported: **WebLayoutMode.NONE** and **WebLayoutMode.FIT_CONTENT**. 1812> 1813> The following restrictions apply with the usage of **WebLayoutMode.FIT_CONTENT**: 1814> - If the **Web** component is wider or longer than 7680 px, specify the **RenderMode.SYNC_RENDER** mode when creating the **Web** component; otherwise, the screen may be blank. 1815> - After the **Web** component is created, dynamic switching of the **layoutMode** is not supported. 1816> - The width and height of a **Web** component cannot exceed 500,000 px when the **RenderMode.SYNC_RENDER** mode is specified, and cannot exceed 7680 px when the **RenderMode.ASYNC_RENDER** mode is specified. 1817> - Frequent changes to the page width and height will trigger a re-layout of the **Web** component, which can affect the user experience. 1818> - Waterfall web pages are not supported (pull down to the bottom to load more). 1819> - Width adaptation is not supported. Only height adaptation is supported. 1820> - Because the height is adaptive to the web page height, the component height cannot be changed by modifying the component height attribute. 1821 1822**System capability**: SystemCapability.Web.Webview.Core 1823 1824**Parameters** 1825 1826| Name | Type | Mandatory | Description | 1827| ---- | ------------------------------------- | ---- | --------------------- | 1828| mode | [WebLayoutMode](./arkts-basic-components-web-e.md#weblayoutmode11) | Yes | Web layout mode.<br>Default value: **WebLayoutMode.NONE**| 1829 1830**Example** 1831 1832 1. After specifying the **layoutMode** to **WebLayoutMode.FIT_CONTENT**, you need to explicitly specify the **renderMode** to **RenderMode.SYNC_RENDER**. Otherwise, rendering errors may occur when the viewport height exceeds 7680 px in the default **RenderMode.ASYNC_RENDER**. 1833 ```ts 1834 // xxx.ets 1835 import { webview } from '@kit.ArkWeb'; 1836 1837 @Entry 1838 @Component 1839 struct WebComponent { 1840 controller: webview.WebviewController = new webview.WebviewController(); 1841 mode: WebLayoutMode = WebLayoutMode.FIT_CONTENT; 1842 1843 build() { 1844 Column() { 1845 Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER }) 1846 .layoutMode(this.mode) 1847 } 1848 } 1849 } 1850 ``` 1851 1852 2. After specifying the layoutMode to **WebLayoutMode.FIT_CONTENT**, you are advised to specify [overScrollMode](#overscrollmode11) to **OverScrollMode.NEVER**. Otherwise, when the web page scrolls to the edge in the nested scrolling scenario, the rebounding effect is triggered first, which affects user experience. 1853 ```ts 1854 // xxx.ets 1855 import { webview } from '@kit.ArkWeb'; 1856 1857 @Entry 1858 @Component 1859 struct WebComponent { 1860 controller: webview.WebviewController = new webview.WebviewController(); 1861 layoutMode: WebLayoutMode = WebLayoutMode.FIT_CONTENT; 1862 @State overScrollMode: OverScrollMode = OverScrollMode.NEVER; 1863 1864 build() { 1865 Column() { 1866 Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER }) 1867 .layoutMode(this.layoutMode) 1868 .overScrollMode(this.overScrollMode) 1869 } 1870 } 1871 } 1872 ``` 1873 1874## nestedScroll<sup>11+</sup> 1875 1876nestedScroll(value: NestedScrollOptions | NestedScrollOptionsExt) 1877 1878Sets nested scrolling options. 1879 1880> **NOTE** 1881> 1882> - You can set the up, down, left, and right directions, or set the forward and backward nested scrolling modes to implement scrolling linkage with the parent component. 1883> - Containers that support nested scrolling: [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) and [bindSheet](../apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#bindsheet). 1884> - Input sources that support nested scrolling: gestures, mouse device, and touchpad. 1885> - In nested scrolling scenarios, since the **Web** component's over-scrolling to the edge will trigger the over-scroll bounce effect first, it is recommended that you set [overScrollMode](#overscrollmode11) to **OverScrollMode.NEVER** to avoid undermining user experience. 1886 1887**System capability**: SystemCapability.Web.Webview.Core 1888 1889**Parameters** 1890 1891| Name | Type | Mandatory | Description | 1892| ----- | ---------------------------------------- | ---- | ---------------- | 1893| value | [NestedScrollOptions](../apis-arkui/arkui-ts/ts-container-scrollable-common.md#nestedscrolloptions10)\| [NestedScrollOptionsExt](./arkts-basic-components-web-i.md#nestedscrolloptionsext14)<sup>14+</sup> | Yes | Nested scrolling options.<br> When the **value** is of the **NestedScrollOptions** type (forward and backward), the default nested scrolling mode of the **scrollForward** and **scrollBackward** options is **NestedScrollMode.SELF_FIRST**.<br> When the **value** is of the **NestedScrollOptionsExt** type (up, down, left, and right), the default nested scrolling mode of the **scrollUp**, **scrollDown**, **scrollLeft**, and **scrollRight **options is [NestedScrollMode.SELF_FIRST](../apis-arkui/arkui-ts/ts-appendix-enums.md#nestedscrollmode10).| 1894 1895**Example** 1896 1897 ```ts 1898 // xxx.ets 1899 import { webview } from '@kit.ArkWeb'; 1900 @Entry 1901 @Component 1902 struct WebComponent { 1903 controller: webview.WebviewController = new webview.WebviewController(); 1904 1905 build() { 1906 Column() { 1907 Web({ src: 'www.example.com', controller: this.controller }) 1908 .nestedScroll({ 1909 scrollForward: NestedScrollMode.SELF_FIRST, 1910 scrollBackward: NestedScrollMode.SELF_FIRST, 1911 }) 1912 } 1913 } 1914 } 1915 ``` 1916 ```ts 1917 // xxx.ets 1918 import { webview } from '@kit.ArkWeb'; 1919 @Entry 1920 @Component 1921 struct WebComponent { 1922 controller: webview.WebviewController = new webview.WebviewController() 1923 build() { 1924 Scroll(){ 1925 Column() { 1926 Text ("Nested Web") 1927 .height("25%") 1928 .width("100%") 1929 .fontSize(30) 1930 .backgroundColor(Color.Yellow) 1931 Web({ src: $rawfile('index.html'), 1932 controller: this.controller }) 1933 .nestedScroll({ 1934 scrollUp: NestedScrollMode.SELF_FIRST, 1935 scrollDown: NestedScrollMode.PARENT_FIRST, 1936 scrollLeft: NestedScrollMode.SELF_FIRST, 1937 scrollRight: NestedScrollMode.SELF_FIRST, 1938 }) 1939 } 1940 } 1941 } 1942 } 1943 ``` 1944 HTML file to be loaded: 1945 ```html 1946 <!-- index.html --> 1947 <!DOCTYPE html> 1948 <html> 1949 <head> 1950 <meta name="viewport" id="viewport" content="width=device-width, initial-scale=1.0"> 1951 <style> 1952 .blue { 1953 background-color: lightblue; 1954 } 1955 .green { 1956 background-color: lightgreen; 1957 } 1958 .blue, .green { 1959 font-size:16px; 1960 height:200px; 1961 text-align: center; /* Horizontally centered */ 1962 line-height: 200px; /* Vertically centered (the height matches the container height) */ 1963 } 1964 </style> 1965 </head> 1966 <body> 1967 <div class="blue" >webArea</div> 1968 <div class="green">webArea</div> 1969 <div class="blue">webArea</div> 1970 <div class="green">webArea</div> 1971 <div class="blue">webArea</div> 1972 <div class="green">webArea</div> 1973 <div class="blue">webArea</div> 1974 </body> 1975 </html> 1976 ``` 1977 1978## bypassVsyncCondition<sup>20+</sup> 1979 1980bypassVsyncCondition(condition: WebBypassVsyncCondition) 1981 1982Sets the rendering process to bypass vsync (vertical synchronization) scheduling and directly trigger drawing when the **scrollBy** API is called to scroll the page. 1983 1984**System capability**: SystemCapability.Web.Webview.Core 1985 1986**Parameters** 1987 1988| Name | Type | Mandatory | Description | 1989| ---- | ------------------------------------- | ---- | --------------------- | 1990| condition | [WebBypassVsyncCondition](./arkts-basic-components-web-e.md#webbypassvsynccondition20) | Yes | Condition for triggering the rendering process to bypass vsync scheduling.| 1991 1992**Example** 1993 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 condition: WebBypassVsyncCondition = WebBypassVsyncCondition.SCROLLBY_FROM_ZERO_OFFSET; 2003 2004 build() { 2005 Column() { 2006 Button('scrollBy') 2007 .onClick(() => { 2008 this.controller.scrollBy(0, 5); 2009 }) 2010 Web({ src: 'www.example.com', controller: this.controller }) 2011 .bypassVsyncCondition(this.condition) 2012 } 2013 } 2014 } 2015 ``` 2016 2017## enableNativeEmbedMode<sup>11+</sup> 2018 2019enableNativeEmbedMode(mode: boolean) 2020 2021Sets whether to enable the same-layer rendering feature. 2022 2023**System capability**: SystemCapability.Web.Webview.Core 2024 2025**Parameters** 2026 2027| Name | Type | Mandatory | Description | 2028| ----- | ---------------------------------------- | ---- | ---------------- | 2029| mode | boolean | Yes | Whether to enable the same-layer rendering feature.<br>The value **true** means to enable the same-layer rendering feature, and **false** means the opposite.<br>The default value is **false**.| 2030 2031**Example** 2032 2033 ```ts 2034 // xxx.ets 2035 import { webview } from '@kit.ArkWeb'; 2036 @Entry 2037 @Component 2038 struct WebComponent { 2039 controller: webview.WebviewController = new webview.WebviewController(); 2040 2041 build() { 2042 Column() { 2043 Web({ src: 'www.example.com', controller: this.controller }) 2044 .enableNativeEmbedMode(true) 2045 } 2046 } 2047 } 2048 ``` 2049## forceDisplayScrollBar<sup>14+</sup> 2050 2051forceDisplayScrollBar(enabled: boolean) 2052 2053 2054Sets whether the scroll bar is always visible. Under the always-visible settings, when the page size exceeds one page, the scroll bar appears and remains visible. 2055 2056When **layoutMode** is set to **WebLayoutMode.FIT_CONTENT**, the **enabled** parameter is set to **false**. 2057 2058**System capability**: SystemCapability.Web.Webview.Core 2059 2060**Parameters** 2061 2062| Name | Type| Mandatory| Description | 2063| ------- | -------- | ---- | ------------------ | 2064| enabled | boolean | Yes | Whether the scroll bar is always visible.<br>The value **true** indicates that the scroll bar is always visible, and **false** indicates the opposite.<br>The default value is **false**.| 2065 2066 2067**Example** 2068 2069 ```ts 2070 // xxx.ets 2071 import { webview } from '@kit.ArkWeb'; 2072 2073 @Entry 2074 @Component 2075 struct WebComponent { 2076 controller: webview.WebviewController = new webview.WebviewController(); 2077 2078 build() { 2079 Column() { 2080 Web({ src: $rawfile('index.html'), controller: this.controller }) 2081 .forceDisplayScrollBar(true) 2082 } 2083 } 2084 } 2085 ``` 2086 2087 HTML file to be loaded: 2088 ```html 2089 <!--index.html--> 2090 <!DOCTYPE html> 2091 <html> 2092 <head> 2093 <meta name="viewport" content="width=device-width, initial-scale=1.0"> 2094 <title>Demo</title> 2095 <style> 2096 body { 2097 width:2560px; 2098 height:2560px; 2099 padding-right:170px; 2100 padding-left:170px; 2101 border:5px solid blueviolet 2102 } 2103 </style> 2104 </head> 2105 <body> 2106 Scroll Test 2107 </body> 2108 </html> 2109 ``` 2110## registerNativeEmbedRule<sup>12+</sup> 2111 2112registerNativeEmbedRule(tag: string, type: string) 2113 2114Registers the HTML tag name and type for same-layer rendering. The tag name only supports <object\> and <embed\>. The tag type only supports visible ASCII characters. 2115 2116If the specified type is the same as the W3C standard <object\> or <embed\> type, the ArkWeb kernel identifies the type as a non-same-layer tag. 2117 2118This API is also controlled by **enableNativeEmbedMode** and does not take effect when same-layer rendering is disabled. When this API is not used, the ArkWeb kernel recognizes the <embed\> tags with the "native/" prefix as same-layer tags. 2119 2120**System capability**: SystemCapability.Web.Webview.Core 2121 2122**Parameters** 2123 2124| Name | Type | Mandatory | Description | 2125|------|--------| ---- |------------------| 2126| tag | string | Yes | Tag name. | 2127| type | string | Yes | Tag type. The ArkWeb kernel uses a prefix to match this parameter.| 2128 2129**Example** 2130 2131 ```ts 2132 // xxx.ets 2133 import { webview } from '@kit.ArkWeb'; 2134 2135 @Entry 2136 @Component 2137 struct WebComponent { 2138 controller: webview.WebviewController = new webview.WebviewController(); 2139 2140 build() { 2141 Column() { 2142 Web({ src: 'www.example.com', controller: this.controller }) 2143 .enableNativeEmbedMode(true) 2144 .registerNativeEmbedRule("object", "application/view") 2145 } 2146 } 2147 } 2148 ``` 2149## defaultTextEncodingFormat<sup>12+</sup> 2150 2151defaultTextEncodingFormat(textEncodingFormat: string) 2152 2153Sets the default text encoding format for the web page. 2154 2155**System capability**: SystemCapability.Web.Webview.Core 2156 2157**Parameters** 2158 2159| Name | Type | Mandatory | Description | 2160| ---- | ------ | ---- | ---------------------------------------- | 2161| textEncodingFormat | string | Yes | Default text encoding format. Default value: **"UTF-8"**| 2162 2163 **Example** 2164 2165 ```ts 2166 // xxx.ets 2167 import { webview } from '@kit.ArkWeb'; 2168 2169 @Entry 2170 @Component 2171 struct WebComponent { 2172 controller: webview.WebviewController = new webview.WebviewController(); 2173 2174 build() { 2175 Column() { 2176 Web({ src: $rawfile('index.html'), controller: this.controller }) 2177 // Set the height. 2178 .height(500) 2179 .defaultTextEncodingFormat("UTF-8") 2180 .javaScriptAccess(true) 2181 } 2182 } 2183 } 2184 ``` 2185 2186```html 2187<!DOCTYPE html> 2188<html> 2189<head> 2190 <meta name="viewport" content="width=device-width" /> 2191 <title>My test html5 page</title> 2192</head> 2193<body> 2194 <p>Hello world!</p> 2195</body> 2196</html> 2197``` 2198## metaViewport<sup>12+</sup> 2199 2200metaViewport(enabled: boolean) 2201 2202Sets whether the **viewport** attribute of the **meta** tag is enabled. 2203 2204> **NOTE** 2205> 2206> - If the device is 2-in-1, the **viewport** attribute is not supported. This means that, regardless of whether this parameter is set to **true** or **false**, the **viewport** attribute will not be parsed and a default layout will be used. 2207> - If the device is a tablet, the **viewport-fit** attribute of the **meta** tag is parsed regardless of whether this parameter is set to **true** or **false**. When **viewport-fit** is set to **cover**, the size of the safe area can be obtained through the CSS attribute. 2208> - Currently, the **viewport** parameter of the **meta** tag on the frontend HTML page is enabled or disabled based on whether **User-Agent** contains the **Mobile** field. If a **User-Agent** does not contain the **Mobile** field, the **viewport** attribute in the **meta** tag is disabled by default. In this case, you can explicitly set the **metaViewport** attribute to **true** to overwrite the disabled state. 2209 2210**System capability**: SystemCapability.Web.Webview.Core 2211 2212**Parameters** 2213 2214| Name| Type| Mandatory| Description | 2215| ------ | -------- | ---- | -------------------------------- | 2216| enabled | boolean | Yes | Whether the **viewport** attribute of the **meta** tag is enabled.<br>The value **true** indicates that the **viewport** attribute of the **meta** tag is enabled and parsed, and the layout is performed based on the **viewport** attribute.<br>The value **false** indicates the **viewport** attribute of the **meta** tag is disabled and not parsed, and the default layout is used.<br>Default value: **true**| 2217 2218**Example** 2219 2220 ```ts 2221// xxx.ets 2222import { webview } from '@kit.ArkWeb'; 2223 2224@Entry 2225@Component 2226struct WebComponent { 2227 controller: webview.WebviewController = new webview.WebviewController(); 2228 2229 build() { 2230 Column() { 2231 Web({ src: $rawfile('index.html'), controller: this.controller }) 2232 .metaViewport(true) 2233 } 2234 } 2235} 2236 ``` 2237 2238```html 2239<!DOCTYPE html> 2240<html> 2241<head> 2242 <meta name="viewport" content="width=device-width, initial-scale=1.0"> 2243</head> 2244<body> 2245 <p>Hello world!</p> 2246</body> 2247</html> 2248``` 2249 2250## textAutosizing<sup>12+</sup> 2251 2252textAutosizing(textAutosizing: boolean) 2253 2254Sets whether to enable automatic text resizing. 2255 2256**System capability**: SystemCapability.Web.Webview.Core 2257 2258**Parameters** 2259 2260| Name | Type | Mandatory | Description | 2261| ---- | ------ | ---- | ---------------------------------------- | 2262| textAutosizing | boolean | Yes | Whether to enable automatic text resizing.<br>The value **true** means to enable automatic text resizing, and **false** means the opposite.<br>Default value: **true**| 2263 2264 **Example** 2265 2266 ```ts 2267 // xxx.ets 2268 import { webview } from '@kit.ArkWeb'; 2269 2270 @Entry 2271 @Component 2272 struct WebComponent { 2273 controller: webview.WebviewController = new webview.WebviewController(); 2274 2275 build() { 2276 Column() { 2277 Web({ src: 'www.example.com', controller: this.controller }) 2278 .textAutosizing(false) 2279 } 2280 } 2281 } 2282 ``` 2283## enableNativeMediaPlayer<sup>12+</sup> 2284 2285enableNativeMediaPlayer(config: NativeMediaPlayerConfig) 2286 2287Sets whether to enable the [application takeover of web media playback feature](../../web/app-takeovers-web-media.md). 2288 2289**System capability**: SystemCapability.Web.Webview.Core 2290 2291**Parameters** 2292 2293| Name | Type | Mandatory | Description| 2294| ---- | ------ | ---- | ---------------------| 2295| config | [NativeMediaPlayerConfig](./arkts-basic-components-web-i.md#nativemediaplayerconfig12) | Yes | **enable**: whether to enable the feature.<br> **shouldOverlay**: whether the image of the video player taken over by the application will overlay the web page content, if this feature is enabled.<br>Default value: **{enable: false, shouldOverlay: false}**| 2296 2297 **Example** 2298 2299 ```ts 2300 // xxx.ets 2301 import { webview } from '@kit.ArkWeb'; 2302 2303 @Entry 2304 @Component 2305 struct WebComponent { 2306 controller: webview.WebviewController = new webview.WebviewController(); 2307 2308 build() { 2309 Column() { 2310 Web({ src: 'www.example.com', controller: this.controller }) 2311 .enableNativeMediaPlayer({enable: true, shouldOverlay: false}) 2312 } 2313 } 2314 } 2315 ``` 2316 2317## onAdsBlocked<sup>12+</sup> 2318 2319onAdsBlocked(callback: OnAdsBlockedCallback) 2320 2321Called after an ad is blocked on the web page to notify the user of detailed information about the blocked ad. To reduce the frequency of notifications and minimize the impact on the page loading process, only the first notification is made when the page is fully loaded. Subsequent blocking events are reported at intervals of 1 second, and no notifications are sent if there is no ad blocked. 2322 2323**System capability**: SystemCapability.Web.Webview.Core 2324 2325**Parameters** 2326 2327| Name | Type | Mandatory | Description | 2328| ------ | ------ | ---- | --------------------- | 2329| callback | [OnAdsBlockedCallback](./arkts-basic-components-web-t.md#onadsblockedcallback12) | Yes| Callback of **onAdsBlocked**.| 2330 2331**Example** 2332 2333 ```ts 2334 // xxx.ets 2335 import { webview } from '@kit.ArkWeb'; 2336 2337 @Entry 2338 @Component 2339 struct WebComponent { 2340 @State totalAdsBlockCounts: number = 0; 2341 controller: webview.WebviewController = new webview.WebviewController(); 2342 2343 build() { 2344 Column() { 2345 Web({ src: 'https://www.example.com', controller: this.controller }) 2346 .onAdsBlocked((details: AdsBlockedDetails) => { 2347 if (details) { 2348 console.log(' Blocked ' + details.adsBlocked.length + ' in ' + details.url); 2349 let adList: Array<string> = Array.from(new Set(details.adsBlocked)); 2350 this.totalAdsBlockCounts += adList.length; 2351 console.log('Total blocked counts :' + this.totalAdsBlockCounts); 2352 } 2353 }) 2354 } 2355 } 2356 } 2357 ``` 2358 2359## keyboardAvoidMode<sup>12+</sup> 2360 2361keyboardAvoidMode(mode: WebKeyboardAvoidMode) 2362 2363Sets the custom soft keyboard avoidance mode. 2364 2365If the keyboard avoidance mode set in **UIContext** is [KeyboardAvoidMode.RESIZE](../apis-arkui/js-apis-arkui-UIContext.md#keyboardavoidmode11), this API does not take effect. 2366 2367**System capability**: SystemCapability.Web.Webview.Core 2368 2369**Parameters** 2370 2371| Name | Type | Mandatory | Description | 2372| ------------------- | ------------------------------ | ------ | ------------- | 2373| mode | [WebKeyboardAvoidMode](./arkts-basic-components-web-e.md#webkeyboardavoidmode12) | Yes | Web soft keyboard avoidance mode.<br>In the nested scrolling scenario, the soft keyboard avoidance mode of the **Web** component is not recommended, including **RESIZE_VISUAL** and **RESIZE_CONTENT**.<br>Default value: **WebKeyboardAvoidMode.RESIZE_CONTENT**| 2374 2375**Example** 2376 2377 ```ts 2378 // xxx.ets 2379 import { webview } from '@kit.ArkWeb'; 2380 2381 @Entry 2382 @Component 2383 struct WebComponent { 2384 controller: webview.WebviewController = new webview.WebviewController(); 2385 @State avoidMode: WebKeyboardAvoidMode = WebKeyboardAvoidMode.RESIZE_VISUAL; 2386 2387 build() { 2388 Column() { 2389 Web({ src: $rawfile("index.html"), controller: this.controller }) 2390 .keyboardAvoidMode(this.avoidMode) 2391 } 2392 } 2393 } 2394 ``` 2395 2396 HTML file to be loaded: 2397 ```html 2398 <!--index.html--> 2399 <!DOCTYPE html> 2400 <html> 2401 <head> 2402 <title>Test Web Page</title> 2403 </head> 2404 <body> 2405 <input type="text" placeholder="Text"> 2406 </body> 2407 </html> 2408 ``` 2409 2410## editMenuOptions<sup>12+</sup> 2411 2412editMenuOptions(editMenu: EditMenuOptions) 2413 2414Sets the custom menu options of the **Web** component. 2415 2416You can use this attribute to customize a text menu. 2417 2418You can use [onCreateMenu](../apis-arkui/arkui-ts/ts-text-common.md#oncreatemenu12) to modify, add, and delete menu options. If you do not want to display the text menu, return an empty array. 2419 2420You can use [onMenuItemClick](../apis-arkui/arkui-ts/ts-text-common.md#onmenuitemclick12) to customize the callback for menu options. This function is triggered after a menu option is clicked and determines whether to execute the default callback based on the return value. If **true** is returned, the system callback is not executed. If **false** is returned, the system callback is executed. 2421 2422In onPrepareMenu<sup>20+</sup>, this callback is triggered after the text selection area changes and before the menu is displayed. You can modify, add, or delete menu options in the callback to dynamically update the menu. 2423 2424If this method is used together with [selectionMenuOptions<sup>(deprecated)</sup>](#selectionmenuoptionsdeprecated), the **selectionMenuOptions<sup> (deprecated) </sup>** method does not take effect. 2425 2426**System capability**: SystemCapability.Web.Webview.Core 2427 2428**Parameters** 2429 2430| Name | Type | Mandatory | Description | 2431| ------------------- | ------------------------------ | ------ | ------------- | 2432| editMenu | [EditMenuOptions](../apis-arkui/arkui-ts/ts-text-common.md#editmenuoptions) | Yes | Custom menu options of the **Web** component.<br>The number of menu options, menu content size, and icon size must be the same as those of the ArkUI [Menu](../apis-arkui/arkui-ts/ts-basic-components-menu.md) component.<br>The values of ([TextMenuItemId](../apis-arkui/arkui-ts/ts-text-common.md#textmenuitemid12)) supported by the **Web** component are **CUT**, **COPY**, **PASTE**, **SELECT_ALL**, **TRANSLATE**, **SEARCH**, and **AI_WRITER**.<br>**textRange** in **onMenuItemClick()** is meaningless in the **Web** component. The input value is **-1**.| 2433 2434**Example** 2435 2436```ts 2437// xxx.ets 2438import { webview } from '@kit.ArkWeb'; 2439 2440let selectText:string = ''; 2441class TestClass { 2442 setSelectText(param: String) { 2443 selectText = param.toString(); 2444 } 2445} 2446 2447@Entry 2448@Component 2449struct WebComponent { 2450 controller: webview.WebviewController = new webview.WebviewController(); 2451 @State testObj: TestClass = new TestClass(); 2452 2453 onCreateMenu(menuItems: Array<TextMenuItem>): Array<TextMenuItem> { 2454 let items = menuItems.filter((menuItem) => { 2455 // Filter the menu items as required. 2456 return ( 2457 menuItem.id.equals(TextMenuItemId.CUT) || 2458 menuItem.id.equals(TextMenuItemId.COPY) || 2459 menuItem.id.equals((TextMenuItemId.PASTE)) || 2460 menuItem.id.equals((TextMenuItemId.TRANSLATE)) || 2461 menuItem.id.equals((TextMenuItemId.SEARCH)) || 2462 menuItem.id.equals((TextMenuItemId.AI_WRITER)) 2463 ) 2464 }); 2465 let customItem1: TextMenuItem = { 2466 content: 'customItem1', 2467 id: TextMenuItemId.of('customItem1'), 2468 icon: $r('app.media.icon') 2469 }; 2470 let customItem2: TextMenuItem = { 2471 content: $r('app.string.customItem2'), 2472 id: TextMenuItemId.of('customItem2'), 2473 icon: $r('app.media.icon') 2474 }; 2475 items.push(customItem1);// Add an item to the end of the item list. 2476 items.unshift(customItem2);// Add an item to the beginning of the item list. 2477 2478 return items; 2479 } 2480 2481 onMenuItemClick(menuItem: TextMenuItem, textRange: TextRange): boolean { 2482 if (menuItem.id.equals(TextMenuItemId.CUT)) { 2483 // Custom behavior 2484 console.log("Intercept ID: CUT") 2485 return true; // Return true to not execute the system callback. 2486 } else if (menuItem.id.equals(TextMenuItemId.COPY)) { 2487 // Custom behavior 2488 console.log("Not intercept ID: COPY") 2489 return false; // Return false to execute the system callback. 2490 } else if (menuItem.id.equals(TextMenuItemId.of('customItem1'))) { 2491 // Custom behavior 2492 console.log("Intercept ID: customItem1") 2493 return true;// Custom menu item. If true is returned, the menu is not closed after being clicked. If false is returned, the menu is closed. 2494 } else if (menuItem.id.equals((TextMenuItemId.of($r('app.string.customItem2'))))){ 2495 // Custom behavior 2496 console.log("Intercept ID: app.string.customItem2") 2497 return true; 2498 } 2499 return false;// Return the default value false. 2500 } 2501 2502 onPrepareMenu(menuItems: Array<TextMenuItem>) => { 2503 let item1: TextMenuItem = { 2504 content: 'prepare1', 2505 id: TextMenuItemId.of('prepareMenu1'), 2506 }; 2507 let item2: TextMenuItem = { 2508 content: 'prepare2' + selectText, 2509 id: TextMenuItemId.of('prepareMenu2'), 2510 }; 2511 items.push(item1);// Add an item to the end of the item list. 2512 items.unshift(item2);// Add an item to the beginning of the item list. 2513 2514 return items; 2515 } 2516 2517 @State EditMenuOptions: EditMenuOptions = 2518 { onCreateMenu: this.onCreateMenu, onMenuItemClick: this.onMenuItemClick, onPrepareMenu:this.onPrepareMenu } 2519 2520 build() { 2521 Column() { 2522 Web({ src: $rawfile("index.html"), controller: this.controller }) 2523 .editMenuOptions(this.EditMenuOptions) 2524 .javaScriptProxy({ 2525 object: this.testObj, 2526 name: "testObjName", 2527 methodList: ["setSelectText"], 2528 controller: this.controller, 2529 }) 2530 } 2531 } 2532} 2533``` 2534 2535 HTML file to be loaded: 2536```html 2537<!--index.html--> 2538<!DOCTYPE html> 2539<html> 2540 <head> 2541 <title>Test Web Page</title> 2542 </head> 2543 <body> 2544 <h1>editMenuOptions Demo</h1> 2545 <span>edit menu options</span> 2546 <script> 2547 function callArkTS() { 2548 let str = testObjName.test(); 2549 document.getElementById("demo").innerHTML = str; 2550 } 2551 2552 document.addEventListener('selectionchange', () => { 2553 var selection = window.getSelection(); 2554 if (selection.rangeCount > 0) { 2555 var selectedText = selection.toString(); 2556 testObjName.setSelectText(selectedText); 2557 } 2558 callArkTS(); 2559 }); 2560 </script> 2561 </body> 2562</html> 2563``` 2564 2565## enableHapticFeedback<sup>13+</sup> 2566 2567enableHapticFeedback(enabled: boolean) 2568 2569Sets whether to enable haptic feedback for long-pressed text in the **Web** component. The **ohos.permission.VIBRATE** permission must be declared. 2570 2571**System capability**: SystemCapability.Web.Webview.Core 2572 2573**Parameters** 2574 2575| Name | Type | Mandatory | Description| 2576| --------- | --------- | ------ | ------------- | 2577| enabled | boolean | Yes | Whether to enable haptic feedback for long-pressed text in the **Web** component.<br>The value **true** means to enable haptic feedback for long-pressed text in the **Web** component, and **false** means the opposite.<br>Default value: **true**| 2578 2579**Example** 2580 2581```ts 2582// xxx.ets 2583import { webview } from '@kit.ArkWeb'; 2584 2585@Entry 2586@Component 2587struct WebComponent { 2588 controller: webview.WebviewController = new webview.WebviewController(); 2589 2590 build() { 2591 Column() { 2592 Web({ src: $rawfile("index.html"), controller: this.controller }) 2593 .enableHapticFeedback(true) 2594 } 2595 } 2596} 2597``` 2598 2599 HTML file to be loaded: 2600```html 2601<!--index.html--> 2602<!DOCTYPE html> 2603<html> 2604 <head> 2605 <title>Test Web Page</title> 2606 </head> 2607 <body> 2608 <h1>enableHapticFeedback Demo</h1> 2609 <span>enable haptic feedback</span> 2610 </body> 2611</html> 2612``` 2613 2614## bindSelectionMenu<sup>13+</sup> 2615 2616bindSelectionMenu(elementType: WebElementType, content: CustomBuilder, responseType: WebResponseType, options?: SelectionMenuOptionsExt) 2617 2618Sets the custom selection menu. 2619 2620**System capability**: SystemCapability.Web.Webview.Core 2621 2622**Parameters** 2623 2624| Name | Type | Mandatory| Description | 2625| ------------ | ------------------------------- | ---- | ----------------------------------- | 2626| elementType | [WebElementType](./arkts-basic-components-web-e.md#webelementtype13) | Yes | Menu type. | 2627| content | [CustomBuilder](../apis-arkui/arkui-ts/ts-types.md#custombuilder8) | Yes | Menu content. | 2628| responseType | [WebResponseType](./arkts-basic-components-web-e.md#webresponsetype13) | Yes | Response type of the menu.| 2629| options | [SelectionMenuOptionsExt](./arkts-basic-components-web-i.md#selectionmenuoptionsext13) | No | Menu options.| 2630 2631**Example** 2632 2633```ts 2634// xxx.ets 2635import { webview } from '@kit.ArkWeb'; 2636 2637interface PreviewBuilderParam { 2638 previewImage: Resource | string | undefined; 2639 width: number; 2640 height: number; 2641} 2642 2643@Builder function PreviewBuilderGlobal($$: PreviewBuilderParam) { 2644 Column() { 2645 Image($$.previewImage) 2646 .objectFit(ImageFit.Fill) 2647 .autoResize(true) 2648 }.width($$.width).height($$.height) 2649} 2650 2651@Entry 2652@Component 2653struct WebComponent { 2654 controller: webview.WebviewController = new webview.WebviewController(); 2655 2656 private result: WebContextMenuResult | undefined = undefined; 2657 @State previewImage: Resource | string | undefined = undefined; 2658 @State previewWidth: number = 0; 2659 @State previewHeight: number = 0; 2660 uiContext: UIContext = this.getUIContext(); 2661 2662 @Builder 2663 MenuBuilder() { 2664 Menu() { 2665 MenuItem({ content: 'Copy', }) 2666 .onClick(() => { 2667 this.result?.copy(); 2668 this.result?.closeContextMenu(); 2669 }) 2670 MenuItem({ content: 'Select All', }) 2671 .onClick(() => { 2672 this.result?.selectAll(); 2673 this.result?.closeContextMenu(); 2674 }) 2675 } 2676 } 2677 build() { 2678 Column() { 2679 Web({ src: $rawfile("index.html"), controller: this.controller }) 2680 .bindSelectionMenu(WebElementType.IMAGE, this.MenuBuilder, WebResponseType.LONG_PRESS, 2681 { 2682 onAppear: () => {}, 2683 onDisappear: () => { 2684 this.result?.closeContextMenu(); 2685 }, 2686 preview: PreviewBuilderGlobal({ 2687 previewImage: this.previewImage, 2688 width: this.previewWidth, 2689 height: this.previewHeight 2690 }), 2691 menuType: MenuType.PREVIEW_MENU 2692 }) 2693 .onContextMenuShow((event) => { 2694 if (event) { 2695 this.result = event.result; 2696 if (event.param.getLinkUrl()) { 2697 return false; 2698 } 2699 this.previewWidth = this.uiContext!.px2vp(event.param.getPreviewWidth()); 2700 this.previewHeight = this.uiContext!.px2vp(event.param.getPreviewHeight()); 2701 if (event.param.getSourceUrl().indexOf("resource://rawfile/") == 0) { 2702 this.previewImage = $rawfile(event.param.getSourceUrl().substr(19)); 2703 } else { 2704 this.previewImage = event.param.getSourceUrl(); 2705 } 2706 return true; 2707 } 2708 return false; 2709 }) 2710 } 2711 } 2712} 2713``` 2714 2715 HTML file to be loaded: 2716```html 2717<!--index.html--> 2718<!DOCTYPE html> 2719<html> 2720 <head> 2721 <title>Test Web Page</title> 2722 </head> 2723 <body> 2724 <h1>bindSelectionMenu Demo</h1> 2725 <img src="./img.png" > 2726 </body> 2727</html> 2728``` 2729 2730## blurOnKeyboardHideMode<sup>14+</sup> 2731 2732blurOnKeyboardHideMode(mode: BlurOnKeyboardHideMode) 2733 2734Sets whether to enable blur mode for the web element when soft keyboard is hidden. 2735 2736**System capability**: SystemCapability.Web.Webview.Core 2737 2738**Parameters** 2739 2740| Name | Type | Mandatory | Description | 2741| ---- | --------------------------------------- | ---- | ------------------ | 2742| mode | [BlurOnKeyboardHideMode](./arkts-basic-components-web-e.md#bluronkeyboardhidemode14) | Yes | Whether to enable blur mode of the web element when soft keyboard is hidden. The default value is **BlurOnKeyboardHideMode.SILENT**.| 2743 2744**Example** 2745 2746 ```ts 2747 // xxx.ets 2748 import { webview } from '@kit.ArkWeb'; 2749 2750 @Entry 2751 @Component 2752 struct WebComponent { 2753 controller: webview.WebviewController = new webview.WebviewController(); 2754 @State blurMode: BlurOnKeyboardHideMode = BlurOnKeyboardHideMode.BLUR; 2755 build() { 2756 Column() { 2757 Web({ src: $rawfile("index.html"), controller: this.controller }) 2758 .blurOnKeyboardHideMode(this.blurMode) 2759 } 2760 } 2761 } 2762 ``` 2763 2764 HTML file to be loaded: 2765```html 2766<!--index.html--> 2767<!DOCTYPE html> 2768<html> 2769 <head> 2770 <title>Test Web Page</title> 2771 </head> 2772 <body> 2773 <h1>blurOnKeyboardHideMode Demo</h1> 2774 <input type="text" id="input_a"> 2775 <script> 2776 const inputElement = document.getElementById('input_a'); 2777 inputElement.addEventListener('blur', function() { 2778 console.log('Input has lost focus'); 2779 }); 2780 </script> 2781 </body> 2782</html> 2783``` 2784 2785## enableFollowSystemFontWeight<sup>18+</sup> 2786 2787enableFollowSystemFontWeight(follow: boolean) 2788 2789Sets whether the **Web** component can change the font weight according to the system settings. 2790 2791> **NOTE** 2792> 2793> Currently, only front-end text elements support this capability. The **canvas** element and embedded .docx and .pdf texts do not support this capability. 2794 2795**System capability**: SystemCapability.Web.Webview.Core 2796 2797**Parameters** 2798 2799| Name | Type | Mandatory| Description | 2800| ------------ | ------------------------------- | ---- | ----------------------------------- | 2801| follow | boolean | Yes | Whether the **Web** component can change the font weight according to the system settings.<br>The value **true** means that the **Web** component can change the font weight according to the system settings, and **false** means the opposite.<br>The default value is **false**.| 2802 2803**Example** 2804 2805 ```ts 2806 // xxx.ets 2807 import { webview } from '@kit.ArkWeb'; 2808 2809 @Entry 2810 @Component 2811 struct WebComponent { 2812 controller: webview.WebviewController = new webview.WebviewController(); 2813 build() { 2814 Column() { 2815 Web({ src: "www.example.com", controller: this.controller }) 2816 .enableFollowSystemFontWeight(true) 2817 } 2818 } 2819 } 2820 ``` 2821 2822## optimizeParserBudget<sup>15+</sup> 2823 2824optimizeParserBudget(optimizeParserBudget: boolean) 2825 2826Sets whether to enable segment-based HTML parsing optimization. 2827 2828To avoid occupying too many main thread resources and enable progressive loading of web pages, the ArkWeb kernel uses the segment-based parsing policy when parsing the HTML files. By default, the ArkWeb kernel uses the parsing time as the segment point. When the parsing time exceeds the threshold, the parsing is interrupted and then the layout and rendering operations are performed. 2829 2830After this optimization is enabled, the ArkWeb kernel checks whether the parsing time exceeds the limit and whether the number of parsed tokens (minimum parsing unit of HTML files, such as **\<div>** and **attr="xxx"**) exceeds the threshold specified by the kernel. If yes, the ArkWeb kernel decreases the threshold. When the First Contentful Paint (FCP) of the page is triggered, the default interrupt judgment logic is restored. In this way, the web page is parsed more frequently before the FCP is triggered, thereby the first-frame content may be parsed in advance and enter a rendering phase, effectively reducing the workload of first-frame rendering, and finally advancing the FCP. 2831 2832When the FCP of a page is triggered, the default segment parsing logic is restored. Therefore, the segment-based HTML parsing optimization takes effect only for the first page loaded by each **Web** component. 2833 2834**System capability**: SystemCapability.Web.Webview.Core 2835 2836**Parameters** 2837 2838| Name | Type | Mandatory | Description | 2839| ---------- | ------- | ---- | ---------------------- | 2840| optimizeParserBudget | boolean | Yes | Whether to enable segment-based HTML parsing optimization.<br>The value **true** means to use the number of parsed records instead of the parsing time as the segment point for HTML segment parsing, and reduce the upper limit of the number of parsed records in each segment. The value **false** means to use the parsing time as the segment point for HTML segment parsing.<br>The default value is **false**.| 2841 2842 2843**Example** 2844 2845 ```ts 2846 // xxx.ets 2847 import { webview } from '@kit.ArkWeb'; 2848 2849 @Entry 2850 @Component 2851 struct WebComponent { 2852 controller: webview.WebviewController = new webview.WebviewController() 2853 build() { 2854 Column() { 2855 Web({ src: 'www.example.com', controller: this.controller }) 2856 .optimizeParserBudget(true) 2857 } 2858 } 2859 } 2860 ``` 2861 2862## enableWebAVSession<sup>18+</sup> 2863 2864enableWebAVSession(enabled: boolean) 2865 2866Sets whether to support an application to connect to media controller. 2867 2868**System capability**: SystemCapability.Web.Webview.Core 2869 2870**Parameters** 2871 2872| Name | Type| Mandatory| Description | 2873| ------- | -------- | ---- | ------------------ | 2874| enabled | boolean | Yes | Whether to support an application to connect to media controller.<br>The value **true** means to support an application to connect to media controller, and **false** means the opposite.<br>Default value: **true**| 2875 2876**Example** 2877 2878 ```ts 2879 // xxx.ets 2880 import { webview } from '@kit.ArkWeb'; 2881 2882 @Entry 2883 @Component 2884 struct WebComponent { 2885 controller: webview.WebviewController = new webview.WebviewController(); 2886 build() { 2887 Column() { 2888 Web({ src: $rawfile('index.html'), controller: this.controller }) 2889 .enableWebAVSession(true) 2890 } 2891 } 2892 } 2893 ``` 2894 2895 HTML file to be loaded: 2896 ```html 2897 <!--index.html--> 2898 <!DOCTYPE html> 2899 <html> 2900 <head> 2901 <title>Video Playback Page</title> 2902 </head> 2903 <body> 2904 <h1>Video Playback</h1> 2905 <video id="testVideo" controls> 2906 // Save an MP4 media file in the rawfile directory of resources and name it example.mp4. 2907 <source src="example.mp4" type="video/mp4"> 2908 </video> 2909 </body> 2910 </html> 2911 ``` 2912 2913## nativeEmbedOptions<sup>16+</sup> 2914 2915nativeEmbedOptions(options?: EmbedOptions) 2916 2917Sets the same-layer rendering configuration. This attribute takes effect only when [enableNativeEmbedMode](#enablenativeembedmode11) is enabled and cannot be dynamically modified. 2918 2919**System capability**: SystemCapability.Web.Webview.Core 2920 2921**Parameters** 2922 2923| Name | Type | Mandatory| Description | 2924| ------------ | ------------------------------- | ---- | ----------------------------------- | 2925| options | [EmbedOptions](./arkts-basic-components-web-i.md#embedoptions16) | No | Same-layer rendering configuration. The default value is **{supportDefaultIntrinsicSize: false}**.| 2926 2927**Example** 2928 2929 ```ts 2930 // xxx.ets 2931 import { webview } from '@kit.ArkWeb'; 2932 2933 @Entry 2934 @Component 2935 struct WebComponent { 2936 controller: webview.WebviewController = new webview.WebviewController(); 2937 options: EmbedOptions = {supportDefaultIntrinsicSize: true}; 2938 2939 build() { 2940 Column() { 2941 Web({ src: $rawfile("index.html"), controller: this.controller }) 2942 .enableNativeEmbedMode(true) 2943 .nativeEmbedOptions(this.options) 2944 } 2945 } 2946 } 2947 ``` 2948HTML file to be loaded: 2949 ```html 2950 <!-- index.html --> 2951 <!DOCTYPE html> 2952 <html> 2953 <head> 2954 <title>Same-Layer Rendered Fixed-Size HTML Test</title> 2955 </head> 2956 <body> 2957 <div> 2958 <embed id="input" type = "native/view" style = "background-color:red"/> 2959 </div> 2960 </body> 2961 </html> 2962 ``` 2963## enableDataDetector<sup>20+</sup> 2964 2965enableDataDetector(enable: boolean) 2966 2967Sets whether to recognize special entities of web texts. This API depends on the text recognition capability at the bottom layer of the device. Otherwise, the setting is invalid. 2968 2969If **enableDataDetector** is set to **true** and [dataDetectorConfig](#datadetectorconfig20) is not set, all types of entities will be recognized, and the **color** and **decoration** attributes of the recognized entities will be changed to the following styles: 2970<!--code_no_check--> 2971```ts 2972color: '#ff007dff' 2973decoration:{ 2974 type: TextDecorationType.Underline, 2975 color: '#ff007dff', 2976 style: TextDecorationStyle.SOLID 2977} 2978``` 2979 2980Currently, full-text entity recognition is triggered only after the page is loaded. The filtering rules for entity recognition are as follows: 2981 2982- Text entities in the text box and editable area are not processed. 2983- The text entity in the <a></a> tag is not processed. 2984- Text entities in cross-domain iframes and nested iframes are not processed. 2985- Cross-node entities are not recognized. For example, `<div>Satu</div><div>rday</div>`. 2986 2987 2988After a text entity on a web page is processed, it is converted into a hyperlink. When you touch or click the entity, the corresponding entity operation menu is displayed based on the entity type. Long-press, touch-drag, right-click, or mouse-drag on a hyperlink will trigger its default action. 2989 2990If the calculation style of the page text element contains **user-select:none** or the page Javascript intercepts the **select** event, the **Select text** option in the entity menu is invalid, but the entity text can still be copied. 2991 2992**System capability**: SystemCapability.Web.Webview.Core 2993 2994**Parameters** 2995 2996| Name| Type | Mandatory| Description | 2997| ------ | ------- | ---- | --------------------------------- | 2998| enable | boolean | Yes | Whether to enable web text recognition. The value **true** means to enable web text recognition, and **false** means the opposite.<br>Default value: **false**.| 2999 3000**Example** 3001 3002 ```ts 3003 // xxx.ets 3004 import { webview } from '@kit.ArkWeb'; 3005 3006 @Entry 3007 @Component 3008 struct WebComponent { 3009 controller: webview.WebviewController = new webview.WebviewController(); 3010 3011 build() { 3012 Column() { 3013 Web({ src: $rawfile("index.html"), controller: this.controller }) 3014 .enableDataDetector(true) 3015 } 3016 } 3017 } 3018 ``` 3019HTML file to be loaded: 3020 ```html 3021 <!-- index.html --> 3022 <!DOCTYPE html> 3023 <html> 3024 <head> 3025 <title>Example enableDataDetector</title>; 3026 </head> 3027 <body> 3028 <p> Telephone: 400-123-4567 </p> 3029 <p>Email: example@example.com </p> 3030 </body> 3031 </html> 3032 ``` 3033 3034## dataDetectorConfig<sup>20+</sup> 3035 3036dataDetectorConfig(config: TextDataDetectorConfig) 3037 3038Configures text recognition settings. 3039 3040This API must be used together with [enableDataDetector](#enabledatadetector20). It takes effect only when **enableDataDetector** is set to **true**. 3041 3042When entities A and B overlap, the following rules are followed: 3043 30441. If A is a subset of B (A ⊂ B), then B is retained; otherwise, A is retained. 3045 30462. If A is not a subset of B (A ⊄ B) and B is not a subset of A (B ⊄ A), and if the starting point of A is earlier than that of B (A.start < B.start), then A is retained; otherwise, B is retained. 3047 3048 3049**System capability**: SystemCapability.Web.Webview.Core 3050 3051**Parameters** 3052 3053| Name| Type | Mandatory| Description | 3054| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3055| config | [TextDataDetectorConfig](../apis-arkui/arkui-ts/ts-text-common.md#textdatadetectorconfig11)| Yes | Text recognition configuration.| 3056 3057> **NOTE** 3058> 3059> The **onDetectResultUpdate** method in **TextDataDetectorConfig** is not supported in the **Web** component. The configured callback will not be called. 3060 3061**Example** 3062 3063 ```ts 3064 // xxx.ets 3065 import { webview } from '@kit.ArkWeb'; 3066 3067 @Entry 3068 @Component 3069 struct WebComponent { 3070 controller: webview.WebviewController = new webview.WebviewController(); 3071 3072 build() { 3073 Column() { 3074 Web({ src: $rawfile("index.html"), controller: this.controller }) 3075 .enableDataDetector(true) 3076 .dataDetectorConfig({ 3077 types: [ 3078 TextDataDetectorType.PHONE_NUMBER, 3079 TextDataDetectorType.EMAIL 3080 ], 3081 color: Color.Red, 3082 decoration: { 3083 type: TextDecorationType.LineThrough, 3084 color: Color.Green, 3085 style: TextDecorationStyle.WAVY 3086 } 3087 }) 3088 } 3089 } 3090 } 3091 ``` 3092HTML file to be loaded: 3093 ```html 3094 <!-- index.html --> 3095 <!DOCTYPE html> 3096 <html> 3097 <head> 3098 <title>Example dataDetectorConfig</title>; 3099 </head> 3100 <body> 3101 <p> Telephone: 400-123-4567 </p> 3102 <p> Email: 12345678901@example.com </p> 3103 <p> Website: www.example.com (cannot be identified) </p> 3104 </body> 3105 </html> 3106 ``` 3107 3108## gestureFocusMode<sup>20+</sup> 3109 3110gestureFocusMode(mode: GestureFocusMode) 3111 3112Sets the gesture focus mode of the **Web** component. 3113 3114**System capability**: SystemCapability.Web.Webview.Core 3115 3116**Parameters** 3117 3118| Name | Type | Mandatory | Description | 3119| ------------------- | ------------------------------ | ------ | ------------- | 3120| mode | [GestureFocusMode](./arkts-basic-components-web-e.md#gesturefocusmode20) | Yes | Gesture focus mode of the **Web** component.<br>Default value: **GestureFocusMode.DEFAULT**, indicating that the **Web** component is focused when any gesture is performed on it.| 3121 3122**Example** 3123 3124 ```ts 3125 // xxx.ets 3126 import { webview } from '@kit.ArkWeb'; 3127 3128 @Entry 3129 @Component 3130 struct WebComponent { 3131 controller: webview.WebviewController = new webview.WebviewController(); 3132 @State mode: GestureFocusMode = GestureFocusMode.DEFAULT; 3133 build() { 3134 Column() { 3135 Web({ src: $rawfile("index.html"), controller: this.controller }) 3136 .gestureFocusMode(this.mode) 3137 } 3138 } 3139 } 3140 ``` 3141 3142 HTML file to be loaded: 3143 ```html 3144 <!--index.html--> 3145 <!DOCTYPE html> 3146 <html> 3147 <head> 3148 <title>Test Web Page</title> 3149 </head> 3150 <body> 3151 <input type="text" placeholder="Text"> 3152 </body> 3153 </html> 3154 ``` 3155 3156## password<sup>(deprecated)</sup> 3157 3158password(password: boolean) 3159 3160Sets whether to save the password. This API is an empty API. 3161 3162> **NOTE** 3163> 3164> This API is deprecated since API version 10, and no new API is provided as a substitute. 3165 3166**System capability**: SystemCapability.Web.Webview.Core 3167 3168## textZoomAtio<sup>(deprecated)</sup> 3169 3170textZoomAtio(textZoomAtio: number) 3171 3172Sets the text zoom ratio of the page. 3173 3174**System capability**: SystemCapability.Web.Webview.Core 3175 3176This API is deprecated since API version 9. You are advised to use [textZoomRatio<sup>9+</sup>](#textzoomratio9) instead. 3177 3178**Parameters** 3179 3180| Name | Type | Mandatory | Description | 3181| ------------ | ------ | ---- | -------------------------------- | 3182| textZoomAtio | number | Yes | Text zoom ratio to set.<br>The value is a positive integer.<br>Default value: **100**| 3183 3184**Example** 3185 3186 ```ts 3187 // xxx.ets 3188 @Entry 3189 @Component 3190 struct WebComponent { 3191 controller: WebController = new WebController() 3192 @State ratio: number = 150 3193 build() { 3194 Column() { 3195 Web({ src: 'www.example.com', controller: this.controller }) 3196 .textZoomAtio(this.ratio) 3197 } 3198 } 3199 } 3200 ``` 3201 3202## userAgent<sup>(deprecated)</sup> 3203 3204userAgent(userAgent: string) 3205 3206Sets the user agent. 3207 3208> **NOTE** 3209> 3210> This API is supported since API version 8 and deprecated since API version 10. You are advised to use [setCustomUserAgent](./arkts-apis-webview-WebviewController.md#setcustomuseragent10)<sup>10+</sup> instead. 3211 3212**System capability**: SystemCapability.Web.Webview.Core 3213 3214**Parameters** 3215 3216| Name | Type | Mandatory | Description | 3217| --------- | ------ | ---- | --------- | 3218| userAgent | string | Yes | User agent to set.| 3219 3220**Example** 3221 3222 ```ts 3223 // xxx.ets 3224 import { webview } from '@kit.ArkWeb'; 3225 3226 @Entry 3227 @Component 3228 struct WebComponent { 3229 controller: webview.WebviewController = new webview.WebviewController(); 3230 @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'; 3231 3232 build() { 3233 Column() { 3234 Web({ src: 'www.example.com', controller: this.controller }) 3235 .userAgent(this.userAgent) 3236 } 3237 } 3238 } 3239 ``` 3240 3241## tableData<sup>(deprecated)</sup> 3242 3243tableData(tableData: boolean) 3244 3245Sets whether to save form data. This API is an empty API. 3246 3247> **NOTE** 3248> 3249> This API is deprecated since API version 10, and no new API is provided as a substitute. 3250 3251**System capability**: SystemCapability.Web.Webview.Core 3252 3253## wideViewModeAccess<sup>(deprecated)</sup> 3254 3255wideViewModeAccess(wideViewModeAccess: boolean) 3256 3257Sets whether to support the **viewport** attribute of the HTML \<meta> tag. This API is an empty API. 3258 3259> **NOTE** 3260> 3261> This API is deprecated since API version 10, and no new API is provided as a substitute. 3262 3263**System capability**: SystemCapability.Web.Webview.Core 3264 3265## selectionMenuOptions<sup>(deprecated)</sup> 3266 3267selectionMenuOptions(expandedMenuOptions: Array\<ExpandedMenuItemOptions>) 3268 3269Sets the extended options of the custom context menu on selection, including the text content, icon, and callback. 3270 3271The API only supports the selection of plain text; if the selected content contains images or other non-text elements, the **action** information may display garbled content. 3272 3273> **NOTE** 3274> 3275> This API is supported since API version 12 and deprecated since API version 20. You are advised to use [editMenuOptions<sup>12+</sup>](#editmenuoptions12) instead. 3276 3277**System capability**: SystemCapability.Web.Webview.Core 3278 3279**Parameters** 3280 3281| Name | Type | Mandatory | Description | 3282| ------------------- | ---------------------------------------------------------- | ---- | ------------- | 3283| expandedMenuOptions | Array<[ExpandedMenuItemOptions](./arkts-basic-components-web-i.md#expandedmenuitemoptions12)> | Yes | Extended options of the custom context menu on selection.<br>The number of menu options, menu content size, and start icon size must be the same as those of the ArkUI [Menu](../apis-arkui/arkui-ts/ts-basic-components-menu.md) component.| 3284 3285**Example** 3286 3287 ```ts 3288 // xxx.ets 3289 import { webview } from '@kit.ArkWeb'; 3290 3291 @Entry 3292 @Component 3293 struct WebComponent { 3294 controller: webview.WebviewController = new webview.WebviewController(); 3295 @State menuOptionArray: Array<ExpandedMenuItemOptions> = [ 3296 {content: 'Apple', startIcon: $r('app.media.icon'), action: (selectedText) => { 3297 console.info('select info ' + selectedText.toString()); 3298 }}, 3299 {content: 'Banana', startIcon: $r('app.media.icon'), action: (selectedText) => { 3300 console.info('select info ' + selectedText.toString()); 3301 }} 3302 ]; 3303 3304 build() { 3305 Column() { 3306 Web({ src: $rawfile("index.html"), controller: this.controller }) 3307 .selectionMenuOptions(this.menuOptionArray) 3308 } 3309 } 3310 } 3311 ``` 3312 3313 HTML file to be loaded: 3314 ```html 3315 <!--index.html--> 3316 <!DOCTYPE html> 3317 <html> 3318 <head> 3319 <title>Test Web Page</title> 3320 </head> 3321 <body> 3322 <h1>selectionMenuOptions Demo</h1> 3323 <span>selection menu options</span> 3324 </body> 3325 </html> 3326 ``` 3327
