HarmonyOS application page UIAbility

An introduction to UIAbility:

1.1 UIAbility is an application component containing a user interface, mainly used to interact with users

1.2 UIAbility is also a unit of system scheduling, providing a window for the application to draw the interface.

2. UIAbility jump and parameter passing

2.1 Navigation between pages can be achieved through the page routing router module. The page routing module finds the target page according to the page URL to achieve the jump. Through the page routing module, you can use different URLs to access different pages, including jumping to a specified page in UIAbility, replacing the current page with a page in UIAbility, returning to the previous page or a specified page, etc.

2.2 Before using page routing, you need to import the router module first, as shown in the following code.

import router from '@ohos.router';

2.3 Jump page method 1: router.pushUrl adds a page, params is the passed parameters

router.pushUrl({
  url: 'pages/Second',
  params: {
    src: 'Index页面传来的数据',
  }
}, router.RouterMode.Single)

2.4 Jump page method 2: router.replaceUrl replaces the page, params is the passed parameters

router.replaceUrl({
  url: 'pages/Second',
  params: {
    src: 'Index页面传来的数据',
  }
}, router.RouterMode.Single)

2.5 Receive parameters and obtain the custom parameters passed from the Index page by calling the router.getParams() method.

import router from '@ohos.router';

@Entry
@Component
struct Second {
  @State src: string = router.getParams()?.['src'];
  // 页面刷新展示
  ...
}

2.6 The effect is shown in the figure below. In the Index page, after clicking "Next", you can jump from the Index page to the Second page, and receive parameters and refresh the page in the Second page.

3 UIAbility returns to the previous page and passes parameters

3.1 Return to the page: When calling the router.back() method, add optional options parameters (add url parameters) to return to the specified page.

Return to previous page

router.back();

3.2 Return to the specified page and pass parameters

router.back({
  url: 'pages/Index',
  params: {
    src: 'Second页面传来的数据',
  }
})

3.3 Return to the page to receive parameters

import router from '@ohos.router';

@Entry
@Component
struct Index {
  @State src: string = '';

  onPageShow() {
    this.src = router.getParams()?.['src'];
  }

  // 页面刷新展示
  ...
}

3.4 The effect diagram is shown in the figure below. In the Second page, after clicking "Back", you can return to the Index page from the Second page, and receive parameters and refresh the page in the Index page.

Four UIAbility life cycle

4.1 Life cycle diagram

4.2 Create：

Triggered when a UIAbility instance is created, the system will call the onCreate callback. Related initialization operations can be performed in the onCreate callback

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';

export default class EntryAbility extends UIAbility {
    onCreate(want, launchParam) {
        // 应用初始化
        ...
    }
    ...
}

4.3 onWindowStageCreate：

After the UIAbility instance is created, the system will create a WindowStage before entering the Foreground. Each UIAbility instance holds a WindowStage instance. You can set the UI page loading and WindowStage event subscription in the onWindowStageCreate callback.

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';

export default class EntryAbility extends UIAbility {
    ...

    onWindowStageCreate(windowStage: window.WindowStage) {
        // 设置UI页面加载
        // 设置WindowStage的事件订阅（获焦/失焦、可见/不可见）
        ...

        windowStage.loadContent('pages/Index', (err, data) => {
            ...
        });
    }
    ...
}

4.4 onForeground：

Triggered before UIAbility's UI page is visible, that is, when UIAbility switches to the foreground. You can apply for the resources needed by the system in the onForeground callback, or reapply for the resources released in onBackground.

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';

export default class EntryAbility extends UIAbility {
    ...

    onForeground() {
        // 申请系统需要的资源，或者重新申请在onBackground中释放的资源
        ...
    }

    onBackground() {
        // 释放UI页面不可见时无用的资源，或者在此回调中执行较为耗时的操作
        // 例如状态保存等
        ...
    }
}

4.5 onWindowStageDestroy：

Before the UIAbility instance is destroyed, it will first enter the onWindowStageDestroy callback, and we can release the UI page resources in this callback.

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';

export default class EntryAbility extends UIAbility {
    ...

