鸿蒙开发(六)-UIAbility组件

鸿蒙开发(六)-UIAbility组件

本文主要讲述下UIAbility组件相关。

1：UIAbility简介

UIAbility组件是一种包含UI界面的应用组件，组要用于和用户交互。

UIAbility需要再module.json5配置文件中声明。

我们直接把代码自动生成的json5文件拿出来看下：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ts",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ]
  }
}

这里我们主要看abilities标签：

1. name: UIAbility的组件名称，整个应用唯一（最长127字节）
2. srcEntry: UIAbility组件代码路径 （最长127字节）
3. description：描述
4. icon:图标
5. label: 标签
6. permissions:权限信息
7. launchType:启动模式
8. exported:是否可以被其他应用调用
9. startWindowIcon：标识UIAbility启动页图标
10. startWindowBackground：启动页面背景颜色

具体更多的可以参考文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V2/module-configuration-file-0000001427744540-V2#ZH-CN_TOPIC_0000001573929365__abilities%E6%A0%87%E7%AD%BE

2：UIAbility的生命周期

UIAbility的生命周期包含onCreate，onDestroy，onForeground，

onBackground。另外除了这四种外，还包含了onWindowStageCreate以及onWindowStageDestroy状态。

1. onCreate：UIAbility实例创建完成时触发，可在该方法中定义变量，加载资源。
2. onForeground：UIAbility切换前台
3. onBackground：UIAbility切换后台
4. onDestroy：UIAbility销毁实例，可在该方法中进行系统资源的释放。

下面是EntryAbility的代码：

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

export default class EntryAbility extends UIAbility {
  onCreate(want, launchParam) {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
  }

  onDestroy() {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy');
  }

  onWindowStageCreate(windowStage: window.WindowStage) {
    // Main window is created, set main page for this ability
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
        return;
      }
      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
    });
  }

  onWindowStageDestroy() {
    // Main window is destroyed, release UI related resources
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
  }

  onForeground() {
    // Ability has brought to foreground
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground');
  }

  onBackground() {
    // Ability has back to background
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground');
  }
};

我们可以根据以下几种情况看下生命周期：

1. 启动UIAbility：

   onCreate->onWindowStageCreate->onForeground

2. 返回退出UIAbility：

   onBackground->onWindowStageDestroy->onDestroy

3. 前台时点击home在重新启动

   onBackground->onForeground

UIAbility代码如下：

/**
 * The class of a UI ability.
 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
 * @StageModelOnly
 * @since 9
 */
export default class UIAbility extends Ability {
    /**
     * Indicates configuration information about an ability context.
     * @type { UIAbilityContext }
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    context: UIAbilityContext;
    /**
     * Indicates ability launch want.
     * @type { Want }
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    launchWant: Want;
    /**
     * Indicates ability last request want.
     * @type { Want }
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    lastRequestWant: Want;
    /**
     * Call Service Stub Object.
     * @type { Callee }
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    callee: Callee;
    /**
     * Called back when an ability is started for initialization.
     * @param { Want } want - Indicates the want info of the created ability.
     * @param { AbilityConstant.LaunchParam } param - Indicates the launch param.
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onCreate(want: Want, param: AbilityConstant.LaunchParam): void;
    /**
     * Called back when an ability window stage is created.
     * @param { window.WindowStage } windowStage - Indicates the created WindowStage.
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onWindowStageCreate(windowStage: window.WindowStage): void;
    /**
     * Called back when an ability window stage is destroyed.
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onWindowStageDestroy(): void;
    /**
     * Called back when an ability window stage is restored.
     * @param { window.WindowStage } windowStage - window stage to restore
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onWindowStageRestore(windowStage: window.WindowStage): void;
    /**
     * Called back before an ability is destroyed.
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onDestroy(): void | Promise<void>;
    /**
     * Called back when the state of an ability changes to foreground.
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onForeground(): void;
    /**
     * Called back when the state of an ability changes to background.
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onBackground(): void;
    /**
     * Called back when an ability prepares to continue.
     * @param { {[key: string]: Object} } wantParam - Indicates the want parameter.
     * @returns { AbilityConstant.OnContinueResult } Return the result of onContinue.
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onContinue(wantParam: {
        [key: string]: Object;
    }): AbilityConstant.OnContinueResult;
    /**
     * Called when the launch mode of an ability is set to singleton.
     * This happens when you re-launch an ability that has been at the top of the ability stack.
     * @param { Want } want - Indicates the want info of ability.
     * @param { AbilityConstant.LaunchParam } launchParams - Indicates the launch parameters.
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void;
    /**
     * Called when dump client information is required.
     * It is recommended that developers don't DUMP sensitive information.
     * @param { Array<string> } params - Indicates the params from command.
     * @returns { Array<string> } Return the dump info array.
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onDump(params: Array<string>): Array<string>;
    /**
     * Called back when an ability prepares to save.
     * @param reason state type when save.
     * @param wantParam Indicates the want parameter.
     * @returns 0 if ability agrees to save data successfully, otherwise errcode.
     * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore
     * @StageModelOnly
     * @since 9
     */
    onSaveState(reason: AbilityConstant.StateType, wantParam: {
        [key: string]: Object;
    }): AbilityConstant.OnSaveResult;
}

