HarmonyOS应用实践-UIAbility的使用

什么是UIAbility?

UIAbility是一种包含用户界面的应用组件 ，主要用于和用户进行交互。同时它也是系统调度的单元 ，为应用提供窗口在其中进行绘制页面。

每个UIAbility实例，都对应着一个最近任务列表中的人物。
一个应用可以有一个UIAbility，也可以有多个 。
一个UIAbility可以对应多个页面，建议将一个独立的功能模块放到一个UIAbility中，以多页面的形式呈现。

UIAbility内页面的跳转和数据传递

UIAbility内页面的跳转和传递

目录/文件	描述
src/main/ets/entryability/EntryAbility.ts	在此文件中实现 UIAbility 的生命周期回调内容，根据业务需求编写逻辑。
src/main/ets/pages/Index	作为应用的入口页面，基于 UIAbility 实现页面的功能。您可以在这个页面中添加页面的内容和交互逻辑。
src/main/ets/pages/Second	用于实现页面间的跳转和数据传递。您可以在这个页面中编写代码来接收数据、处理导航逻辑等。

使用router模块实现页面间的导航

页面跳转和参数接收

页面跳转

导入router模块

import router from '@ohos.router';

方法	router.pushUrl()	router.replaceUrl()
用途	用于添加新页面到页面栈，保留原有页面。	用于替换当前页面，将目标页面URL替代为当前页面URL。
参数	接受目标页面URL和导航模式参数。	接受目标页面URL和导航模式参数。
页面栈变化	如果目标页面的URL已存在于页面栈中，会增加页面栈的元素数量。	如果目标页面的URL已存在于页面栈中，会减少页面栈的元素数量。
行为	创建新页面并添加到页面栈，保留原有页面。	移动现有页面到栈顶，替换当前页面，销毁被替换的当前页面。
导航模式	通常支持 "Single" 和 "Standard" 模式。	通常支持 "Single" 和 "Standard" 模式。
使用场景	用于常规页面切换，保留原有页面状态。	用于特殊场景，如页面替换和销毁。

特征	router.pushUrl()	router.replaceUrl()
导航模式	通常支持 "Single" 和 "Standard" 模式。	通常支持 "Single" 和 "Standard" 模式。
"Single" 行为	- 如果目标页面的URL已存在于页面栈中，会增加页面栈的元素数量。 - 最近的相同URL页面会被移动到栈顶，成为新建页。 - 原来的页面仍然存在于栈中，页面栈的元素数量不变。	- 如果目标页面的URL已存在于页面栈中，会减少页面栈的元素数量。 - 移动现有页面到栈顶，替换当前页面，销毁被替换的当前页面。
"Standard" 行为	- 无论目标页面的URL在页面栈中是否存在相同的URL页面，会按照多实例模式进行导航。 - 页面栈的元素数量保持不变。	- 无论目标页面的URL在页面栈中是否存在相同的URL页面，会按照多实例模式进行导航。 - 页面栈的元素数量保持不变。

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

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

参数接收

通过调用router.getParams()方法获取Index页面传递过来的自定义参数

import router from '@ohos.router';

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

页面返回和参数接收

页面返回

在Second页面中，可以通过调用router.back()方法实现返回到上一个页面，或者在调用router.back()方法时增加可选的options参数（增加url参数）返回到指定页面。

import router from '@ohos.router';
// 返回上级
router.back();
// 返回制定页面
router.back({ url: 'pages/Index' });

页面返回询问对话框

启用页面返回询问对话框功能：

使用 router.enableBackPageAlert() 方法开启页面返回询问对话框功能。这个功能只针对当前页面生效。在调用 router.pushUrl() 或 router.replaceUrl() 方法后，跳转到的新页面被视为新建页面，因此在页面返回之前需要先调用 router.enableBackPageAlert() 方法，以启用页面返回询问对话框功能。

router.enableBackPageAlert({
  message: 'Message Info'
});

router.back();

关闭页面返回询问对话框功能：

如果需要关闭页面返回询问对话框功能，可以使用 router.disableAlertBeforeBackPage() 方法。这个方法用于在特定情况下禁用询问对话框，以确保在页面返回时不会出现确认提示。

参数接收

在Second页面中，调用router.back()方法返回上一个页面或者返回指定页面时，根据需要继续增加自定义参数，例如在返回时增加一个自定义参数src。

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

