We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
Advanced filters
API versionAll
DeviceAll
Atomic service APIsNot filter by this

Attributes

Last updated: 2026-09-10 06:21
Content overview
Overview
domStorageAccess
fileAccess
imageAccess
javaScriptProxy
javaScriptAccess
overScrollMode11+
mixedMode
onlineImageAccess
zoomAccess
overviewModeAccess
databaseAccess
geolocationAccess
mediaPlayGestureAccess9+
multiWindowAccess9+
horizontalScrollBarAccess9+
verticalScrollBarAccess9+
cacheMode
copyOptions11+
textZoomRatio9+
initialScale9+
blockNetwork9+
defaultFixedFontSize9+
defaultFontSize9+
minFontSize9+
minLogicalFontSize9+
webFixedFont9+
webSansSerifFont9+
webSerifFont9+
webStandardFont9+
webFantasyFont9+
webCursiveFont9+
darkMode9+
forceDarkAccess9+
pinchSmooth9+
allowWindowOpenMethod10+
mediaOptions10+
javaScriptOnDocumentStart11+
javaScriptOnDocumentEnd11+
runJavaScriptOnDocumentStart15+
runJavaScriptOnDocumentEnd15+
runJavaScriptOnHeadEnd15+
layoutMode11+
nestedScroll11+
enableScrollDirectionalLock
bypassVsyncCondition20+
enableNativeEmbedMode11+
forceDisplayScrollBar14+
registerNativeEmbedRule12+
defaultTextEncodingFormat12+
metaViewport12+
textAutosizing12+
enableNativeMediaPlayer12+
onAdsBlocked12+
keyboardAvoidMode12+
editMenuOptions12+
enableHapticFeedback13+
bindSelectionMenu13+
blurOnKeyboardHideMode14+
enableFollowSystemFontWeight18+
optimizeParserBudget15+
enableWebAVSession18+
nativeEmbedOptions16+
enableDataDetector20+
dataDetectorConfig20+
enableSelectedDataDetector22+
gestureFocusMode20+
rotateRenderEffect22+
forceEnableZoom21+
backToTop22+
blankScreenDetectionConfig22+
enableImageAnalyzer23+
enableAutoFill23+
enableDefaultContextMenu24+
enableDrag
password(deprecated)
textZoomAtio(deprecated)
userAgent(deprecated)
tableData(deprecated)
wideViewModeAccess(deprecated)
selectionMenuOptions(deprecated)
zoomControlAccess22+
aiSessionOptions
scrollbarLayoutPolicy
keyboardAppearance
enableFullscreenVideoOverlay
enableMediaNetworkProxy
Expand

The supported universal attributes include aspectRatio, backdropBlur, backgroundColor, bindContentCover, bindContextMenu, bindMenu, bindSheet, borderColor, borderRadius, borderStyle, borderWidth, clip, constraintSize, defaultFocus, focusable, tabIndex, groupDefaultFocus, displayPriority, enabled, flexBasis, flexShrink, layoutWeight, id, gridOffset, gridSpan, useSizeType, height, touchable, margin, markAnchor, offset, width, zIndex, visibility, scale, translate, responseRegion, size, opacity, shadow, sharedTransition, transition, position, and direction.

NOTE

  • This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.

  • The sample effect is subject to the actual device.

Overview

Web component attributes are used to configure the web page loading behavior, security policies, runtime environment, and interaction capabilities of the Web component through chain calls in the ArkUI declarative syntax. They serve as the primary entry point for customizing Web component behavior. For general style and layout attributes (such as size, margin, background, and visibility), see Size Settings. This chapter describes only attributes specific to the Web component. For runtime dynamic control capabilities (such as loading URLs, navigating forward/backward, registering/unregistering JS objects, running JavaScript, and injecting CSS), use them together with WebviewController.

domStorageAccess

domStorageAccess(domStorageAccess: boolean)

Sets whether to enable the DOM Storage API permission. If this attribute is not explicitly called, the DOM Storage API permission is disabled by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
domStorageAccess boolean Yes

Set whether to enable the document object model storage interface (DOM Storage API) permission.

true indicates enabling, and false indicates disabling.

When undefined or null is passed in, the value is false.
NOTE
  • A web page can be loaded only when its DOM Storage API is set to true.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .domStorageAccess(true)
  13.     }
  14.   }
  15. }

fileAccess

fileAccess(fileAccess: boolean)

Sets 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). For API version 11 and earlier versions, access to the file system in the application is enabled by default if this attribute is not explicitly called. Since API version 12, access to the file system in the application is disabled by default if this attribute is not explicitly called.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
fileAccess boolean Yes

Whether to enable access to the file system in the app.

The value true means to enable, and false means to disable.

In addition, when fileAccess is false, resources in the read-only resource directory /data/storage/el1/bundle/entry/resources/resfile can still be accessed through the file protocol, which is not controlled by fileAccess.

In API version 11 and earlier, the value is true when undefined or null is passed. In API version 12 and later, the value is false when undefined or null is passed.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .fileAccess(true)
  13.     }
  14.   }
  15. }

imageAccess

imageAccess(imageAccess: boolean)

Sets whether to allow automatic loading of image resources. If this attribute is not explicitly called, automatic loading is allowed by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
imageAccess boolean Yes

Set whether to allow automatic loading of image resources.

true indicates allowing, and false indicates disallowing.

The value is false when undefined or null is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .imageAccess(true)
  13.     }
  14.   }
  15. }

javaScriptProxy

javaScriptProxy(javaScriptProxy: JavaScriptProxy)

Registers the ArkTS object in javaScriptProxy with the Web component. The object will be registered in all frames of the web page, including all iframes, using the name specified in JavaScriptProxy. This enables JavaScript to call methods of the ArkTS object in javaScriptProxy.

NOTE

The javaScriptProxy API must be used together with deleteJavaScriptRegister9+ to prevent memory leaks.

All parameters of the javaScriptProxy object cannot be updated.

When registering a javaScriptProxy object, at least one of the synchronous or asynchronous method lists must be non-empty. Both types of methods can be registered simultaneously.

This API supports registering only one object. To register multiple objects, use registerJavaScriptProxy9+.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
javaScriptProxy JavaScriptProxy Yes

Object to be registered. Methods can be declared, but attributes cannot.

When undefined or null is passed in, the ArkTS object in javaScriptProxy is not registered with the Web component.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. 

  5. class TestObj {
  6.   constructor() {
  7.   }
  8. 

  9.   test(data1: string, data2: string, data3: string): string {
  10.     console.info("data1:" + data1);
  11.     console.info("data2:" + data2);
  12.     console.info("data3:" + data3);
  13.     return "AceString";
  14.   }
  15. 

  16.   asyncTest(data: string): void {
  17.     console.info("async data:" + data);
  18.   }
  19. 

  20.   toString(): void {
  21.     console.info('toString' + "interface instead.");
  22.   }
  23. }
  24. 

  25. @Entry
  26. @Component
  27. struct WebComponent {
  28.   controller: webview.WebviewController = new webview.WebviewController();
  29.   testObj = new TestObj();
  30.   build() {
  31.     Column() {
  32.       Button('deleteJavaScriptRegister')
  33.         .onClick(() => {
  34.           try {
  35.             this.controller.deleteJavaScriptRegister("objName");
  36.           } catch (error) {
  37.             console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
  38.           }
  39.         })
  40.       Web({ src: 'www.example.com', controller: this.controller })
  41.         .javaScriptAccess(true)
  42.         .javaScriptProxy({
  43.           object: this.testObj,
  44.           name: "objName",
  45.           methodList: ["test", "toString"],
  46.           asyncMethodList: ["asyncTest"],
  47.           controller: this.controller,
  48.       })
  49.     }
  50.   }
  51. }

javaScriptAccess

javaScriptAccess(javaScriptAccess: boolean)

Sets whether to allow execution of JavaScript scripts. If this attribute is not explicitly called, execution is allowed by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
javaScriptAccess boolean Yes

Whether to allow JavaScript scripts to be executed.

true indicates allowing, and false indicates disallowing.

The value is false when undefined or null is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   build() {
  9.     Column() {
  10.       Web({ src: 'www.example.com', controller: this.controller })
  11.         .javaScriptAccess(true)
  12.     }
  13.   }
  14. }

overScrollMode11+

overScrollMode(mode: OverScrollMode)

Sets the over-scroll mode of the Web component. When enabled, if the user scrolls to the edge of the root web page, the Web component bounces back with an elastic animation, and inner pages on the root page do not trigger the bounce effect. If this attribute is not explicitly called, the over-scroll mode is disabled by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
mode OverScrollMode Yes

Whether to enable the overscroll mode.

When undefined or null is passed in, the value is OverScrollMode.NEVER.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State mode: OverScrollMode = OverScrollMode.ALWAYS;
  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .overScrollMode(this.mode)
  13.     }
  14.   }
  15. }

mixedMode

mixedMode(mixedMode: MixedMode)

Sets the behavior when a secure source attempts to load resources from an insecure source. When this attribute is not explicitly called, the default value is MixedMode.None, which means that secure sources are not allowed to load content from insecure sources.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
mixedMode MixedMode Yes

Mixed content mode to be set.

If undefined or null is passed in, the value MixedMode.All is used.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State mode: MixedMode = MixedMode.All;
  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .mixedMode(this.mode)
  13.     }
  14.   }
  15. }

onlineImageAccess

onlineImageAccess(onlineImageAccess: boolean)

Sets whether to allow loading of image resources from the network (resources accessed via HTTP and HTTPS). If this attribute is not explicitly called, loading is allowed by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
onlineImageAccess boolean Yes

Set whether to allow loading image resources from the network.

true indicates allowing, and false indicates disallowing.

The value is false when undefined or null is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .onlineImageAccess(true)
  13.     }
  14.   }
  15. }

zoomAccess

zoomAccess(zoomAccess: boolean)

Sets whether to support zoom gestures. If this attribute is not explicitly called, zoom gestures are supported by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
zoomAccess boolean Yes

Set whether to support gesture-based scaling.

true indicates support, and false indicates no support.

The value is false when undefined or null is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .zoomAccess(true)
  13.     }
  14.   }
  15. }

overviewModeAccess

overviewModeAccess(overviewModeAccess: boolean)

Sets whether to load web pages by using the overview mode. That is, zoom out the content to fit the screen width. When this attribute is not explicitly called, web pages can be loaded in overview mode by default.

System capability: SystemCapability.Web.Webview.Core

Device behavior: This API has no effect on the PCs/2-in-1 devices and works on other devices.

Parameters

Expand
Name Type Mandatory Description
overviewModeAccess boolean Yes

Set whether to use the overview mode to load the web page.

true indicates using it, and false indicates not using it.

The value is false when undefined or null is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .overviewModeAccess(true)
  13.     }
  14.   }
  15. }

databaseAccess

databaseAccess(databaseAccess: boolean)

Sets whether to enable the Web SQL Database storage API permission. If this permission is not explicitly called, it is disabled by default.

NOTE
  • After the ArkWeb kernel is upgraded to M132, the API's control over the Web SQL Database becomes invalid because the kernel discards Web SQL. For details about the ArkWeb kernel version, see Constraints.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
databaseAccess boolean Yes

Whether to enable Web SQL Database storage API permission.

true means enabling the detection, and false means disabling it.

If undefined or null is passed in, the value is false.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .databaseAccess(true)
  13.     }
  14.   }
  15. }

geolocationAccess

geolocationAccess(geolocationAccess: boolean)

Sets whether to enable the geolocation permission. If this attribute is not explicitly called, the permission is enabled by default. For details about how to use this feature, see Managing Location Permissions.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
geolocationAccess boolean Yes

Set whether to enable the geolocation permission.

true indicates enabling, and false indicates disabling.

The value is false when undefined or null is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .geolocationAccess(true)
  13.     }
  14.   }
  15. }

mediaPlayGestureAccess9+

mediaPlayGestureAccess(access: boolean)

Sets whether autoplay of audible videos requires a user tap. Muted video playback is not affected by this API. If this attribute is not explicitly set, a user tap is required by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
access boolean Yes

Sets whether autoplay of audio/video requires a manual click by the user.

true indicates that a manual click by the user is required, and false indicates that it is not required and autoplay is allowed.

When undefined or null is passed in, the value is false.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State access: boolean = true;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: $rawfile('index.html'), controller: this.controller })
  13.         .mediaPlayGestureAccess(this.access)
  14.     }
  15.   }
  16. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <title>Video Playback Page</title>
  6. </head>
  7. <body>
  8. <h1>Video Playback</h1>
  9. <video id="testVideo" controls autoplay>
  10.     // Configure the autoplay attribute in the video tag to allow automatic video playback.
  11.     // Save an MP4 media file in the rawfile directory of resources and name it example.mp4.
  12.     <source src="example.mp4" type="video/mp4">
  13. </video>
  14. </body>
  15. </html>

multiWindowAccess9+

multiWindowAccess(multiWindow: boolean)

Sets whether to enable the multi-window permission. If this attribute is not explicitly called, the permission is disabled by default.

Enabling the multi-window permission requires implementation of the onWindowNew event. For the sample code, see onWindowNew.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
multiWindow boolean Yes

Set whether to enable the multi-window permission.

true indicates enabling, and false indicates disabling.

horizontalScrollBarAccess9+

horizontalScrollBarAccess(horizontalScrollBar: boolean)

Sets whether to display the horizontal scrollbar, including the system default scrollbar and user-defined scrollbars. If this attribute is not explicitly called, the scrollbar is displayed by default.

NOTE
  • If an @State decorated variable is used to control the visibility of the horizontal scrollbar, controller.refresh() must be called for the settings to take effect.
  • When the @State decorated variable changes frequently and dynamically, it is recommended to maintain a one-to-one correspondence between the toggle variable and the Web component.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
horizontalScrollBar boolean Yes

Set whether to display the horizontal scroll bar.

