目录

@ohos.app.ability.UIAbility (带界面的应用组件)

UIAbility是包含UI界面的应用组件,继承自Ability,提供UIAbility组件创建、销毁、前后台切换等生命周期回调,同时也具备后台通信能力。

本模块首批接口从API version 9 开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

本模块接口仅可在Stage模型下使用。

各类Ability的继承关系详见继承关系说明。

UIAbility生命周期状态

图1 UIAbility生命周期状态

后台通信能力

通过Call调用可以与目标UIAbility进行后台通信。Call调用示意图如下所示。

图2 Call调用示意图

导入模块

import { UIAbility } from '@kit.AbilityKit';

UIAbility

表示包含UI界面的应用组件,提供组件创建、销毁、前后台切换等生命周期回调,同时也具备后台通信能力。

[h2]属性

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

名称 类型 只读 可选 说明
context UIAbilityContext 否 否

UIAbility的上下文。

元服务API:从API version 11开始,该接口支持在元服务中使用。

launchWant Want 否 否

UIAbility冷启动时接收到的Want参数,取值为onCreate接收到的Want参数。

元服务API:从API version 11开始,该接口支持在元服务中使用。

lastRequestWant Want 否 否

最近一次拉起UIAbility请求的Want参数。

- 首次拉起UIAbility时,取值为onCreate接收到的Want参数。

- 重复拉起UIAbility时,取值为onNewWant最近一次接收到的Want参数。

元服务API:从API version 11开始,该接口支持在元服务中使用。

callee Callee 否 否 系统为UIAbility创建的后台通信对象,Callee UIAbility(被调用方)可以通过Callee对象接收Caller对象发送的数据。
specifiedId23+ string 否 是 仅当UIAbility启动模式为specified时存在,取值为开发者自定义的UIAbility标识。
isDestroyed boolean 否 否

用于判断UIAbility是否已被销毁。默认值为false,表示UIAbility未销毁,当onDestroy回调执行后,该属性会被设置为true,表示UIAbility已销毁。

起始版本: 26.0.0

[h2]onCreate

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void

当UIAbility实例创建完成时,系统会触发该回调,开发者可在该回调中执行初始化逻辑(如定义变量、加载资源等)。该回调仅会在UIAbility冷启动时触发。

同步接口,不支持异步回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
want Want 是 调用方拉起该UIAbility时传递的数据。
launchParam AbilityConstant.LaunchParam 是 应用启动参数,包含应用启动原因、应用上次退出原因等。

示例:

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

export default class MyUIAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    // 执行异步任务
    hilog.info(0x0000, 'testTag',
      `onCreate, want: ${want.abilityName}, the launchReason is ${launchParam.launchReason}, the lastExitReason is ${launchParam.lastExitReason}`);
  }
}

[h2]onWindowStageCreate

onWindowStageCreate(windowStage: window.WindowStage): void

当WindowStage实例创建完成后,系统会触发该回调。开发者可以在该回调中通过WindowStage加载页面。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
windowStage window.WindowStage 是 WindowStage实例对象。

示例:

import { UIAbility } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class MyUIAbility extends UIAbility {
  // 主窗口已创建,为该UIAbility设置主页面
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', `Failed to load the content. Cause: ${JSON.stringify(err)}`);
        return;
      }
      hilog.info(0x0000, 'testTag', `Succeeded in loading the content. Data: ${JSON.stringify(data)}`);
    });
  }
}

[h2]onWindowStageWillDestroy12+

onWindowStageWillDestroy(windowStage: window.WindowStage): void

当WindowStage即将销毁时,系统触发该回调。开发者可以在该生命周期中取消windowStage事件的监听。

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
windowStage window.WindowStage 是 WindowStage实例对象。

示例:

import { UIAbility } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class MyUIAbility extends UIAbility {
  onWindowStageWillDestroy(windowStage: window.WindowStage) {
    hilog.info(0x0000, 'testTag', `onWindowStageWillDestroy`);
  }
}

[h2]onWindowStageDestroy

onWindowStageDestroy(): void

当WindowStage销毁后,系统触发该回调。该回调用于通知开发者WindowStage对象已被销毁,不能再继续使用。

