harmony 鸿蒙@ohos.app.ability.CompletionHandler (拉端结果操作类)

2025-06-12
浏览 (4)

@ohos.app.ability.CompletionHandler (拉端结果操作类)

CompletionHandler作为StartOptions的可选参数，用于处理拉端请求的结果。

说明：

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

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

约束限制

当前支持使用该模块的接口包括： - startAbility - startAbilityForResult

导入模块

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

CompletionHandler

CompletionHandler提供了onRequestSuccess和onRequestFailure两个回调函数，分别用来处理拉端成功和失败时的结果。

onRequestSuccess

onRequestSuccess(elementName: ElementName, message: string): void

拉端成功时的回调函数。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
elementName	ElementName	是	被拉起应用的ElementName信息。
message	string	是	成功拉起应用时的信息。该信息采用JSON格式，样式如下： { “errMsg”: “Succeeded.” }

示例：

参见CompletionHandler使用。

onRequestFailure

onRequestFailure(elementName: ElementName, message: string): void

拉端失败时的回调函数。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
elementName	ElementName	是	被拉起应用的ElementName信息。
message	string	是	拉起应用失败时的信息。该信息采用JSON格式，样式如下： { “errMsg”: “xxx” } 其中，”xxx”的取值说明如下： Failed to call <api-name>：表示调用接口出错。其中，<api-name>为具体的接口名，比如startAbility。 User refused redirection：表示用户关闭了应用跳转弹框。 User closed the implicit startup picker：表示用户关闭了隐式启动时的应用选择弹框。 User closed the app clone picker：表示用户关闭了分身应用选择弹框。 Free installation failed：表示免安装失败。

示例：

参见CompletionHandler使用。

CompletionHandler使用

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

  export default class EntryAbility extends UIAbility {
    onForeground() {
      let want: Want = {
        deviceId: '',
        bundleName: 'com.example.myapplication',
        abilityName: 'EntryAbility'
      };

      let completionHandler: CompletionHandler = {
        onRequestSuccess: (elementName: bundleManager.ElementName, message: string): void => {
          console.log(`${elementName.bundleName}-${elementName.moduleName}-${elementName.abilityName} start succeeded: ${message}`);
        },
        onRequestFailure: (elementName: bundleManager.ElementName, message: string): void => {
          console.log(`${elementName.bundleName}-${elementName.moduleName}-${elementName.abilityName} start failed: ${message}`);
        }
      };

      let options: StartOptions = {
        completionHandler: completionHandler
      };

      try {
        this.context.startAbility(want, options, (err: BusinessError) => {
          if (err.code) {
            // 处理业务逻辑错误
            console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
            return;
          }
          // 执行正常业务
          console.info('startAbility succeed');
        });
      } catch (err) {
        // 处理入参错误异常
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.error(`startAbility failed, code is ${code}, message is ${message}`);
      }
    }
  }