推送卡片刷新消息

场景介绍

如今衣食住行娱乐影音应用占据了大多数人的手机，一部手机可以满足日常大多需求，但对需要经常查看或进行简单操作的应用来说，总需要用户点开应用体验较繁琐。针对此种场景，HarmonyOS提供了Form Kit（卡片开发服务），您可以将应用的重要信息或操作前置到卡片，以达到服务直达、减少体验层级的目的。

面对需要实时更新信息的应用卡片，Push Kit向开发者提供了卡片刷新服务。应用通过集成Push Kit后获取Push Token，基于Push Kit的系统级通道，便可以在合适场景向用户即时推送卡片内容，从而提升用户的感知度和活跃度。

约束与限制

推送卡片刷新消息支持Phone、Tablet、PC/2in1设备。并且从6.1.0(23)版本开始，新增支持Wearable、TV设备。

频控规则

调测阶段，每个项目每日全网最多可推送1000条测试消息。发送测试消息需设置testMessage为true。

正式发布阶段，单设备单应用下每日推送消息总条数受设备消息频控限制，系统会根据现网使用场景和流量进行管控，不合理的使用场景系统会进行频控。

单张服务卡片刷新消息数量受应用是否上架影响：

已上架：单设备单应用下单张卡片每日限制发送2条消息。
未上架：单设备单应用下单张卡片每日限制发送5条消息。

不论是测试消息还是正式消息，卡片刷新消息单次发送仅能携带一个Token。

开发步骤

开发卡片

推送卡片刷新消息前，您需先完成本地卡片的开发。

参见创建一个ArkTS卡片，完成本地服务卡片的创建。

在项目模块级别下的src/main/resources/base/profile/form_config.json中配置dataProxyEnabled字段为true，开启卡片代理刷新功能。

{
  "forms": [
    {
      "name": "widget",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "colorMode": "auto",
      "isDefault": true,
      "updateEnabled": true,
      "updateDuration": 1,
      "scheduledUpdateTime": "10:30",
      "defaultDimension": "2*2",
      "supportDimensions": ["2*2"],
      "dataProxyEnabled": true
    }
  ]
}

在卡片生命周期管理文件（下以EntryFormAbility为例）的onAddForm()回调中获取formId，定义需要在卡片页面文件（下以WidgetCard为例）中和通过Push Kit要刷新的字段，如下以text_key和image_key为例。

// 文件路径: src/main/ets/entryformability/EntryFormAbility.ets
import { formBindingData, formInfo, FormExtensionAbility } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';

export default class EntryFormAbility extends FormExtensionAbility {
  onAddForm(want: Want): formBindingData.FormBindingData {
    // 获取formId
    const formId = want.parameters![formInfo.FormParam.IDENTITY_KEY] as string;

    // 定义需要在WidgetCard中刷新的字段
    class CreateFormData {
      formId: string = '';
      text_key: string = '';
      image_key: string = '';
    }

    const obj: CreateFormData = {
      formId: formId,
      text_key: '默认文本',
      image_key: ''
    }
    const bindingData: formBindingData.FormBindingData = formBindingData.createFormBindingData(obj);

    // 定义需要通过Push Kit代理刷新的字段，每个key均需要在上面bindingData中定义
    const text_key: formBindingData.ProxyData = {
      key: 'text_key',
      subscriberId: formId
    };
    const image_key: formBindingData.ProxyData = {
      key: 'image_key',
      subscriberId: formId
    };
    bindingData.proxies = [text_key, image_key];
    return bindingData;
  }
}

卡片页面文件（下以src/main/ets/widget/pages/WidgetCard.ets为例）中，创建LocalStorage变量并与@Entry装饰器绑定，使用@LocalStorageProp装饰器创建key-value的变量。

本文创建了formId、text和image三个变量，对应的key为formId、text_key和image_key，需要注意的是卡片页面布局中image对应的组件是Image图片组件，图片组件传递的变量必须以memory:// 开头。

// 文件路径: src/main/ets/widget/pages/WidgetCard.ets
// 定义页面级的UI状态存储LocalStorage
const storage = new LocalStorage();

// 绑定
@Entry(storage)
@Component
struct WidgetCard {
  @LocalStorageProp('formId') formId: string = '';
  @LocalStorageProp('text_key') text: string = '';
  @LocalStorageProp('image_key') image: string = '';

  build() {
    Flex({ direction: FlexDirection.Column }) {
      Row() {
        Text() {
          // Span是Text组件的子组件，用于显示行内文本
          Span('formID:')
          Span(this.formId)
        }
        .fontSize(10)
      }

      Row() {
        Text() {
          Span('文本:')
          Span(this.text)
        }
        .fontSize(10)
      }

      Row() {
        if (this.image) {
          Image('memory://' + this.image).height(80)
        }
      }
    }
    .padding(10)
    .onClick(() => {
      postCardAction(this, {
        action: 'router',
        abilityName: 'MainAbility', // 请配置为应用实际的abilityName
      });
    })
  }
}