仅当UIAbility正常退出时会触发该回调,异常退出场景(例如低内存终止进程)不会触发该回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

示例:

import { UIAbility } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

export default class MyUIAbility extends UIAbility {
  onWindowStageDestroy() {
    // 主窗口已销毁,释放UI相关资源
    hilog.info(0x0000, 'testTag', `onWindowStageDestroy`);
  }
}

[h2]onWindowStageRestore

onWindowStageRestore(windowStage: window.WindowStage): void

当UIAbility跨端迁移时,目标端UIAbility恢复页面栈时回调。

在应用迁移启动时,无论是冷启动还是热启动,都会在执行完onCreate()/onNewWant()后,触发onWindowStageRestore()生命周期函数,不执行onWindowStageCreate()生命周期函数。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
windowStage window.WindowStage 是 WindowStage实例对象。

示例:

import { UIAbility } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class MyUIAbility extends UIAbility {
  onWindowStageRestore(windowStage: window.WindowStage) {
    hilog.info(0x0000, 'testTag', `onWindowStageRestore`);
  }
}

[h2]onDestroy

onDestroy(): void | Promise<void>

当UIAbility被销毁(例如使用terminateSelf接口停止UIAbility)时,系统触发该回调。开发者可以在该生命周期中执行资源清理、数据保存等相关操作。

使用同步回调或Promise异步回调。

  • 在执行完onDestroy生命周期回调后,应用可能会退出,从而导致其中的异步函数(比如异步写入数据库)未能正确执行。在此情况下,推荐使用Promise异步回调。
  • 该回调仅在UIAbility正常退出时触发,当UIAbility异常退出(例如低内存终止进程)时,该回调将不被触发。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

返回值:

类型 说明
void | Promise<void> 无返回结果或无返回结果的Promise对象。

示例:

[h2]onWillForeground20+

onWillForeground(): void

UIAbility生命周期回调,应用转到前台前触发,在onForeground前被调用。可在该回调中实现采集应用开始进入前台的时间。如果与onDidForeground配合使用,还可以统计出从应用开始进入前台到切换至前台状态的耗时。

同步接口,不支持异步回调。

元服务API:从API version 20开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

示例:

import { UIAbility } from '@kit.AbilityKit';
import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWillForeground(): void {
    // 应用开始进入前台事件打点
    let eventParams: Record<string, number> = { 'xxxx': 100 };
    let eventInfo: hiAppEvent.AppEventInfo = {
      // 事件领域定义
      domain: "lifecycle",
      // 事件名称定义
      name: "onwillforeground",
      // 事件类型定义
      eventType: hiAppEvent.EventType.BEHAVIOR,
      // 事件参数定义
      params: eventParams,
    };
    hiAppEvent.write(eventInfo).then(() => {
      hilog.info(0x0000, 'testTag', `HiAppEvent success to write event`);
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`);
    });
  }

  // ...

  onDidForeground(): void {
    // 应用进入前台后事件打点
    let eventParams: Record<string, number> = { 'xxxx': 100 };
    let eventInfo: hiAppEvent.AppEventInfo = {
      // 事件领域定义
      domain: "lifecycle",
      // 事件名称定义
      name: "ondidforeground",
      // 事件类型定义
      eventType: hiAppEvent.EventType.BEHAVIOR,
      // 事件参数定义
      params: eventParams,
    };
    hiAppEvent.write(eventInfo).then(() => {
      hilog.info(0x0000, 'testTag', `HiAppEvent success to write event`);
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`);
    });
  }
}

[h2]onForeground

onForeground(): void

当应用首次启动到前台或者从后台转入到前台时,系统触发该回调。开发者可在该回调中实现系统所需资源的申请,如应用转到前台时申请定位服务等。

同步接口,不支持异步回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

示例:

import { UIAbility } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

export default class MyUIAbility extends UIAbility {
  onForeground() {
    hilog.info(0x0000, 'testTag', `onForeground`);
  }
}

[h2]onDidForeground20+

onDidForeground(): void

UIAbility生命周期回调,应用转到前台后触发,在onForeground后被调用,可在该回调中实现应用切换到前台后的时间打点。如果与onWillForeground配合使用,还可以统计出从应用开始进入前台到切换至前台状态的耗时。

