Stage卡片开发指导

卡片概述

卡片是一种界面展示形式，可以将应用的重要信息或操作前置到卡片，以达到服务直达，减少体验层级的目的。

卡片常用于嵌入到其他应用（当前只支持系统应用）中作为其界面的一部分显示，并支持拉起页面，发送消息等基础的交互功能。卡片使用方负责显示卡片。

卡片的基本概念：

• 卡片提供方：提供卡片显示内容原子化服务，控制卡片的显示内容、控件布局以及控件点击事件。
• 卡片使用方：显示卡片内容的宿主应用，控制卡片在宿主中展示的位置。
• 卡片管理服务：用于管理系统中所添加卡片的常驻代理服务，包括卡片对象的管理与使用，以及卡片周期性刷新等。

说明： 卡片使用方和提供方不要求常驻运行，在需要添加/删除/请求更新卡片时，卡片管理服务会拉起卡片提供方获取卡片信息。

开发者仅需作为卡片提供方进行卡片内容的开发，卡片使用方和卡片管理服务由系统自动处理。

卡片提供方控制卡片实际显示的内容、控件布局以及点击事件。

场景介绍

Stage卡片开发，即基于Stage模型的卡片提供方开发，主要涉及如下功能逻辑：

• 卡片生命周期回调函数FormExtension开发。
• 创建卡片数据FormBindingData对象。
• 通过FormProvider更新卡片。
• 卡片页面开发。

接口说明

FormExtension类拥有如下API接口，具体的API介绍详见接口文档。

表1 FormExtension API接口功能介绍

FormExtension类还拥有成员context，为FormExtensionContext类，具体的API介绍详见接口文档。

表2 FormExtensionContext API接口功能介绍

FormProvider类具体的API介绍详见接口文档。

表3 FormProvider API接口功能介绍

开发步骤

创建卡片FormExtension

创建Stage模型的卡片，需实现FormExtension生命周期接口。具体示例代码如下：

1. 导入相关模块

   import FormExtension from '@ohos.application.FormExtension'
   import formBindingData from '@ohos.application.formBindingData'
   import formInfo from '@ohos.application.formInfo'
   import formProvider from '@ohos.application.formProvider'
   

2. 实现FormExtension生命周期接口

   export default class FormAbility extends FormExtension {
       onCreate(want) {
           console.log('FormAbility onCreate');
           // 由开发人员自行实现，将创建的卡片信息持久化，以便在下次获取/更新该卡片实例时进行使用
           let obj = {
               "title": "titleOnCreate",
               "detail": "detailOnCreate"
           };
           let formData = formBindingData.createFormBindingData(obj);
           return formData;
       }
       onCastToNormal(formId) {
           // 使用方将临时卡片转换为常态卡片触发，提供方需要做相应的处理
           console.log('FormAbility onCastToNormal');
       }
       onUpdate(formId) {
           // 若卡片支持定时更新/定点更新/卡片使用方主动请求更新功能，则提供方需要重写该方法以支持数据更新
           console.log('FormAbility onUpdate');
           let obj = {
               "title": "titleOnUpdate",
               "detail": "detailOnUpdate"
           };
           let formData = formBindingData.createFormBindingData(obj);
           formProvider.updateForm(formId, formData).catch((error) => {
               console.log('FormAbility updateForm, error:' + JSON.stringify(error));
           });
       }
       onVisibilityChange(newStatus) {
           // 使用方发起可见或者不可见通知触发，提供方需要做相应的处理
           console.log('FormAbility onVisibilityChange');
       }
       onEvent(formId, message) {
           // 若卡片支持触发事件，则需要重写该方法并实现对事件的触发
           console.log('FormAbility onEvent');
       }
       onDestroy(formId) {
           // 删除卡片实例数据
           console.log('FormAbility onDestroy');
       }
       onConfigurationUpdated(config) {
           console.log('FormAbility onConfigurationUpdated, config:' + JSON.stringify(config));
       }
   }
   

配置卡片配置文件