true indicates displaying, and false indicates not displaying.

When undefined or null is passed in, the value is false.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. 

  5. @Entry
  6. @Component
  7. struct WebComponent {
  8.   controller: webview.WebviewController = new webview.WebviewController();
  9.   @State isShow: boolean = true;
  10.   @State btnMsg: string = 'Hide scrollbar';
  11. 

  12.   build() {
  13.     Column() {
  14.       // If an @State decorated variable is used to control the horizontal scrollbar visibility, controller.refresh() must be called for the settings to take effect.
  15.       Button('refresh')
  16.         .onClick(() => {
  17.           if (this.isShow) {
  18.             this.isShow = false;
  19.             this.btnMsg = 'Show scrollbar';
  20.           } else {
  21.             this.isShow = true;
  22.             this.btnMsg = 'Hide scrollbar';
  23.           }
  24.           try {
  25.             this.controller.refresh();
  26.           } catch (error) {
  27.             console.error(`Failed to refresh Web. Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
  28.           }
  29.         }).height('10%').width('40%')
  30.       Web({ src: $rawfile('index.html'), controller: this.controller }).height('90%')
  31.         .horizontalScrollBarAccess(this.isShow)
  32.     }
  33.   }
  34. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <meta name="viewport" id="viewport" content="width=device-width,initial-scale=1.0">
  6.     <title>Demo</title>
  7.     <style>
  8.         body {
  9.           width:3000px;
  10.           height:6000px;
  11.           padding-right:170px;
  12.           padding-left:170px;
  13.           border:5px solid blueviolet;
  14.         }
  15.     </style>
  16. </head>
  17. <body>
  18. Scroll Test
  19. </body>
  20. </html>

verticalScrollBarAccess9+

verticalScrollBarAccess(verticalScrollBar: boolean)

Sets whether to display the vertical scrollbar, including the system default scrollbar and user-defined scrollbars. If this attribute is not explicitly called, the scrollbar is displayed by default.

NOTE
  • If an @State decorated variable is used to control the vertical scrollbar visibility, controller.refresh() must be called for the settings to take effect.
  • 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.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
verticalScrollBar boolean Yes

Set whether to display the vertical scroll bar.

true indicates displaying, and false indicates not displaying.

The value is false when undefined or null is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. 

  5. @Entry
  6. @Component
  7. struct WebComponent {
  8.   controller: webview.WebviewController = new webview.WebviewController();
  9.   @State isShow: boolean = true;
  10.   @State btnMsg: string = 'Hide scrollbar';
  11. 

  12.   build() {
  13.     Column() {
  14.       // If an @State decorated variable is used to control the vertical scrollbar visibility, controller.refresh() must be called for the settings to take effect.
  15.       Button(this.btnMsg)
  16.         .onClick(() => {
  17.           if (this.isShow) {
  18.             this.isShow = false;
  19.             this.btnMsg = 'Show scrollbar';
  20.           } else {
  21.             this.isShow = true;
  22.             this.btnMsg = 'Hide scrollbar';
  23.           }
  24.           try {
  25.             this.controller.refresh();
  26.           } catch (error) {
  27.             console.error(`Failed to refresh Web. Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
  28.           }
  29.         }).height('10%').width('40%')
  30.       Web({ src: $rawfile('index.html'), controller: this.controller }).height('90%')
  31.         .verticalScrollBarAccess(this.isShow)
  32.     }
  33.   }
  34. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <meta name="viewport" id="viewport" content="width=device-width,initial-scale=1.0">
  6.     <title>Demo</title>
  7.     <style>
  8.         body {
  9.           width:3000px;
  10.           height:6000px;
  11.           padding-right:170px;
  12.           padding-left:170px;
  13.           border:5px solid blueviolet;
  14.         }
  15.     </style>
  16. </head>
  17. <body>
  18. Scroll Test
  19. </body>
  20. </html>

cacheMode

cacheMode(cacheMode: CacheMode)

Sets the cache mode. When this attribute is not explicitly called, the default value CacheMode.Default is used.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
cacheMode CacheMode Yes

Cache mode to set.

When undefined or null is passed in, the value is CacheMode.Default.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State mode: CacheMode = CacheMode.None;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .cacheMode(this.mode)
  14.     }
  15.   }
  16. }

copyOptions11+

copyOptions(value: CopyOptions)

Sets the clipboard copy scope option. If this attribute is not explicitly called, pasting across all apps on the current device is supported by default after copying.

NOTE

When this attribute is set to CopyOptions.None, the enablePreviewMenu configuration item in dataDetectorConfig does not take effect. When enableDataDetector is set to true and this attribute is set to CopyOptions.LocalDevice, the AI menu feature is activated.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
value CopyOptions Yes

Pasteboard copy options.

When undefined or null is passed in, the value is CopyOptions.None.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .copyOptions(CopyOptions.None)
  13.     }
  14.   }
  15. }

textZoomRatio9+

textZoomRatio(textZoomRatio: number)

Sets the text zoom ratio of the page. When this attribute is not explicitly called, the default zoom ratio is 100%.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
textZoomRatio number Yes

Text zoom percentage of the page to be set. 100 indicates the original size, a value greater than 100 indicates zooming in, and a value less than 100 indicates zooming out.

The value is an integer in the range (0, 2147483647].

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State ratio: number = 150;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .textZoomRatio(this.ratio)
  14.     }
  15.   }
  16. }

initialScale9+

initialScale(percent: number)

Sets the zoom percentage of the entire page. If this attribute is not explicitly called, the default value is 100.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
percent number Yes

Scale factor of the entire page.

Value range: (0, 1000]

When undefined or null is passed in, the attribute setting does not take effect.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State percent: number = 100;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .initialScale(this.percent)
  14.     }
  15.   }
  16. }

blockNetwork9+

blockNetwork(block: boolean)

Sets whether to block online downloads. When this attribute is not explicitly called, online resources can be loaded by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
block boolean Yes

Whether to allow online downloads.

The value true means to block online downloads, and false means the opposite.

If undefined or null is passed in, the value is false.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State block: boolean = true;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .blockNetwork(this.block)
  14.     }
  15.   }
  16. }

defaultFixedFontSize9+

defaultFixedFontSize(size: number)

Sets the default fixed font size for the web page. For HTML elements that use the monospace font and do not specify font-size, the font size is rendered based on this value.

When this attribute is not explicitly called, the default fixed font size is 13.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
size number Yes

Default fixed font size to set, in px.

Value range: [-2^31, 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.

When null or undefined is passed in, the value is 13.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State fontSize: number = 16;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .defaultFixedFontSize(this.fontSize)
  14.     }
  15.   }
  16. }

defaultFontSize9+

defaultFontSize(size: number)

Sets the default font size for the web page. For HTML elements that use non-monospace fonts and do not specify font-size, the font size is rendered based on this value.

When this attribute is not explicitly called, the default font size of the web page is 16.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
size number Yes

Default font size to set, in px.

Value range: [-2^31, 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.

When null or undefined is passed in, the value is 16.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State fontSize: number = 13;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .defaultFontSize(this.fontSize)
  14.     }
  15.   }
  16. }

minFontSize9+

minFontSize(size: number)

Sets the minimum font size for the web page. If the font size of HTML elements is smaller than the value set by this API, the font size is rendered based on the value set by this API.

When no attribute is explicitly called, the default minimum font size of the web page is 8.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
size number Yes

Minimum font size to set, in px.

Value range: [-2^31, 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.

When null or undefined is passed in, the value is 8.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State fontSize: number = 13;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .minFontSize(this.fontSize)
  14.     }
  15.   }
  16. }

minLogicalFontSize9+

minLogicalFontSize(size: number)

Sets the minimum logical font size for the web page.

For HTML elements whose font size is not specified:

  1. If the font size of the element is smaller than the value set by this API, the font size is rendered based on the API value.
  2. If minLogicalFontSize and minFontSize are both set, the larger value of the two will be used for elements whose font size is not specified.

When this attribute is not explicitly called, the default minimum logical font size of the web page is 8.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
size number Yes

Sets the minimum logical font size for web pages, in px.

The value ranges from [-2^31, 2^31-1]. During actual rendering, values greater than 72 px are rendered as 72 px, and values less than 1 px are rendered as 1 px.

Defaults to 8 when null or undefined is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State fontSize: number = 13;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .minLogicalFontSize(this.fontSize)
  14.     }
  15.   }
  16. }

webFixedFont9+

webFixedFont(family: string)

Sets the fixed font family of the web page to render HTML elements that use the monospace font.

When this attribute is not explicitly called, the default fixed font family of the web page is monospace.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
family string Yes

Fixed font family for web pages. The value is a font name string, for example, "monospace" or "Arial".

The value monospace is used when null or undefined is passed.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State family: string = "monospace";
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .webFixedFont(this.family)
  14.     }
  15.   }
  16. }

webSansSerifFont9+

webSansSerifFont(family: string)

Sets the sans-serif font family of the web page to render HTML elements that use the sans-serif font.

When this attribute is not explicitly called, the sans-serif font family of the web page is sans-serif by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
family string Yes

Sans-serif font family to set.

When null or undefined is passed in, the sans-serif font family is sans-serif.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State family: string = "sans-serif";
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .webSansSerifFont(this.family)
  14.     }
  15.   }
  16. }

webSerifFont9+

webSerifFont(family: string)

Sets the serif font family of the web page to render HTML elements that use the serif font.

When this attribute is not explicitly called, the default serif font family of the web page is serif.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
family string Yes

Serif font family to set.

When null or undefined is passed in, the sans-serif font family is serif.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State family: string = "serif";
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .webSerifFont(this.family)
  14.     }
  15.   }
  16. }

webStandardFont9+

webStandardFont(family: string)

Sets the standard font family of the web page to render HTML elements whose font style is not specified.

When this attribute is not explicitly called, the default standard font family of the web page is sans-serif.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
family string Yes

Standard font family to set.

When null or undefined is passed in, the sans-serif font family is sans-serif.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State family: string = "sans-serif";
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .webStandardFont(this.family)
  14.     }
  15.   }
  16. }

webFantasyFont9+

webFantasyFont(family: string)

Sets the fantasy font family of the web page to render HTML elements that use the fantasy font.

When this attribute is not explicitly called, the default fantasy font family of the web page is fantasy.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
family string Yes

Fantasy font family to set.

When null or undefined is passed in, the value is fantasy.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. @Entry
  4. @Component
  5. struct WebComponent {
  6.   controller: webview.WebviewController = new webview.WebviewController();
  7.   @State family: string = "fantasy";
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .webFantasyFont(this.family)
  13.     }
  14.   }
  15. }

webCursiveFont9+

webCursiveFont(family: string)

Sets the cursive font family of the web page to render HTML elements that use the cursive font.

When this attribute is not explicitly called, the default cursive font family of the web page is cursive.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
family string Yes

Cursive font family to set.

When null or undefined is passed in, the value is cursive.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State family: string = "cursive";
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .webCursiveFont(this.family)
  14.     }
  15.   }
  16. }

darkMode9+

darkMode(mode: WebDarkMode)

Sets the dark mode of the Web component. If this attribute is not explicitly called, dark mode is disabled by default.

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. For details about how to use dark mode, see Setting Dark Mode.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
mode WebDarkMode Yes

Dark mode for the web page, which can be set to Off, On, or Auto.

When null or undefined is passed, the value is WebDarkMode.Off.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State mode: WebDarkMode = WebDarkMode.On;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .darkMode(this.mode)
  14.     }
  15.   }
  16. }

forceDarkAccess9+

forceDarkAccess(access: boolean)

Sets whether to enable forcible dark mode for the web page. This API is applicable only when darkMode is enabled. When this attribute is not explicitly called, forcible dark mode is disabled for the web page by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
access boolean Yes

Whether to enable forced dark mode for web pages.

The value true means to enable it, and false means not to enable it.

If null or undefined is passed, the default value false is used.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State mode: WebDarkMode = WebDarkMode.On;
  9.   @State access: boolean = true;
  10. 

  11.   build() {
  12.     Column() {
  13.       Web({ src: 'www.example.com', controller: this.controller })
  14.         .darkMode(this.mode)
  15.         .forceDarkAccess(this.access)
  16.     }
  17.   }
  18. }

pinchSmooth9+

pinchSmooth(isEnabled: boolean)

Sets whether to enable pinch smooth mode for the web page. When this attribute is not explicitly called, pinch smooth mode is disabled by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
isEnabled boolean Yes

Whether to enable pinch smooth mode for the web page.

The value true means to enable pinch smooth mode, and false means the opposite.

If undefined or null is passed in, the value is false.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .pinchSmooth(true)
  13.     }
  14.   }
  15. }

allowWindowOpenMethod10+

allowWindowOpenMethod(flag: boolean)

Sets whether to allow a new window to automatically open through JavaScript.

NOTE
  • This API takes effect only when javaScriptAccess is enabled.
  • This API opens a new window when multiWindowAccess is enabled, and a local window when it is disabled.
  • 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.
  • 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.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
flag boolean Yes

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.