同步接口,不支持异步回调。

元服务API:从API version 20开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

示例:

参考onWillForeground。

[h2]onWillBackground20+

onWillBackground(): void

UIAbility生命周期回调,当应用从前台转到后台前触发,在onBackground前被调用。可在该回调中实现数据打点,例如,打点应用运行过程中发生的故障信息、统计信息、安全信息、用户行为信息等。

同步接口,不支持异步回调。

元服务API:从API version 20开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

示例:

import { UIAbility } from '@kit.AbilityKit';
import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class MyUIAbility extends UIAbility {
  onWillBackground(): void {
    let eventParams: Record<string, number | string> = {
      "int_data": 100,
      "str_data": "strValue",
    };
    // 打点应用故障信息
    hiAppEvent.write({
      domain: "test_domain",
      name: "test_event",
      eventType: hiAppEvent.EventType.FAULT,
      params: eventParams,
    }, (err: BusinessError) => {
      if (err) {
        hilog.error(0x0000, 'testTag', `hiAppEvent code: ${err.code}, message: ${err.message}`);
        return;
      }
      hilog.info(0x0000, 'testTag', `hiAppEvent success to write event`);
    });
  }
}

[h2]onBackground

onBackground(): void

当应用从前台转入到后台时,系统触发该回调。开发者可在该回调中实现UI不可见时的资源释放操作,如停止定位功能等。

同步接口,不支持异步回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

示例:

import { UIAbility } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

export default class MyUIAbility extends UIAbility {
  onBackground() {
    // UIAbility回到后台
    hilog.info(0x0000, 'testTag', `onBackground`);
  }
}

[h2]onDidBackground20+

onDidBackground(): void

UIAbility生命周期回调,当应用从前台转到后台后触发,在onBackground之后被调用。可在该回调中实现应用进入后台之后的资源释放操作,如进入后台后停止音频播放等。

同步接口,不支持异步回调。

元服务API:从API version 20开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

示例:

import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { audio } from '@kit.AudioKit';

export default class MyUIAbility extends UIAbility {
  static audioRenderer: audio.AudioRenderer;

  // ...
  onForeground(): void {
    let audioStreamInfo: audio.AudioStreamInfo = {
      samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, // 采样率。
      channels: audio.AudioChannel.CHANNEL_2, // 通道。
      sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, // 采样格式。
      encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW // 编码格式。
    };

    let audioRendererInfo: audio.AudioRendererInfo = {
      usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // 音频流使用类型:音乐。根据业务场景配置,参考StreamUsage。
      rendererFlags: 0 // 音频渲染器标志。
    };

    let audioRendererOptions: audio.AudioRendererOptions = {
      streamInfo: audioStreamInfo,
      rendererInfo: audioRendererInfo
    };

    // 在前台时申请audioRenderer,用于播放PCM(Pulse Code Modulation)音频数据
    audio.createAudioRenderer(audioRendererOptions).then((data) => {
      MyUIAbility.audioRenderer = data;
      hilog.info(0x0000, 'testTag', `AudioRenderer Created : Success : Stream Type: SUCCESS.`);
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', `AudioRenderer Created : F : ${JSON.stringify(err)}.`);
    });
  }

  onDidBackground() {
    // 转到后台后,释放audioRenderer资源
    MyUIAbility.audioRenderer.release((err: BusinessError) => {
      if (err) {
        hilog.error(0x0000, 'testTag', `AudioRenderer release failed, error: ${JSON.stringify(err)}.`);
      } else {
        hilog.info(0x0000, 'testTag', `AudioRenderer released.`);
      }
    });
  }
}

[h2]onContinue

onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult | Promise<AbilityConstant.OnContinueResult>

当UIAbility准备跨端迁移时触发,可以保存待迁移的业务数据。支持同步返回和使用Promise异步调用。

对于API version 18之前的版本,仅支持同步调用;API version 18及后续版本,支持Promise异步调用。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
wantParam Record<string, Object> 是 开发者通过该参数保存待迁移的数据。

返回值:

类型 说明
AbilityConstant.OnContinueResult | Promise<AbilityConstant.OnContinueResult>

