HarmonyOS NEXT project practice：Window Immersive Effect

reference material:
https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-immersive

Overview of Immersive Effects
Immersive mode usually refers to making the interface of an application more focused on content, without allowing users to be distracted by irrelevant elements. In mobile applications, full screen window elements include a status bar, application interface, and navigation bar (as shown below). Immersive page development often achieves the following goals by extending the application page to the status bar and navigation bar:

• Unify the color tone of the page and avoidance areas to provide users with a better visual experience.
• Maximize the use of the screen's visible area to provide a larger layout space for the page.
• Provide a fully immersive experience, allowing users to immerse themselves without being distracted by other things.

Two solutions to achieve immersive effects
Option 1: Set the window to full screen mode
Option 2: Expand Component Security Zone
Recommend using option one, which has the advantage of achieving immersive effects for the entire application (all pages).

interface

setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void>

• Set whether the layout of the main window or sub window is immersive layout, using Promise asynchronous callback. Starting from API version 14, this interface does not take effect when used in the free multi window mode of 2-in1 devices or tablet devices (which can be turned on by clicking the free multi window button in the device control center).
• When the immersive layout takes effect, the layout does not avoid the status bar and bottom navigation area, and components may overlap with them.
• When the non immersive layout takes effect, the layout avoids the status bar and bottom navigation area, and components do not overlap with them.

Prerequisite:
Windows provide some basic capabilities for managing windows, including creating and destroying the current window, setting various properties, and managing and scheduling between windows.
This module provides the following commonly used functions related to windows:
Window: The current window instance, the basic unit managed by the window manager.
WindowStage: Window Manager. Manage various basic window units.

Here is the practical code to achieve immersive effects:

import { window } from '@kit.ArkUI';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct SetFullWindowPage {
  @StorageProp('topRectHeight')
  topRectHeight: number = 0;
  @StorageProp('bottomRectHeight')
  bottomRectHeight: number = 0;

  build() {
    Column({ space: 10 }) {
      Text('SetFullWindow Page')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
      Text(`topRectHeight = ${this.topRectHeight}`)
      Text(`bottomRectHeight = ${this.bottomRectHeight}`)

      Button('SetFullWindow')
        .onClick(() => {
          this.setFullWindow(true)
        })
      Button('CancelFullWindow')
        .onClick(() => {
          this.setFullWindow(false)
        })
    }
    .height('100%')
    .width('100%')
    .backgroundColor('#cccccc')
    .padding({ top: this.topRectHeight, bottom: this.bottomRectHeight })
  }

  async setFullWindow(isLayoutFullScreen: boolean = true) {
    let context = getContext(this) as common.UIAbilityContext;
    let windowClass = await window.getLastWindow(context);
    // 1. 设置窗口全屏
    windowClass.setWindowLayoutFullScreen(isLayoutFullScreen).then(() => {
      console.info('Succeeded in setting the window layout to full-screen mode.');
    }).catch((err: BusinessError) => {
      console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err));
    });
    // 2. 获取布局避让遮挡的区域
    let type = window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR; // 以导航条避让为例
    let avoidArea = windowClass.getWindowAvoidArea(type);
    let bottomRectHeight = avoidArea.bottomRect.height; // 获取到导航条区域的高度
    AppStorage.setOrCreate('bottomRectHeight', px2vp(bottomRectHeight));
    type = window.AvoidAreaType.TYPE_SYSTEM; // 以状态栏避让为例
    avoidArea = windowClass.getWindowAvoidArea(type);
    let topRectHeight = avoidArea.topRect.height; // 获取状态栏区域高度
    AppStorage.setOrCreate('topRectHeight', px2vp(topRectHeight));

    // 3. 注册监听函数，动态获取避让区域数据
    windowClass.on('avoidAreaChange', (data) => {
      if (data.type === window.AvoidAreaType.TYPE_SYSTEM) {
        let topRectHeight = data.area.topRect.height;
        AppStorage.setOrCreate('topRectHeight', px2vp(topRectHeight));
      } else if (data.type == window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR) {
        let bottomRectHeight = data.area.bottomRect.height;
        AppStorage.setOrCreate('bottomRectHeight', px2vp(bottomRectHeight));
      }
    });
  }
}