Components

This module provides Web components with web page display capabilities. For details about web control capabilities, see Module Description.

NOTE

• The initial APIs of this component are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.

• The sample effect is subject to the actual device.

This module provides the following common functionalities related to web page display:

• ClientAuthenticationHandler: Client certificate request event.
• ConsoleMessage: Console information.
• ControllerHandler: WebviewController object of the new Web component.
• DataResubmissionHandler: Form data operation object.
• EventResult: Same-layer event consumption result.
• FileSelectorParam: File selector object of the Web component.
• FileSelectorResult: File selection result of the Web component.
• FullScreenExitHandler: Object for exiting full screen of the Web component.
• HttpAuthHandler: Object for performing operations related to HttpAuth authentication requests.
• JsGeolocation: Geolocation permission related functionalities.
• JsResult: Dialog box operations.
• PermissionRequest: Permission request.
• ScreenCaptureHandler: Screen capture permission operations.
• SslErrorHandler: SSL error event operations.
• WebContextMenuParam: Menu information displayed when the screen is long-pressed or the right mouse button is clicked.
• WebContextMenuResult: Object that controls the menu displayed when the screen is long-pressed or the right mouse button is clicked.
• WebCookie: Cookie management operations of the Web component in the current application.
• WebKeyboardController: Object that controls the custom keyboard.
• WebResourceError: Resource management error.
• WebResourceRequest: Resource obtaining request.
• WebResourceResponse: Resource obtaining response.

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.

Child Components

Not supported

APIs

Web(value: WebOptions)

NOTE

Transition animation is not supported.

Web components on the same page must be bound to different WebviewController instances.

System capability: SystemCapability.Web.Webview.Core

Parameters

Name	Type	Mandatory	Description
value	WebOptions	Yes	Define web options.

Example

Example of loading online web pages:

// 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:

// 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 in synchronous mode:

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

// xxx.ets
import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebComponent {
  controller1: webview.WebviewController = new webview.WebviewController();
  controller2: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller1, sharedRenderProcessToken: "111" })
      Web({ src: 'www.w3.org', controller: this.controller2, sharedRenderProcessToken: "111" })
    }
  }
}

Specify whether the Web component handles mouse events as touch events.

// xxx.ets
import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebComponent {
  controller1: webview.WebviewController = new webview.WebviewController();
  controller2: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller1, emulateTouchFromMouseEvent: false })
      Web({ src: 'www.w3.org', controller: this.controller2, emulateTouchFromMouseEvent: true })
    }
  }
}

Example of loading local web pages using $rawfile():

// 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 })
    }
  }
}

Load the resource file through the resources protocol.

When $rawfile is used to load a URL contains a number sign (#), the content following the number sign is treated as a fragment. To avoid this issue, you can use the resource://rawfile/ protocol prefix instead.

// 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#home", controller: this.controller })
    }
  }
}

Create an index.html file in src/main/resources/rawfile.

<!-- index.html -->
<!DOCTYPE html>
<html>
<body>
<div id="content"></div>

<script>
	function loadContent() {
	  var hash = window.location.hash;
	  var contentDiv = document.getElementById('content');

	  if (hash === '#home') {
		contentDiv.innerHTML = '<h1>Home Page</h1><p>Welcome to the Home Page!</p>';
	  } else {
		contentDiv.innerHTML = '<h1>Default Page</h1><p>This is the default content.</p>';
	  }
	}

	// Load the UI.
	window.addEventListener('load', loadContent);

	// Update the UI when the hash changes.
	window.addEventListener('hashchange', loadContent);
</script>
</body>
</html>

To load the local resource file in the sandbox path, you need to configure the fileAccess permission of the file system in the application.

1. Obtain the sandbox path through the constructed singleton object GlobalContext.

   // GlobalContext.ets
   export class GlobalContext {
     private constructor() {}
     private static instance: GlobalContext;
     private _objects = new Map<string, Object>();
   
     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);
     }
   }
   

   // 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 })
         .fileAccess(true)
       }
     }
   }
   

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.

   // 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.info("Sandbox path is " + GlobalContext.getContext().getObject("filesDir"));
     }
   }
   

   HTML file to be loaded:

   <!-- index.html -->
   <!DOCTYPE html>
   <html>
       <body>
           <p>Hello World</p>
       </body>
   </html>