【HarmonyOS NEXT】Stage模型UIAbility组件

一、背景

在Stage 模型开发中，UIAbility 是承载应用界面与用户交互的核心组件，也是多模块、跨应用开发的关键载体。刚开始很容易混淆概念，整理总结下加深自己的理解。

二、概念

是什么？：

UIAbility组件是一种包含UI的应用组件，主要用于和用户交互。一个应用包含1个或多个UIAbility

通俗类比：把整个应用 App 比作一家 "公司"，UIAbility 就是公司里的 "独立部门"（如销售部、财务部、技术部）：

公司（App）可根据业务需要拆分多个部门（UIAbility）；
每个部门（UIAbility）分工明确、互不干扰，能独立完成核心业务；
部门间可协同（UIAbility 跳转），但各自有独立的运作流程（生命周期）。

作用是啥？

把"页面+业务逻辑"打包成一个独立的功能单元，实现业务解耦

什么场景下用？

只要是能独立闭环的业务，都可以拆成UIAbility

常见场景：功能模块（首页/登录/个人中心/购物车）、独立业务（支付流程/收货地址/商品搜索）

三、生命周期

可以类比为 "部门从成立到解散" 的全流程

生命周期回调	触发时机	典型业务操作
`onCreate`	首次创建 UIAbility 实例（仅触发 1 次）	主题初始化、首选项读取、隐私协议检查、第三方 SDK 初始化（如埋点、推送 SDK）
`onWindowStageCreate`	窗口创建完成（UIAbility 启动 / 切前台触发）	加载页面 UI、设置沉浸式导航栏、初始化应用加载页（Splash）
`onForeground`	UIAbility 从后台切换至前台	重置后台标识、重新拉取最新配置、恢复实时数据刷新（如购物车商品数量）
`onBackground`	UIAbility 从前台切换至后台	清除前台标识、数据上报（如页面停留时长）、本地数据缓存（如未提交的表单）
`onWindowStageDestroy`	窗口销毁前（如关闭 UIAbility）	释放窗口相关 UI 资源（如图片缓存、定时器）
`onDestroy`	UIAbility 实例销毁前	释放全局资源（如数据库连接）、保存持久化数据（如用户编辑的草稿）
`onNewWant`	UIAbility 实例已存在，再次被启动时	处理 App 热启动跳转（如从推送通知打开指定页面、跨应用跳转的参数接收）

四、UIAbility跳转：跨应用（lucyTest→myTest）

前提：两个应用都已启动

需求：在lucyTest应用的 UIAbility 中点击按钮，跳转到myTest应用的 UIAbility，并在myTest的生命周期中获取跳转方的关键信息（Pid、BundleName、AbilityName）。

4.1、发送方：lucyTest-->实现跳转逻辑

步骤1:在index页面，按钮点击跳转到目标页面

TypeScript 复制代码

//lucyTest-->index.ets
import { testUtils } from '../utils/testUtils'

@Entry
@Component
struct Index {
  build() {
    Column({ space: 20 }) {
      Text('这里是lucyTest工程')
      Button('跳转到myTest工程')
        .onClick(async () => {
          await testUtils()
        })
    }
    .margin({ top: 100 })
    .width('100%')
    .height('100%')
  }
}

步骤2:执行跳转逻辑

TypeScript 复制代码

import common from "@ohos.app.ability.common";

export async function testUtils() {
  try {
    const context = getContext() as common.UIAbilityContext;
    await context.startAbility({
      bundleName: 'com.example.mytest',
      abilityName: 'EntryAbility',
    })
    console.log('lucy== start-成功')
  } catch (err) {
    // 捕获错误，打印具体原因（关键！）
    const error = err as BusinessError;
    console.log("lucy== 跨App跳转失败：", error.code, error.message);
  }
}

4.2、接收方：myTest-->配置与信息获取

步骤1:提供应用加载页面

TypeScript 复制代码

@Entry
@Component
struct Index {
  build() {
    Column() {
      Button('我是myTest工程页面哈')
        .margin({ top: 100 })
    }
    .width('100%')
    .height('100%')
    .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])
  }
}

步骤2:在myTest的onCreate生命周期中，获取并打印lucyTest的Pid、BundleName和AbilityName。

当发送方lucyTest执行按钮点击跳转到接收方myTest时，在myTest的onCreate生命周期中，可以获取到lucyTest的Pid、BundleName和AbilityName等信息

4.3、跳转时踩过的坑：

1、跳转失败：日志提示 "找不到 Ability"

原因：目标 UIAbility 的bundleName/abilityName写错，或未配置exported: true

解决：核对bundleName（与myTest的app.json5一致）、abilityName（与module.json5一致），确保exported: true

2、跳转无反应：日志报错16000001

原因：通过检查bundleName、moduleName和abilityName都是正确的，最后发现是ability所属的hap没有被安装

解决：应用没安装，安装应用成功后即可启动正常跳转