1# @ohos.app.ability.CompletionHandler (拉起应用结果的操作类) 2<!--Kit: Ability Kit--> 3<!--Subsystem: Ability--> 4<!--Owner: @littlejerry1; @yangxuguang-huawei; @Luobniz21--> 5<!--Designer: @ccllee1--> 6<!--Tester: @lixueqing513--> 7<!--Adviser: @huipeizi--> 8 9CompletionHandler作为[StartOptions](js-apis-app-ability-startOptions.md)的可选参数，用于处理拉起应用请求的结果。 10 11 12> **说明：** 13> 14> - 本模块首批接口从API version 20 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> 16> - 本模块接口仅可在Stage模型下使用。 17 18 19## 约束限制 20 21当前支持使用该模块的接口包括： 22- [startAbility](js-apis-inner-application-uiAbilityContext.md#startability-2) 23- [startAbilityForResult](js-apis-inner-application-uiAbilityContext.md#startabilityforresult-2) 24 25<!--Del--> 26- [startAbilityForResultWithAccount](js-apis-inner-application-uiAbilityContext-sys.md#startabilityforresultwithaccount-2) 27- [startAbilityWithAccount](js-apis-inner-application-uiAbilityContext-sys.md#startabilitywithaccount-2) 28- [startRecentAbility](js-apis-inner-application-uiAbilityContext-sys.md#startrecentability-2) 29- [startAbilityAsCaller](js-apis-inner-application-uiAbilityContext-sys.md#startabilityascaller10-2) 30<!--DelEnd--> 31 32## 导入模块 33 34```ts 35import { CompletionHandler } from '@kit.AbilityKit'; 36``` 37 38## CompletionHandler 39 40CompletionHandler提供了[onRequestSuccess](#onrequestsuccess)和[onRequestFailure](#onrequestfailure)两个回调函数，分别用来处理拉起应用成功和失败时的结果。 41 42### onRequestSuccess 43 44onRequestSuccess(elementName: ElementName, message: string): void 45 46拉起应用成功时的回调函数。 47 48**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 49 50**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 51 52**参数：** 53 54| 参数名 | 类型 | 必填 | 说明 | 55| -------- | -------- | -------- | -------- | 56| elementName | [ElementName](js-apis-bundleManager-elementName.md) | 是 | ElementName信息用于标识被拉起应用。通常，ElementName仅包含abilityName和bundleName。moduleName和deviceId信息是否存在取决于调用方是否传入。shortName和uri为空。| 57| message | string | 是 | 成功拉起应用时的信息。该信息采用JSON格式，样式如下：<br>{<br> "errMsg": "Succeeded."<br>}</br> | 58 59**示例：** 60 61参见[CompletionHandler使用](#completionhandler使用)。 62 63### onRequestFailure 64 65onRequestFailure(elementName: ElementName, message: string): void 66 67拉起应用失败时的回调函数。 68 69**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 70 71**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 72 73**参数：** 74 75| 参数名 | 类型 | 必填 | 说明 | 76| -------- | -------- | -------- | -------- | 77| elementName | [ElementName](js-apis-bundleManager-elementName.md) | 是 | ElementName信息用于标识被拉起应用。<br>- 通常，ElementName仅包含abilityName和bundleName。moduleName和deviceId信息是否存在取决于调用方是否传入。shortName和uri为空。<br>- 隐式启动失败时，无法获取ElementName信息。 | 78| message | string | 是 | 拉起应用失败时的信息。该信息采用JSON格式，样式如下：<br>{<br> "errMsg": "xxx"<br>}<br>其中，"xxx"的取值说明如下：<br>Failed to call \<api-name\>：表示调用接口出错。其中，\<api-name\>为具体的接口名，比如startAbility。<br>User refused redirection：表示用户关闭了应用跳转弹框。<br>User closed the implicit startup picker：表示用户关闭了隐式启动时的应用选择弹框。<br>User closed the app clone picker：表示用户关闭了分身应用选择弹框。<br>Free installation failed：表示免安装失败。</br> | 79 80**示例：** 81 82参见[CompletionHandler使用](#completionhandler使用)。 83 84### CompletionHandler使用 85 86 ```ts 87 import { UIAbility, Want, StartOptions, CompletionHandler, bundleManager } from '@kit.AbilityKit'; 88 import { BusinessError } from '@kit.BasicServicesKit'; 89 90 export default class EntryAbility extends UIAbility { 91 onForeground() { 92 let want: Want = { 93 deviceId: '', 94 bundleName: 'com.example.myapplication', 95 abilityName: 'EntryAbility' 96 }; 97 98 let completionHandler: CompletionHandler = { 99 onRequestSuccess: (elementName: bundleManager.ElementName, message: string): void => { 100 console.info(`${elementName.bundleName}-${elementName.moduleName}-${elementName.abilityName} start succeeded: ${message}`); 101 }, 102 onRequestFailure: (elementName: bundleManager.ElementName, message: string): void => { 103 console.error(`${elementName.bundleName}-${elementName.moduleName}-${elementName.abilityName} start failed: ${message}`); 104 } 105 }; 106 107 let options: StartOptions = { 108 completionHandler: completionHandler 109 }; 110 111 try { 112 this.context.startAbility(want, options, (err: BusinessError) => { 113 if (err.code) { 114 // 处理业务逻辑错误 115 console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); 116 return; 117 } 118 // 执行正常业务 119 console.info('startAbility succeed'); 120 }); 121 } catch (err) { 122 // 处理入参错误异常 123 let code = (err as BusinessError).code; 124 let message = (err as BusinessError).message; 125 console.error(`startAbility failed, code is ${code}, message is ${message}`); 126 } 127 } 128 } 129 ``` 130