1# @ohos.app.ability.AbilityConstant (Ability相关常量) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @littlejerry1--> 6<!--Designer: @ccllee1--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10AbilityConstant提供Ability相关的枚举，包括应用启动原因[LaunchReason](#launchreason)、上次退出原因[LastExitReason](#lastexitreason)、迁移结果[OnContinueResult](#oncontinueresult)等。 11 12> **说明：** 13> 14> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> 16> - 本模块接口仅可在Stage模型下使用。 17 18## 导入模块 19 20```ts 21import { AbilityConstant } from '@kit.AbilityKit'; 22``` 23 24## 常量 25 26**系统能力**：SystemCapability.Ability.AbilityBase 27 28**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 29 30| 名称 | 类型 | 值 | 说明 | 31| ---- | -----| ---- | ---------------------------------------------------------- | 32| REASON_MESSAGE_DESKTOP_SHORTCUT<sup>20+</sup> | string | "ReasonMessage_DesktopShortcut" | 通过桌面快捷方式启动。开发者如果从[LaunchParam](#launchparam)的launchReasonMessage属性中获取到该字符串，表示UIAbility是通过点击桌面快捷方式启动的。| 33 34## LaunchParam 35 36启动参数，主要包括Ability启动原因以及上次退出原因。Ability启动时由系统自动传入，开发者无需修改。 37 38**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 39 40| 名称 | 类型 | 只读 | 可选 | 说明 | 41| -------- | -------- | -------- | -------- | -------- | 42| launchReason | [LaunchReason](#launchreason)| 否 | 否 | 枚举类型，表示Ability启动原因（如故障恢复拉起、意图调用拉起、原子化服务分享拉起等），详见[LaunchReason](#launchreason)。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 43| launchReasonMessage<sup>18+</sup> | string | 否 | 是 | 表示Ability启动的详细原因。<br>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。 | 44| lastExitReason | [LastExitReason](#lastexitreason) | 否 | 否 | 枚举类型，表示Ability上次退出原因。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 45| lastExitMessage<sup>12+</sup> | string | 否 | 否 | 表示Ability上次退出的详细原因。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 46| lastExitDetailInfo<sup>18+</sup> | [LastExitDetailInfo](#lastexitdetailinfo18) | 否 | 是 | 表示Ability上次退出时的关键运行信息（含进程ID、退出时间戳、RSS内存值等）。<br>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。 | 47 48## LaunchReason 49 50Ability启动原因，该类型为枚举，可配合UIAbility的[onCreate(want, launchParam)](js-apis-app-ability-uiAbility.md#oncreate)方法根据launchParam.launchReason的不同类型执行相应操作。 51 52**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 53 54| 名称 | 值 | 说明 | 55| ----------------------------- | ---- | ------------------------------------------------------------ | 56| UNKNOWN | 0 | 未知原因。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 57| START_ABILITY | 1 | 通过[startAbility](js-apis-inner-application-uiAbilityContext.md#startability)接口启动Ability。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 58| CALL | 2 | 通过[startAbilityByCall](js-apis-inner-application-uiAbilityContext.md#startabilitybycall)接口启动Ability。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 59| CONTINUATION | 3 | 跨端迁移启动Ability。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 60| APP_RECOVERY | 4 | 设置应用恢复后，应用故障时自动恢复启动Ability。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 61| SHARE<sup>10+</sup> | 5 | 通过原子化服务分享启动Ability。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 62| AUTO_STARTUP<sup>11+</sup> | 8 | 通过设置开机自启动来启动Ability。 | 63| INSIGHT_INTENT<sup>11+</sup> | 9 | 通过洞察意图来启动Ability。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 64| PREPARE_CONTINUATION<sup>12+</sup> | 10 | 跨端迁移提前启动Ability。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。| 65| PRELOAD<sup>20+</sup> | 11 | 表明该UIAbility是通过预加载机制启动的。<br>**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。| 66 67**示例：** 68 69```ts 70import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit'; 71 72export default class MyAbility extends UIAbility { 73 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 74 if (launchParam.launchReason === AbilityConstant.LaunchReason.START_ABILITY) { 75 console.log('The ability has been started by the way of startAbility.'); 76 } 77 } 78} 79``` 80 81## LastExitReason 82 83Ability上次退出原因，该类型为枚举，可配合UIAbility的[onCreate()](js-apis-app-ability-uiAbility.md#oncreate)方法根据launchParam.lastExitReason的不同类型执行相应操作。 84 85**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 86 87| 名称 | 值 | 说明 | 88| ----------------------------- | ---- | ------------------------------------------------------------ | 89| UNKNOWN | 0 | 未知原因。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 90| ABILITY_NOT_RESPONDING<sup>(deprecated)</sup> | 1 | Ability未响应。<br>**说明:** 从API version 9开始支持，从API version 10开始废弃，请使用APP_FREEZE替代。| 91| NORMAL | 2 | 用户主动关闭，应用程序正常退出。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。<br>**说明**：当开发者直接调用[process.exit()](../apis-arkts/js-apis-process.md#processexitdeprecated)、内核kill命令等非Ability Kit提供的能力强制退出应用进程时，也会返回NORMAL。 | 92| CPP_CRASH<sup>10+</sup> | 3 | [进程崩溃](../../dfx/cppcrash-guidelines.md)导致的应用程序退出。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 93| JS_ERROR<sup>10+</sup> | 4 | 当应用存在JS语法错误并未被开发者捕获时，触发JS_ERROR故障，导致应用程序退出。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 94| APP_FREEZE<sup>10+</sup> | 5 | [应用冻屏](../../dfx/appfreeze-guidelines.md)导致的应用程序退出。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 95| PERFORMANCE_CONTROL<sup>10+</sup> | 6 | 因系统性能问题（如设备内存不足）导致的应用程序退出。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。<br>**说明**：该接口即将废弃，建议使用RESOURCE_CONTROL替代。 | 96| RESOURCE_CONTROL<sup>10+</sup> | 7 | 系统资源使用不当导致的应用程序退出。具体错误原因可以通过[LaunchParam.lastExitMessage](#launchparam)获取，可能原因如下: <br> - CPU Highload，CPU高负载。<br> - CPU_EXT Highload，快速CPU负载检测。<br> - IO Manage Control，I/O管控。<br> - App Memory Deterioration，应用内存超限劣化。<br> - Temperature Control，温度管控。<br> - Memory Pressure，整机低内存触发按优先级由低到高查杀。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。| 97| UPGRADE<sup>10+</sup> | 8 | 应用升级导致的应用程序退出。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 98| USER_REQUEST<sup>18+</sup> | 9 | 应用程序因多任务中心请求而退出。<br>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。 | 99| SIGNAL<sup>18+</sup> | 10 | 应用程序因收到系统kill指令信号而退出。<br>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。 | 100 101**示例：** 102 103```ts 104import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit'; 105 106export default class MyAbility extends UIAbility { 107 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 108 if (launchParam.lastExitReason === AbilityConstant.LastExitReason.APP_FREEZE) { 109 console.log('The ability has exit last because the ability was not responding.'); 110 } 111 if (launchParam.lastExitReason === AbilityConstant.LastExitReason.RESOURCE_CONTROL) { 112 console.log('The ability has exit last because the rss control，the lastExitReason is '+ launchParam.lastExitReason + ', the lastExitMessage is ' + launchParam.lastExitMessage); 113 } 114 } 115} 116``` 117 118## LastExitDetailInfo<sup>18+</sup> 119 120记录Ability所在进程上次退出时的关键运行信息。 121 122**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 123 124| 名称 | 类型 | 只读 | 可选 | 说明 | 125| -------- | -------- | -------- | -------- | -------- | 126| pid | number | 否 | 否 | Ability上次退出所在进程的进程号。 <br/>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。| 127| processName | string | 否 | 否 | Ability上次退出所在进程的名称。 <br/>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。| 128| uid | number | 否 | 否 | Ability上次退出所在应用的UID。 <br/>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。| 129| exitSubReason | number | 否 | 否 | Ability上次退出的子原因。 <br/>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。| 130| exitMsg | string | 否 | 否 | Ability上次退出时所在进程被kill的描述信息。 <br/>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。| 131| rss | number | 否 | 否 | Ability上次退出时所在进程实际占用内存大小，单位KB。 <br/>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。| 132| pss | number | 否 | 否 | Ability上次退出时所在进程实际使用的物理内存大小，单位KB。 <br/>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。| 133| timestamp | number | 否 | 否 | Ability上次退出时的时间戳。 <br/>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。| 134| processState<sup>20+</sup> | [appManager.ProcessState](js-apis-app-ability-appManager.md#processstate10) | 否 | 是 | Ability上次退出时的进程状态。<br/>**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 | 135 136**示例**: 137 138```ts 139import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit'; 140 141export default class MyAbility extends UIAbility { 142 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 143 if (launchParam.lastExitDetailInfo) { 144 console.log('pid: ' + launchParam.lastExitDetailInfo.pid + 145 '\n processName: ' + launchParam.lastExitDetailInfo.processName + 146 '\n uid: ' + launchParam.lastExitDetailInfo.uid + 147 '\n exitSubReason: ' + launchParam.lastExitDetailInfo.exitSubReason + 148 '\n exitMsg: ' + launchParam.lastExitDetailInfo.exitMsg + 149 '\n rss: ' + launchParam.lastExitDetailInfo.rss + 150 '\n pss: ' + launchParam.lastExitDetailInfo.pss + 151 '\n timestamp: ' + launchParam.lastExitDetailInfo.timestamp + 152 '\n processState: ' + launchParam.lastExitDetailInfo.processState 153 ); 154 } 155 } 156} 157``` 158 159## OnContinueResult 160 161Ability迁移结果，该类型为枚举，可配合UIAbility的[onContinue()](js-apis-app-ability-uiAbility.md#oncontinue)方法完成相应的返回。 162 163**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 164 165**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 166 167| 名称 | 值 | 说明 | 168| ----------------------------- | ---- | ------------------------------------------------------------ | 169| AGREE | 0 | 表示同意。 | 170| REJECT | 1 | 表示拒绝：如应用在[onContinue](js-apis-app-ability-uiAbility.md#oncontinue)中异常会导致迁移以后数据恢复时显示异常，则可以返回REJECT。 | 171| MISMATCH | 2 | 表示版本不匹配：迁移发起端应用可以在[onContinue](js-apis-app-ability-uiAbility.md#oncontinue)中获取到迁移目标端应用的版本号，进行协商后，如果版本不匹配导致无法迁移，可以返回该结果。| 172 173**示例：** 174 175```ts 176import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 177 178export default class MyAbility extends UIAbility { 179 onContinue(wantParam: Record<string, Object>) { 180 return AbilityConstant.OnContinueResult.AGREE; 181 } 182} 183``` 184 185## MemoryLevel 186 187整机可用内存级别，该类型为枚举，可配合UIAbility的[onMemoryLevel()](js-apis-app-ability-ability.md#abilityonmemorylevel)方法根据level执行不同内存级别的相应操作。 188 189**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 190 191**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 192 193| 名称 | 值 | 说明 | 194| --- | --- | --- | 195| MEMORY_LEVEL_MODERATE | 0 | 整机可用内存适中。 | 196| MEMORY_LEVEL_LOW | 1 | 整机可用内存低。 | 197| MEMORY_LEVEL_CRITICAL | 2 | 整机可用内存极低。 | 198 199> **说明：** 200> 201> 不同产品的触发条件可能存在差异。以12G内存的标准设备为例： 202> - 当整机可用内存下降至1700M~1800M时，会触发取值为0的onMemoryLevel回调，表示当前整机可用内存适中。 203> - 当整机可用内存下降至1600M~1700M时，会触发取值为1的onMemoryLevel回调，表示当前整机可用内存偏低。 204> - 当整机可用内存下降至1600M以下时，会触发取值为2的onMemoryLevel回调，表示当前整机可用内存很低。 205 206**示例：** 207 208```ts 209import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 210 211export default class MyAbility extends UIAbility { 212 onMemoryLevel(level: AbilityConstant.MemoryLevel) { 213 if (level === AbilityConstant.MemoryLevel.MEMORY_LEVEL_CRITICAL) { 214 console.log('The memory of device is critical, please release some memory.'); 215 } 216 } 217} 218``` 219 220## WindowMode<sup>12+</sup> 221 222启动UIAbility时窗口的创建模式，类型为枚举。可配合[startAbility](js-apis-inner-application-uiAbilityContext.md#startability)方法使用。 223 224**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 225 226| 名称 | 值 | 说明 | 227| --- | --- | --- | 228| WINDOW_MODE_FULLSCREEN | 1 | 全屏模式。仅在2in1和Tablet设备上生效。 | 229| WINDOW_MODE_SPLIT_PRIMARY | 100 | 支持应用内拉起Ability时设置为分屏，左侧分屏。仅在折叠屏和Tablet设备上生效。 | 230| WINDOW_MODE_SPLIT_SECONDARY | 101 | 支持应用内拉起Ability时设置为分屏，右侧分屏。仅在折叠屏和Tablet设备上生效。 | 231 232**示例：** 233 234```ts 235import { UIAbility, StartOptions, Want, AbilityConstant } from '@kit.AbilityKit'; 236import { BusinessError } from '@kit.BasicServicesKit'; 237 238let want: Want = { 239 bundleName: 'com.example.myapplication', 240 abilityName: 'EntryAbility' 241}; 242let option: StartOptions = { 243 windowMode: AbilityConstant.WindowMode.WINDOW_MODE_SPLIT_PRIMARY 244}; 245 246// 确保从上下文获取到context 247export default class MyAbility extends UIAbility { 248 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 249 this.context.startAbility(want, option).then(() => { 250 console.log('Succeed to start ability.'); 251 }).catch((error: BusinessError) => { 252 console.error(`Failed to start ability with error: ${JSON.stringify(error)}`); 253 }); 254 } 255} 256``` 257 258## OnSaveResult 259 260保存应用数据的结果，该类型为枚举。配合UIAbility的[onSaveState()](js-apis-app-ability-uiAbility.md#onsavestate)方法使用，可以实现[UIAbility备份恢复](../../application-models/ability-recover-guideline.md)。 261 262**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 263 264**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 265 266| 名称 | 值 | 说明 | 267| ----------------------------- | ---- | ------------------------------------------------------------ | 268| ALL_AGREE | 0 | 总是同意保存状态。 | 269| CONTINUATION_REJECT | 1 | 拒绝迁移保存状态。 | 270| CONTINUATION_MISMATCH | 2 | 迁移不匹配。| 271| RECOVERY_AGREE | 3 | 同意恢复保存状态。 | 272| RECOVERY_REJECT | 4 | 拒绝恢复保存状态。| 273| ALL_REJECT | 5 | 总是拒绝保存状态。| 274 275**示例：** 276 277```ts 278import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 279 280export default class MyAbility extends UIAbility { 281 onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>) { 282 return AbilityConstant.OnSaveResult.ALL_AGREE; 283 } 284} 285``` 286 287## StateType 288 289保存应用数据场景原因，该类型为枚举。配合UIAbility的[onSaveState()](js-apis-app-ability-uiAbility.md#onsavestate)方法使用，可以实现[UIAbility备份恢复](../../application-models/ability-recover-guideline.md)。 290 291**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 292 293**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 294 295| 名称 | 值 | 说明 | 296| ----------------------------- | ---- | ------------------------------------------------------------ | 297| CONTINUATION | 0 | 应用迁移场景。 | 298| APP_RECOVERY | 1 | 应用故障恢复场景。 | 299 300**示例：** 301 302```ts 303import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 304 305export default class MyAbility extends UIAbility { 306 onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>) { 307 if (reason === AbilityConstant.StateType.CONTINUATION) { 308 console.log('Save the ability data when the ability continuation.'); 309 } 310 return AbilityConstant.OnSaveResult.ALL_AGREE; 311 } 312} 313``` 314 315## ContinueState<sup>10+</sup> 316 317流转状态枚举值。用于表示当前应用任务流转的状态。可配合[UIAbilityContext](js-apis-inner-application-uiAbilityContext.md)的[setMissionContinueState](js-apis-inner-application-uiAbilityContext.md#setmissioncontinuestate10)方法进行设置。 318 319**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 320 321**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 322 323| 名称 | 值 | 说明 | 324| ------------- | --------- | ------------------------------------------------------------ | 325| ACTIVE | 0 | 指示当前应用任务流转处于激活状态。 | 326| INACTIVE | 1 | 指示当前应用任务流转处于未激活状态。 | 327 328**示例：** 329 330```ts 331import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit'; 332import { BusinessError } from '@kit.BasicServicesKit'; 333 334export default class MyAbility extends UIAbility { 335 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 336 this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE, (result: BusinessError) => { 337 console.info(`setMissionContinueState: ${JSON.stringify(result)}`); 338 }); 339 } 340} 341``` 342 343## CollaborateResult<sup>18+</sup> 344 345应用协同状态，该类型为枚举。用于多设备场景下，调用方应用拉起协同方应用时，协同方应用是否接受协同。需要配合UIAbility的[onCollaborate()](js-apis-app-ability-uiAbility.md#oncollaborate18)方法进行设置。 346 347**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 348 349| 名称 | 值 | 说明 | 350| -------- | ---- | ---------- | 351| ACCEPT | 0 | 接受协同。 | 352| REJECT | 1 | 拒绝协同。 | 353 354**示例：** 355 356```ts 357import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 358 359export default class MyAbility extends UIAbility { 360 onCollaborate(wantParam: Record<string, Object>) { 361 return AbilityConstant.CollaborateResult.ACCEPT; 362 } 363} 364``` 365 366## PrepareTermination<sup>15+</sup> 367 368应用准备关闭时返回的动作，该类型为枚举。需要配合[AbilityStage](js-apis-app-ability-abilityStage.md)的[onPrepareTermination](js-apis-app-ability-abilityStage.md#onpreparetermination15)或者[onPrepareTerminationAsync](js-apis-app-ability-abilityStage.md#onprepareterminationasync15)方法使用。 369 370**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 371 372**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 373 374| 名称 | 值 | 说明 | 375| ------------- | --------- | ----------- | 376| TERMINATE_IMMEDIATELY | 0 | 表示立即执行结束动作，默认值。| 377| CANCEL | 1 | 表示取消结束动作。| 378 379**示例：** 380 381```ts 382import { AbilityConstant, AbilityStage } from '@kit.AbilityKit'; 383 384export default class MyAbilityStage extends AbilityStage { 385 onPrepareTermination(): AbilityConstant.PrepareTermination { 386 console.info('MyAbilityStage.onPrepareTermination is called'); 387 return AbilityConstant.PrepareTermination.CANCEL; 388 } 389} 390```