3：UIAbility启动页面

根据上面的代码我们可以看到，EntryAbility在onWindowStageCreate()通过loadContent指定了启动页面为pages/Index。

  onWindowStageCreate(windowStage: window.WindowStage) {
    // Main window is created, set main page for this ability
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
        return;
      }
      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
    });
  }

4：UIAbility跳转

跳转UIAbility需要用到startAbility();

参数为want: Want，我们可以看下Want代码：

/*
 * Copyright (c) 2022 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * Want is the basic communication component of the system.
 * @syscap SystemCapability.Ability.AbilityBase
 * @since 9
 */
export default class Want {
    /**
     * bundle name
     * @syscap SystemCapability.Ability.AbilityBase
     * @since 9
     */
    bundleName?: string;
    /**
     * ability name
     * @syscap SystemCapability.Ability.AbilityBase
     * @since 9
     */
    abilityName?: string;
    /**
     * device id
     * @syscap SystemCapability.Ability.AbilityBase
     * @since 9
     */
    deviceId?: string;
    /**
     * The description of a URI in a Want.
     * @syscap SystemCapability.Ability.AbilityBase
     * @since 9
     */
    uri?: string;
    /**
     * The description of the type in this Want.
     * @syscap SystemCapability.Ability.AbilityBase
     * @since 9
     */
    type?: string;
    /**
     * The options of the flags in this Want.
     * @syscap SystemCapability.Ability.AbilityBase
     * @since 9
     */
    flags?: number;
    /**
     * The description of an action in an want.
     * @syscap SystemCapability.Ability.AbilityBase
     * @since 9
     */
    action?: string;
    /**
     * The description of the WantParams object in an Want
     * @syscap SystemCapability.Ability.AbilityBase
     * @since 9
     */
    parameters?: {
        [key: string]: Object;
    };
    /**
     * The description of a entities in a Want.
     * @syscap SystemCapability.Ability.AbilityBase
     * @since 9
     */
    entities?: Array<string>;
    /**
     * The description of an module name in an want.
     * @syscap SystemCapability.Ability.AbilityBase
     * @since 9
     */
    moduleName?: string;
}

我们简单写个跳转的例子：

let want ={
  deviceId:"",
  abilityName:"SecondAbility",
  bundleName:"com.zh.lowcode"
}
this.context.startAbility(want);

跳转后我们可以继续看下两个Ability的生命周期变化如下：

ability1:onCreate->onWindowStageCreate->onForeground

ability2:onCreate->onWindowStageCreate->onForeground

ability1:onBackground

03-11 00:28:45.161 15056-7672/? I 00000/testTag: Ability onCreate
03-11 00:28:45.447 15056-7672/? I 00000/testTag: Ability onWindowStageCreate
03-11 00:28:45.745 15056-7672/? I 00000/testTag: Ability onForeground
03-11 00:28:45.887 15056-7672/? I 00000/testTag: Succeeded in loading the content. Data:
03-11 00:28:46.373 15056-7672/? I 00000/testTag: Ability2 onCreate
03-11 00:28:46.561 15056-7672/? I 00000/testTag: Ability2 onWindowStageCreate
03-11 00:28:47.004 15056-7672/? I 00000/testTag: Ability2 onForeground
03-11 00:28:47.011 15056-7672/? I 00000/testTag: Ability onBackground
03-11 00:28:47.160 15056-7672/? I 00000/testTag: Succeeded in loading the content. Data: