【HarmonyOS 5】鸿蒙中的UIAbility详解(一)

【HarmonyOS 5】鸿蒙中的UIAbility详解(一)

一、UIAbility是什么?

Stage模型中的组件类型名,即UIAbility组件,包含UI,提供展示UI的能力,主要用于和用户交互。

UIAbility类似于传统移动开发Android中的Activity或者Fragment。类似IOS开发中的 UIViewController。

UIAbility 是 HarmonyOS 应用框架的核心组件,负责管理应用的用户界面生命周期和上下文信息。

二、设置指定启动页面

启动页面必须设置:否则应用启动后会白屏。

避免应用启动后白屏,需在onWindowStageCreate生命周期中设置默认加载页面。通过WindowStageloadContent()方法指定页面路径。

typescript 复制代码
export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err, data) => { /* 处理回调 */ });
  }
}

DevEco Studio默认生成的项目会自动加载Index页面,可按需修改路径。

三、获取上下文信息(UIAbilityContext)

获取应用配置信息(如包名、Ability名称等),或调用操作Ability的方法(如启动、终止Ability)。通过this.context直接访问。

typescript 复制代码
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    const context = this.context; // 直接获取上下文
  }
}

在页面组件中获取 : 通过getUIContext().getHostContext()转换为UIAbilityContext

typescript 复制代码
@Entry
@Component
struct Page {
  private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
  startAbilityTest() { this.context.startAbility(want); } // 启动其他Ability
}

启动页面设置与上下文使用代码示例

typescript 复制代码
// UIAbility定义
export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Main', () => {}); // 设置启动页面
  }

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    const context = this.context; // 获取上下文
    context.startAbility({ abilityName: 'OtherAbility' }); // 启动其他Ability
  }
}

// 页面组件中使用上下文
@Entry
@Component
struct MainPage {
  private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
  build() {
    Button('终止当前Ability').onClick(() => this.context.terminateSelf());
  }
}

四、UIAbility生命周期与操作

UIAbility的生命周期包含 Create(创建)、Foreground(前台)、Background(后台)、Destroy(销毁) 四个核心状态,以及与窗口(WindowStage)相关的子状态。通过生命周期回调钩子函数,可监听状态变化并执行对应操作。

生命周期状态流转图

scss 复制代码
创建实例          窗口创建       进入前台         切到后台         窗口销毁       实例销毁
  ↓               ↓             ↓               ↓               ↓             ↓
onCreate() → onWindowStageCreate() → onForeground() → onBackground() → onWindowStageDestroy() → onDestroy()
         ↑       ↖                ↗                ↖                ↑
         └─────── WindowStageWillDestroy() ────────────────────────┘

1、onCreate

UIAbility实例创建完成时触发。初始化页面数据、加载资源(如定义变量、获取上下文this.context)。

typescript 复制代码
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    // 初始化操作(如获取上下文、配置数据)
    const context = this.context; 
  }
}

2、WindowStageCreate

UIAbility实例创建后,进入前台前,系统创建WindowStage时触发。设置启动页面(loadContent())、订阅窗口事件(如前后台切换、焦点变化)。

dart 复制代码
    onWindowStageCreate(windowStage: window.WindowStage) {
      windowStage.loadContent('pages/Index'); // 设置启动页面
      windowStage.on('windowStageEvent', (event) => { // 订阅窗口事件
        switch (event) {
          case window.WindowStageEventType.SHOWN: // 切到前台
            console.log('窗口切到前台');
            break;
        }
      });
    }
 

3、WindowStageWillDestroy

WindowStage销毁前触发(此时窗口仍可用)。释放通过WindowStage获取的资源,注销事件订阅(off('windowStageEvent'))。

4、WindowStageDestroy

WindowStage销毁时触发(UI资源释放)。释放UI相关资源(如临时文件、图形对象)。

5、Foreground