The user behavior here refers to a user requests to open a new window (window.open) within 5 seconds after operating the Web component.

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.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. // There are two Web components on the same page. When the WebComponent object opens a new window, the NewWebViewComp object is displayed.
  5. @CustomDialog
  6. struct NewWebViewComp {
  7.     controller?: CustomDialogController;
  8.     webviewController1: webview.WebviewController = new webview.WebviewController();
  9. 

  10.     build() {
  11.         Column() {
  12.             Web({ src: "", controller: this.webviewController1 })
  13.                 .javaScriptAccess(true)
  14.                 .multiWindowAccess(false)
  15.                 .onWindowExit(() => {
  16.                     console.info("NewWebViewComp onWindowExit");
  17.                     if (this.controller) {
  18.                         this.controller.close();
  19.                     }
  20.                 })
  21.                 .onActivateContent(() => {
  22.                     // This Web needs to be displayed in the foreground. It is recommended that the application perform tab or window switching here.
  23.                     console.info("NewWebViewComp onActivateContent")
  24.                 })
  25.         }
  26.     }
  27. }
  28. 

  29. @Entry
  30. @Component
  31. struct WebComponent {
  32.     controller: webview.WebviewController = new webview.WebviewController();
  33.     dialogController: CustomDialogController | null = null;
  34. 

  35.     build() {
  36.         Column() {
  37.             Web({ src: $rawfile("index.html"), controller: this.controller })
  38.                 .javaScriptAccess(true)
  39.                 // MultiWindowAccess needs to be enabled.
  40.                 .multiWindowAccess(true)
  41.                 .allowWindowOpenMethod(true)
  42.                 .onWindowNew((event) => {
  43.                     if (this.dialogController) {
  44.                         this.dialogController.close()
  45.                     }
  46.                     let popController: webview.WebviewController = new webview.WebviewController();
  47.                     // Return the WebviewController corresponding to the new window to the Web kernel.
  48.                     // If the event.handler.setWebController interface is not called, the rendering process will be blocked.
  49.                     // If no new window is created, set it to null when calling the event.handler.setWebController interface to notify the Web that no new window has been created.
  50.                     event.handler.setWebController(popController);
  51.                     this.dialogController = new CustomDialogController({
  52.                         builder: NewWebViewComp({ webviewController1: popController }),
  53.                         // Set isModal to false to prevent the new window from being destroyed, so that the onActivateContent callback can be triggered.
  54.                         isModal: false
  55.                     })
  56.                     this.dialogController.open();
  57.                 })
  58.         }
  59.     }
  60. }

Example of the HTML file

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <html>
  4. <body>
  5. <div>
  6.     <button type="button" onclick="delayOpenwindow(5000)">delayOpenwindow_5s</button>
  7. </div>
  8. 

  9. <script>
  10.     function openwindowAll(){
  11.         open("https://www.example.com","_blank","height=400,width=600,top=100,left=100,scrollbars=no")
  12.     }
  13.     function delayOpenwindow(t){
  14.         setTimeout(openwindowAll, t);
  15.     }
  16. </script>
  17. </body>
  18. </html>

mediaOptions10+

mediaOptions(options: WebMediaOptions)

Sets 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. When this attribute is not explicitly set, the web audio cannot be automatically resumed after regaining the focus by default, and the audio of multiple Web instances in an application is exclusive.

NOTE
  • Audios in the same Web instance are considered as the same audio.
  • The media playback policy controls videos with an audio track.
  • You are advised to set audioExclusive to the same value for all Web components.
  • Audio and video interruption takes effect within an application and between applications, and playback resumption takes effect only between applications.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
options WebMediaOptions Yes

Web-based media playback policy.

After the parameter settings are updated, the playback must be started again for the settings to take effect.

When undefined or null is passed in, {resumeInterval: 0, audioExclusive: true} is used.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State options: WebMediaOptions = {resumeInterval: 10, audioExclusive: true};
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .mediaOptions(this.options)
  14.     }
  15.   }
  16. }

javaScriptOnDocumentStart11+

javaScriptOnDocumentStart(scripts: Array<ScriptItem>)

Injects 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. When this attribute is not explicitly called, JavaScript scripts are not injected into the Web component by default.

NOTE

  • The script is injected after the root element (HTML Element) of the web document is created but before any other content is loaded.

  • The scripts are executed in lexicographic order, not in the order of the array. If the original array order is required, use the runJavaScriptOnDocumentStart API instead.

  • When scripts with identical content are injected multiple times, they are silently deduplicated without display or notification, and the scriptRules from the first injection are used.

  • This API does not support UrlRegexRule.

  • You are advised to use runJavaScriptOnDocumentStart instead.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
scripts Array<ScriptItem> Yes

Script item array to be injected.

When undefined or null is passed in, JavaScript scripts are not injected into Web components.

Example of the .ets file

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct Index {
  7.     controller: webview.WebviewController = new webview.WebviewController();
  8.     private localStorage: string =
  9.         "if (typeof(Storage) !== 'undefined') {" +
  10.         "   localStorage.setItem('color', 'Red');" +
  11.         "}";
  12.     @State scripts: Array<ScriptItem> = [
  13.         { script: this.localStorage, scriptRules: ["*"] }
  14.     ];
  15. 

  16.     build() {
  17.         Column({ space: 20 }) {
  18.             Web({ src: $rawfile('index.html'), controller: this.controller })
  19.                 .javaScriptAccess(true)
  20.                 .domStorageAccess(true)
  21.                 .backgroundColor(Color.Grey)
  22.                 .javaScriptOnDocumentStart(this.scripts)
  23.                 .width('100%')
  24.                 .height('100%')
  25.         }
  26.     }
  27. }

Example of the HTML file

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <html>
  4.   <head>
  5.     <meta charset="utf-8">
  6.   </head>
  7.   <body style="font-size: 30px;" onload='bodyOnLoadLocalStorage()'>
  8.       Hello world!
  9.       <div id="result"></div>
  10.   </body>
  11.   <script type="text/javascript">
  12.     function bodyOnLoadLocalStorage() {
  13.       if (typeof(Storage) !== 'undefined') {
  14.         document.getElementById('result').innerHTML = localStorage.getItem('color');
  15.       } else {
  16.         document.getElementById('result').innerHTML = 'Your browser does not support localStorage.';
  17.       }
  18.     }
  19.   </script>
  20. </html>

javaScriptOnDocumentEnd11+

javaScriptOnDocumentEnd(scripts: Array<ScriptItem>)

Injects 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. When this attribute is not explicitly called, JavaScript scripts are not injected into the Web component by default.

NOTE

  • The script runs after any JavaScript code on the page, and the DOM tree has already been loaded and rendered at that point.

  • The scripts are executed in lexicographic order, not in the order of the array.

  • When scripts with identical content are injected multiple times, they are silently deduplicated without display or notification, and the scriptRules from the first injection are used.

  • This API does not support UrlRegexRule.

  • You are advised to use runJavaScriptOnDocumentEnd instead.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
scripts Array<ScriptItem> Yes

Script item array to be injected.

When undefined or null is passed in, JavaScript scripts are not injected into Web components.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct Index {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   private jsStr: string =
  9.     "window.document.getElementById(\"result\").innerHTML = 'this is msg from javaScriptOnDocumentEnd'";
  10.   @State scripts: Array<ScriptItem> = [
  11.     { script: this.jsStr, scriptRules: ["*"] }
  12.   ];
  13. 

  14.   build() {
  15.     Column({ space: 20 }) {
  16.       Web({ src: $rawfile('index.html'), controller: this.controller })
  17.         .javaScriptAccess(true)
  18.         .domStorageAccess(true)
  19.         .backgroundColor(Color.Grey)
  20.         .javaScriptOnDocumentEnd(this.scripts)
  21.         .width('100%')
  22.         .height('100%')
  23.     }
  24.   }
  25. }
Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <meta charset="utf-8">
  6. </head>
  7. <body style="font-size: 30px;">
  8. Hello world!
  9. <div id="result">test msg</div>
  10. </body>
  11. </html>

runJavaScriptOnDocumentStart15+

runJavaScriptOnDocumentStart(scripts: Array<ScriptItem>)

Injects 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. When this attribute is not explicitly called, JavaScript scripts are not injected into the Web component by default.

NOTE

  • The script is injected after the root element (HTML Element) of the web document is created but before any other content is loaded.

  • The scripts are executed in the order of the array.

  • When scripts with identical content are injected multiple times, they are silently deduplicated without display or notification, and the scriptRules from the first injection are used.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
scripts Array<ScriptItem> Yes

Script item array to be injected.

When undefined or null is passed in, JavaScript scripts are not injected into Web components.

Example of the .ets file

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct Index {
  7.     controller: webview.WebviewController = new webview.WebviewController();
  8.     private localStorage: string =
  9.         "if (typeof(Storage) !== 'undefined') {" +
  10.         "   localStorage.setItem('color', 'Red');" +
  11.         "}";
  12.     private localStorage2: string =
  13.         "console.info('runJavaScriptOnDocumentStart urlRegexRules Matching succeeded.')";
  14.     @State scripts: Array<ScriptItem> = [
  15.         { script: this.localStorage, scriptRules: ["*"] },
  16.         { script: this.localStorage2, scriptRules: [], urlRegexRules: [{secondLevelDomain: "", rule: ".*index.html"}] }
  17.     ];
  18. 

  19.     build() {
  20.         Column({ space: 20 }) {
  21.             Web({ src: $rawfile('index.html'), controller: this.controller })
  22.                 .javaScriptAccess(true)
  23.                 .domStorageAccess(true)
  24.                 .backgroundColor(Color.Grey)
  25.                 .runJavaScriptOnDocumentStart(this.scripts)
  26.                 .width('100%')
  27.                 .height('100%')
  28.         }
  29.     }
  30. }

Example of the HTML file

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <html>
  4.   <head>
  5.     <meta charset="utf-8">
  6.   </head>
  7.   <body style="font-size: 30px;" onload='bodyOnLoadLocalStorage()'>
  8.       Hello world!
  9.       <div id="result"></div>
  10.   </body>
  11.   <script type="text/javascript">
  12.     function bodyOnLoadLocalStorage() {
  13.       if (typeof(Storage) !== 'undefined') {
  14.         document.getElementById('result').innerHTML = localStorage.getItem('color');
  15.       } else {
  16.         document.getElementById('result').innerHTML = 'Your browser does not support localStorage.';
  17.       }
  18.     }
  19.   </script>
  20. </html>

runJavaScriptOnDocumentEnd15+

runJavaScriptOnDocumentEnd(scripts: Array<ScriptItem>)

Injects 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. When this attribute is not explicitly called, JavaScript scripts are not injected into the Web component by default.

NOTE

  • The script runs after any JavaScript code on the page, and the DOM tree has already been loaded and rendered at that point.

  • The scripts are executed in the order of the array.

  • When scripts with identical content are injected multiple times, they are silently deduplicated without display or notification, and the scriptRules from the first injection are used.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
scripts Array<ScriptItem> Yes

Script item array to be injected.

When undefined or null is passed in, JavaScript scripts are not injected into Web components.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct Index {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   private jsStr: string =
  9.     "window.document.getElementById(\"result\").innerHTML = 'this is msg from runJavaScriptOnDocumentEnd'";
  10.   private jsStr2: string = "console.info('runJavaScriptOnDocumentEnd urlRegexRules Matching succeeded.')";
  11.   @State scripts: Array<ScriptItem> = [
  12.     { script: this.jsStr, scriptRules: ["*"] },
  13.     { script: this.jsStr2, scriptRules: [], urlRegexRules: [{secondLevelDomain: "", rule: ".*index.html"}] }
  14.   ];
  15. 

  16.   build() {
  17.     Column({ space: 20 }) {
  18.       Web({ src: $rawfile('index.html'), controller: this.controller })
  19.         .javaScriptAccess(true)
  20.         .domStorageAccess(true)
  21.         .backgroundColor(Color.Grey)
  22.         .runJavaScriptOnDocumentEnd(this.scripts)
  23.         .width('100%')
  24.         .height('100%')
  25.     }
  26.   }
  27. }
Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <meta charset="utf-8">
  6. </head>
  7. <body style="font-size: 30px;">
  8. Hello world!
  9. <div id="result">test msg</div>
  10. </body>
  11. </html>

runJavaScriptOnHeadEnd15+

runJavaScriptOnHeadEnd(scripts: Array<ScriptItem>)

Injects 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. When this attribute is not explicitly called, JavaScript scripts are not injected into the Web component by default.

NOTE

  • This script is executed in the array order.

  • 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.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
scripts Array<ScriptItem> Yes

Script item array to be injected.

When undefined or null is passed in, JavaScript scripts are not injected into Web components.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct Index {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   private jsStr: string =
  9.     "window.document.getElementById(\"result\").innerHTML = 'this is msg from runJavaScriptOnHeadEnd'";
  10.   private jsStr2: string = "console.info('runJavaScriptOnHeadEnd urlRegexRules Matching succeeded.')";
  11.   @State scripts: Array<ScriptItem> = [
  12.     { script: this.jsStr, scriptRules: ["*"] },
  13.     { script: this.jsStr2, scriptRules: [], urlRegexRules: [{secondLevelDomain: "", rule: ".*index.html"}] }
  14.   ];
  15. 

  16.   build() {
  17.     Column({ space: 20 }) {
  18.       Web({ src: $rawfile('index.html'), controller: this.controller })
  19.         .javaScriptAccess(true)
  20.         .domStorageAccess(true)
  21.         .backgroundColor(Color.Grey)
  22.         .runJavaScriptOnHeadEnd(this.scripts)
  23.         .width('100%')
  24.         .height('100%')
  25.     }
  26.   }
  27. }
Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <meta charset="utf-8">
  6. </head>
  7. <body style="font-size: 30px;">
  8. Hello world!
  9. <div id="result">test msg</div>
  10. </body>
  11. </html>

layoutMode11+

layoutMode(mode: WebLayoutMode)

Sets the layout mode of the Web component. If this attribute is not explicitly called, the Web layout follows the system mode (WebLayoutMode.NONE) by default. For common issues, see Web Component Size Adapting to Page Content Layout.

NOTE

Currently, only two Web layout modes are supported:

  • The Web layout follows the system mode (WebLayoutMode.NONE).
  • The Web component height adapts to the frontend page height (WebLayoutMode.FIT_CONTENT).

