UIAbility Component Overview

The UIAbility component is an application component that contains UI, primarily used for user interaction.

The design philosophy of UIAbility:

Native support for cross-end migration and multi-end collaboration at the application component level.
Support for multiple devices and multi-window forms.

Principles and suggestions for UIAbility division:

The UIAbility component is the basic unit of system scheduling, providing a window for the application to render its interface. An application can contain one or more UIAbility components. For example, in a payment application, the entry function and the payment and receipt functions can be configured as independent UIAbility components.

Each UIAbility component instance will display a corresponding task in the recent tasks list.

For developers, they can choose a single or multiple UIAbility based on specific scenarios, with the following suggestions:

If developers want to see a single task in the task view, it is recommended to use one UIAbility with multiple pages.
If developers want to see multiple tasks in the task view or need to open multiple windows simultaneously, it is recommended to use multiple UIAbility components to develop different module functions.

Declaration Configuration#

To enable the application to use UIAbility normally, it is necessary to declare the name, entry, label, and other related information of UIAbility in the abilities tag of the module.json5 configuration file.

{
  "module": {
    // ...
    "abilities": [
      {
        "name": "EntryAbility", // Name of the UIAbility component
        "srcEntry": "./ets/entryability/EntryAbility.ets", // Code path of the UIAbility component
        "description": "$string:EntryAbility_desc", // Description of the UIAbility component
        "icon": "$media:icon", // Icon of the UIAbility component
        "label": "$string:EntryAbility_label", // Label of the UIAbility component
        "startWindowIcon": "$media:icon", // Index of the UIAbility component's launch page icon resource file
        "startWindowBackground": "$color:start_window_background", // Index of the UIAbility component's launch page background color resource file
        // ...
      }
    ]
  }
}

UIAbility Component Lifecycle#

When users open, switch, and return to the corresponding application, the UIAbility instances in the application will transition between different states in their lifecycle. The UIAbility class provides a series of callbacks that indicate when a certain state of the current UIAbility instance changes, going through the creation and destruction of the UIAbility instance, or when the UIAbility instance undergoes a foreground/background state switch.

The lifecycle of UIAbility includes four states: Create, Foreground, Background, and Destroy.

Create State#

The Create state is triggered when the UIAbility instance is created during the application loading process, and the system will call the onCreate() callback. Initialization operations for the page can be performed in this callback, such as variable definition and resource loading, for subsequent UI display.

import { AbilityConstant, UIAbility, Want } from "@kit.AbilityKit";

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Page initialization
  }
  // ...
}

WindowStageCreate and WindowStageDestroy States#

After the UIAbility instance is created, before entering the Foreground, the system will create a WindowStage. After the WindowStage is created, it will enter the onWindowStageCreate() callback, where UI loading and event subscriptions for the WindowStage can be set.

import { UIAbility } from "@kit.AbilityKit";
import { window } from "@kit.ArkUI";
import { hilog } from "@kit.PerformanceAnalysisKit";

const TAG: string = "[EntryAbility]";
const DOMAIN_NUMBER: number = 0xff00;

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    // Set event subscriptions for WindowStage (focus/loss of focus, visible/invisible)
    try {
      windowStage.on("windowStageEvent", (data) => {
        let stageEventType: window.WindowStageEventType = data;
        switch (stageEventType) {
          case window.WindowStageEventType.SHOWN: // Switch to foreground
            hilog.info(DOMAIN_NUMBER, TAG, "windowStage foreground.");
            break;
          case window.WindowStageEventType.ACTIVE: // Active state
            hilog.info(DOMAIN_NUMBER, TAG, "windowStage active.");
            break;
          case window.WindowStageEventType.INACTIVE: // Inactive state
            hilog.info(DOMAIN_NUMBER, TAG, "windowStage inactive.");
            break;
          case window.WindowStageEventType.HIDDEN: // Switch to background
            hilog.info(DOMAIN_NUMBER, TAG, "windowStage background.");
            break;
          default:
            break;
        }
      });
    } catch (exception) {
      hilog.error(
        DOMAIN_NUMBER,
        TAG,
        "Failed to enable the listener for window stage event changes. Cause:" +
          JSON.stringify(exception)
      );
    }
    hilog.info(DOMAIN_NUMBER, TAG, "%{public}s", "Ability onWindowStageCreate");
    // Set UI loading
    windowStage.loadContent("pages/Index", (err, data) => {
      // ...
    });
  }
}

WindowStageWillDestroy State#

Corresponding to the onWindowStageWillDestroy() callback, executed before the WindowStage is destroyed, at which point the WindowStage can be used.

Foreground and Background States#

The Foreground and Background states are triggered when the UIAbility instance switches to the foreground and background, respectively, corresponding to the onForeground() callback and onBackground() callback.

The onForeground() callback is triggered before the UI of the UIAbility is visible, such as when the UIAbility switches to the foreground. System resources needed can be requested in the onForeground() callback, or resources released in onBackground() can be re-requested.

The onBackground() callback is triggered after the UI of the UIAbility is completely invisible, such as when the UIAbility switches to the background. Unused resources when the UI is invisible can be released in the onBackground() callback, or time-consuming operations, such as state saving, can be executed in this callback.

For example, if the application needs to use user location during use, assuming the application has obtained user location permission authorization. Before the UI is displayed, the location function can be activated in the onForeground() callback to obtain the current location information.

When the application switches to the background state, the location function can be stopped in the onBackground() callback to save system resource consumption.

import { UIAbility } from "@kit.AbilityKit";

export default class EntryAbility extends UIAbility {
  // ...

  onForeground(): void {
    // Request system resources needed, or re-request resources released in onBackground()
  }

  onBackground(): void {
    // Release unused resources when UI is invisible, or perform time-consuming operations in this callback
    // For example, state saving, etc.
  }
}

Destroy State#

The Destroy state is triggered when the UIAbility instance is destroyed. System resource release, data saving, and other operations can be performed in the onDestroy() callback.

For example, calling the terminateSelf() method stops the current UIAbility instance, executes the onDestroy() callback, and completes the destruction of the UIAbility instance.

::: tip Note
If the user swipes up on the recent tasks list to close the UIAbility instance, the process will directly terminate the process. This process will not execute the onDestroy() callback.

:::

import { UIAbility } from "@kit.AbilityKit";

export default class EntryAbility extends UIAbility {
  // ...

  onDestroy() {
    // Release system resources, save data, etc.
  }
}

UIAbility Component Launch Modes#

The launch mode of UIAbility refers to the different presentation states of the UIAbility instance at startup. For different business scenarios, the system provides three launch modes:

singleton (single instance mode)

multiton (multiple instance mode)

specified (specified instance mode)

UIAbility Component Launch Modes

Basic Usage of UIAbility Component#

The basic usage of the UIAbility component includes: specifying the launch page of UIAbility and obtaining the context UIAbilityContext of UIAbility.

Specifying the Launch Page of UIAbility#

During the startup process of UIAbility in the application, it is necessary to specify the launch page; otherwise, the application will display a white screen due to the absence of a default loading page after startup. The launch page can be set in the onWindowStageCreate() lifecycle callback of UIAbility through the loadContent() method of the WindowStage object.

import { UIAbility } from "@kit.AbilityKit";
import { window } from "@kit.ArkUI";

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    // Main window is created, set main page for this ability
    windowStage.loadContent("pages/Index", (err, data) => {
      // ...
    });
  }
  // ...
}

This article is synchronized and updated to xLog by Mix Space Original link: http://www.sroxck.top/posts/harmony/uiability