互动卡片开发实践

概述

场景动效类型互动卡片（本文后续简称为互动卡片），是一种支持动态动画和实时交互的卡片形态，区别于动态卡片，互动卡片能够在用户触发时展示流畅的帧动画、3D变换效果，并支持陀螺仪等传感器交互，还能将动效渲染区域扩展到卡片自身边界之外，营造“破框”效果。互动卡片包含非激活态和激活态两种状态：非激活态下，卡片与普通卡片行为一致，由FormExtensionAbility管理；激活态下，由LiveFormExtensionAbility加载动态UI页面展示动画和交互内容。详细信息请参考场景动效类型互动卡片开发指导

场景介绍

本项目包含四种互动卡片，分别对应不同的交互场景和体验效果：

睡眠卡片

触发方式

点击。

体验及交互

点击卡片触发憨憨起床动画，三叶草旋转，气球飘出卡片边界，憨憨从睡姿变为醒姿，动画结束后卡片状态更新为“按时起床”。

效果预览

快递卡片

触发方式

点击、摇一摇。

体验及交互

点击卡片或摇动设备激活卡片后，倾斜手机驱动憨憨沿路线跑动——向右倾斜憨憨向右移动并缩小（近→远透视），向左倾斜憨憨向左移动并放大（远→近透视）。

效果预览

运动卡片

触发方式

点击。

体验及交互

• 开始运动：点击“开始运动”触发憨憨拉伸运动动画。
• 结束运动：点击“结束运动”触发庆祝动画并显示卡路里计数，从0逐步增长到300kcal。

效果预览

• 开始运动

  

• 结束运动

  

音乐卡片

触发方式

点击。

体验及交互

• 播放：播放音乐时憨憨跳舞、专辑封面旋转。
• 切歌：切歌时憨憨出框取专辑进行替换。

效果预览

• 播放：

  

• 切歌：

  

整体方案

互动卡片以动态卡片作为入口，通过form_config.json中的sceneAnimationParams标签配置关联LiveFormExtensionAbility。用户触发激活（点击或摇一摇）后，系统根据sceneAnimationParams.abilityName激活对应的LiveFormExtensionAbility实例，调用onLiveFormCreate方法加载动态UI页面，展示动画和交互内容。详见互动卡片实现原理。

动态卡片创建

动态卡片是互动卡片的入口，开发者需按照创建ArkTS卡片流程进行创建。

互动卡片配置及触发方法

互动卡片的配置和触发涉及三个关键部分：

1. 在module.json5的extensionAbilities中声明LiveFormExtensionAbility，type设置为liveForm，声明为互动卡片。

{
  "name": "DeliveryLiveCardAbility",
  "srcEntry": "./ets/livecardability/DeliveryLiveCardAbility.ets",
  "type": "liveForm",
  "exported": false
},

2. 在form_config.json中通过sceneAnimationParams.abilityName指定触发动画时激活的LiveFormExtensionAbility名称。

3. 触发方式

互动卡片支持两种触发方式：

• 点击触发：用户点击卡片时，卡片通过postCardAction(MESSAGE)发送requestOverflow消息到FormExtensionAbility，FormExtensionAbility调用formProvider.requestOverflow激活互动卡片。
• 摇一摇触发：在form_config.json中通过sceneAnimationParams.triggerTypes增加"shake"字段，系统自动监听摇动事件并激活LiveFormExtensionAbility。

摇一摇触发流程：

通信方式

动态卡片、应用和互动卡片三者之间存在多种通信方式，不同通信方向使用不同的API和数据传递机制：

各卡片使用的通信方式如下：

睡眠卡片：使用ROUTER跳转页面（CloverPage、SleepReport）、MESSAGE触发出框动画、formProvider.updateForm回推isSleep状态到动态卡片。LocalStorage在互动卡片内部传递formRect、borderRadius等初始数据。