• 卡片需要在应用配置文件module.json5中的extensionAbilities标签下，配置ExtensionAbility相关信息，内部字段结构说明：

对于FormExtensionAbility来说，需要填写metadata元信息标签，其中键名称为固定字符串"ohos.extension.form"，资源为卡片的具体配置信息的索引。

配置示例如下：

 ```json

"extensionAbilities": [{ "name": "FormAbility", "srcEnty": "./ets/FormAbility/FormAbility.ts", "label": "$string:form_FormAbility_label", "description": "$string:form_FormAbility_desc", "type": "form", "metadata": [{ "name": "ohos.extension.form", "resource": "$profile:form_config" }] }] ```

• 卡片的具体配置信息。在上述 FormExtensionAbility 的元信息中，指定了的卡片具体配置信息的资源索引，如使用 $profile:form_config 指定开发视图的 resources/base/profile/ 目录下的 form_config.json 作为卡片profile配置文件。

  内部字段结构说明：

 配置示例如下：

 ```json

{ "forms": [{ "name": "widget", "description": "This is a service widget.", "src": "./js/widget/pages/index/index", "window": { "autoDesignWidth": true, "designWidth": 720 }, "isDefault": true, "colorMode": "auto", "supportDimensions": ["22"], "defaultDimension": "22", "updateEnabled": true, "scheduledUpdateTime": "10:30", "formConfigAbility": "ability://ohos.samples.FormApplication.MainAbility" }] } ```

卡片信息的持久化

因大部分卡片提供方都不是常驻服务，只有在需要使用时才会被拉起获取卡片信息，且卡片管理服务支持对卡片进行多实例管理，卡片ID对应实例ID，因此若卡片提供方支持对卡片数据进行配置，则需要对卡片的业务数据按照卡片ID进行持久化管理，以便在后续获取、更新以及拉起时能获取到正确的卡片业务数据。

       onCreate(want) {
           console.log('FormAbility onCreate');

           let formId = want.parameters["ohos.extra.param.key.form_identity"];
           let formName = want.parameters["ohos.extra.param.key.form_name"];
           let tempFlag = want.parameters["ohos.extra.param.key.form_temporary"];
           // 由开发人员自行实现，将创建的卡片信息持久化，以便在下次获取/更新该卡片实例时进行使用
           // storeFormInfo 接口未在此处实现，具体实现请参考：相关实例 章节中的 FormExtAbility Stage模型卡片 实例
           storeFormInfo(formId, formName, tempFlag, want);

           let obj = {
               "title": "titleOnCreate",
               "detail": "detailOnCreate"
           };
           let formData = formBindingData.createFormBindingData(obj);
           return formData;
       }

且需要适配onDestroy卡片删除通知接口，在其中实现卡片实例数据的删除。

       onDestroy(formId) {
           console.log('FormAbility onDestroy');

           // 由开发人员自行实现，删除之前持久化的卡片实例数据
           // deleteFormInfo 接口未在此处实现，具体实现请参考：相关实例 章节中的 FormExtAbility Stage模型卡片 实例
           deleteFormInfo(formId);
       }

具体的持久化方法可以参考轻量级数据存储开发指导。

需要注意的是，卡片使用方在请求卡片时传递给提供方应用的Want数据中存在临时标记字段，表示此次请求的卡片是否为临时卡片：

• 常态卡片：卡片使用方会持久化的卡片；

• 临时卡片：卡片使用方不会持久化的卡片；

由于临时卡片的数据具有非持久化的特殊性，某些场景比如卡片服务框架死亡重启，此时临时卡片数据在卡片管理服务中已经删除，且对应的卡片ID不会通知到提供方，所以卡片提供方需要自己负责清理长时间未删除的临时卡片数据。同时对应的卡片使用方可能会将之前请求的临时卡片转换为常态卡片。如果转换成功，卡片提供方也需要对对应的临时卡片ID进行处理，把卡片提供方记录的临时卡片数据转换为常态卡片数据，防止提供方在清理长时间未删除的临时卡片时，把已经转换为常态卡片的临时卡片信息删除，导致卡片信息丢失。