表示是否同意迁移的结果:

- AGREE:表示同意。

- REJECT:表示拒绝,如应用在onContinue中异常可以返回REJECT。

- MISMATCH:表示版本不匹配,接续源端应用可以在onContinue中获取到迁移对端应用的版本号,进行协商后,如果版本不匹配导致无法迁移,可以返回该结果。

该回调与onWindowStageRestore成对出现。在接续场景下,源端的UIAbility触发onContinue保存自定义数据,在目标端UIAbility触发onWindowStageRestore恢复自定义数据。

示例:

[h2]onNewWant

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void

当已经启动的UIAbility实例再次被拉起时,系统会触发该回调。若在特定场景下(参见Scenarios),不需要触发该生命周期回调,可以使用setOnNewWantSkipScenarios接口设置。

同步接口,不支持异步回调。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
want Want 是 调用方再次拉起该UIAbility时传递的数据。
launchParam AbilityConstant.LaunchParam 是 UIAbility启动参数,包含启动原因等。

示例:

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';

export default class MyUIAbility extends UIAbility {
  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) {
    console.info(`onNewWant, want: ${want.abilityName}`);
    console.info(`onNewWant, launchParam: ${JSON.stringify(launchParam)}`);
  }
}

[h2]onDump

onDump(params: Array<string>): Array<string>

应用调测场景下,通过命令行dump UIAbility数据时,系统会触发该回调。开发者可以在该回调中返回UIAbility要转储的非敏感信息。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
params Array<string> 是 表示dump命令参数。

返回值:

类型 说明
Array<string> 返回的dump信息。

示例:

import { UIAbility } from '@kit.AbilityKit';

export default class MyUIAbility extends UIAbility {
  onDump(params: Array<string>) {
    console.info(`dump, params: ${JSON.stringify(params)}`);
    return ['params'];
  }
}

[h2]onSaveState

onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>): AbilityConstant.OnSaveResult

该接口需要与appRecovery配合使用。如果应用已使能故障恢复功能(即enableAppRecovery接口中的saveOccasion参数设置为SAVE_WHEN_ERROR),当应用出现故障时,系统将触发该回调来保存UIAbility的数据。

从API version 20开始,当onSaveStateAsync实现时,本回调函数将不执行。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
reason AbilityConstant.StateType 是 触发应用保存状态的原因,当前仅支持APP_RECOVERY(即应用故障恢复场景)。
wantParam Record<string, Object> 是 用户自定义的应用状态数据,应用再启动时被保存在onCreate的Want.parameters中。

返回值:

类型 说明
AbilityConstant.OnSaveResult 返回一个数据保存策略的对象(如全部拒绝、全部允许、只允许故障恢复场景等)。

示例:

import { UIAbility, AbilityConstant } from '@kit.AbilityKit';

export default class MyUIAbility extends UIAbility {
  onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>) {
    console.info('onSaveState');
    wantParam['myData'] = 'my1234567';
    return AbilityConstant.OnSaveResult.RECOVERY_AGREE;
  }
}

[h2]onSaveStateAsync20+

onSaveStateAsync(stateType: AbilityConstant.StateType, wantParam: Record<string, Object>): Promise<AbilityConstant.OnSaveResult>

该接口需要与appRecovery配合使用。如果应用已使能故障恢复功能(即enableAppRecovery接口中的saveOccasion参数设置为SAVE_WHEN_ERROR),当应用出现故障时,将触发该回调来保存UIAbility的数据。使用Promise异步回调。

元服务API:从API version 20开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
stateType AbilityConstant.StateType 是 触发应用保存状态的原因,当前仅支持APP_RECOVERY(即应用故障恢复场景)。
wantParam Record<string, Object> 是 用户自定义的应用状态数据,应用再启动时被保存在onCreate的Want.parameters中。

返回值:

类型 说明
Promise<AbilityConstant.OnSaveResult> Promise对象。返回一个数据保存策略的对象(如全部拒绝、全部允许、只允许故障恢复场景等)。

示例:

import { UIAbility, AbilityConstant } from '@kit.AbilityKit';

