# Web
The **Web** component can be used to display web pages. It can be used with the [@ohos.web.webview](js-apis-webview.md) module, which provides APIs for web control.
> **NOTE**
>
> - This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
> - You can preview how this component looks on a real device, but not in DevEco Studio Previewer.
## Required Permissions
To use online resources, the application must have the **ohos.permission.INTERNET** permission. For details about how to apply for a permission, see [Declaring Permissions](../../security/AccessToken/declare-permissions.md).
## Child Components
Not supported
## APIs
Web(options: { src: ResourceStr, controller: WebviewController | WebController, renderMode? : RenderMode, incognitoMode? : boolean, sharedRenderProcessToken? : string})
> **NOTE**
>
> Transition animation is not supported.
> **Web** components on the same page must be bound to different **WebviewController** instances.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ---------------------------------------- | ---- | ---------------------------------------- |
| src | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | Yes | Address of a web page resource. To access local resource files, use the **$rawfile** or **resource** protocol. To load a local resource file (in HTML or TXT format) in the sandbox outside of the application package, use **file://** to specify the path of the sandbox. **src** cannot be dynamically changed through a state variable (for example, @State). To change the value, call [loadUrl()](js-apis-webview.md#loadurl).|
| controller | [WebviewController9+](js-apis-webview.md#webviewcontroller) \| [WebController](#webcontroller) | Yes | Controller. This API is deprecated since API version 9. You are advised to use **WebviewController** instead.|
| renderMode12+ | [RenderMode](#rendermode12)| No | Rendering mode. **RenderMode.ASYNC_RENDER** (default, cannot be dynamically adjusted): The **Web** component is rendered asynchronously. **RenderMode.SYNC_RENDER**: The **Web** component is rendered synchronously within the current execution context.|
| incognitoMode11+ | boolean | No| Whether to enable incognito mode. The value **true** means to enable incognito mode, and **false** means the opposite. Default value: **false**|
| sharedRenderProcessToken12+ | string | No| The token of the shared rendering process specified by the **Web** component. In multi-rendering process mode, the **Web** component with the same token preferentially attempts to reuse the rendering process bound to the token. The token is bound to the rendering process when the rendering process is initialized. When the rendering process is not associated with a **Web** component, its binding to the token is removed. Default value: **""** |
**Example**
Example of loading online web pages:
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
Example of loading online web pages in incognito mode:
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller, incognitoMode: true })
}
}
}
```
Example of rendering the **Web** component synchronously within the current execution context:
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER })
}
}
}
```
Example of using the **Web** component to specify the shared rendering process.
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller, sharedRenderProcessToken: "111" })
Web({ src: 'www.w3.org', controller: this.controller, sharedRenderProcessToken: "111" })
}
}
}
```
Example of loading local web pages:
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
// Load a local resource file through $rawfile.
Web({ src: $rawfile("index.html"), controller: this.controller })
}
}
}
```
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
// Load a local resource file through the resource protocol.
Web({ src: "resource://rawfile/index.html", controller: this.controller })
}
}
}
```
Example of loading local resource files in the sandbox:
1. Obtain the sandbox path through the constructed singleton object **GlobalContext**.
```ts
// GlobalContext.ets
export class GlobalContext {
private constructor() {}
private static instance: GlobalContext;
private _objects = new Map();
public static getContext(): GlobalContext {
if (!GlobalContext.instance) {
GlobalContext.instance = new GlobalContext();
}
return GlobalContext.instance;
}
getObject(value: string): Object | undefined {
return this._objects.get(value);
}
setObject(key: string, objectClass: Object): void {
this._objects.set(key, objectClass);
}
}
```
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { GlobalContext } from '../GlobalContext';
let url = 'file://' + GlobalContext.getContext().getObject("filesDir") + '/index.html';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
// Load the files in the sandbox.
Web({ src: url, controller: this.controller })
}
}
}
```
2. Modify the **EntryAbility.ets** file.
The following uses **filesDir** as an example to describe how to obtain the path of the sandbox. For details about how to obtain other paths, see [Obtaining Application File Paths](../../application-models/application-context-stage.md#obtaining-application-file-paths).
```ts
// xxx.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { webview } from '@kit.ArkWeb';
import { GlobalContext } from '../GlobalContext';
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
// Data synchronization between the UIAbility component and UI can be implemented by binding filesDir to the GlobalContext object.
GlobalContext.getContext().setObject("filesDir", this.context.filesDir);
console.log("Sandbox path is " + GlobalContext.getContext().getObject("filesDir"));
}
}
```
HTML file to be loaded:
```html
Hello World
```
## Attributes
The following universal attributes are supported: [aspectRatio](../apis-arkui/arkui-ts/ts-universal-attributes-layout-constraints.md#aspectratio), [backdropBlur](../apis-arkui/arkui-ts/ts-universal-attributes-image-effect.md#backdropblur), [backgroundColor](../apis-arkui/arkui-ts/ts-universal-attributes-background.md#backgroundcolor), [bindContentCover](../apis-arkui/arkui-ts/ts-universal-attributes-modal-transition.md#bindcontentcover), [bindContextMenu](../apis-arkui/arkui-ts/ts-universal-attributes-menu.md#bindcontextmenu8), [bindMenu](../apis-arkui/arkui-ts/ts-universal-attributes-menu.md#bindmenu), [bindSheet](../apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md#bindsheet), [borderColor](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#bordercolor), [borderRadius](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#borderradius), [borderStyle](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#borderstyle), [borderWidth](../apis-arkui/arkui-ts/ts-universal-attributes-border.md#borderwidth), [clip](../apis-arkui/arkui-ts/ts-universal-attributes-sharp-clipping.md#clip), [constraintSize](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#constraintsize), [defaultFocus](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#defaultfocus9), [focusable](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#focusable), [tabIndex](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#tabindex9), [groupDefaultFocus](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#groupdefaultfocus9), [focusOnTouch](../apis-arkui/arkui-ts/ts-universal-attributes-focus.md#focusontouch9), [displayPriority](../apis-arkui/arkui-ts/ts-universal-attributes-layout-constraints.md#displaypriority), [enabled](../apis-arkui/arkui-ts/ts-universal-attributes-enable.md#enabled), [flexBasis](../apis-arkui/arkui-ts/ts-universal-attributes-flex-layout.md#flexbasis), [flexGrow](../apis-arkui/arkui-ts/ts-universal-attributes-flex-layout.md#flexgrow), [flexShrink](../apis-arkui/arkui-ts/ts-universal-attributes-flex-layout.md#flexshrink), [layoutWeight](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#layoutweight), [id](../apis-arkui/arkui-ts/ts-universal-attributes-component-id.md), [gridOffset](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md), [gridSpan](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md), [useSizeType](../apis-arkui/arkui-ts/ts-universal-attributes-grid.md), [height](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#height), [touchable](../apis-arkui/arkui-ts/ts-universal-attributes-click.md), [margin](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#margin), [markAnchor](../apis-arkui/arkui-ts/ts-universal-attributes-location.md#markanchor), [offset](../apis-arkui/arkui-ts/ts-universal-attributes-location.md#offset), [width](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#width), [zIndex](../apis-arkui/arkui-ts/ts-universal-attributes-z-order.md#zindex), [visibility](../apis-arkui/arkui-ts/ts-universal-attributes-visibility.md#visibility), [scale](../apis-arkui/arkui-ts/ts-universal-attributes-transformation.md#scale), [translate](../apis-arkui/arkui-ts/ts-universal-attributes-transformation.md#translate), [responseRegion](../apis-arkui/arkui-ts/ts-universal-attributes-touch-target.md#responseregion), [size](../apis-arkui/arkui-ts/ts-universal-attributes-size.md#size), [stateStyles](../apis-arkui/arkui-ts/ts-universal-attributes-polymorphic-style.md#statestyles), [opacity](../apis-arkui/arkui-ts/ts-universal-attributes-opacity.md#opacity), [shadow](../apis-arkui/arkui-ts/ts-universal-attributes-image-effect.md#shadow), [sharedTransition](../apis-arkui/arkui-ts/ts-transition-animation-shared-elements.md), [transition](../apis-arkui/arkui-ts/ts-transition-animation-component.md)
### domStorageAccess
domStorageAccess(domStorageAccess: boolean)
Sets whether to enable the DOM Storage API. By default, this feature is disabled.
**System capability**: SystemCapability.Web.Webview.Core
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---------------- | ------- | ---- | ----- | ------------------------------------ |
| domStorageAccess | boolean | Yes | false | Whether to enable the DOM Storage API.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.domStorageAccess(true)
}
}
}
```
### 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)](../../quick-start/resource-categories-and-access.md).
**fileAccess** is disabled by default since API version 12. When **fileAccess** is set to **false**, files in the read-only **/data/storage/el1/bundle/entry/resources/resfile** directory can still be accessed through the **file** protocol.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---------- | ------- | ---- | ---- | ---------------------- |
| fileAccess | boolean | Yes | false | Whether to enable access to the file system in the application. Default value: API version 11 and earlier: **true** API version 12 and later: **false**|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.fileAccess(true)
}
}
}
```
### imageAccess
imageAccess(imageAccess: boolean)
Sets whether to enable automatic image loading. By default, this feature is enabled.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ----------- | ------- | ---- | ---- | --------------- |
| imageAccess | boolean | Yes | true | Whether to enable automatic image loading.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.imageAccess(true)
}
}
}
```
### javaScriptProxy
javaScriptProxy(javaScriptProxy: JavaScriptProxy)
Registers a JavaScript object with the window. APIs of this object can then be invoked in the window. The parameters cannot be updated. This API can be used in synchronous or asynchronous mode, or in both modes. If the API can be used in both synchronous and asynchronous modes, it is called asynchronously by default. Only one object can be registered through this API. To register multiple objects, use [registerJavaScriptProxy9+](js-apis-webview.md#registerjavascriptproxy).
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ---------------------------------------- | ---- |---------------------------------------- |
| javaScriptProxy | [JavaScriptProxy](#javascriptproxy12) | Yes | Object to be registered. Methods can be declared, but attributes cannot. |
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
class TestObj {
constructor() {
}
test(data1: string, data2: string, data3: string): string {
console.log("data1:" + data1);
console.log("data2:" + data2);
console.log("data3:" + data3);
return "AceString";
}
asyncTest(data: string): void {
console.log("async data:" + data);
}
toString(): void {
console.log('toString' + "interface instead.");
}
}
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
testObj = new TestObj();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.javaScriptAccess(true)
.javaScriptProxy({
object: this.testObj,
name: "objName",
methodList: ["test", "toString"],
asyncMethodList: ["asyncTest"],
controller: this.controller,
})
}
}
}
```
### javaScriptAccess
javaScriptAccess(javaScriptAccess: boolean)
Sets whether JavaScript scripts can be executed. By default, JavaScript scripts can be executed.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---------------- | ------- | ---- | ---- | ------------------- |
| javaScriptAccess | boolean | Yes | true | Whether JavaScript scripts can be executed.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.javaScriptAccess(true)
}
}
}
```
### overScrollMode11+
overScrollMode(mode: OverScrollMode)
Sets the overscroll mode, which is disabled by default. When the overscroll mode is enabled and the boundary of the scrolling area is reached, the **Web** component plays a bounce effect animation.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---- | --------------------------------------- | ---- | -------------------- | ------------------ |
| mode | [OverScrollMode](#overscrollmode11) | Yes | OverScrollMode.NEVER | Whether to enable the overscroll mode.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State mode: OverScrollMode = OverScrollMode.ALWAYS;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.overScrollMode(this.mode)
}
}
}
```
### mixedMode
mixedMode(mixedMode: MixedMode)
Sets whether to enable loading of HTTP and HTTPS hybrid content can be loaded. By default, this feature is disabled.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| --------- | --------------------------- | ---- | -------------- | --------- |
| mixedMode | [MixedMode](#mixedmode)| Yes | MixedMode.None | Mixed content to load.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State mode: MixedMode = MixedMode.All;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.mixedMode(this.mode)
}
}
}
```
### onlineImageAccess
onlineImageAccess(onlineImageAccess: boolean)
Sets whether to enable access to online images through HTTP and HTTPS. By default, this feature is enabled.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ----------------- | ------- | ---- | ---- | ---------------- |
| onlineImageAccess | boolean | Yes | true | Whether to enable access to online images through HTTP and HTTPS.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onlineImageAccess(true)
}
}
}
```
### zoomAccess
zoomAccess(zoomAccess: boolean)
Sets whether to enable zoom gestures. By default, this feature is enabled.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---------- | ------- | ---- | ---- | ------------- |
| zoomAccess | boolean | Yes | true | Whether to enable zoom gestures.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.zoomAccess(true)
}
}
}
```
### overviewModeAccess
overviewModeAccess(overviewModeAccess: boolean)
Sets whether to load web pages by using the overview mode. By default, this feature is enabled. Currently, only mobile devices are supported.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------------------ | ------- | ---- | ---- | --------------- |
| overviewModeAccess | boolean | Yes | true | Whether to load web pages by using the overview mode.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.overviewModeAccess(true)
}
}
}
```
### databaseAccess
databaseAccess(databaseAccess: boolean)
Sets whether to enable database access. By default, this feature is disabled.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| -------------- | ------- | ---- | ----- | ----------------- |
| databaseAccess | boolean | Yes | false | Whether to enable database access.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.databaseAccess(true)
}
}
}
```
### geolocationAccess
geolocationAccess(geolocationAccess: boolean)
Sets whether to enable geolocation access. By default, this feature is enabled. For details, see [Managing Location Permissions](../../web/web-geolocation-permission.md).
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ----------------- | ------- | ---- | ---- | --------------- |
| geolocationAccess | boolean | Yes | true | Whether to enable geolocation access.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.geolocationAccess(true)
}
}
}
```
### mediaPlayGestureAccess
mediaPlayGestureAccess(access: boolean)
Sets whether video playback must be started by user gestures. This API is not applicable to videos that do not have an audio track or whose audio track is muted.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------ | ------- | ---- | ---- | ------------------- |
| access | boolean | Yes | true | Whether video playback must be started by user gestures.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State access: boolean = true;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.mediaPlayGestureAccess(this.access)
}
}
}
```
### multiWindowAccess9+
multiWindowAccess(multiWindow: boolean)
Sets whether to enable the multi-window permission. By default, this feature is disabled.
Enabling the multi-window permission requires implementation of the **onWindowNew** event. For the sample code, see [onWindowNew](#onwindownew9).
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ----------- | ------- | ---- | ----- | ------------ |
| multiWindow | boolean | Yes | false | Whether to enable the multi-window permission.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.multiWindowAccess(false)
}
}
}
```
### horizontalScrollBarAccess9+
horizontalScrollBarAccess(horizontalScrollBar: boolean)
Sets whether to display the horizontal scrollbar, including the default system scrollbar and custom scrollbar. By default, the horizontal scrollbar is displayed.
> **NOTE**
>
> - If an @State decorated variable is used to control the horizontal scrollbar visibility, **controller.refresh()** must be called for the settings to take effect.
> - If the horizontal scrollbar visibility changes frequently through an @State decorated variable, it is recommended that the variable correspond to the **Web** component one by one.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------------------- | ------- | ---- | ---- | ------------ |
| horizontalScrollBar | boolean | Yes | true | Whether to display the horizontal scrollbar.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State isShow: boolean = false;
build() {
Column() {
// If an @State decorated variable is used to control the horizontal scrollbar visibility, controller.refresh() must be called for the settings to take effect.
Button('refresh')
.onClick(() => {
this.isShow = true;
try {
this.controller.refresh();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: $rawfile('index.html'), controller: this.controller })
.horizontalScrollBarAccess(this.isShow)
}
}
}
```
HTML file to be loaded:
```html
Demo
Scroll Test
```
### verticalScrollBarAccess9+
verticalScrollBarAccess(verticalScrollBar: boolean)
Sets whether to display the vertical scrollbar, including the default system scrollbar and custom scrollbar. By default, the vertical scrollbar is displayed.
> **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.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ----------------- | ------- | ---- | ---- | ------------ |
| verticalScrollBar | boolean | Yes | true | Whether to display the vertical scrollbar.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State isShow: boolean = false;
build() {
Column() {
// If an @State decorated variable is used to control the vertical scrollbar visibility, controller.refresh() must be called for the settings to take effect.
Button('refresh')
.onClick(() => {
this.isShow = true;
try {
this.controller.refresh();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: $rawfile('index.html'), controller: this.controller })
.verticalScrollBarAccess(this.isShow)
}
}
}
```
HTML file to be loaded:
```html
Demo
Scroll Test
```
### password(deprecated)
password(password: boolean)
Sets whether the password should be saved. This API is a void API.
> **NOTE**
>
> This API is deprecated since API version 10, and no new API is provided as a substitute.
### cacheMode
cacheMode(cacheMode: CacheMode)
Sets the cache mode.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| --------- | --------------------------- | ---- | ----------------- | --------- |
| cacheMode | [CacheMode](#cachemode9) | Yes | CacheMode.Default | Cache mode to set.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State mode: CacheMode = CacheMode.None;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.cacheMode(this.mode)
}
}
}
```
### copyOptions11+
copyOptions(value: CopyOptions)
Sets the pasteboard copy options.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| --------- | --------------------------- | ---- | ----------------- | --------- |
| value | [CopyOptions](../apis-arkui/arkui-ts/ts-appendix-enums.md#copyoptions9) | Yes | CopyOptions.LocalDevice | Pasteboard copy options.|
**Example**
```ts
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.copyOptions(CopyOptions.None)
}
}
}
```
### textZoomAtio(deprecated)
textZoomAtio(textZoomAtio: number)
Sets the text zoom ratio of the page. The default value is **100**, which indicates 100%.
This API is deprecated since API version 9. You are advised to use [textZoomRatio9+](#textzoomratio9) instead.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------------ | ------ | ---- | ---- | -------------------------------- |
| textZoomAtio | number | Yes | 100 | Text zoom ratio to set. The value is an integer. The value range is (0, +∞).|
**Example**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
@State atio: number = 150
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.textZoomAtio(this.atio)
}
}
}
```
### textZoomRatio9+
textZoomRatio(textZoomRatio: number)
Sets the text zoom ratio of the page. The default value is **100**, which indicates 100%.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------------- | ------ | ---- | ---- | -------------------------------- |
| textZoomRatio | number | Yes | 100 | Text zoom ratio to set. The value is an integer. The value range is (0, +∞).|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State atio: number = 150;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.textZoomRatio(this.atio)
}
}
}
```
### initialScale9+
initialScale(percent: number)
Sets the scale factor of the entire page. The default value is 100%.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------- | ------ | ---- | ---- | ----------------------------- |
| percent | number | Yes | 100 | Scale factor of the entire page.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State percent: number = 100;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.initialScale(this.percent)
}
}
}
```
### 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 [setCustomUserAgent](js-apis-webview.md#setcustomuseragent10)10+ instead.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| --------- | ------ | ---- | ---- | --------- |
| userAgent | string | Yes | - | User agent to set.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State userAgent:string = 'Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36';
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.userAgent(this.userAgent)
}
}
}
```
### blockNetwork9+
blockNetwork(block: boolean)
Sets whether to block online downloads.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ----- | ------- | ---- | ----- | ------------------- |
| block | boolean | Yes | false | Whether to block online downloads.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State block: boolean = true;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.blockNetwork(this.block)
}
}
}
```
### defaultFixedFontSize9+
defaultFixedFontSize(size: number)
Sets the default fixed font size for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---- | ------ | ---- | ---- | ---------------------------------------- |
| size | number | Yes | 13 | Default fixed font size to set, in px. The value ranges from -2^31 to 2^31-1. In actual rendering, values greater than 72 are handled as 72, and values less than 1 are handled as 1.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State fontSize: number = 16;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.defaultFixedFontSize(this.fontSize)
}
}
}
```
### defaultFontSize9+
defaultFontSize(size: number)
Sets the default font size for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---- | ------ | ---- | ---- | ---------------------------------------- |
| size | number | Yes | 16 | Default font size to set, in px. The value ranges from -2^31 to 2^31-1. In actual rendering, values greater than 72 are handled as 72, and values less than 1 are handled as 1.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State fontSize: number = 13;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.defaultFontSize(this.fontSize)
}
}
}
```
### minFontSize9+
minFontSize(size: number)
Sets the minimum font size for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---- | ------ | ---- | ---- | ---------------------------------------- |
| size | number | Yes | 8 | Minimum font size to set, in px. The value ranges from -2^31 to 2^31-1. In actual rendering, values greater than 72 are handled as 72, and values less than 1 are handled as 1.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State fontSize: number = 13;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.minFontSize(this.fontSize)
}
}
}
```
### minLogicalFontSize9+
minLogicalFontSize(size: number)
Sets the minimum logical font size for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---- | ------ | ---- | ---- | ---------------------------------------- |
| size | number | Yes | 8 | Minimum logical font size to set, in px. The value ranges from -2^31 to 2^31-1. In actual rendering, values greater than 72 are handled as 72, and values less than 1 are handled as 1.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State fontSize: number = 13;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.minLogicalFontSize(this.fontSize)
}
}
}
```
### webFixedFont9+
webFixedFont(family: string)
Sets the fixed font family for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------ | ------ | ---- | --------- | ------------------- |
| family | string | Yes | monospace | Fixed font family to set.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State family: string = "monospace";
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.webFixedFont(this.family)
}
}
}
```
### webSansSerifFont9+
webSansSerifFont(family: string)
Sets the sans serif font family for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------ | ------ | ---- | ---------- | ------------------------ |
| family | string | Yes | sans-serif | Sans serif font family to set.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State family: string = "sans-serif";
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.webSansSerifFont(this.family)
}
}
}
```
### webSerifFont9+
webSerifFont(family: string)
Sets the serif font family for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------ | ------ | ---- | ----- | ------------------- |
| family | string | Yes | serif | Serif font family to set.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State family: string = "serif";
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.webSerifFont(this.family)
}
}
}
```
### webStandardFont9+
webStandardFont(family: string)
Sets the standard font family for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------ | ------ | ---- | ---------- | ---------------------- |
| family | string | Yes | sans serif | Standard font family to set.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State family: string = "sans-serif";
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.webStandardFont(this.family)
}
}
}
```
### webFantasyFont9+
webFantasyFont(family: string)
Sets the fantasy font family for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------ | ------ | ---- | ------- | --------------------- |
| family | string | Yes | fantasy | Fantasy font family to set.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State family: string = "fantasy";
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.webFantasyFont(this.family)
}
}
}
```
### webCursiveFont9+
webCursiveFont(family: string)
Sets the cursive font family for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------ | ------ | ---- | ------- | --------------------- |
| family | string | Yes | cursive | Cursive font family to set.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State family: string = "cursive";
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.webCursiveFont(this.family)
}
}
}
```
### darkMode9+
darkMode(mode: WebDarkMode)
Sets the web dark mode. By default, web dark mode is disabled. When it is enabled, the **Web** component enables the dark theme defined for web pages if the theme has been defined in **prefers-color-scheme** of a media query, and remains unchanged otherwise. To enable the forcible dark mode, use this API with [forceDarkAccess](#forcedarkaccess9).
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---- | -------------------------------- | ---- | --------------- | ---------------------- |
| mode | [WebDarkMode](#webdarkmode9) | Yes | WebDarkMode.Off | Web dark mode to set.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State mode: WebDarkMode = WebDarkMode.On;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.darkMode(this.mode)
}
}
}
```
### forceDarkAccess9+
forceDarkAccess(access: boolean)
Sets whether to enable forcible dark mode for the web page. By default, this feature is turned off. This API is applicable only when dark mode is enabled in [darkMode](#darkmode9).
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------ | ------- | ---- | ----- | --------------- |
| access | boolean | Yes | false | Whether to enable forcible dark mode for the web page.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State mode: WebDarkMode = WebDarkMode.On;
@State access: boolean = true;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.darkMode(this.mode)
.forceDarkAccess(this.access)
}
}
}
```
### tableData(deprecated)
tableData(tableData: boolean)
Sets whether form data should be saved. This API is a void API.
> **NOTE**
>
> This API is deprecated since API version 10, and no new API is provided as a substitute.
### wideViewModeAccess(deprecated)
wideViewModeAccess(wideViewModeAccess: boolean)
Sets whether to support the viewport attribute of the HTML **\** tag. This API is a void API.
> **NOTE**
>
> This API is deprecated since API version 10, and no new API is provided as a substitute.
### pinchSmooth9+
pinchSmooth(isEnabled: boolean)
Sets whether to enable smooth pinch mode for the web page.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| --------- | ------- | ---- | ----- | ------------- |
| isEnabled | boolean | Yes | false | Whether to enable smooth pinch mode for the web page.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.pinchSmooth(true)
}
}
}
```
### allowWindowOpenMethod10+
allowWindowOpenMethod(flag: boolean)
Sets whether to allow a new window to automatically open through JavaScript.
When **flag** is set to **true**, a new window can automatically open through JavaScript. When **flag** is set to **false**, a new window can still automatically open through JavaScript for user behavior, but cannot for non-user behavior. The user behavior here refers to that a user requests to open a new window (**window.open**) within 5 seconds of operating the **Web** component.
This API takes effect only when [javaScriptAccess](#javascriptaccess) is enabled.
This API opens a new window when [multiWindowAccess](#multiwindowaccess9) is enabled and opens a local window when [multiWindowAccess](#multiwindowaccess9) 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**.
To check the settings of **persist.web.allowWindowOpenMethod.enabled**,
run the **hdc shell param get persist.web.allowWindowOpenMethod.enabled** command. If the attribute is set to 0 or does not exist,
you can run the **hdc shell param set persist.web.allowWindowOpenMethod.enabled 1** command to enable it.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---- | ------- | ---- | ---------------------------------------- | ------------------------- |
| flag | boolean | Yes | Subject to the settings of the **persist.web.allowWindowOpenMethod.enabled** system attribute. If this attribute is set, the default value of **flag** is **true**. Otherwise, the default value of **flag** is **false**.| Whether to allow a new window to automatically open through JavaScript.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
// There are two Web components on the same page. When the Web Component object opens a new window, the NewWebViewComp object is displayed.
@CustomDialog
struct NewWebViewComp {
controller?: CustomDialogController;
webviewController1: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: "", controller: this.webviewController1 })
.javaScriptAccess(true)
.multiWindowAccess(false)
.onWindowExit(() => {
console.info("NewWebViewComp onWindowExit");
if (this.controller) {
this.controller.close();
}
})
}
}
}
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
dialogController: CustomDialogController | null = null;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.javaScriptAccess(true)
// MultiWindowAccess needs to be enabled.
.multiWindowAccess(true)
.allowWindowOpenMethod(true)
.onWindowNew((event) => {
if (this.dialogController) {
this.dialogController.close();
}
let popController: webview.WebviewController = new webview.WebviewController();
this.dialogController = new CustomDialogController({
builder: NewWebViewComp({ webviewController1: popController })
})
this.dialogController.open();
// Return the WebviewController object corresponding to the new window to the kernel.
// If opening a new window is not needed, set the parameter to null when calling the event.handler.setWebController API.
// If the event.handler.setWebController API is not called, the render process will be blocked.
event.handler.setWebController(popController);
})
}
}
}
```
### 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.
> **NOTE**
>
> - Audios in the same **Web** instance are considered as the same audio.
> - The media playback policy controls videos with an audio track.
> - After the parameter settings are updated, the playback must be started again for the settings to take effect.
> - It is recommended that you set the same **audioExclusive** value for all **Web** components.
> - Audio and video interruption takes effect within an app and between apps, and playback resumption takes effect only between apps.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------- | ------------------------------------- | ---- | ---------------------------------------- | ---------------------------------------- |
| options | [WebMediaOptions](#webmediaoptions10) | Yes | {resumeInterval: 0, audioExclusive: true} | Web-based media playback policy. The default value of **resumeInterval** is **0**, indicating that the playback is not automatically resumed.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State options: WebMediaOptions = {resumeInterval: 10, audioExclusive: true};
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.mediaOptions(this.options)
}
}
}
```
### javaScriptOnDocumentStart11+
javaScriptOnDocumentStart(scripts: Array\)
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**.
> **NOTE**
>
> - The script runs before any JavaScript code of the page, when the DOM tree may not have been loaded or rendered.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------- | ----------------------------------- | ---- | ---- | ------------------ |
| scripts | Array\<[ScriptItem](#scriptitem11)> | Yes | - | Script item array to be injected.|
**Example in the .ets file**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct Index {
controller: webview.WebviewController = new webview.WebviewController();
private localStorage: string =
"if (typeof(Storage) !== 'undefined') {" +
" localStorage.setItem('color', 'Red');" +
"}";
@State scripts: Array = [
{ script: this.localStorage, scriptRules: ["*"] }
];
build() {
Column({ space: 20 }) {
Web({ src: $rawfile('index.html'), controller: this.controller })
.javaScriptAccess(true)
.domStorageAccess(true)
.backgroundColor(Color.Grey)
.javaScriptOnDocumentStart(this.scripts)
.width('100%')
.height('100%')
}
}
}
```
**Example in the HTML file**
```html
Hello world!
```
### javaScriptOnDocumentEnd11+
javaScriptOnDocumentEnd(scripts: Array\)
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**.
> **NOTE**
>
> - The script runs before any JavaScript code of the page, when the DOM tree has been loaded and rendered.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------- | ----------------------------------- | ---- | ---- | ------------------ |
| scripts | Array\<[ScriptItem](#scriptitem11)> | Yes | - | Script item array to be injected.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct Index {
controller: webview.WebviewController = new webview.WebviewController();
private jsStr: string =
"window.document.getElementById(\"result\").innerHTML = 'this is msg from javaScriptOnDocumentEnd'";
@State scripts: Array = [
{ script: this.jsStr, scriptRules: ["*"] }
];
build() {
Column({ space: 20 }) {
Web({ src: $rawfile('index.html'), controller: this.controller })
.javaScriptAccess(true)
.domStorageAccess(true)
.backgroundColor(Color.Grey)
.javaScriptOnDocumentEnd(this.scripts)
.width('100%')
.height('100%')
}
}
}
```
```html
Hello world!
test msg
```
### layoutMode11+
layoutMode(mode: WebLayoutMode)
Sets the web layout mode.
> **NOTE**
>
> Currently, only two web layout modes are supported: **WebLayoutMode.NONE** and **WebLayoutMode.FIT_CONTENT**.
>
> The following restrictions apply with the usage of **WebLayoutMode.FIT_CONTENT**:
> - If the web content is wider or longer than 8000 px, specify the **RenderMode.SYNC_RENDER** mode when creating the **Web** component; otherwise, the screen may be blank.
> - After the **Web** component is created, dynamic switching of the **layoutMode** is not supported.
> - The width and height of the **Web** component cannot exceed 500,000 px each.
> - Frequent changes to the page width and height will trigger a re-layout of the **Web** component, which can affect the user experience.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---- | ------------------------------------- | ---- | ------------------ | --------------------- |
| mode | [WebLayoutMode](#weblayoutmode11) | Yes | WebLayoutMode.NONE | Web layout mode.|
**Example**
1. After specifying the **layoutMode** as **WebLayoutMode.FIT_CONTENT**, you must explicitly specify **renderMode** as **RenderMode.SYNC_RENDER**.
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State mode: WebLayoutMode = WebLayoutMode.FIT_CONTENT;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER })
.layoutMode(this.mode)
}
}
}
```
2. After specifying the **layoutMode** as **WebLayoutMode.FIT_CONTENT**, you are advised to specify **overScrollMode** as **OverScrollMode.NEVER**.
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State layoutMode: WebLayoutMode = WebLayoutMode.FIT_CONTENT;
@State overScrollMode: OverScrollMode = OverScrollMode.NEVER;
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller, renderMode: RenderMode.SYNC_RENDER })
.layoutMode(this.layoutMode)
.overScrollMode(this.overScrollMode)
}
}
}
```
### nestedScroll11+
nestedScroll(value: NestedScrollOptions)
Sets nested scrolling options.
> **NOTE**
>
> - You can set the nested scrolling mode in both forward and backward directions to implement scrolling linkage with the parent component.
> - You can set separate nested scrolling modes for the forward and backward directions.
> - The default mode for **scrollForward** and **scrollBackward** is **NestedScrollMode.SELF_FIRST**.
> - Containers that support nested scrolling: **\**, **\**, **\**, **\**, **\**, **\**.
> - 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 the user experience.
**Parameters**
| Name | Type | Mandatory | Description |
| ----- | ---------------------------------------- | ---- | ---------------- |
| value | [NestedScrollOptions](#nestedscrolloptions11) | Yes | Nested scrolling options.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.nestedScroll({
scrollForward: NestedScrollMode.SELF_FIRST,
scrollBackward: NestedScrollMode.SELF_FIRST,
})
}
}
}
```
### enableNativeEmbedMode11+
enableNativeEmbedMode(mode: boolean)
Specifies whether to enable the same-layer rendering feature. By default, this feature is disabled.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ----- | ---------------------------------------- | ---- | ------------------| ---------------- |
| mode | boolean | Yes | false | Whether to enable the same-layer rendering feature.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.enableNativeEmbedMode(true)
}
}
}
```
### forceDisplayScrollBar14+
forceDisplayScrollBar(enabled: boolean)
Sets whether the scroll bar is always visible. By default, it is not always visible. Under the always-visible settings, when the page size exceeds one page, the scroll bar appears and remains visible.
**Parameters**
| Name | Type| Mandatory| Default Value| Description |
| ------- | -------- | ---- | ------ | ------------------ |
| enabled | boolean | Yes | false | Whether the scroll bar is always visible.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController()
build() {
Column() {
Web({ src: $rawfile('index.html'), controller: this.controller })
.forceDisplayScrollBar(true)
}
}
}
```
HTML file to be loaded:
```html
Demo
Scroll Test
```
### 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 can be any non-empty string, case-insensitive. If the standard type is the same as the standard type of **object** or **embed**, the ArkWeb engine will recognize it as a non-same-layer tag. This API is also controlled by the **enableNativeEmbedMode** API and does not take effect if same-layer rendering is not enabled. When this API is not used, the ArkWeb engine recognizes the **embed** tags with the "native/" prefix as same-layer tags.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
|------|--------| ---- |------|------------------|
| tag | string | Yes | "" | Tag name. |
| type | string | Yes | "" | Tag type. It is used by the ArkWeb engine for prefix matching.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.enableNativeEmbedMode(true)
.registerNativeEmbedRule("object", "application/view")
}
}
}
```
### defaultTextEncodingFormat12+
defaultTextEncodingFormat(textEncodingFormat: string)
Sets the default character encoding for web pages.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---- | ------ | ---- | ---- | ---------------------------------------- |
| textEncodingFormat | string | Yes | "UTF-8" | Default character encoding.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: $rawfile('index.html'), controller: this.controller })
// Set the height.
.height(500)
.defaultTextEncodingFormat("UTF-8")
.javaScriptAccess(true)
}
}
}
```
```html
My test html5 page
Hello world!
```
### metaViewport12+
metaViewport(enable: boolean)
Sets whether the **viewport** property of the **meta** tag is enabled.
> **NOTE**
>
> - If this parameter is set to **false**, the **viewport** property of the **meta** tag is not enabled. This means that the property will not be parsed and a default layout will be used.
> - If this parameter is set to **true**, the **viewport** property of the **meta** tag is enabled. This means that the property will be parsed and used for the layout.
> - If set to an invalid value, this parameter does not take effect.
> - If the device is 2-in-1, the **viewport** property is not supported. This means that, regardless of whether this parameter is set to **true** or **false**, the **viewport** property will not be parsed and a default layout will be used.
**Parameters**
| Name| Type| Mandatory| Default Value| Description |
| ------ | -------- | ---- | ------ | -------------------------------- |
| enable | boolean | Yes | true | Whether the **viewport** property of the **meta** tag is enabled.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: $rawfile('index.html'), controller: this.controller })
.metaViewport(true)
}
}
}
```
```html
Hello world!
```
### textAutosizing12+
textAutosizing(textAutosizing: boolean)
Sets whether automatic text resizing is enabled.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ---- | ------ | ---- | ---- | ---------------------------------------- |
| textAutosizing | boolean | Yes | true | Whether automatic text resizing is enabled.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.textAutosizing(false)
}
}
}
```
### enableNativeMediaPlayer12+
enableNativeMediaPlayer(config: NativeMediaPlayerConfig)
Enable the [application takeover of web media playback feature](../../web/app-takeovers-web-media.md).
**System capability**: SystemCapability.Web.Webview.Core
**Parameters**
| Name | Type | Mandatory | Default Value | Description|
| ---- | ------ | ---- | ---- | ---------------------|
| config | [NativeMediaPlayerConfig](#nativemediaplayerconfig12) | Yes | {enable: false, shouldOverlay: false} | **enable**: whether to enable the feature. **shouldOverlay**: whether the image of the video player taken over by the application will overlay the web page content, if this feature is enabled.|
**Example**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.enableNativeMediaPlayer({enable: true, shouldOverlay: false})
}
}
}
```
### selectionMenuOptions12+
selectionMenuOptions(expandedMenuOptions: Array\)
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.
**Parameters**
| Name | Type | Description |
| ------------------- | ---------------------------------------------------------- | ------------- |
| expandedMenuOptions | Array<[ExpandedMenuItemOptions](#expandedmenuitemoptions12)> | 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 [\