卡片拉起应用UIAbility到后台（call事件）
==========================

许多应用希望借助卡片的能力，实现和应用在前台时相同的功能。例如音乐卡片，卡片上提供播放、暂停等按钮，点击不同按钮将触发音乐应用的不同功能，进而提高用户的体验。在卡片中使用[postCardAction](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-postcardaction#postcardaction-1)接口的call能力，能够将卡片提供方应用的指定的UIAbility拉到后台。同时，call能力提供了调用应用指定方法、传递数据的功能，使应用在后台运行时可以通过卡片上的按钮执行不同的功能。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/98/v3/afw5e-xsSlWT7Jiy6AVZGQ/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073342Z&HW-CC-Expire=86400&HW-CC-Sign=31C6718D011DF6DE1E360E9622D8F4AAC012C2DD155BC1F0364C19F4919C82C7)

本文主要介绍动态卡片的事件开发。对于静态卡片，请参见[FormLink](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-formlink)。

#### 开发步骤

1.  创建动态卡片
    
    新建一个名为WidgetEventCall的ArkTs动态卡片。
    
2.  页面布局代码实现
    
    在卡片页面中布局两个按钮，点击按钮A或按钮B，会调用postCardAction向指定UIAbility发送call事件，在call事件内定义了需要调用的方法。按钮A和按钮B分别对应调用funA、funB方法，其中funA携带了formID参数，funB携带了formID和num参数，开发过程中请根据实际需要传参。postCardAction中的method参数为必填参数，用于标识需要调用的方法名称，与步骤3中UIAbility监听的方法一致，其他参数为非必填。
    
    //src/main/ets/widgeteventcall/pages/WidgetEventCallCard.ets
    let storageEventCall = new LocalStorage();
    
    @Entry(storageEventCall)
    @Component
    struct WidgetEventCallCard {
      @LocalStorageProp('formId') formId: string = '12400633174999288';
      // $r('app.string.ButtonA\_label')和$r('app.string.ButtonB\_label')需要替换为开发者所需的资源文件
      private funA: Resource = $r('app.string.ButtonA\_label');
      private funB: Resource = $r('app.string.ButtonB\_label');
    
      build() {
        RelativeContainer() {
          Button(this.funA)
            .id('funA\_\_')
            .fontSize(14)
            .fontWeight(FontWeight.Bold)
            .alignRules({
              center: { anchor: '\_\_container\_\_', align: VerticalAlign.Center },
              middle: { anchor: '\_\_container\_\_', align: HorizontalAlign.Center }
            })
            .onClick(() => {
              postCardAction(this, {
                action: 'call',
                // 只能跳转到当前应用下的UIAbility，与module.json5中定义保持一致
                abilityName: 'WidgetEventCallEntryAbility',
                params: {
                  formId: this.formId,
                  // 需要调用的方法名称
                  method: 'funA'
                }
              });
            })
    
          Button(this.funB)
            .id('funB\_\_')
            .fontSize(14)
            .fontWeight(FontWeight.Bold)
            .margin({ top: 10 })
            .alignRules({
              top: { anchor: 'funA\_\_', align: VerticalAlign.Bottom },
              middle: { anchor: '\_\_container\_\_', align: HorizontalAlign.Center }
            })
            .onClick(() => {
              postCardAction(this, {
                action: 'call',
                abilityName: 'WidgetEventCallEntryAbility',
                params: {
                  formId: this.formId,
                  // 需要调用的方法名称
                  method: 'funB',
                  num: 1
                }
              });
            })
        }
        .height('100%')
        .width('100%')
      }
    }
    
3.  创建指定的UIAbility
    
    在UIAbility中监听call事件，根据监听到的method参数中的方法名称调用对应方法，并通过[rpc.Parcelable](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-rpc#parcelable9)获取参数。UIAbility中监听的方法与步骤2中调用的方法需保持一致。
    
    //src/main/ets/WidgetEventCallEntryAbility/WidgetEventCallEntryAbility.ets
    import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
    import { BusinessError } from '@kit.BasicServicesKit';
    import { rpc } from '@kit.IPCKit';
    import { hilog } from '@kit.PerformanceAnalysisKit';
    
    const TAG: string = 'WidgetEventCallEntryAbility';
    const DOMAIN\_NUMBER: number = 0xFF00;
    const CONST\_NUMBER\_1: number = 1;
    const CONST\_NUMBER\_2: number = 2;
    
    // ipc通信返回类型的实现，用于数据序列化和反序列化
    class MyParcelable implements rpc.Parcelable {
      private num: number;
      private str: string;
    
      constructor(num: number, str: string) {
        this.num = num;
        this.str = str;
      }
    
      marshalling(messageSequence: rpc.MessageSequence): boolean {
        messageSequence.writeInt(this.num);
        messageSequence.writeString(this.str);
        return true;
      }
    
      unmarshalling(messageSequence: rpc.MessageSequence): boolean {
        this.num = messageSequence.readInt();
        this.str = messageSequence.readString();
        return true;
      }
    }
    
    export default class WidgetEventCallEntryAbility extends UIAbility {
      // 如果UIAbility启动，在收到call事件后会触发onCreate生命周期回调
      onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        try {
          // 监听call事件所需的方法并调用
          this.callee.on('funA', (data: rpc.MessageSequence) => {
            // 获取call事件中传递的所有参数
            hilog.info(DOMAIN\_NUMBER, TAG, \`FunACall param:  ${JSON.stringify(data.readString())}\`);
            return new MyParcelable(CONST\_NUMBER\_1, 'aaa');
          });
          this.callee.on('funB', (data: rpc.MessageSequence) => {
            // 获取call事件中传递的所有参数
            hilog.info(DOMAIN\_NUMBER, TAG, \`FunBCall param:  ${JSON.stringify(data.readString())}\`);
            return new MyParcelable(CONST\_NUMBER\_2, 'bbb');
          });
        } catch (err) {
          hilog.error(DOMAIN\_NUMBER, TAG, \`Failed to register callee on. Cause: ${JSON.stringify(err as BusinessError)}\`);
        }
      }
    
      // 进程退出时，解除监听
      onDestroy(): void | Promise<void> {
        try {
          this.callee.off('funA');
          this.callee.off('funB');
        } catch (err) {
          hilog.error(DOMAIN\_NUMBER, TAG, \`Failed to register callee off. Cause: ${JSON.stringify(err as BusinessError)}\`);
        }
      }
    }
    
4.  配置后台运行权限
    
    call事件存在约束限制，卡片提供方应用需要在module.json5下添加后台运行权限([ohos.permission.KEEP\_BACKGROUND\_RUNNING](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/permissions-for-all#ohospermissionkeep_background_running))。
    
    //src/main/module.json5
    "requestPermissions": \[
      {
        "name": "ohos.permission.KEEP\_BACKGROUND\_RUNNING",
      },
    // ···
      // \[EndExclude jscard\_extension\_ability\]
    \]
    
5.  配置指定的UIAbility
    
    在module.json5的abilities数组内添加WidgetEventCallEntryAbility对应的配置信息。
    
    //src/main/module.json5
    "abilities": \[
    // ···
      {
        "name": "WidgetEventCallEntryAbility",
        "srcEntry": "./ets/widgeteventcallentryability/WidgetEventCallEntryAbility.ets",
        "description": "$string:WidgetEventCallEntryAbility\_desc",
        "icon": "$media:icon",
        "label": "$string:WidgetEventCallEntryAbility\_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start\_window\_background"
      }
    \],