class MyUIAbility extends UIAbility {
  async onSaveStateAsync(reason: AbilityConstant.StateType,
    wantParam: Record<string, Object>): Promise<AbilityConstant.OnSaveResult> {
    await new Promise<string>((res, rej) => {
      setTimeout(res, 1000); // 延时1秒后执行
    });
    return AbilityConstant.OnSaveResult.RECOVERY_AGREE;
  }
}

[h2]onShare10+

onShare(wantParam: Record<string, Object>): void

当跨端分享元服务时,系统触发该回调。开发者可以在该回调中设置待分享元服务的标题、摘要和URL等数据。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
wantParam Record<string, Object> 是 待分享的数据。

示例:

import { UIAbility } from '@kit.AbilityKit';

export default class MyUIAbility extends UIAbility {
  onShare(wantParams: Record<string, Object>) {
    console.info('onShare');
    wantParams['ohos.extra.param.key.shareUrl'] = 'example.com';
  }
}

[h2]onPrepareToTerminate10+

onPrepareToTerminate(): boolean

在UIAbility即将关闭前(例如用户通过点击应用窗口右上角的关闭按钮、或者通过Dock栏/托盘右键退出应用时),系统会触发该回调,用于在UIAbility正式关闭前执行其他操作。开发者可以在该回调中返回true阻拦此次关闭,然后在合适时机主动调用terminateSelf接口关闭。例如,询问用户是否确认关闭UIAbility,再主动销毁UIAbility。

需要权限:ohos.permission.PREPARE_APP_TERMINATE

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

设备行为差异:该接口仅在PC/2in1和Tablet设备中可正常执行回调,在其他设备上不执行回调。

返回值:

类型 说明
boolean 是否执行UIAbility关闭操作,返回true表示本次UIAbility关闭流程取消,返回false表示UIAbility继续正常关闭。

示例:

import { UIAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onPrepareToTerminate() {
    // 开发者定义预关闭动作
    // 例如拉起另一个ability,根据ability处理结果执行异步关闭
    let want: Want = {
      bundleName: 'com.example.myapplication',
      moduleName: 'entry',
      abilityName: 'SecondAbility'
    }
    this.context.startAbilityForResult(want)
      .then((result) => {
        // 获取ability处理结果,当返回结果的resultCode为0关闭当前UIAbility
        console.info('startAbilityForResult success, resultCode is ' + result.resultCode);
        if (result.resultCode === 0) {
          this.context.terminateSelf();
        }
      }).catch((err: BusinessError) => {
      // 异常处理
      console.error('startAbilityForResult failed, err:' + JSON.stringify(err));
      this.context.terminateSelf();
    });

    return true; // 已定义预关闭操作后,返回true表示UIAbility取消关闭
  }
}

[h2]onPrepareToTerminateAsync15+

onPrepareToTerminateAsync(): Promise<boolean>

在UIAbility关闭前(例如用户通过点击应用窗口右上角的关闭按钮、或者通过Dock栏/托盘右键退出应用时),系统会触发该回调,用于在UIAbility正式关闭前执行其他操作。

开发者可以在该回调中返回true阻拦此次关闭,然后在合适时机主动调用terminateSelf接口关闭。例如,询问用户是否确认关闭UIAbility,再主动销毁UIAbility。

需要权限:ohos.permission.PREPARE_APP_TERMINATE

元服务API:从API version 15开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

设备行为差异:

返回值:

类型 说明
Promise<boolean> Promise对象。表示是否执行UIAbility关闭操作,返回true表示本次UIAbility关闭流程取消,返回false表示UIAbility继续正常关闭。

示例:

import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  async onPrepareToTerminateAsync(): Promise<boolean> {
    await new Promise<boolean>((res, rej) => {
      setTimeout(res, 2000); // 延时2秒
    });
    return true; // 已定义预关闭操作后,返回true表示UIAbility取消关闭
  }
}

[h2]onBackPressed10+

onBackPressed(): boolean

UIAbility生命周期回调,当UIAbility侧滑返回时触发,根据返回值决定是否销毁UIAbility。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

返回值:

类型 说明
boolean 返回true表示UIAbility将会被移到后台不销毁,返回false表示UIAbility将正常销毁。

示例:

import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onBackPressed() {
    return true;
  }
}

