开启掘金成长之旅！这是我参与「掘金日新计划 · 12 月更文挑战」的第12天，点击查看活动详情

Stage卡片开发指导

卡片概述

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

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

卡片的基本概念：

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

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

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

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

创建卡片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'
   javascript
   

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));
       }
   }
   javascript
   

配置卡片配置文件

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

  属性名称	含义	数据类型	是否可缺省
  name	表示ExtensionAbility的名字，该标签不可缺省。	字符串	否
  srcEntrance	表示ExtensionAbility所对应的生命周期代码的路径，该标签不可缺省。	字符串	否
  description	表示ExtensionAbility的描述。可以是表示描述内容的字符串，也可以是对描述内容的资源索引以支持多语言。	字符串	可缺省，缺省值为空。
  icon	表示ExtensionAbility的图标资源文件的索引。	字符串	可缺省，缺省值为空。
  label	表示ExtensionAbility的标签信息，即ExtensionAbility对外显示的文字描述信息。取值可以是描述性内容，也可以是标识label的资源索引。	字符串	可缺省，缺省值为空。
  type	表示ExtensionAbility的类型，对于当前FormExtensionAbility的开发，需要将其配置为form。	字符串	否
  permissions	表示其他应用的Ability调用此Ability时需要申请的权限。	字符串数组	可缺省，缺省值为空。
  metadata	表示ExtensionAbility的元信息，用于描述ExtensionAbility的配置信息。	对象	可缺省，缺省值为空

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

  配置示例如下：

  "extensionAbilities": [{
   "name": "FormAbility",
   "srcEntrance": "./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"
   }]
  }]