The adaptive layout of the Web component height based on the frontend page has the following limitations:

  • When layoutMode is set to WebLayoutMode.FIT_CONTENT:
  • If the width or height of the Web component exceeds 7680 px, specify the RenderMode.SYNC_RENDER mode when creating the Web component. Otherwise, the entire screen will be blank.
  • Dynamic switching of the layoutMode mode is not supported after the Web component is created.
  • Web component size specifications: When RenderMode.ASYNC_RENDER is specified, the width and height must not exceed 7680 px respectively.
  • Frequent changes to the page width and height will trigger re-layout of the Web component, affecting the user experience.
  • Waterfall layout web pages (loading more content when scrolling to the bottom) are not supported.
  • Width adaptation is not supported; only height adaptation is supported.
  • Because the height adapts to the web page height, you cannot modify the component height by changing the component height attribute.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
mode WebLayoutMode Yes

Set the web layout mode to follow the system or use adaptive layout.

When null or undefined is passed in, the value is WebLayoutMode.NONE

Example

  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.
Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   mode: WebLayoutMode = WebLayoutMode.FIT_CONTENT;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER })
  13.         .layoutMode(this.mode)
  14.     }
  15.   }
  16. }
  1. After specifying the layoutMode to WebLayoutMode.FIT_CONTENT, you are advised to specify overScrollMode 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.
Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   layoutMode: WebLayoutMode = WebLayoutMode.FIT_CONTENT;
  9.   @State overScrollMode: OverScrollMode = OverScrollMode.NEVER;
  10. 

  11.   build() {
  12.     Column() {
  13.       Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER })
  14.         .layoutMode(this.layoutMode)
  15.         .overScrollMode(this.overScrollMode)
  16.     }
  17.   }
  18. }

nestedScroll11+

nestedScroll(value: NestedScrollOptions | NestedScrollOptionsExt)

Sets nested scrolling options.

NOTE
  • 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.
  • Containers that support nested scrolling: Grid, List, Scroll, Swiper, Tabs, WaterFlow, Refresh and bindSheet.
  • Input sources that support nested scrolling: gestures, mouse device, and touchpad.
  • 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 to OverScrollMode.NEVER to avoid undermining user experience.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
value NestedScrollOptions| NestedScrollOptionsExt14+ Yes

Nested scrolling options.

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.

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.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. @Entry
  4. @Component
  5. struct WebComponent {
  6.   controller: webview.WebviewController = new webview.WebviewController();
  7. 

  8.   build() {
  9.     Column() {
  10.       Web({ src: 'www.example.com', controller: this.controller })
  11.         .nestedScroll({
  12.           scrollForward: NestedScrollMode.SELF_FIRST,
  13.           scrollBackward: NestedScrollMode.SELF_FIRST,
  14.         })
  15.     }
  16.   }
  17. }
Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. @Entry
  4. @Component
  5. struct WebComponent {
  6.   controller: webview.WebviewController = new webview.WebviewController()
  7.   build() {
  8.     Scroll(){
  9.       Column() {
  10.         Text("Nested Web")
  11.           .height("25%")
  12.           .width("100%")
  13.           .fontSize(30)
  14.           .backgroundColor(Color.Yellow)
  15.         Web({ src: $rawfile('index.html'),
  16.               controller: this.controller })
  17.           .nestedScroll({
  18.             scrollUp: NestedScrollMode.SELF_FIRST,
  19.             scrollDown: NestedScrollMode.PARENT_FIRST,
  20.             scrollLeft: NestedScrollMode.SELF_FIRST,
  21.             scrollRight: NestedScrollMode.SELF_FIRST,
  22.           })
  23.       }
  24.     }
  25.   }
  26. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <meta name="viewport" id="viewport" content="width=device-width, initial-scale=1.0">
  6.     <style>
  7.         .blue {
  8.           background-color: lightblue;
  9.         }
  10.         .green {
  11.           background-color: lightgreen;
  12.         }
  13.         .blue, .green {
  14.         font-size:16px;
  15.         height:200px;
  16.         text-align: center;       /* Horizontally centered */
  17.         line-height: 200px;       /* Vertically centered (the height matches the container height) */
  18.         }
  19.     </style>
  20. </head>
  21. <body>
  22. <div class="blue" >webArea</div>
  23. <div class="green">webArea</div>
  24. <div class="blue">webArea</div>
  25. <div class="green">webArea</div>
  26. <div class="blue">webArea</div>
  27. <div class="green">webArea</div>
  28. <div class="blue">webArea</div>
  29. </body>
  30. </html>

enableScrollDirectionalLock

enableScrollDirectionalLock(value: boolean, type: ScrollDirectionalLockType)

Sets the scroll direction lock for the Web component to prevent simultaneous horizontal and vertical scrolling when the user swipes diagonally, thereby improving the scrolling experience. If this method is not explicitly called, scroll direction lock is supported by default in nested scrolling scenarios. The ALL mode applies to all scenarios where scroll locking is needed, while the NESTED_SCROLL mode applies only to nested scrolling scenarios.

System capability: SystemCapability.Web.Webview.Core

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Parameters

Expand
Name Type Mandatory Description
value boolean Yes Whether to support scroll direction locking. The value true indicates that the scroll direction is locked, and the scroll view locks the scroll axis based on the user's initial scroll direction. The value false indicates that the scroll direction is not locked.
type ScrollDirectionalLockType Yes Sets the scenarios in which the Web component expects scroll direction locking. ALL indicates that scroll locking is supported in all scenarios, and NESTED_SCROLL indicates that scroll locking is supported in nested scrolling scenarios.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .width('100%')
  13.         .height('100%')
  14.         // Support locking the scroll direction in all scenarios.
  15.         .enableScrollDirectionalLock(true, ScrollDirectionalLockType.ALL)
  16.     }
  17.   }
  18. }

bypassVsyncCondition20+

bypassVsyncCondition(condition: WebBypassVsyncCondition)

Sets the rendering process to bypass vsync (vertical synchronization) scheduling and directly trigger drawing when the scrollBy API is called to scroll the page. When this attribute is not explicitly called, vsync scheduling is not skipped by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
condition WebBypassVsyncCondition Yes

Condition for triggering the rendering process to bypass vsync scheduling.

When undefined or null is passed in, the value is NONE.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   condition: WebBypassVsyncCondition = WebBypassVsyncCondition.SCROLLBY_FROM_ZERO_OFFSET;
  9. 

  10.   build() {
  11.     Column() {
  12.       Button('scrollBy')
  13.         .onClick(() => {
  14.           this.controller.scrollBy(0, 5);
  15.         })
  16.       Web({ src: 'www.example.com', controller: this.controller })
  17.         .bypassVsyncCondition(this.condition)
  18.     }
  19.   }
  20. }

enableNativeEmbedMode11+

enableNativeEmbedMode(enabled: boolean)

Sets whether to enable the same-layer rendering feature. When this method is not explicitly called, the same-layer rendering feature is disabled by default.

NOTE

APIs such as registerNativeEmbedRule and nativeEmbedOptions take effect only when this attribute is enabled.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
enabled boolean Yes

Whether to enable the same-layer rendering feature.

The value true means to enable the same-layer rendering feature, and false means the opposite.

When undefined or null is passed in, the value is false.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. @Entry
  4. @Component
  5. struct WebComponent {
  6.   controller: webview.WebviewController = new webview.WebviewController();
  7. 

  8.   build() {
  9.     Column() {
  10.       Web({ src: 'www.example.com', controller: this.controller })
  11.         .enableNativeEmbedMode(true)
  12.     }
  13.   }
  14. }

forceDisplayScrollBar14+

forceDisplayScrollBar(enabled: boolean)

Sets 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. When this attribute is not explicitly called, the scroll bar is not always visible by default.

When layoutMode is set to WebLayoutMode.FIT_CONTENT, the enabled parameter is set to false.

NOTE
  • This API takes effect globally across all Web components in the current application. When multiple Web components are set with different values, the value set first takes effect.
  • It is recommended to use setScrollbarMode to set the scrollbar mode of all Web components in the current application. If the setScrollbarMode API is called at the same time, the setting of the forceDisplayScrollBar API does not take effect.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
enabled boolean Yes

Whether the scroll bar is always displayed.

The value true indicates that the scroll bar is always displayed, and false indicates the opposite.

When layoutMode is set to WebLayoutMode.FIT_CONTENT, the enabled parameter is forcibly set to false, and setting it to true does not take effect.

If undefined or null is passed in, the attribute setting does not take effect.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile('index.html'), controller: this.controller })
  12.         .forceDisplayScrollBar(true)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <meta name="viewport" content="width=device-width, initial-scale=1.0">
  6.     <title>Demo</title>
  7.     <style>
  8.       body {
  9.         width:2560px;
  10.         height:2560px;
  11.         padding-right:170px;
  12.         padding-left:170px;
  13.         border:5px solid blueviolet;
  14.       }
  15.     </style>
  16. </head>
  17. <body>
  18. Scroll Test
  19. </body>
  20. </html>

registerNativeEmbedRule12+

registerNativeEmbedRule(tag: string, type: string)

Registers 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.

If 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.

This 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.

For details, see Using Same-Layer Rendering.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
tag string Yes Tag name.
type string Yes Tag type. The ArkWeb kernel uses a prefix to match this parameter.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. import { NodeController, BuilderNode, NodeRenderType, FrameNode, UIContext } from '@kit.ArkUI';
  4. 

  5. declare class Params {
  6.   text: string;
  7.   width: number;
  8.   height: number;
  9. }
  10. 

  11. declare class NodeControllerParams {
  12.   surfaceId: string;
  13.   renderType: NodeRenderType;
  14.   width: number;
  15.   height: number;
  16. }
  17. 

  18. class MyNodeController extends NodeController {
  19.   private rootNode: BuilderNode<[Params]> | undefined | null;
  20.   private surfaceId_: string = "";
  21.   private renderType_: NodeRenderType = NodeRenderType.RENDER_TYPE_DISPLAY;
  22.   private width_: number = 0;
  23.   private height_: number = 0;
  24. 

  25.   setRenderOption(params: NodeControllerParams) {
  26.     this.surfaceId_ = params.surfaceId;
  27.     this.renderType_ = params.renderType;
  28.     this.width_ = params.width;
  29.     this.height_ = params.height;
  30.   }
  31. 

  32.   makeNode(uiContext: UIContext): FrameNode | null {
  33.     this.rootNode = new BuilderNode(uiContext, { surfaceId: this.surfaceId_, type: this.renderType_ });
  34.     this.rootNode.build(wrapBuilder(ButtonBuilder), { text: "myButton", width: this.width_, height: this.height_ });
  35.     return this.rootNode.getFrameNode();
  36.   }
  37. 

  38.   postInputEvent(event: TouchEvent | MouseEvent | undefined): boolean {
  39.     return this.rootNode?.postInputEvent(event) as boolean;
  40.   }
  41. }
  42. 

  43. @Component
  44. struct ButtonComponent {
  45.   @Prop params: Params;
  46.   @State bkColor: Color = Color.Red;
  47. 

  48.   build() {
  49.     Column() {
  50.       Button(this.params.text)
  51.         .height(50)
  52.         .width(200)
  53.         .border({ width: 2, color: Color.Red })
  54.         .backgroundColor(this.bkColor)
  55.     }
  56.     .width(this.params.width)
  57.     .height(this.params.height)
  58.   }
  59. }
  60. 

  61. @Builder
  62. function ButtonBuilder(params: Params) {
  63.   ButtonComponent({ params: params })
  64.     .backgroundColor(Color.Green)
  65. }
  66. 

  67. @Entry
  68. @Component
  69. struct WebComponent {
  70.   controller: webview.WebviewController = new webview.WebviewController();
  71.   private nodeController: MyNodeController = new MyNodeController();
  72.   uiContext: UIContext = this.getUIContext();
  73. 

  74.   build() {
  75.     Column() {
  76.       Stack() {
  77.         NodeContainer(this.nodeController)
  78.         Web({ src: $rawfile('index.html'), controller: this.controller })
  79.            // Enable same-layer rendering.
  80.           .enableNativeEmbedMode(true)
  81.            // Register the same-layer tag of <object> and type of "native."
  82.           .registerNativeEmbedRule("object", "native")
  83.            // Obtain the lifecycle change data of the <object> tag.
  84.           .onNativeEmbedLifecycleChange((object) => {
  85.             if (object.status == NativeEmbedStatus.CREATE) {
  86.               this.nodeController.setRenderOption({
  87.                 surfaceId: object.surfaceId as string,
  88.                 renderType: NodeRenderType.RENDER_TYPE_TEXTURE,
  89.                 width: this.uiContext!.px2vp(object.info?.width),
  90.                 height: this.uiContext!.px2vp(object.info?.height)
  91.               });
  92.               this.nodeController.rebuild();
  93.             }
  94.           })
  95.       }
  96.     }
  97.   }
  98. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <title>Same-Layer Rendering Test</title>
  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0">
  7. </head>
  8. <body>
  9. <div>
  10.     <div id="bodyId">
  11.         <object id="nativeButton" type ="native/button" width="300" height="300" style="background-color:red">
  12.         </object>
  13.     </div>
  14. </div>
  15. </body>
  16. </html>

defaultTextEncodingFormat12+

defaultTextEncodingFormat(textEncodingFormat: string)

Sets the default text encoding format for the web page. When this attribute is not explicitly called, the default text encoding format of the web page is UTF-8.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
textEncodingFormat string Yes

Default text encoding format.

When null or undefined is passed in, the value is UTF-8.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile('index.html'), controller: this.controller })
  12.         // Set the height.
  13.         .height(500)
  14.         .defaultTextEncodingFormat("UTF-8")
  15.         .javaScriptAccess(true)
  16.     }
  17.   }
  18. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <meta name="viewport" content="width=device-width" />
  6.     <title>My test html5 page</title>
  7. </head>
  8. <body>
  9.     <p>Hello world!</p>
  10. </body>
  11. </html>

metaViewport12+

metaViewport(enabled: boolean)

Sets whether the viewport attribute of the meta tag is enabled. When this attribute is not explicitly called, the viewport attribute of the meta tag is supported by default.