从Second页面返回到Index页面。在Index页面通过调用router.getParams()方法，获取Second页面传递过来的自定义参数。

在调用 router.back() 方法时，不会新建页面 ，而是返回到原来的页面。在原来页面中使用 @State 声明的变量不会重复声明 ，也不会触发页面的 aboutToAppear() 生命周期回调 。因此，不能直接在变量声明以及页面的 aboutToAppear() 生命周期回调中接收和解析 router.back() 传递过来的自定义参数。

这意味着当使用 router.back() 返回到前一个页面时，需要采取其他方式来传递和处理自定义参数，因为原页面的状态和生命周期不会重新初始化。

可以放在业务需要的位置进行参数解析。示例代码在Index页面中的onPageShow()生命周期回调中进行参数的解析。

import router from '@ohos.router';

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

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

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

UIAbility的生命周期

在UIAbility的生命周期中，最重要的状态包括：

• Create状态 ：在UIAbility实例创建时触发，用于应用的初始化操作。在onCreate回调中，您可以进行系统资源的初始化和其他相关操作。

• Foreground状态 ：在UIAbility的UI页面可见之前触发，即UIAbility切换至前台时触发onForeground回调。这是您申请系统需要的资源，或者重新申请在Background中释放的资源的关键时刻。

• Background状态 ：在UIAbility的UI页面完全不可见之后触发，即UIAbility切换至后台时触发onBackground回调。在此回调中，您可以释放UI页面不可见时无用的资源，执行耗时操作，例如状态保存等。这对于系统资源的合理利用至关重要。

• Destroy状态：在UIAbility销毁时触发，用于完成系统资源的释放、数据的保存等操作。这是应用退出或关闭的关键阶段。

此外，窗口管理器（WindowStage）的两个回调也很重要：

• WindowStageCreate状态 ：在UIAbility实例创建完成之后，系统会创建一个WindowStage。在onWindowStageCreate回调中，您可以设置UI页面加载，设置WindowStage的事件订阅，以确保应用正确管理UI界面功能。

• WindowStageDestroy状态：在UIAbility实例销毁之前触发，用于释放UI页面资源，清理WindowStage相关内容，以确保资源的正确释放。

这些生命周期状态和回调是UIAbility应用中的关键部分，需要特别关注和管理，以确保应用的正确运行和资源的有效利用。

以下是UIAbility生命周期状态和相关回调的说明，以表格形式展示，以便更清晰地理解：

状态	触发时机	回调方法	主要作用
Create	UIAbility实例创建时触发	onCreate(want, launchParam)	初始化操作，应用初始化等
WindowStageCreate	UIAbility实例创建后触发，系统创建WindowStage	onWindowStageCreate(windowStage)	设置UI页面加载、事件订阅等
Foreground	UIAbility切换至前台时触发	onForeground()	申请系统资源，重新申请在onBackground中释放的资源，等操作
Background	UIAbility切换至后台时触发	onBackground()	释放UI页面不可见时无用的资源，执行耗时操作，例如状态保存等
WindowStageDestroy	UIAbility实例销毁之前触发，释放UI页面资源	onWindowStageDestroy()	释放UI页面资源，清理WindowStage相关内容
Destroy	UIAbility销毁时触发	onDestroy()	释放系统资源，保存数据等

UIAbility的启动模式

以下是UIAbility启动模式（singleton、multiton、specified）的详细说明，以表格形式展示，以便更清晰地了解它们的区别和配置方法：

启动模式	描述	配置方法
singleton（单实例模式）	用户在应用中浏览内容后，返回桌面，再次打开应用时，显示的是上次访问的界面。每次startAbility()调用时，复用现有UIAbility实例。系统中只存在一个唯一实例。	在 module.json5 中的 "launchType" 字段配置为 "singleton"。
multiton（多实例模式）	用户可以在分屏中同时使用两个不同应用，或者使用同一个应用进行分屏。每次startAbility()调用时，都会在应用进程中创建一个新的UIAbility实例。可以在最近任务列表中看到多个UIAbility实例。	在 module.json5 中的 "launchType" 字段配置为 "multiton"。
specified（指定实例模式）	用户可以在应用中打开同一文档内容，也可以新建不同的文档实例。允许开发者为每个UIAbility实例创建一个字符串Key标识。系统会根据Key标识决定是否创建多个实例。	在 module.json5 中的 "launchType" 字段配置为 "specified"。