[h2]onCollaborate18+

onCollaborate(wantParam: Record<string, Object>): AbilityConstant.CollaborateResult

UIAbility生命周期回调,在多设备协同场景下,协同方应用在被拉起的过程中返回是否接受协同。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
wantParam Record<string, Object> 是 want相关参数,仅支持key值取"ohos.extra.param.key.supportCollaborateIndex"。通过该key值可以获取到调用方传输的数据并进行相应的处理。

返回值:

类型 说明
AbilityConstant.CollaborateResult 协同方是否接受协同的结果。

示例:

import { UIAbility, AbilityConstant } from '@kit.AbilityKit';

export default class MyAbility extends UIAbility {
  onCollaborate(wantParam: Record<string, Object>) {
    return AbilityConstant.CollaborateResult.ACCEPT;
  }
}

Caller

调用方Caller UIAbility通过startAbilityByCall接口拉起目标Callee UIAbility,目标UIAbility启动成功后,返回一个Caller对象给调用方进行通信。

[h2]call

call(method: string, data: rpc.Parcelable): Promise<void>

Caller UIAbility向Callee UIAbility发送双方约定好的序列化的数据。使用Promise异步回调。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
method string 是 由Caller和Callee双方约定好的方法名,Callee方通过该字段区分消息类型。
data rpc.Parcelable 是 由Caller向Callee发送的消息内容,消息内容是序列化的数据。

返回值:

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16200001 The caller has been released.
16200002 The callee does not exist.
16000050 Internal error.

示例:

import { UIAbility, Caller } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

class MyMessageAble implements rpc.Parcelable { // 自定义的Parcelable数据结构
  name: string;
  str: string;
  num: number = 1;

  constructor(name: string, str: string) {
    this.name = name;
    this.str = str;
  }

  marshalling(messageSequence: rpc.MessageSequence) {
    messageSequence.writeInt(this.num);
    messageSequence.writeString(this.str);
    console.info(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`);
    return true;
  }

  unmarshalling(messageSequence: rpc.MessageSequence) {
    this.num = messageSequence.readInt();
    this.str = messageSequence.readString();
    console.info(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`);
    return true;
  }
}

let method = 'call_Function'; // 约定的通知消息字符串

export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
      let caller: Caller = obj;
      let msg = new MyMessageAble('msg', 'world'); // 参考Parcelable数据定义
      caller.call(method, msg)
        .then(() => {
          console.info('Caller call() called');
        })
        .catch((callErr: BusinessError) => {
          console.error(`Caller.call catch error, error.code: ${callErr.code}, error.message: ${callErr.message}`);
        });
    }).catch((err: BusinessError) => {
      console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`);
    });
  }
}

[h2]callWithResult

callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence>

Caller UIAbility向Callee UIAbility发送消息,Callee UIAbility处理完成后返回结果。使用Promise异步回调。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
method string 是 由Caller和Callee双方约定好的方法名,Callee方通过该字段区分消息类型。
data rpc.Parcelable 是 由Caller向Callee发送的消息内容,消息内容是序列化的数据。

返回值:

类型 说明
Promise<rpc.MessageSequence> Promise对象,返回Callee UIAbility的应答数据。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16200001 The caller has been released.
16200002 The callee does not exist.
16000050 Internal error.

示例:

import { UIAbility, Caller } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

class MyMessageAble implements rpc.Parcelable {
  name: string
  str: string
  num: number = 1

  constructor(name: string, str: string) {
    this.name = name;
    this.str = str;
  }

  marshalling(messageSequence: rpc.MessageSequence) {
    messageSequence.writeInt(this.num);
    messageSequence.writeString(this.str);
    console.info(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`);
    return true;
  }

  unmarshalling(messageSequence: rpc.MessageSequence) {
    this.num = messageSequence.readInt();
    this.str = messageSequence.readString();
    console.info(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`);
    return true;
  }
}

let method = 'call_Function';
let caller: Caller;

export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
      caller = obj;
      let msg = new MyMessageAble('msg', 'world');
      caller.callWithResult(method, msg)
        .then((data) => {
          console.info('Caller callWithResult() called');
          let retMsg = new MyMessageAble('msg', 'world');
          data.readParcelable(retMsg);
        })
        .catch((callErr: BusinessError) => {
          console.error(`Caller.callWithResult catch error, error.code: ${callErr.code}, error.message: ${callErr.message}`);
        });
    }).catch((err: BusinessError) => {
      console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`);
    });
  }
}