NOTE
  • Whether the viewport attribute of the <meta> tag in the frontend HTML page is enabled is determined by checking whether the User-Agent contains the "Mobile" field. When the 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 override the disabled state.

System capability: SystemCapability.Web.Webview.Core

Device behavior difference: This API can be called on phones, wearables, and TVs, but does not work on PCs or 2in1 devices. For tablets, the viewport-fit attribute in the meta tag will be parsed no matter 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.

Parameters

Expand
Name Type Mandatory Description
enabled boolean Yes

Whether the viewport attribute of the meta tag is enabled.

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.

The value false indicates the viewport attribute of the meta tag is disabled and not parsed, and the default layout is used.

When null or undefined is passed in, the value is true.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile('index.html'), controller: this.controller })
  12.         .metaViewport(true)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <meta name="viewport" content="width=device-width, initial-scale=1.0">
  6. </head>
  7. <body>
  8.     <p>Hello world!</p>
  9. </body>
  10. </html>

textAutosizing12+

textAutosizing(textAutosizing: boolean)

Sets whether to enable automatic font sizing for the Web component. When no attribute is explicitly called, automatic font sizing is enabled for the Web component by default.

After automatic font sizing takes effect, any text smaller than 16 px is enlarged to fall between 16 px and 32 px. This eliminates readability issues on narrow screens (viewport < 980 px) where mobile-specific layouts are absent.

NOTE
  • The preconditions for automatic font sizing to take effect are as follows:
    • The device type should be phone, tablet, wearable, or TV.
    • The viewport width of the Web component is less than 980 px.
    • The page is text-heavy: font size (px) × character count ≥ 3920.
    • metaViewport is not set on the frontend, or the metaViewport does not contain the width and initial-scale attributes.

System capability: SystemCapability.Web.Webview.Core

Device behavior: This API has no effect on the PCs/2-in-1 devices and works on other devices.

Parameters

Expand
Name Type Mandatory Description
textAutosizing boolean Yes

Whether to enable automatic text resizing.

The value true means to enable automatic text resizing, and false means the opposite.

When undefined or null is passed in, the value is true.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .textAutosizing(false)
  13.     }
  14.   }
  15. }

enableNativeMediaPlayer12+

enableNativeMediaPlayer(config: NativeMediaPlayerConfig)

Sets whether to enable the application to take over web page media playback. When this attribute is not explicitly called, the web page media playback takeover feature is disabled by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
config NativeMediaPlayerConfig Yes

Configuration object for the application to take over web page media playback. It contains the following attributes: enable (boolean type, whether to enable this feature, defaults to false), shouldOverlay (boolean type, when the feature is enabled, whether the player view that the application takes over for web page video overlays the web page content, defaults to false).

When undefined or null is passed in, the value is {enable: false, shouldOverlay: false}.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .enableNativeMediaPlayer({enable: true, shouldOverlay: false})
  13.     }
  14.   }
  15. }

onAdsBlocked12+

onAdsBlocked(callback: OnAdsBlockedCallback)

Called 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.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
callback OnAdsBlockedCallback Yes Callback of onAdsBlocked.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   @State totalAdsBlockCounts: number = 0;
  8.   controller: webview.WebviewController = new webview.WebviewController();
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'https://www.example.com', controller: this.controller })
  13.       .onAdsBlocked((details: AdsBlockedDetails) => {
  14.         if (details) {
  15.           console.info(' Blocked ' + details.adsBlocked.length + ' in ' + details.url);
  16.           let adList: Array<string> = Array.from(new Set(details.adsBlocked));
  17.           this.totalAdsBlockCounts += adList.length;
  18.           console.info('Total blocked counts :' + this.totalAdsBlockCounts);
  19.         }
  20.       })
  21.     }
  22.   }
  23. }

keyboardAvoidMode12+

keyboardAvoidMode(mode: WebKeyboardAvoidMode)

Sets the custom soft keyboard avoidance mode.

If the keyboard avoidance mode set in UIContext is KeyboardAvoidMode.RESIZE, this API does not take effect.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
mode WebKeyboardAvoidMode Yes

Web soft keyboard avoidance mode.

In the nested scrolling scenario, the soft keyboard avoidance mode of the Web component is not recommended, including RESIZE_VISUAL and RESIZE_CONTENT.

Default value: WebKeyboardAvoidMode.RESIZE_CONTENT

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State avoidMode: WebKeyboardAvoidMode = WebKeyboardAvoidMode.RESIZE_VISUAL;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: $rawfile("index.html"), controller: this.controller })
  13.       .keyboardAvoidMode(this.avoidMode)
  14.     }
  15.   }
  16. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.   <title>Test Web Page</title>
  6. </head>
  7. <body>
  8.   <input type="text" placeholder="Text">
  9. </body>
  10. </html>

editMenuOptions12+

editMenuOptions(editMenu: EditMenuOptions)

Sets a custom text selection menu for the Web component.

NOTE

This API is similar to bindSelectionMenu, with the following differences:

  • editMenuOptions: Adds extension items based on the system default menu style, with the trigger conditions unchanged.

  • bindSelectionMenu: Fully customizes the menu style and trigger conditions, as defined by the developer.

    It is not recommended to use both at the same time. Choose based on the degree of customization required.

You can use this attribute to customize a text menu.

You can use onCreateMenu to modify, add, and delete menu options. If you do not want to display the text menu, return an empty array.

You can use onMenuItemClick 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.

In onPrepareMenu20+, 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.

If this method is used together with selectionMenuOptions(deprecated), the selectionMenuOptions (deprecated) method does not take effect.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
editMenu EditMenuOptions Yes

Custom text menu options for Web.

The number of menu items, the content size of the menu, and the icon size are consistent with the ArkUI Menu component.

Among the system-defined ID enumeration values (TextMenuItemId) in the menu, only CUT, COPY, PASTE, SELECT_ALL, TRANSLATE, SEARCH, and AI_WRITER are supported in Web.