卡片数据交互

当卡片应用需要更新数据时（如触发了定时更新或定点更新），卡片应用获取最新数据，并调用updateForm接口更新卡片。示例如下：

onUpdate(formId) {
    // 若卡片支持定时更新/定点更新/卡片使用方主动请求更新功能，则提供方需要重写该方法以支持数据更新
    console.log('FormAbility onUpdate');
    let obj = {
        "title": "titleOnUpdate",
        "detail": "detailOnUpdate"
    };
    let formData = formBindingData.createFormBindingData(obj);
    // 调用updateForm接口去更新对应的卡片，仅更新入参中携带的数据信息，其他信息保持不变
    formProvider.updateForm(formId, formData).catch((error) => {
        console.log('FormAbility updateForm, error:' + JSON.stringify(error));
    });
}

开发卡片页面

开发者可以使用hml+css+json开发JS卡片页面：

说明： 当前仅支持JS扩展的类Web开发范式来实现卡片的UI页面。

• hml:

<div class="container">
    <stack>
        <div class="container-img">
            <image src="/common/widget.png" class="bg-img"></image>
        </div>
        <div class="container-inner">
            <text class="title">{{title}}</text>
            <text class="detail_text" onclick="routerEvent">{{detail}}</text>
        </div>
    </stack>
</div>

• css:

.container {
 flex-direction: column;
 justify-content: center;
 align-items: center;
}

.bg-img {
 flex-shrink: 0;
 height: 100%;
}

.container-inner {
 flex-direction: column;
 justify-content: flex-end;
 align-items: flex-start;
 height: 100%;
 width: 100%;
 padding: 12px;
}

.title {
 font-size: 19px;
 font-weight: bold;
 color: white;
 text-overflow: ellipsis;
 max-lines: 1;
}

.detail_text {
 font-size: 16px;
 color: white;
 opacity: 0.66;
 text-overflow: ellipsis;
 max-lines: 1;
 margin-top: 6px;
}

• json:

{
  "data": {
    "title": "TitleDefault",
    "detail": "TextDefault"
  },
  "actions": {
    "routerEvent": {
      "action": "router",
      "abilityName": "MainAbility",
      "params": {
        "message": "add detail"
      }
    }
  }
}

最终可以得到如下卡片：

开发卡片事件

卡片支持为组件设置action，包括router事件和message事件，其中router事件用于Ability跳转，message事件用于卡片开发人员自定义点击事件。关键步骤说明如下：

1. 在hml中为组件设置onclick属性，其值对应到json文件的actions字段中。
2. 若设置router事件，则
   • action属性值为"router"；
   • abilityName为跳转目标的Ability名，如目前DevEco创建的Stage模型的MainAbility默认名为MainAbility；
   • params为跳转目标Ability的自定义参数，可以按需填写。其值可以在目标Ability启动时的want中的parameters里获取。如Stage模型MainAbility的onCreate生命周期里的入参want的parameters字段下获取到配置的参数；
3. 若设置message事件，则
   • action属性值为"message"；
   • params为message事件的用户自定义参数，可以按需填写。其值可以在卡片生命周期函数onEvent中的message里获取；

示例如下：

• hml:

<div class="container">
    <stack>
        <div class="container-img">
            <image src="/common/widget.png" class="bg-img"></image>
        </div>
        <div class="container-inner">
            <text class="title" onclick="routerEvent">{{title}}</text>
            <text class="detail_text" onclick="messageEvent">{{detail}}</text>
        </div>
    </stack>
</div>

• json:

{
  "data": {
    "title": "TitleDefault",
    "detail": "TextDefault"
  },
  "actions": {
    "routerEvent": {
      "action": "router",
      "abilityName": "MainAbility",
      "params": {
        "message": "add detail"
      }
    },
    "messageEvent": {
      "action": "message",
      "params": {
        "message": "add detail"
      }
    }
  }
}

相关实例

针对Stage模型卡片提供方的开发，有以下相关实例可供参考：

• FormExtAbility：Stage模型卡片（ArkTS）（API9）