音乐卡片：使用CALL调用播控方法（播放/暂停/切歌/收藏）、ROUTER跳转页面（MusicPage）、MESSAGE触发出框动画并携带triggerAction上下文。应用与互动卡片间通过RDB存储歌曲列表和收藏状态、文件存储触发动作上下文和当前歌曲，实现跨进程数据同步。应用在切歌、播放状态改变时，通过formProvider.updateForm将歌曲信息同步到所有动态卡片中。

运动卡片：使用CALL调用运动控制方法（开始/结束/重置）、ROUTER跳转页面（ExercisePage）、MESSAGE触发出框动画。应用与互动卡片间通过文件存储持久化运动状态，互动卡片通过formProvider.updateForm回推卡路里数据到动态卡片。

快递卡片：使用ROUTER跳转页面（DeliveryPage）、MESSAGE触发出框动画。互动卡片内部通过LocalStorage传递formRect、borderRadius等初始数据。

快递卡片详细开发步骤

场景描述

以快递卡片为例，演示完整的互动卡片开发流程。快递卡片需要实现点击触发出框动画、陀螺仪交互驱动憨憨移动、摇一摇激活等功能。效果如下：

实现原理

快递卡片涉及动态卡片UI、LiveFormExtensionAbility、数据通信、陀螺仪交互四个核心模块。动态卡片展示背景和憨憨；LiveFormExtensionAbility加载动画UI并传递卡片尺寸信息；通信机制实现点击触发动画和页面跳转；陀螺仪交互实现憨憨实时响应设备倾斜。

开发步骤

配置卡片和Ability

1. 配置form_config.json：定义快递卡片基本信息、配置LiveFormExtensionAbility和摇一摇支持。
   收起

   自动换行

   深色代码主题

   复制

   {
     "name": "DeliveryCard",
     "displayName": "$string:DeliveryCard",
     "description": "$string:DeliveryCardDes",
     "src": "./ets/widget/pages/DeliveryCard.ets",
     "uiSyntax": "arkts",
     "defaultDimension": "2*2",
     "supportDimensions": [
       "2*2"
     ],
     "sceneAnimationParams": {
       "abilityName": "DeliveryLiveCardAbility",
       "triggerTypes": ["shake"]
     }
   }

2. 声明DeliveryLiveCardAbility：在module.json5中声明LiveFormExtensionAbility扩展能力。
   收起

   自动换行

   深色代码主题

   复制

   {
     "name": "DeliveryLiveCardAbility",
     "srcEntry": "./ets/livecardability/DeliveryLiveCardAbility.ets",
     "type": "liveForm",
     "exported": false
   },

   module.json5

实现动态卡片UI

let storageUpdateCall = new LocalStorage();

@Entry(storageUpdateCall)
@Component
struct DeliveryCard {
  @LocalStorageProp('formWidth') formWidth: number = 0;
  @LocalStorageProp('formHeight') formHeight: number = 0;

  build() {
    RelativeContainer() {
      Image($rawfile('delivery/background.png'))
        .objectFit(ImageFit.Contain)
        .width('100%')
        .height('100%')
        .aspectRatio(1);
      Image($rawfile('delivery/fuzzball.png'))
        .objectFit(ImageFit.Contain)
        .width('145%')
        .height('145%')
        .offset({
          x: `-22.5%`,
          y: `-22.5%`
        });
      Row() {
        Image($r('app.media.delivery_box'))
          .objectFit(ImageFit.Contain)
          .width(this.formWidth * 0.2 + 'px')
          .height(this.formHeight * 0.2 + 'px');
        Text($r('app.string.delivery_in_transit'))
          .fontSize('21.55f')
          .fontColor('#646166')
          .fontFamily('HarmonyOS Scans SC');
      }
      .justifyContent(FlexAlign.SpaceEvenly)
      .alignRules({
        middle: { anchor: '__container__', align: HorizontalAlign.Center },
        bottom: { anchor: '__container__', align: VerticalAlign.Bottom }
      })
      .backgroundColor('#BFFFFFFF')
      .width(this.formWidth * 0.830 + 'px')
      .height(this.formHeight * 0.205 + 'px')
      .margin({ bottom: this.formHeight * 0.082 + 'px' })
      .borderRadius('9%');
      Stack()
        .width('100%')
        .height('30%')
        .onClick(() => {
          ActionUtils.jumpAppPage(this, 'DeliveryPage');
        })
        .alignRules({
          left: { anchor: '__container__', align: HorizontalAlign.Start },
          bottom: { anchor: '__container__', align: VerticalAlign.Bottom }
        });
    }
    .width('100%')
    .height('100%')
    .onClick(() => {
      ActionUtils.requestOverFlow(this, LiveCardScale.DELIVERY_WIDTH,
        LiveCardScale.DELIVERY_HEIGHT, LIVE_CARD_DURATION);
    });
  }
}