The textRange parameter in the onMenuItemClick function is meaningless in Web, and the passed-in value is -1.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. let selectText:string = '';
  5. class TestClass {
  6.   setSelectText(param: String) {
  7.     selectText = param.toString();
  8.   }
  9. }
  10. 

  11. @Entry
  12. @Component
  13. struct WebComponent {
  14.   controller: webview.WebviewController = new webview.WebviewController();
  15.   @State testObj: TestClass = new TestClass();
  16. 

  17.   onCreateMenu(menuItems: Array<TextMenuItem>): Array<TextMenuItem> {
  18.     let items = menuItems.filter((menuItem) => {
  19.       // Filter the menu items as required.
  20.       return (
  21.         menuItem.id.equals(TextMenuItemId.CUT) ||
  22.         menuItem.id.equals(TextMenuItemId.COPY) ||
  23.         menuItem.id.equals((TextMenuItemId.PASTE)) ||
  24.         menuItem.id.equals((TextMenuItemId.TRANSLATE)) ||
  25.         menuItem.id.equals((TextMenuItemId.SEARCH)) ||
  26.         menuItem.id.equals((TextMenuItemId.AI_WRITER))
  27.       )
  28.     });
  29.     let customItem1: TextMenuItem = {
  30.       content: 'customItem1',
  31.       id: TextMenuItemId.of('customItem1'),
  32.       icon: $r('app.media.icon')
  33.     };
  34.     let customItem2: TextMenuItem = {
  35.       content: $r('app.string.customItem2'),
  36.       id: TextMenuItemId.of('customItem2'),
  37.       icon: $r('app.media.icon')
  38.     };
  39.     items.push(customItem1);// Add an item to the end of the item list.
  40.     items.unshift(customItem2);// Add an item to the beginning of the item list.
  41. 

  42.     return items;
  43.   }
  44. 

  45.   onMenuItemClick(menuItem: TextMenuItem, textRange: TextRange): boolean {
  46.     if (menuItem.id.equals(TextMenuItemId.CUT)) {
  47.       // Custom behavior
  48.       console.info("Intercept ID: CUT")
  49.       // Return true to intercept this menu item and not perform the system default cut operation.
  50.       return true;
  51.     } else if (menuItem.id.equals(TextMenuItemId.COPY)) {
  52.       // Custom behavior
  53.       console.info("Not intercept ID: COPY")
  54.       // Return false to not intercept this menu item and perform the system default copy operation.
  55.       return false;
  56.     } else if (menuItem.id.equals(TextMenuItemId.of('customItem1'))) {
  57.       // Custom behavior
  58.       console.info("Intercept ID: customItem1")
  59.       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.
  60.     } else if (menuItem.id.equals((TextMenuItemId.of($r('app.string.customItem2'))))){
  61.       // Custom behavior
  62.       console.info("Intercept ID: app.string.customItem2")
  63.       return true;
  64.     }
  65.     return false;// Return the default value false.
  66.   }
  67. 

  68.    onPrepareMenu = (menuItems: Array<TextMenuItem>) => {
  69.     let item1: TextMenuItem = {
  70.       content: 'prepare1',
  71.       id: TextMenuItemId.of('prepareMenu1'),
  72.     };
  73.     let item2: TextMenuItem = {
  74.       content: 'prepare2' + selectText,
  75.       id: TextMenuItemId.of('prepareMenu2'),
  76.     };
  77.     menuItems.push(item1);// Add an item to the end of the item list.
  78.     menuItems.unshift(item2);// Add an item to the beginning of the item list.
  79. 

  80.     return menuItems;
  81.   }
  82. 

  83.   @State EditMenuOptions: EditMenuOptions =
  84.     { onCreateMenu: this.onCreateMenu, onMenuItemClick: this.onMenuItemClick, onPrepareMenu:this.onPrepareMenu }
  85. 

  86.   build() {
  87.     Column() {
  88.       Web({ src: $rawfile("index.html"), controller: this.controller })
  89.         .editMenuOptions(this.EditMenuOptions)
  90.         .javaScriptProxy({
  91.           object: this.testObj,
  92.           name: "testObjName",
  93.           methodList: ["setSelectText"],
  94.           controller: this.controller,
  95.         })
  96.     }
  97.   }
  98. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4.   <head>
  5.       <title>Test Web Page</title>
  6.   </head>
  7.   <body>
  8.     <h1>editMenuOptions Demo</h1>
  9.     <span>edit menu options</span>
  10.     <script>
  11.       document.addEventListener('selectionchange', () => {
  12.         var selection = window.getSelection();
  13.         if (selection.rangeCount > 0) {
  14.           var selectedText = selection.toString();
  15.           testObjName.setSelectText(selectedText);
  16.         }
  17.       });
  18.   </script>
  19.   </body>
  20. </html>

enableHapticFeedback13+

enableHapticFeedback(enabled: boolean)

Sets whether to enable haptic feedback for long-pressed text in the Web component. The ohos.permission.VIBRATE permission must be declared. When this attribute is not explicitly called, haptic feedback is enabled by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
enabled boolean Yes

Whether to enable vibration.

true indicates enabling vibration, and false indicates disabling vibration.

When undefined or null is passed in, the default value is retained, that is, vibration is enabled.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.       .enableHapticFeedback(true)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4.   <head>
  5.       <title>Test Web Page</title>
  6.   </head>
  7.   <body>
  8.     <h1>enableHapticFeedback Demo</h1>
  9.     <span>enable haptic feedback</span>
  10.   </body>
  11. </html>

bindSelectionMenu13+

bindSelectionMenu(elementType: WebElementType, content: CustomBuilder, responseType: WebResponseType, options?: SelectionMenuOptionsExt)

Sets the custom selection menu.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
elementType WebElementType Yes Menu type.
content CustomBuilder Yes Menu content.
responseType WebResponseType Yes Response type of the menu.
options SelectionMenuOptionsExt No Options of the menu. The default configuration is used when undefined or null is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. import { pasteboard } from '@kit.BasicServicesKit';
  4. import { BusinessError } from '@kit.BasicServicesKit';
  5. 

  6. interface PreviewBuilderParam {
  7.   width: number;
  8.   height: number;
  9.   url:Resource | string | undefined;
  10. }
  11. 

  12. interface PreviewBuilderParamForImage {
  13.   previewImage: Resource | string | undefined;
  14.   width: number;
  15.   height: number;
  16. }
  17. 

  18. 

  19. @Builder function PreviewBuilderGlobalForImage($$: PreviewBuilderParamForImage) {
  20.   Column() {
  21.     Image($$.previewImage)
  22.       .objectFit(ImageFit.Fill)
  23.       .autoResize(true)
  24.   }.width($$.width).height($$.height)
  25. }
  26. 

  27. @Entry
  28. @Component
  29. struct SelectionMenuLongPress {
  30.   controller: webview.WebviewController = new webview.WebviewController();
  31.   previewController: webview.WebviewController = new webview.WebviewController();
  32.   @Builder PreviewBuilder($$: PreviewBuilderParam){
  33.     Column() {
  34.       Stack(){
  35.         Text("") // Select whether to display the URL.
  36.           .padding(5)
  37.           .width('100%')
  38.           .textAlign(TextAlign.Start)
  39.           .backgroundColor(Color.White)
  40.           .copyOption(CopyOptions.LocalDevice)
  41.           .maxLines(1)
  42.           .textOverflow({overflow:TextOverflow.Ellipsis})
  43.         Progress({ value: this.progressValue, total: 100, type: ProgressType.Linear }) // Display the progress bar.
  44.           .style({ strokeWidth: 3, enableSmoothEffect: true })
  45.           .backgroundColor(Color.White)
  46.           .opacity(this.progressVisible?1:0)
  47.           .backgroundColor(Color.White)
  48.       }.alignContent(Alignment.Bottom)
  49.       Web({src:$$.url,controller: new webview.WebviewController()})
  50.         .javaScriptAccess(true)
  51.         .fileAccess(true)
  52.         .onlineImageAccess(true)
  53.         .imageAccess(true)
  54.         .domStorageAccess(true)
  55.         .onPageBegin(()=>{
  56.           this.progressValue = 0;
  57.           this.progressVisible = true;
  58.         })
  59.         .onProgressChange((event)=>{
  60.           this.progressValue = event.newProgress;
  61.         })
  62.         .onPageEnd(()=>{
  63.           this.progressVisible = false;
  64.         })
  65.         .hitTestBehavior(HitTestMode.None) // Disable the gesture response during web page preview.
  66.     }.width($$.width).height($$.height) // Set the preview width and height.
  67.   }
  68. 

  69.   private result: WebContextMenuResult | undefined = undefined;
  70.   @State previewImage: Resource | string | undefined = undefined;
  71.   @State previewWidth: number = 1;
  72.   @State previewHeight: number = 1;
  73.   @State previewWidthImage: number = 1;
  74.   @State previewHeightImage: number = 1;
  75.   @State linkURL:string = "";
  76.   @State progressValue:number = 0;
  77.   @State progressVisible:boolean = true;
  78.   uiContext: UIContext = this.getUIContext();
  79.   enablePaste = false;
  80. 

  81.   clearSelection() {
  82.     try {
  83.       this.controller.runJavaScript(
  84.         'clearSelection()',
  85.         (error, result) => {
  86.           if (error) {
  87.             console.error(`run clearSelection JavaScript error, ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
  88.             return;
  89.           }
  90.           if (result) {
  91.             console.info(`The clearSelection() return value is: ${result}`);
  92.           }
  93.         });
  94.     } catch (error) {
  95.       console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
  96.     }
  97.   }
  98. 

  99. 

  100.   @Builder
  101.   LinkMenuBuilder() {
  102.     Menu() {
  103.       MenuItem({ content: 'Copy Link', })
  104.         .onClick(() => {
  105.           const pasteboardData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, this.linkURL);
  106.           const systemPasteboard = pasteboard.getSystemPasteboard();
  107.           systemPasteboard.setData(pasteboardData);
  108.         })
  109.       MenuItem({content:'Open Link'})
  110.         .onClick(()=>{
  111.           this.controller.loadUrl(this.linkURL);
  112.         })
  113.     }
  114.   }
  115.   @Builder
  116.   ImageMenuBuilder() {
  117.     Menu() {
  118.       MenuItem({ content: 'Copy Image', })
  119.         .onClick(() => {
  120.           this.result?.copyImage();
  121.           this.result?.closeContextMenu();
  122.         })
  123.     }
  124.   }
  125.   @Builder
  126.   TextMenuBuilder() {
  127.     Menu() {
  128.       MenuItem({ content: 'Copy', })
  129.         .onClick(() => {
  130.           try {
  131.             this.controller.runJavaScript(
  132.               'copySelectedText()',
  133.               (error, result) => {
  134.                 if (error) {
  135.                   console.error(`run copySelectedText JavaScript error, ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
  136.                   return;
  137.                 }
  138.                 if (result) {
  139.                   console.info(`The copySelectedText() return value is: ${result}`);
  140.                 }
  141.               });
  142.           } catch (error) {
  143.             console.error(`Failed to clear selection. Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
  144.           }
  145.           this.clearSelection()
  146.         }).backgroundColor(Color.Pink)
  147.     }
  148.   }
  149.   build() {
  150.     Column() {
  151.       Web({ src: $rawfile("index.html"), controller: this.controller })
  152.         .javaScriptAccess(true)
  153.         .fileAccess(true)
  154.         .onlineImageAccess(true)
  155.         .imageAccess(true)
  156.         .domStorageAccess(true)
  157.         .bindSelectionMenu(WebElementType.TEXT, this.TextMenuBuilder, WebResponseType.LONG_PRESS,
  158.           {
  159.             onAppear: () => {},
  160.             onDisappear: () => {},
  161.             menuType: MenuType.SELECTION_MENU,
  162.           })
  163.         .bindSelectionMenu(WebElementType.LINK, this.LinkMenuBuilder, WebResponseType.LONG_PRESS,
  164.           {
  165.             onAppear: () => {},
  166.             onDisappear: () => {
  167.               this.result?.closeContextMenu();
  168.             },
  169.             preview: this.PreviewBuilder({
  170.               width: 500,
  171.               height: 400,
  172.               url:this.linkURL
  173.             }),
  174.             menuType: MenuType.PREVIEW_MENU
  175.           })
  176.         .bindSelectionMenu(WebElementType.IMAGE, this.ImageMenuBuilder, WebResponseType.LONG_PRESS,
  177.           {
  178.             onAppear: () => {},
  179.             onDisappear: () => {
  180.               this.result?.closeContextMenu();
  181.             },
  182.             preview: PreviewBuilderGlobalForImage({
  183.               previewImage: this.previewImage,
  184.               width: this.previewWidthImage,
  185.               height: this.previewHeightImage,
  186.             }),
  187.             menuType: MenuType.PREVIEW_MENU,
  188.           })
  189.         .zoomAccess(true)
  190.         .onContextMenuShow((event) => {
  191.           if (event) {
  192.             this.result = event.result;
  193.             this.previewWidthImage = this.uiContext!.px2vp(event.param.getPreviewWidth());
  194.             this.previewHeightImage = this.uiContext!.px2vp(event.param.getPreviewHeight());
  195.             if (event.param.getSourceUrl().indexOf("resource://rawfile/") == 0) {
  196.               this.previewImage = $rawfile(event.param.getSourceUrl().substring(19));
  197.             } else {
  198.               this.previewImage = event.param.getSourceUrl();
  199.             }
  200.             this.linkURL = event.param.getLinkUrl()
  201.             // Return true to intercept the system default context menu and use the custom menu.
  202.             return true;
  203.           }
  204.           return false;
  205.         })
  206.     }
  207. 

  208.   }
  209.   // Swipe back
  210.   onBackPress(): boolean | void {
  211.     if (this.controller.accessStep(-1)) {
  212.       this.controller.backward();
  213.       return true;
  214.     } else {
  215.       return false;
  216.     }
  217.   }
  218. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html lang="zh-CN">
  4. <head>
  5.     <meta charset="UTF-8">
  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0">
  7.     <title>Touch and hold to copy text</title>
  8.     <style>
  9.         .container {
  10.             background-color: white;
  11.             padding: 30px;
  12.             margin: 20px 0;
  13.         }
  15.         .context {
  16.             line-height: 1.8;
  17.             font-size: 18px;
  18.         }
  20.         .context span {
  21.             border-radius: 8px;
  22.             background-color: #f8f9fa;
  23.         }
  25.         .context a {
  26.             color: #3498db;
  27.             text-decoration: none;
  28.             font-size: 18px;
  29.             font-weight: 600;
  30.             padding: 12px 24px;
  31.             border: 2px solid #3498db;
  32.             border-radius: 30px;
  33.             display: inline-block;
  34.             position: relative;
  35.             overflow: hidden;
  36.             margin-bottom: 20px;
  37.         }
  39.         .context img {
  40.             max-width: 100%;
  41.             height: auto;
  42.             display: block;
  43.             margin-bottom: 20px;
  44.         }
  46.         .context:hover img {
  47.             transform: scale(1.05);
  48.         }
  49.     </style>
  50. </head>
  51. <body>
  52. <div class="container">
  53. 

  54.     <div class="context">
  55.         <!--img.png is in the same directory as the html file-->
  56.         <img src="img.png">
  57.     </div>
  58. 

  59.     <div class="context">
  60.         <a  href="https://www.example.com">Touch and hold the link to display the menu</a>
  61.     </div>
  62. 

  63.     <div class="context">
  64.         <span>In this digital age, the text copying functionality has grown increasingly important. Whether quoting famous remarks, saving key information, or sharing interesting content, copying text is an integral part of our daily operations.</span>
  65.     </div>
  66. 

  67. </div>
  68. <br>
  69. 

  70. <script>
  71.     function copySelectedText() {
  72.         const selectedText = window.getSelection().toString();
  73.         if (selectedText.length > 0) {
  74.             // Use the Clipboard API to copy text.
  75.             navigator.clipboard.writeText(selectedText)
  76.                 .then(() => {
  77.                     showNotification();
  78.                 })
  79.                 .catch(err => {
  80.                     console.error('Copy failed:', err);
  81.                 });
  82.         }
  83.     }
  84.      function clearSelection() {
  85.         if (window.getSelection) {
  86.             window.getSelection().removeAllRanges();
  87.         }
  88.     }
  89. </script>
  90. </body>
  91. </html>

blurOnKeyboardHideMode14+

blurOnKeyboardHideMode(mode: BlurOnKeyboardHideMode)

Sets the blur mode for Web elements when the soft keyboard is dismissed. If this attribute is not explicitly called, the BlurOnKeyboardHideMode.SILENT mode is used by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
mode BlurOnKeyboardHideMode Yes Whether to enable blur mode of the web element when soft keyboard is hidden. The default value is BlurOnKeyboardHideMode.SILENT.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State blurMode: BlurOnKeyboardHideMode = BlurOnKeyboardHideMode.BLUR;
  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .blurOnKeyboardHideMode(this.blurMode)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4.   <head>
  5.       <title>Test Web Page</title>
  6.   </head>
  7.   <body>
  8.     <h1>blurOnKeyboardHideMode Demo</h1>
  9.     <input type="text" id="input_a">
  10.     <script>
  11.       const inputElement = document.getElementById('input_a');
  12.       inputElement.addEventListener('blur', function() {
  13.         console.info('Input has lost focus');
  14.       });
  15.     </script>
  16.   </body>
  17. </html>

enableFollowSystemFontWeight18+

enableFollowSystemFontWeight(follow: boolean)

Sets whether the Web component can change the font weight according to the system settings. When this attribute is not explicitly called, the Web component does not change the font weight according to the system settings by default.

NOTE

Currently, only front-end text elements support this capability. The canvas element and embedded .docx and .pdf texts do not support this capability.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
follow boolean Yes

Whether the Web component can change the font weight according to the system settings.

The value true means that the Web component can change the font weight according to the system settings, and false means the opposite.

When undefined or null is passed in, the value is false.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   build() {
  9.     Column() {
  10.       Web({ src: "www.example.com", controller: this.controller })
  11.         .enableFollowSystemFontWeight(true)
  12.     }
  13.   }
  14. }

optimizeParserBudget15+

optimizeParserBudget(optimizeParserBudget: boolean)

Sets whether to enable segment-based HTML parsing optimization. If no attribute is explicitly called, the parsing time is used as the segment point by default.

To 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.

After optimization is enabled, the ArkWeb kernel not only checks whether the parsing time exceeds the limit, but also additionally determines whether the number of parsed tokens (the smallest parsing units of an HTML document, such as <div>, attr="xxx", etc.) exceeds the threshold specified by the kernel, and lowers this threshold. When the FCP (First Contentful Paint) of the page is triggered, the default interrupt judgment logic is restored. This makes the parsing operations before FCP more frequent, thereby increasing the possibility that the first-frame content is parsed and enters the rendering phase earlier, while effectively reducing the rendering workload of the first frame, ultimately advancing the FCP time.

When 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.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
optimizeParserBudget boolean Yes

Whether to enable segment-based HTML parsing optimization.

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.

If undefined or null is passed in, the value is false.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController()
  8.   build() {
  9.     Column() {
  10.       Web({ src: 'www.example.com', controller: this.controller })
  11.         .optimizeParserBudget(true)
  12.     }
  13.   }
  14. }

enableWebAVSession18+

enableWebAVSession(enabled: boolean)

Sets whether to support an application to connect to media controller. If this attribute is not explicitly set, the application can connect to media controller by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
enabled boolean Yes

Whether to support an application to connect to media controller.

The value true means to support an application to connect to media controller, and false means the opposite.

When undefined or null is passed in, the value is true.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   build() {
  9.     Column() {
  10.       Web({ src: $rawfile('index.html'), controller: this.controller })
  11.         .enableWebAVSession(true)
  12.     }
  13.   }
  14. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <title>Video Playback Page</title>
  6. </head>
  7. <body>
  8.     <h1>Video Playback</h1>
  9.     <video id="testVideo" controls>
  10.         <!--Save an MP4 media file in the rawfile directory of resources and name it example.mp4.-->
  11.         <source src="example.mp4" type="video/mp4">
  12.     </video>
  13. </body>
  14. </html>

nativeEmbedOptions16+

nativeEmbedOptions(options?: EmbedOptions)

Sets the same-layer rendering configuration. This attribute takes effect only when enableNativeEmbedMode is enabled and cannot be dynamically modified. If this attribute is not explicitly called, the default value {supportDefaultIntrinsicSize: false} is used.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
options EmbedOptions No

Configuration options of the same-layer rendering.

If undefined or null is passed in, the value {supportDefaultIntrinsicSize: false} is used.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   options: EmbedOptions = {supportDefaultIntrinsicSize: true};
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: $rawfile("index.html"), controller: this.controller })
  13.         .enableNativeEmbedMode(true)
  14.         .nativeEmbedOptions(this.options)
  15.     }
  16.   }
  17. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <title>Same-Layer Rendered Fixed-Size HTML Test</title>
  6. </head>
  7. <body>
  8. <div>
  9.     <embed id="input" type = "native/view" style = "background-color:red"/>
  10. </div>
  11. </body>
  12. </html>

enableDataDetector20+

enableDataDetector(enable: boolean)

Sets whether to recognize special entities of web texts, such as emails, phone numbers, and URLs. This API depends on the text recognition capability at the bottom layer of the device. Otherwise, the setting is invalid. When this attribute is not explicitly called, the detector is disabled by default.

NOTE

Attributes such as dataDetectorConfig and enableSelectedDataDetector take effect only when this attribute is enabled.

If enableDataDetector is set to true and dataDetectorConfig 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:

Collapse
Word wrap
Dark theme
Copy code
  1. color: '#ff0a59f7',
  2. decoration:{
  3.   type: TextDecorationType.Underline,
  4.   color: '#ff0a59f7',
  5.   style: TextDecorationStyle.SOLID
  6. }

When enableDataDetector is set to true and copyOptions is set to CopyOptions.LocalDevice, the AI menu feature is activated. In this case, after text is selected on the web page, the text selection menu can display the corresponding AI menu items, including url (open link), email (create new email), phoneNumber (call), address (navigate to the location), and dateTime (create new schedule reminder) from TextMenuItemId.

When the AI menu takes effect, the corresponding option can be displayed only when the selection contains a complete AI entity. This menu item and the askAI menu item in TextMenuItemId do not appear at the same time.

For details about the application scenario, see Using Smart Text Data Detector.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
enable boolean Yes

Whether to enable web text recognition. The value true means to enable web text recognition, and false means the opposite.

When undefined or null is passed in, the attribute setting does not take effect.
NOTE

Dynamically updating the enableDataDetector status does not affect the current page immediately. You need to refresh the page for the new configuration to take effect.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .enableDataDetector(true)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <title>Example enableDataDetector</title>;
  6. </head>
  7. <body>
  8.     <p> Telephone: 400-123-4567 </p>
  9.     <p>Email: example@example.com </p>
  10. </body>
  11. </html>

dataDetectorConfig20+

dataDetectorConfig(config: TextDataDetectorConfig)

Configures text recognition settings.

This API must be used together with enableDataDetector. It takes effect only when enableDataDetector is set to true.

When entities A and B overlap, the following rules are followed:

  1. If A is a subset of B (A ⊂ B), then B is retained; otherwise, A is retained.

  2. 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.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
config TextDataDetectorConfig Yes Text recognition configuration.
NOTE

The onDetectResultUpdate method in TextDataDetectorConfig is not supported in the Web component. The configured callback will not be called.

When copyOptions is set to CopyOptions.None, the enablePreviewMenu item in TextDataDetectorConfig is invalid.

Dynamically updating the TextDataDetectorConfig configuration does not affect the current page immediately. You need to refresh the page for the new configuration to take effect.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .enableDataDetector(true)
  13.         .dataDetectorConfig({
  14.           types: [
  15.             TextDataDetectorType.PHONE_NUMBER,
  16.             TextDataDetectorType.EMAIL
  17.           ],
  18.           color: Color.Red,
  19.           decoration: {
  20.             type: TextDecorationType.LineThrough,
  21.             color: Color.Green,
  22.             style: TextDecorationStyle.WAVY
  23.           }
  24.         })
  25.     }
  26.   }
  27. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <title>Example dataDetectorConfig</title>;
  6. </head>
  7. <body>
  8.     <p> Telephone: 400-123-4567 </p>
  9.     <p> Email: 12345678901@example.com </p>
  10.     <p> Website: www.example.com (cannot be identified) </p>
  11. </body>
  12. </html>

enableSelectedDataDetector22+

enableSelectedDataDetector(enable: boolean)

Sets whether to enable the AI menu feature for text selection menu. After the AI menu feature is enabled, the email, phone number, website, date, and address in the selection can be identified, and the corresponding AI menu items are displayed in the text selection menu. By default, the AI menu feature is enabled.

When the AI menu feature is enabled, after text is selected on the web page, the text selection menu can display the corresponding AI menu items, including url (open link), email (create new email), phoneNumber (call), address (navigate to the location), and dateTime (create new schedule) from TextMenuItemId.

When the AI menu takes effect, the corresponding option can be displayed only when the selection contains a complete AI entity. This menu item and the askAI menu item in TextMenuItemId do not appear at the same time.

For details about the application scenario, see Using Smart Text Data Detector.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
enable boolean Yes

Whether to enable web text recognition. The value true means to enable web text recognition, and false means the opposite.

If undefined or null is passed in, the attribute is reset to the default value.
NOTE

If enableSelectedDataDetector is not set or is set to true, the types in dataDetectorConfig are used. If dataDetectorConfig is not set, all types are recognized by default.

If enableSelectedDataDetector is set to false, the AI menu for text selection is not activated.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .enableSelectedDataDetector(true)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <title>enableSelectedDataDetector Example</title>
  6. </head>
  7. <body>
  8.     <p> Telephone: 400-123-4567 </p>
  9.     <p>Email: example@example.com </p>
  10. </body>
  11. </html>

gestureFocusMode20+

gestureFocusMode(mode: GestureFocusMode)

Sets the gesture focus mode of the Web component, which controls the focus response behavior of the Web component. If this attribute is not explicitly called, the default behavior is that any gesture causes the Web component to gain focus when the gesture is pressed.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
mode GestureFocusMode Yes Gesture focus mode of the Web component. If undefined or null is passed in, the value GestureFocusMode.DEFAULT is used.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State mode: GestureFocusMode = GestureFocusMode.DEFAULT;
  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .gestureFocusMode(this.mode)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.   <title>Test Web Page</title>
  6. </head>
  7. <body>
  8.   <input type="text" placeholder="Text">
  9. </body>
  10. </html>

rotateRenderEffect22+

rotateRenderEffect(effect: WebRotateEffect)

Sets how the final state of the Web component's content is rendered during its width and height animation process when the component rotates. If this attribute is not explicitly called, by default, the component's content stays at the final size and always aligned with the upper left corner of the component.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
effect WebRotateEffect Yes How the final state of the Web component's content is rendered during its width and height animation process when the component rotates.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State effect: WebRotateEffect = WebRotateEffect.TOPLEFT_EFFECT;
  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .rotateRenderEffect(this.effect)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.   <title>Test Web Page</title>
  6. </head>
  7. <body>
  8.   <p>Test Web Page</p>
  9. </body>
  10. </html>

forceEnableZoom21+

forceEnableZoom(enable: boolean)

Sets whether to enable the forcible zoom functionality for the Web component.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
enable boolean Yes

Whether to comply with the zoom restriction specified by the <meta name="viewport"> tag on the web page.

The value true means to not comply with the web page zoom restriction, and false means the opposite.

When undefined or null is passed in, the attribute setting does not take effect.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .forceEnableZoom(true)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.   <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no">
  6.   <title>Test Web Page</title>
  7. </head>
  8. <body>
  9.   <h1>forceEnableZoom Demo</h1>
  10.   <span>You can scale page when forceEnableZoom is true.</span>
  11. </body>
  12. </html>

backToTop22+

backToTop(backToTop: boolean)

Sets whether to enable the back-to-top feature for the Web component when the status bar is touched. When this attribute is not explicitly called, the back-to-top feature for the status bar is enabled by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
backToTop boolean Yes

Whether to enable the back-to-top feature. The value true means to enable the feature, and false means the opposite.

When undefined or null is passed in, the value is true.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .backToTop(true)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.     <meta name="viewport" id="viewport" content="width=device-width, initial-scale=1.0">
  6.     <style>
  7.         .blue {
  8.           background-color: lightblue;
  9.         }
  10.         .green {
  11.           background-color: lightgreen;
  12.         }
  13.         .blue, .green {
  14.          font-size:16px;
  15.          height:200px;
  16.          text-align: center;       /* Horizontally centered */
  17.          line-height: 200px;       /* Vertically centered (the height matches the container height) */
  18.         }
  19.     </style>
  20. </head>
  21. <body>
  22. <div class="blue" >webArea</div>
  23. <div class="green">webArea</div>
  24. <div class="blue">webArea</div>
  25. <div class="green">webArea</div>
  26. <div class="blue">webArea</div>
  27. <div class="green">webArea</div>
  28. <div class="blue">webArea</div>
  29. <div class="green">webArea</div>
  30. <div class="blue">webArea</div>
  31. </body>
  32. </html>

blankScreenDetectionConfig22+

blankScreenDetectionConfig(detectConfig: BlankScreenDetectionConfig)

Sets the blank screen detection configuration, such as whether to enable the detection, detection time, and detection policy. When this attribute is not explicitly called, blank screen detection is disabled by default.

NOTE
  • Based on the configuration of detectConfig, onDetectedBlankScreen may be triggered when a blank screen or near-blank screen is detected after a web page is loaded.
  • The setting takes effect in the next navigation.
  • After the user interacts with the web page, the system does not check whether a blank screen occurs.
  • This feature is not supported when layoutMode is set to WebLayoutMode.FIT_CONTENT.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
detectConfig BlankScreenDetectionConfig Yes Blank screen detection policy.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // blankScreenDetectionConfig.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .blankScreenDetectionConfig({
  13.           enable: true,
  14.           detectionTiming: [2, 4, 6, 8],
  15.           contentfulNodesCountThreshold: 4,
  16.           detectionMethods:[BlankScreenDetectionMethod.DETECTION_CONTENTFUL_NODES_SEVENTEEN]
  17.         })
  18.         .onDetectedBlankScreen((event: BlankScreenDetectionEventInfo)=>{
  19.           console.info(`Found blank screen on ${event.url}.`);
  20.           console.info(`The blank screen reason is ${event.blankScreenReason}.`);
  21.           console.info(`The blank screen detail is ${event.blankScreenDetails?.detectedContentfulNodesCount}.`);
  22.         })
  23.     }
  24.   }
  25. }

enableImageAnalyzer23+

enableImageAnalyzer(enable: boolean)

Sets whether to enable AI analysis of web page images. Currently, the image text recognition feature is supported. If this attribute is not explicitly called, this feature is enabled by default.

NOTE

When you long-press or hover the mouse over the image text, AI analyzer is triggered and the text in the image can be selected. The specifications of images that can trigger analyzer are as follows:

  • The original width and height of the image are greater than or equal to 100 pixels.

  • For devices other than 2-in-1 devices, the image rendering width must exceed 80% of the web page width.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
enable boolean Yes

Whether to enable AI analyzer for web page images. The value true means to enable AI analyzer, and false means the opposite.

If undefined or null is passed in, the value is reset to true.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .enableImageAnalyzer(true) // To disable the image analyzer, set this parameter to false.
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <head>
  4.   <meta charset="UTF-8">
  5.   <meta name="viewport" id="viewport" content="width=device-width, initial-scale=1.0">
  6.   <style>
  7.     .image-container {
  8.       width: 90%;
  9.     }
  10.     .image-container img {
  11.       width: 100%;
  12.       height: auto;
  13.     }
  14.   </style>
  15. </head>
  16. <body>
  17.   <div class="image-container">
  18.     <!--example.jpg is in the same directory as the HTML file-->
  19.     <img src="example.jpg" alt="Image to be analyzed by AI">
  20.   </div>
  21. </body>
  22. </html>

enableAutoFill23+

enableAutoFill(value: boolean)

Sets whether to enable web page autofill. By default, this feature is enabled.

NOTE

The autofill feature of this API depends on SmartFill service and Password Autofill Service.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
value boolean Yes

Whether to enable autofill for web pages. The value true means to enable autofill, and false means the opposite.

When undefined or null is passed in, the value is true.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .enableAutoFill(true)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!-- index.html -->
  2. <!DOCTYPE html>
  3. <html>
  4.   <head>
  5.     <meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0;" name="viewport"/>
  6.     <title>Autofill test</title>
  7.   </head>
  8.   <body>
  9.     <h4 align="center">Autofill test</h4>
  10.     <form method="post" action="">
  11.       <div align="center">
  12.         <label for="name" style="width: 120px; display: inline-block; text-align: end;">Name:</label>
  13.         <input type="text" id="name" autocomplete="name"/><br/><br/>
  14.         <label for="tel-national" style="width: 120px; display: inline-block; text-align: end;">Mobile number:</label>
  15.         <input type="text" id="tel-national" autocomplete="tel-national"/><br/><br/>
  16.       </div>
  17.       <div align="center">
  18.         <button type="submit" style="width: 80px">Submit</button>
  19.       </div>
  20.     </form>
  21.   </body>
  22. </html>

enableDefaultContextMenu24+

enableDefaultContextMenu(enable: boolean)

Sets whether to enable the default right-click context menu. If this method is not explicitly called, the menu is disabled by default. The default menu supports only the CUT, COPY, PASTE, and SELECT_ALL menu items.

NOTE
  • When the onContextMenuShow callback is set and returns true in the callback, the setting of this API does not take effect.
  • The default menu items are controlled by editMenuOptions, through which you can customize the menu options.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
enable boolean Yes

Whether to enable the default right-click context menu. The value true indicates enabling, and false indicates disabling.

The value is false when undefined or null is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .enableDefaultContextMenu(true)
  13.     }
  14.   }
  15. }

enableDrag

enableDrag(value: boolean)

Sets whether to enable the drag function. If this attribute is not explicitly called, the web page drag function is enabled by default.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
value boolean Yes Whether to enable the web page drag function. The value true indicates enabling, and false indicates disabling. When undefined or null is passed in, the value is true.
Example
Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct Index {
  7.   private controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile('test.html'), controller: this.controller })
  12.         .enableDrag(false)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--test.html-->
  2. <!DOCTYPE html>
  3. <html>
  4.   <head><meta charset="UTF-8"><title>Drag test</title></head>
  5.   <body>
  6.     <div id="drag" draggable="true" style="width:100px;height:100px;background:red;margin:20px;"></div>
  7.     <div id="drop" style="width:200px;height:200px;background:gray;margin:20px;"></div>
  8.     <script>
  9.       drag.ondragstart=e=>e.dataTransfer.setData('text/plain','');
  10.       drop.ondragover=e=>e.preventDefault();
  11.       drop.ondrop=e=>{e.preventDefault(); drop.style.background='green';};
  12.       drag.ondragend=()=>{drop.style.background='gray';};
  13.     </script>
  14.   </body>
  15. </html>

password(deprecated)

password(password: boolean)

Sets whether to save the password. This API is an empty API.

NOTE

This API is supported since API version 8 and deprecated since API version 10. You are advised to use enableAutoFill23+ instead.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
password boolean Yes

Whether to allow the web component to save passwords. The value true means the web component is allowed to save passwords, and false means the opposite.

If undefined or null is passed, the default value false is used.

textZoomAtio(deprecated)

textZoomAtio(textZoomAtio: number)

Sets the text zoom ratio of the page.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use textZoomRatio9+ instead.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
textZoomAtio number Yes

Text zoom percentage of the web page to set. 100 indicates the original size, a value greater than 100 indicates zooming in, and a value less than 100 indicates zooming out.

The value range is (0, 2147483647].

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct WebComponent {
  5.   controller: WebController = new WebController()
  6.   @State ratio: number = 150
  7.   build() {
  8.     Column() {
  9.       Web({ src: 'www.example.com', controller: this.controller })
  10.         .textZoomAtio(this.ratio)
  11.     }
  12.   }
  13. }

userAgent(deprecated)

userAgent(userAgent: string)

Sets the user agent.

NOTE

This API is supported since API version 8 and deprecated since API version 10. You are advised to use setCustomUserAgent10+ instead.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
userAgent string Yes User agent to set.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @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';
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: 'www.example.com', controller: this.controller })
  13.         .userAgent(this.userAgent)
  14.     }
  15.   }
  16. }

tableData(deprecated)

tableData(tableData: boolean)

Sets whether to save form data. When this attribute is not explicitly called, the Web component is allowed to save form data by default. This API is an empty API.

NOTE

This API is supported since API version 8 and deprecated since API version 10. You are advised to use enableAutoFill23+ instead.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
tableData boolean Yes

Whether to allow the Web component to save form data. The value true means the Web component is allowed to save form data, and false means the opposite.

If undefined or null is passed, the value is true.

wideViewModeAccess(deprecated)

wideViewModeAccess(wideViewModeAccess: boolean)

Sets whether to support the viewport attribute of the HTML <meta> tag. This API is an empty API.

NOTE

This API is supported since API version 8 and deprecated since API version 10. You are advised to use metaViewport12+ instead.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
wideViewModeAccess boolean Yes

Whether to support the viewport attribute of the HTML <meta> tag.

The value true means to support the viewport attribute of the HTML <meta> tag, and false means the opposite.

selectionMenuOptions(deprecated)

selectionMenuOptions(expandedMenuOptions: Array<ExpandedMenuItemOptions>)

Sets the extended options of the custom context menu on selection, including the text content, icon, and callback.

The 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.

NOTE

When used together with editMenuOptions, this API does not take effect.

This API is supported since API version 12 and deprecated since API version 20. You are advised to use editMenuOptions12+ instead.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
expandedMenuOptions Array<ExpandedMenuItemOptions> Yes

Extended options of the custom context menu on selection.

The number of menu options, menu content size, and start icon size must be the same as those of the ArkUI Menu component.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State menuOptionArray: Array<ExpandedMenuItemOptions> = [
  9.     {content: 'Apple', startIcon: $r('app.media.icon'), action: (selectedText) => {
  10.       console.info('select info ' + selectedText.toString());
  11.     }},
  12.     {content: 'Banana', startIcon: $r('app.media.icon'), action: (selectedText) => {
  13.       console.info('select info ' + selectedText.toString());
  14.     }}
  15.   ];
  16. 

  17.   build() {
  18.     Column() {
  19.       Web({ src: $rawfile("index.html"), controller: this.controller })
  20.       .selectionMenuOptions(this.menuOptionArray)
  21.     }
  22.   }
  23. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.   <title>Test Web Page</title>
  6. </head>
  7. <body>
  8.   <h1>selectionMenuOptions Demo</h1>
  9.   <span>selection menu options</span>
  10. </body>
  11. </html>

zoomControlAccess22+

zoomControlAccess(zoomControlAccess: boolean)

Sets whether to allow zooming by pressing Ctrl + '-/+' or Ctrl + mouse wheel/touchpad.

If this attribute is not explicitly called, zooming by pressing Ctrl + '-/+' or Ctrl + mouse wheel/touchpad is allowed by default.

System capability: SystemCapability.Web.Webview.Core

Parameters

Expand
Name Type Mandatory Description
zoomControlAccess boolean Yes Set whether to allow scaling through combined keys. true indicates support, and false indicates no support. The value is false when null or undefined is passed in.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: $rawfile("index.html"), controller: this.controller })
  12.         .zoomControlAccess(true)
  13.     }
  14.   }
  15. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.   <meta name="viewport" content="width=device-width, initial-scale=1.0">
  6.   <title>Test Web Page</title>
  7. </head>
  8. <body>
  9.   <h1>zoomControlAccess Demo</h1>
  10.   <span>You can zoom in/out page when zoomControlAccess is true.</span>
  11. </body>
  12. </html>

aiSessionOptions

aiSessionOptions(aiSessions: Array<AISessionEvent>)

Configures custom frontend AI sessions for the Web component, used to register multiple custom AI sessions.

System capability: SystemCapability.Web.Webview.Core

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Parameters

Expand
Name Type Mandatory Description
aiSessions Array<AISessionEvent> Yes Array of frontend AI session configuration objects. Each object contains the AI session type and the corresponding lifecycle callback methods. Currently, only the models included in AISessionType are supported.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct DemoPage {
  7.   private webController: webview.WebviewController = new webview.WebviewController();
  8.   sessions: Map<string, string> = new Map<string, string>();
  9. 

  10.   onCreateAISession = (id: string, params: string, result: OnAISessionCallback): boolean => {
  11.     this.sessions.set(id, params); // Simulate creating an AI session.
  12.     console.info(`[AISession]onCreateAISession params: ${params}`);
  13.     // Notify the caller that the AI session is created successfully.
  14.     result(AISessionResultType.SUCCESS, "AISession created");
  15.     return true;
  16.   }
  17. 

  18.   onExecuteAIAction = (id: string, params: string, result: OnAISessionCallback): void => {
  19.     this.sessions.get(id); // Simulate retrieving the session and executing an action.
  20.     console.info(`[AISession]onExecuteAIAction params: ${params}`);
  21.     // Simulate streaming the AI execution result: multiple RUNNING calls indicate the task is in progress and return data chunks, and a final SUCCESS indicates task completion.
  22.     result(AISessionResultType.RUNNING, "AISession chunk 1\n");
  23.     result(AISessionResultType.RUNNING, "AISession chunk 2\n");
  24.     result(AISessionResultType.SUCCESS, "AISession chunk end\n");
  25.   }
  26. 

  27.   onDestroyAISession = (id: string): void => {
  28.     this.sessions.delete(id); // Simulate destroying the session and releasing resources.
  29.   }
  30. 

  31.   @State options: AISessionEvent = {
  32.     aiSessionType: AISessionType.SUMMARIZER,
  33.     onCreateAISession: this.onCreateAISession,
  34.     onExecuteAIAction: this.onExecuteAIAction,
  35.     onDestroyAISession: this.onDestroyAISession
  36.   }
  37. 

  38.   build() {
  39.     Column() {
  40.       Web({ src: $rawfile('index.html'), controller: this.webController })
  41.         .aiSessionOptions([this.options])
  42.     }
  43.     .width('100%')
  44.     .height('100%')
  45.   }
  46. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!DOCTYPE html>
  2. <html lang="zh-CN">
  3. <head>
  4.   <meta charset="UTF-8">
  5.   <meta name="viewport" content="width=device-width,initial-scale=1.0">
  6.   <title>Summarizer API Test</title>
  7. </head>
  8. <body style="max-width:600px;margin:20px auto;padding:0 16px;">
  9.   <p id="status">checking...</p>
  10.   <button id="initBtn" onclick="init()">Create Session</button>
  11.   <br><br>
  12.   <textarea id="input" rows="6" style="width:100%;font:inherit" placeholder="paste text to summarize"></textarea>
  13.   <br><br>
  14.   <button id="btn" onclick="run()" disabled>Summarize</button>
  15.   <pre id="result"></pre>
  16.   <script>
  17.     let s;
  18.     (async () => {
  19.       const d = document.getElementById('status');
  20.       if (!('Summarizer' in self)) { d.textContent = 'API not supported'; return; }
  21.       const a = await Summarizer.availability();
  22.       d.textContent = 'Summarizer: ' + a;
  23.       if (a === 'unavailable') document.getElementById('initBtn').disabled = true;
  24.     })();
  26.     async function init() {
  27.       const d = document.getElementById('status'), ib = document.getElementById('initBtn');
  28.       ib.disabled = true;
  29.       d.textContent = 'creating...';
  30.       try {
  31.         s = await Summarizer.create({
  32.           type: 'tldr', length: 'medium', format: 'plain-text',
  33.           monitor(m) { m.addEventListener('downloadprogress', e => { d.textContent = 'downloading ' + (e.loaded * 100 | 0) + '%' }); }
  34.         });
  35.         d.textContent = 'ready';
  36.         document.getElementById('btn').disabled = false;
  37.       } catch (e) { d.textContent = 'Error: ' + e.message; ib.disabled = false; }
  38.     }
  40.     async function run() {
  41.       const t = document.getElementById('input').value.trim();
  42.       if (!t || !s) return;
  43.       const btn = document.getElementById('btn'), r = document.getElementById('result');
  44.       btn.disabled = true;
  45.       r.textContent = '...';
  46.       try { r.textContent = await s.summarize(t); }
  47.       catch (e) { r.textContent = 'Error: ' + e.message; }
  48.       btn.disabled = false;
  49.     }
  50.   </script>
  51. </body>
  52. </html>

scrollbarLayoutPolicy

scrollbarLayoutPolicy(policy: ScrollbarLayoutPolicy)

Selects the layout mode of the vertical scrollbar within the Web component, used to adapt to the writing direction of different languages. The CONTENT mode is suitable for scenarios where the web page CSS direction attribute needs to be followed, while the SYSTEM mode is suitable for scenarios in multilingual apps where the system language direction needs to be followed, such as for right-to-left languages like Arabic and Hebrew.

System capability: SystemCapability.Web.Webview.Core

Model restriction: This API can be used only in the stage model.

Since: 26.0.0

Parameters

Expand
Name Type Mandatory Description
policy ScrollbarLayoutPolicy Yes Sets the layout mode of the vertical scrollbar in the Web component. Available values: CONTENT (follows the direction attribute of the web page CSS), SYSTEM (lays out based on the left-to-right or right-to-left writing direction of the system language. For right-to-left languages, the scrollbar is laid out on the left. This applies to all nested multi-level scrollbars in the web page).

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.         .width('100%')
  13.         .height('100%')
  14.         // Set to SYSTEM to indicate following the system language direction for layout. Set to CONTENT to indicate using the Web style layout.
  15.         .scrollbarLayoutPolicy(ScrollbarLayoutPolicy.SYSTEM)
  16.     }
  17.   }
  18. }

keyboardAppearance

keyboardAppearance(mode: WebKeyboardAppearanceMode)

Sets the keyboard appearance mode, which controls the appearance style of the keyboard that pops up for input boxes in the Web component, including immersive and non-immersive modes. If this method is not explicitly called, the system immersive mode is followed by default.

System capability: SystemCapability.Web.Webview.Core

Model restriction: This API can be used only in the stage model.

Since: 26.0.0

Parameters

Expand
Name Type Mandatory Description
mode WebKeyboardAppearanceMode Yes Keyboard appearance. When undefined or null is passed in, the system immersive mode is followed.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8.   @State appearanceMode: WebKeyboardAppearanceMode = WebKeyboardAppearanceMode.DARK_IMMERSIVE;
  9. 

  10.   build() {
  11.     Column() {
  12.       Web({ src: $rawfile("index.html"), controller: this.controller })
  13.       .keyboardAppearance(this.appearanceMode)
  14.     }
  15.   }
  16. }

HTML file to be loaded:

Collapse
Word wrap
Dark theme
Copy code
  1. <!--index.html-->
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5.   <title>Test web page</title>
  6. </head>
  7. <body>
  8.   <input type="text" placeholder="Text">
  9. </body>
  10. </html>

enableFullscreenVideoOverlay

enableFullscreenVideoOverlay(enabled: boolean)

Sets whether to enable the overlay fullscreen playback feature for the Web component. If this attribute is not explicitly called, this feature is disabled by default.

NOTE
  • Currently, only videos in H.264 and H.265 decoding formats are supported.
  • Only fullscreen requests initiated by video elements are responded to.

Since: 26.0.0

System capability: SystemCapability.Web.Webview.Core

Model restriction: This API can be used only in the stage model.

Device behavior: This API has no effect on the PCs/2-in-1 devices and works on other devices.

Parameters

Expand
Name Type Mandatory Description
enabled boolean Yes

Sets whether to enable the overlay fullscreen playback feature for the Web component.

true indicates enabling this feature.

false indicates disabling this feature.

When undefined or null is passed in, the value is false.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.       .enableFullscreenVideoOverlay(true)
  13.     }
  14.   }
  15. }

enableMediaNetworkProxy

enableMediaNetworkProxy(enabled: boolean)

Sets whether to enable the media resource network request proxy feature for the Web component. If this attribute is not explicitly called, this feature is disabled by default.

NOTE
  • Currently, only HLS streaming media videos are supported.

Since: 26.0.0

System capability: SystemCapability.Web.Webview.Core

Model restriction: This API can be used only in the stage model.

Parameters

Expand
Name Type Mandatory Description
enabled boolean Yes

Sets whether to enable the media resource network request proxy for the Web component.

true indicates enabling this function.

false indicates disabling it.

Example

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. import { webview } from '@kit.ArkWeb';
  3. 

  4. @Entry
  5. @Component
  6. struct WebComponent {
  7.   controller: webview.WebviewController = new webview.WebviewController();
  8. 

  9.   build() {
  10.     Column() {
  11.       Web({ src: 'www.example.com', controller: this.controller })
  12.       .enableMediaNetworkProxy(true)
  13.     }
  14.   }
  15. }
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice
Search in References
Enter a keyword.