[h2]release

release(): void

Caller主动释放与Callee UIAbility的连接。调用该接口后,Caller不能再使用call或callWithResult向Callee方发送消息。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

错误码:

以下错误码详细介绍请参考元能力子系统错误码。

错误码ID 错误信息
16200001 The caller has been released.
16200002 The callee does not exist.

示例:

import { UIAbility, Caller } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let caller: Caller;

export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
      caller = obj;
      try {
        caller.release();
      } catch (releaseErr) {
        console.error(`Caller.release catch error, error.code: ${releaseErr.code}, error.message: ${releaseErr.message}`);
      }
    }).catch((err: BusinessError) => {
      console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`);
    });
  }
}

[h2]onRelease

onRelease(callback: OnReleaseCallback): void

Caller UIAbility可使用该接口注册与Callee UIAbility连接断开通知的监听。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
callback OnReleaseCallback 是 回调函数,返回onRelease回调结果。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16200001 The caller has been released.

示例:

import { UIAbility, Caller } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
      let caller: Caller = obj;
      try {
        caller.onRelease((str) => {
          console.info(`Caller OnRelease CallBack is called ${str}`);
        });
      } catch (error) {
        console.error(`Caller.onRelease catch error, error.code: ${error.code}, error.message: ${error.message}`);
      }
    }).catch((err: BusinessError) => {
      console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`);
    });
  }
}

[h2]onRemoteStateChange10+

onRemoteStateChange(callback: OnRemoteStateChangeCallback): void

注册协同场景下跨设备组件状态变化监听通知。使用callback异步回调。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
callback OnRemoteStateChangeCallback 是 回调函数,返回onRemoteStateChange回调结果。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16200001 The caller has been released.

示例:

import { UIAbility, Caller } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class MainAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    let dstDeviceId: string = 'xxxxx';
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: dstDeviceId
    }).then((obj) => {
      let caller: Caller = obj;
      try {
        caller.onRemoteStateChange((str) => {
          console.info('Remote state changed ' + str);
        });
      } catch (error) {
        console.error(`Caller.onRemoteStateChange catch error, error.code: ${JSON.stringify(error.code)}, error.message: ${JSON.stringify(error.message)}`);
      }
    }).catch((err: BusinessError) => {
      console.error(`Caller GetCaller error, error.code: ${JSON.stringify(err.code)}, error.message: ${JSON.stringify(err.message)}`);
    });
  }
}

[h2]on('release')

on(type: 'release', callback: OnReleaseCallback): void

Caller UIAbility可使用该接口注册与Callee UIAbility连接断开通知的监听。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
type string 是 监听releaseCall事件,固定为'release'。
callback OnReleaseCallback 是 回调函数,返回on回调结果。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16200001 The caller has been released.

示例:

import { UIAbility, Caller } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    let dstDeviceId: string = 'xxxx';
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: dstDeviceId
    }).then((obj) => {
      let caller: Caller = obj;
      try {
        caller.on('release', (str) => {
          console.info(`Caller OnRelease CallBack is called ${str}`);
        });
      } catch (error) {
        console.error(`Caller.on catch error, error.code: ${error.code}, error.message: ${error.message}`);
      }
    }).catch((err: BusinessError) => {
      console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`);
    });
  }
}

[h2]off('release')

off(type: 'release', callback: OnReleaseCallback): void

取消注册Callee UIAbility断开通知的监听,与on('release')是反向操作,当前暂未支持。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
type string 是 监听releaseCall事件,固定为'release'。
callback OnReleaseCallback 是 回调函数,返回off回调结果。

错误码:

以下错误码详细介绍请参考通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

import { UIAbility, Caller, OnReleaseCallback } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
      let caller: Caller = obj;
      try {
        let onReleaseCallBack: OnReleaseCallback = (str) => {
          console.info(`Caller OnRelease CallBack is called ${str}`);
        };
        caller.on('release', onReleaseCallBack);
        caller.off('release', onReleaseCallBack);
      } catch (error) {
        console.error(`Caller.on or Caller.off catch error, error.code: ${error.code}, error.message: ${error.message}`);
      }
    }).catch((err: BusinessError) => {
      console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`);
    });
  }
}

