UIAbility Component Overview

The UIAbility component is an application component that includes a 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 recommendations for UIAbility division:

The UIAbility component is the basic unit of system scheduling, providing a window for the application to draw its interface. An application can contain one or more UIAbility components. For example, in a payment application, the entry function and the payment/receiving 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 UIAbilities based on specific scenarios, with the following recommendations:

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 UIAbilities to develop different module functionalities.

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 the user opens, switches, and returns 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 state switching between foreground and background.

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: // Focus state
            hilog.info(DOMAIN_NUMBER, TAG, "windowStage active.");
            break;
          case window.WindowStageEventType.INACTIVE: // Loss of focus 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, this is 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, corresponding to the onForeground() and onBackground() callbacks.

The onForeground() callback is triggered before the UI of the UIAbility is visible, such as when the UIAbility switches to the foreground. Resources required by the system 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. In the onBackground() callback, useless resources when the UI is invisible can be released, or time-consuming operations can be executed, such as state saving.

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 resources needed by the system, or re-request resources released in onBackground()
  }

  onBackground(): void {
    // Release useless resources when the 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 be terminated directly. 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 the UIAbility and obtaining the context of the UIAbility UIAbilityContext.

Specifying the Launch Page of UIAbility#

During the startup process of the UIAbility in the application, it is necessary to specify the launch page; otherwise, the application will experience 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 the 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 was synchronized and updated to xLog by Mix Space. The original link is http://www.sroxck.top/posts/harmony/uiability