Web component rendering mode

Web Component Rendering Modes in HarmonyOS Next

Overview

HarmonyOS Next Web components support two rendering modes to accommodate different application scenarios and performance requirements.

Rendering Modes

Asynchronous Rendering Mode (Default)

• renderMode: RenderMode.ASYNC_RENDER
• Description: In this mode, the Web component acts as a graphical surface node and is rendered independently. This mode is recommended for application pages composed solely of Web components, offering better performance and lower power consumption.
• Specifications:
  • The maximum width and height of the Web component should not exceed 7,680 pixels (physical pixels). Exceeding this limit may result in a blank screen.
  • Dynamic switching of rendering modes is not supported.

Synchronous Rendering Mode

• renderMode: RenderMode.SYNC_RENDER
• Description: Here, the Web component acts as a graphical canvas node, and its rendering is synchronized with the system components. This mode allows for rendering longer Web content but consumes more performance resources.
• Specifications:
  • The maximum width and height of the Web component should not exceed 500,000 pixels (physical pixels). Exceeding this limit may result in a blank screen.
  • Does not support DSS composition.
  • Dynamic switching of rendering modes is not supported.

Usage Example

The following example demonstrates how to set the rendering mode for a Web component:

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

@Entry
@Component
struct WebHeightPage {
  private webviewController: WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Web({
        src: 'https://www.example.com/',
        controller: this.webviewController,
        renderMode: RenderMode.ASYNC_RENDER // Set the rendering mode
      })
    }
  }
}

Recommendations

• Asynchronous Rendering Mode: Ideal for applications where the Web component is the primary or sole component on the page. Its independent rendering pipeline reduces the load on the main thread, resulting in smoother performance and reduced power usage.
• Synchronous Rendering Mode: Suitable for complex pages where the Web component needs to be rendered alongside other system components. Despite higher resource consumption, this mode ensures consistent rendering for longer content.

Important Notes

• Always ensure that the dimensions of your Web component comply with the specifications of the chosen rendering mode to avoid display issues.
• The rendering mode should be determined during the initial setup of the Web component and not changed dynamically.