[h2]off('release')

off(type: 'release'): void

取消注册Callee UIAbility断开通知的监听,与Caller.on('release')是反向操作,当前暂未支持。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
type string 是 监听releaseCall事件,固定为'release'。

错误码:

以下错误码详细介绍请参考通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

import { UIAbility, Caller, OnReleaseCallback } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let caller: Caller;

export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
      caller = obj;
      try {
        let onReleaseCallBack: OnReleaseCallback = (str) => {
          console.info(`Caller OnRelease CallBack is called ${str}`);
        };
        caller.on('release', onReleaseCallBack);
        caller.off('release');
      } catch (error) {
        console.error(`Caller.on or Caller.off catch error, error.code: ${error.code}, error.message: ${error.message}`);
      }
    }).catch((err: BusinessError) => {
      console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`);
    });
  }
}

Callee

系统为UIAbility创建的后台通信对象,Callee UIAbility(被调用方)可以通过Callee对象接收Caller对象发送的数据。

[h2]on

on(method: string, callback: CalleeCallback): void

通用组件服务端注册消息通知callback。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
method string 是 由Caller和Callee双方约定好的方法名,Callee方通过该字段区分消息类型。
callback CalleeCallback 是 一个rpc.MessageSequence类型入参的js通知同步回调函数, 回调函数至少要返回一个空的rpc.Parcelable数据对象, 其他视为函数执行错误。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16200004 The method has been registered.
16000050 Internal error.

示例:

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';

class MyMessageAble implements rpc.Parcelable {
  name: string
  str: string
  num: number = 1

  constructor(name: string, str: string) {
    this.name = name;
    this.str = str;
  }

  marshalling(messageSequence: rpc.MessageSequence) {
    messageSequence.writeInt(this.num);
    messageSequence.writeString(this.str);
    console.info(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`);
    return true;
  }

  unmarshalling(messageSequence: rpc.MessageSequence) {
    this.num = messageSequence.readInt();
    this.str = messageSequence.readString();
    console.info(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`);
    return true;
  }
}

let method = 'call_Function';

function funcCallBack(pdata: rpc.MessageSequence) {
  let msg = new MyMessageAble('test', '');
  pdata.readParcelable(msg);
  return new MyMessageAble('test1', 'Callee test');
}

export default class MainUIAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    console.info('Callee onCreate is called');
    try {
      this.callee.on(method, funcCallBack);
    } catch (error) {
      console.error(`Callee.on catch error, error.code: ${error.code}, error.message: ${error.message}`);
    }
  }
}

[h2]off

off(method: string): void

解除通用组件服务端注册消息通知callback。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
method string 是 已注册的通知事件字符串。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16200005 The method has not been registered.
16000050 Internal error.

示例:

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';

let method = 'call_Function';

export default class MainUIAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    console.info('Callee onCreate is called');
    try {
      this.callee.off(method);
    } catch (error) {
      console.error(`Callee.off catch error, error.code: ${error.code}, error.message: ${error.message}`);
    }
  }
}

OnReleaseCallback

[h2](msg: string)

(msg: string): void

注册通用组件服务端Stub(桩)断开监听通知的回调函数类型。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
msg string 是 用于传递释放消息。

OnRemoteStateChangeCallback10+

[h2](msg: string)10+

(msg: string): void

注册协同场景下跨设备组件状态变化监听通知的回调函数类型。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
msg string 是 用于传递释放消息。

CalleeCallback

[h2](indata: rpc.MessageSequence)

(indata: rpc.MessageSequence): rpc.Parcelable

通用组件服务端注册消息通知的回调函数类型。

系统能力:SystemCapability.Ability.AbilityRuntime.AbilityCore

参数:

参数名 类型 必填 说明
indata rpc.MessageSequence 是 发送需传递的数据。

返回值:

类型 说明
rpc.Parcelable 返回的数据对象。