UIAbility切换至前台、UI可见前触发。申请系统资源(如定位、传感器权限)、恢复后台释放的资源。

dart 复制代码
    onForeground() {
      // 开启定位功能
      location.start(); 
    }

6、Background

UIAbility切换至后台、UI完全不可见后触发。释放无用资源、执行耗时操作(如数据持久化)。

dart 复制代码
    onBackground() {
      // 停止定位、保存当前状态
      location.stop(); 
      saveDataToLocal();
   }

7、onDestroy

UIAbility实例被终止时触发(如调用terminateSelf())。释放全局资源、清理内存(如关闭网络连接、注销监听器)。

typescript 复制代码
onDestroy() {
  // 释放数据库连接、取消定时器
  db.close(); 
  clearInterval(timer);
}

注意 :API 13+中,若用户通过最近任务一键清理应用,不会触发onDestroy(),而是直接终止进程。

四、UIAbility的常用函数操作

1. 终止UIAbility实例

调用terminateSelf()终止当前Ability。

typescript 复制代码
context.terminateSelf((err) => {
  if (err) { console.error('终止失败:', err); } 
  else { console.info('终止成功'); }
});

2. 获取拉起方信息

当UIAbilityA通过startAbility启动UIAbilityB时,UIAbilityB可获取调用方信息。

typescript 复制代码
export default class UIAbilityB extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    console.log(`调用方Pid: ${want.parameters?.['ohos.aafwk.param.callerPid']}`);
  }
}

跨Ability信息传递代码示例

typescript 复制代码
// UIAbilityA中启动UIAbilityB
@Entry
@Component
struct UIAbilityAPage {
  private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
  build() {
    Button('拉起UIAbilityB').onClick(() => {
      this.context.startAbility({ 
        bundleName: this.context.abilityInfo.bundleName, 
        abilityName: 'UIAbilityB' 
      });
    });
  }
}

// UIAbilityB中获取调用方信息
export default class UIAbilityB extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    console.log(`调用方包名: ${want.parameters?.['ohos.aafwk.param.callerBundleName']}`);
  }
}

注意

当UIAbility设置为singleton启动模式时,重复调用startAbility()启动同一实例,不会重新走onCreateonWindowStageCreate流程 ,而是触发onNewWant回调。

typescript 复制代码
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) {
  // 根据新的Want参数更新页面数据
  this.data = want.parameters?.data; 
}
相关推荐
HarmonyOS_SDK2 小时前
打破场景边界,支付宝联合实况窗提供全新出行服务体验
harmonyos
安卓开发者2 小时前
鸿蒙NEXT应用数据持久化全面解析:从用户首选项到分布式数据库
数据库·分布式·harmonyos
森之鸟2 小时前
开发中使用——鸿蒙播放本地mp3文件
华为·harmonyos
前端世界4 小时前
HarmonyOS 数据处理性能优化:算法 + 异步 + 分布式实战
算法·性能优化·harmonyos
HarmonyOS小助手5 小时前
【案例+1】HarmonyOS官方模板优秀案例 第7期:金融理财 · 记账应用
harmonyos·鸿蒙·鸿蒙生态
爱笑的眼睛116 小时前
HarmonyOS 应用开发深入浅出:基于 Stage 模型与声明式 UI 的现代化状态管理实践
华为·harmonyos
爱笑的眼睛117 小时前
HarmonyOS 应用开发深度解析:掌握 ArkTS 声明式 UI 与现代化状态管理
华为·harmonyos
爱笑的眼睛117 小时前
HarmonyOS 应用开发深度解析:基于 ArkTS 的跨组件状态管理最佳实践
华为·harmonyos
前端世界7 小时前
鸿蒙系统下的智能设备故障检测实战:从监控到自愈的全流程实现
华为·harmonyos
2501_919749037 小时前
flutter鸿蒙:使用flutter_local_notifications实现本地通知
flutter·华为·harmonyos