    onWindowStageDestroy() {
        // 释放UI页面资源
        ...
    }
}

4.6 Destroy：

Fired when UIAbility is destroyed. Operations such as releasing system resources and saving data can be performed in the onDestroy callback.

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';

export default class EntryAbility extends UIAbility {
    ...

    onDestroy() {
        // 系统资源的释放、数据的保存等
        ...
    }
}

5 UIAbility startup mode

5.1 UIAbility currently supports three startup modes: singleton (single instance mode), multiton (multiple instance mode) and specified (specified instance mode)

5.2 singleton (single instance mode):

When a user opens an application such as a browser or news and browses to access relevant content, then returns to the desktop and opens the application again, the interface currently accessed by the user is still displayed.

In this case, UIAbility can be configured as singleton (single instance mode). Each time the startAbility() method is called, if a UIAbility instance of this type already exists in the application process, the UIAbility instance in the system will be reused, and there will be only one UIAbility instance in the system.

{
   "module": {
     ...
     "abilities": [
       {
         "launchType": "singleton",
         ...
       }
     ]
  }
}

5.3 multiton (multi-instance mode):

When users use the split-screen function, they hope to split the screen between two different applications (such as the Notes application and the Gallery application), or they also hope to use the same application (such as the Notes application itself) to split the screen.

In this case, UIAbility can be configured as multiton (multi-instance mode). Each time the startAbility() method is called, a UIAbility instance of this type is created in the application process

{
   "module": {
     ...
     "abilities": [
       {
         "launchType": "multiton",
         ...
       }
     ]
  }
}

5.4 specified (specified instance mode):

The user opens the document application, opens a document content from the document application, returns to the document application, continues to open the same document, hoping to open the same document content; and creates a new document in the document application, each time a new document is created, What you want to open is a new blank document.

In this case, UIAbility can be configured as specified (specified instance mode). Before a UIAbility instance is newly created, developers are allowed to create a string Key for the instance. After the newly created UIAbility instance is bound to the Key, each subsequent call to the startAbility method will ask the application which UIAbility instance corresponding to the Key to use to respond to startAbility. ask. If the Key of the UIAbility instance matches, the UIAbility instance bound to it is directly pulled up, otherwise a new UIAbility instance is created. At runtime, it is up to UIAbility internal business to decide whether to create multiple instances.

Step 1: Configure the "launchType" field in the module.json5 file to "specified".

{
   "module": {
     ...
     "abilities": [
       {
         "launchType": "specified",
         ...
       }
     ]
  }
}

Step 2: In the want parameter of calling the startAbility() method, add a custom parameter to distinguish the UIAbility instance, for example, add an "instanceKey" custom parameter

// 在启动指定实例模式的UIAbility时，给每一个UIAbility实例配置一个独立的Key标识
function getInstance() {
    ...
}

let want = {
    deviceId: "", // deviceId为空表示本设备
    bundleName: "com.example.myapplication",
    abilityName: "MainAbility",
    moduleName: "device", // moduleName非必选，默认为当前UIAbility所在的Module
    parameters: { // 自定义信息
        instanceKey: getInstance(),
    },
}
// context为启动方UIAbility的AbilityContext
context.startAbility(want).then(() => {
    ...
}).catch((err) => {
    ...
})

Step 3: In the onAcceptWant life cycle callback of the AbilityStage corresponding to the UIAbility of the pulled party, parse the incoming want parameter and obtain the "instanceKey" custom parameter. Return a string Key identification of the UIAbility instance according to business needs. If the UIAbility identified by this Key has been launched before, the previous UIAbility will be brought back to the foreground and focused without creating a new instance. Otherwise, a new instance will be created and started.

onAcceptWant(want): string {
    // 在被启动方的AbilityStage中，针对启动模式为specified的UIAbility返回一个UIAbility实例对应的一个Key值
    // 当前示例指的是device Module的EntryAbility
   if (want.abilityName === 'MainAbility') {
        return `DeviceModule_MainAbilityInstance_${want.parameters.instanceKey}`;
    }

    return '';
}

HarmonyOS application page UIAbility

Guess you like