实现LiveFormExtensionAbility

onLiveFormCreate(liveFormInfo: LiveFormInfo, session: UIExtensionContentSession): void {
  let storage: LocalStorage = new LocalStorage();
  storage.setOrCreate('context', this.context);
  storage.setOrCreate('session', session);
  let formId: string = liveFormInfo.formId;
  storage.setOrCreate('formId', formId);

  let borderRadius: number = liveFormInfo.borderRadius;
  storage.setOrCreate('borderRadius', borderRadius);

  let formRect: formInfo.Rect = liveFormInfo.rect;
  storage.setOrCreate('formRect', formRect);

  try {
    session.loadContent('livecardability/pages/DeliveryLiveCard', storage);
  } catch (error) {
    Logger.error(TAG, `session.loadContent error`);
  }
}

实现互动卡片激活流程

1. 处理message类型消息：在FormExtensionAbility的onFormEvent中接收requestOverflow消息，激活互动卡片动画。
   收起

   自动换行

   深色代码主题

   复制

   onFormEvent(formId: string, message: string): void {
     const params: Record<string, Object> = JSON.parse(message);
     if (!params || typeof params.message !== 'string') {
       return;
     }
     let shortMessage: string = params.message as string;
   
     if (shortMessage === 'requestOverflow') {
       let widthRatio: number = Math.min(Math.max(params.widthRatio as number || 0, 0), LIVE_CARD_RATIO);
       let heightRatio: number = Math.min(Math.max(params.heightRatio as number || 0, 0), LIVE_CARD_RATIO);
       let duration: number = Math.min(Math.max(params.duration as number || 0, 0), LIVE_CARD_DURATION);
       // ...
   
       this.requestOverflow(formId, widthRatio, heightRatio, duration);
       return;
     } else if (shortMessage === 'updateRequestOverflowState') {
       updateRequestOverFlowState(formId, true);
     }
   }

   EntryFormAbility.ets
2. 请求激活互动卡片。
   收起

   自动换行

   深色代码主题

   复制

   private async requestOverflow(formId: string, widthRatio: number, heightRatio: number,
     duration: number): Promise<void> {
     try {
       let formRect: formInfo.Rect = await formProvider.getFormRect(formId);
       // ...
       if (formRect.width <= 0 || formRect.height <= 0) {
         return;
       }
       let cardWidth = formRect.width * widthRatio;
       let cardHeight = formRect.height * heightRatio;
       let leftOffset = (formRect.width - cardWidth) / 2;
       let topOffset = (formRect.height - cardHeight) / 2;
   
       formProvider.requestOverflow(formId, {
         area: {
           left: leftOffset,
           top: topOffset,
           width: cardWidth,
           height: cardHeight
         },
         duration: duration
       }).catch((e: BusinessError) => {
         Logger.error(TAG, `requestOverflow error, code: ${e.code} message: ${e.message}`);
       }).finally(() => {
         const timeoutId = setTimeout(() => {
           updateRequestOverFlowState(formId, false);
           clearTimeout(timeoutId);
         }, 500)
       });
     } catch (error) {
       // ...
     }
   }

   EntryFormAbility.ets