From 6e0b57e68b3559a256058bd658c97483c9afc1a4 Mon Sep 17 00:00:00 2001 From: yangzk Date: Wed, 23 Mar 2022 18:22:01 +0800 Subject: [PATCH] add form extension ability docs Signed-off-by: yangzk Change-Id: I96d8d2dba9649f71bbb0d3d4062a36e56f38da41 --- zh-cn/application-dev/ability/Readme-CN.md | 3 +- .../application-dev/ability/fa-formability.md | 222 +++++++++-------- .../ability/stage-formextension.md | 224 ++++++++++-------- 3 files changed, 240 insertions(+), 209 deletions(-) diff --git a/zh-cn/application-dev/ability/Readme-CN.md b/zh-cn/application-dev/ability/Readme-CN.md index 98d1c3389a..ea1302c808 100644 --- a/zh-cn/application-dev/ability/Readme-CN.md +++ b/zh-cn/application-dev/ability/Readme-CN.md @@ -6,12 +6,13 @@ - [PageAbility开发指导](fa-pageability.md) - [ServiceAbility开发指导](fa-serviceability.md) - [DataAbility开发指导](fa-dataability.md) - - [FormAbility开发指导](fa-formability.md) + - [FA卡片开发指导](fa-formability.md) - Stage模型 - [Ability开发指导](stage-ability.md) - [ServiceExtensionAbility开发指导](stage-serviceextension.md) - [跨端迁移开发指导](stage-ability-continuation.md) - [Call调用开发指导](stage-call.md) + - [Stage卡片开发指导](stage-formextension.md) - 其他 - [Ability助手使用指导](ability-assistant-guidelines.md) - [测试框架使用指导](ability-delegator.md) \ No newline at end of file diff --git a/zh-cn/application-dev/ability/fa-formability.md b/zh-cn/application-dev/ability/fa-formability.md index 5e3c36e505..38402d2404 100644 --- a/zh-cn/application-dev/ability/fa-formability.md +++ b/zh-cn/application-dev/ability/fa-formability.md @@ -1,4 +1,4 @@ -# FormAbility开发指导 +# FA卡片开发指导 ## 卡片概述 卡片是一种界面展示形式，可以将应用的重要信息或操作前置到卡片，以达到服务直达，减少体验层级的目的。 @@ -20,50 +20,59 @@ 卡片提供方控制卡片实际显示的内容、控件布局以及点击事件。 -## FormAbility基本概念 -FormAbility是基于Form模板的Ability（以下简称“Form”）。卡片提供方开发者可以通过FormAbility控制其自身卡片实际显示的内容及点击事件等。 +## 场景介绍 -FormExtensionAbility中相关生命周期说明如下： +FA卡片开发，即基于[FA模型](fa-brief.md)的卡片提供方开发，主要涉及如下功能逻辑： -- onCreate +- 卡片生命周期回调函数FormAbility开发。 +- 创建卡片数据FormBindingData对象。 +- 通过FormProvider更新卡片。 +- 卡片页面开发。 - 卡片提供方接收创建卡片通知接口。 +## 接口说明 -- onCastToNormal +卡片生命周期回调函数FormAbility的接口如下： - 卡片提供方接收临时卡片转常态卡片通知接口。 +**表1** FormAbility API接口功能介绍 -- onUpdate +| 接口名 | 描述 | +| :----------------------------------------------------------- | :------------------------------------------- | +| onCreate(want: Want): formBindingData.FormBindingData | 卡片提供方接收创建卡片的通知接口。 | +| onCastToNormal(formId: string): void | 卡片提供方接收临时卡片转常态卡片的通知接口。 | +| onUpdate(formId: string): void | 卡片提供方接收更新卡片的通知接口。 | +| onVisibilityChange(newStatus: { [key: string]: number }): void | 卡片提供方接收修改可见性的通知接口。 | +| onEvent(formId: string, message: string): void | 卡片提供方接收处理卡片事件的通知接口。 | +| onDestroy(formId: string): void | 卡片提供方接收销毁卡片的通知接口。 | +| onConfigurationUpdated(config: Configuration): void; | 当系统配置更新时调用。 | - 卡片提供方接收更新卡片通知接口。 +FormProvider类具体的API详见[接口文档](../reference/apis/js-apis-formprovider.md)。 -- onDestroy +**表2** FormProvider API接口功能介绍 - 卡片提供方接收删除卡片通知接口。 +| 接口名 | 描述 | +| :----------------------------------------------------------- | :------------------------------------------------ | +| setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void; | 设置指定卡片的下一次更新时间。 | +| setFormNextRefreshTime(formId: string, minute: number): Promise<void>; | 设置指定卡片的下一次更新时间，以promise方式返回。 | +| updateForm(formId: string, formBindingData: FormBindingData, callback: AsyncCallback<void>): void; | 更新指定的卡片。 | +| updateForm(formId: string, formBindingData: FormBindingData): Promise<void>; | 更新指定的卡片，以promise方式返回。 | -- onEvent +## 开发步骤 - 卡片提供方接收删除卡片通知接口。 +### 创建FormAbility -- onVisibilityChange +创建FA模型的卡片，需实现FormAbility生命周期接口。具体示例代码如下： - 卡片提供方接收卡片可见性通知接口。 - -- onAcquireFormState - - 卡片提供方接收查询卡片状态通知接口。默认返回卡片初始状态。 - -## 创建Form - -1. 创建FormAbility - - 创建Form的代码示例如下： +1. 导入相关模块 ```javascript import formBindingData from '@ohos.application.formBindingData' import formInfo from '@ohos.application.formInfo' import formProvider from '@ohos.application.formProvider' + ``` + +2. 实现FormAbility生命周期接口 + ```javascript export default { onCreate(want) { console.log('FormAbility onCreate'); @@ -110,82 +119,87 @@ FormExtensionAbility中相关生命周期说明如下： } ``` -2. Form配置 - Form需要在应用配置文件config.json中进行配置。 - - - js模块，用于对应卡片的js相关资源，内部字段结构说明： - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | ------------------------ | -| name | 表示JS Component的名字。该标签不可缺省，默认值为default。 | 字符串 | 否 | -| pages | 表示JS Component的页面用于列举JS Component中每个页面的路由信息[页面路径+页面名称]。该标签不可缺省，取值为数组，数组第一个元素代表JS FA首页。 | 数组 | 否 | -| window | 用于定义与显示窗口相关的配置。该标签仅适用于手机、平板、智慧屏、车机、智能穿戴。 | 对象 | 可缺省 | -| type | 表示JS应用的类型。取值范围如下：
normal：标识该JS Component为应用实例。
form：标识该JS Component为卡片实例。 | 字符串 | 可缺省，缺省值为“normal” | -| mode | 定义JS组件的开发模式。 | 对象 | 可缺省，缺省值为空 | +### 配置卡片配置文件 + +Form需要在应用配置文件config.json中进行配置。 + +- js模块，用于对应卡片的js相关资源，内部字段结构说明： + + | 属性名称 | 含义 | 数据类型 | 是否可缺省 | + | -------- | ------------------------------------------------------------ | -------- | ------------------------ | + | name | 表示JS Component的名字。该标签不可缺省，默认值为default。 | 字符串 | 否 | + | pages | 表示JS Component的页面用于列举JS Component中每个页面的路由信息[页面路径+页面名称]。该标签不可缺省，取值为数组，数组第一个元素代表JS FA首页。 | 数组 | 否 | + | window | 用于定义与显示窗口相关的配置。该标签仅适用于手机、平板、智慧屏、车机、智能穿戴。 | 对象 | 可缺省 | + | type | 表示JS应用的类型。取值范围如下：
normal：标识该JS Component为应用实例。
form：标识该JS Component为卡片实例。 | 字符串 | 可缺省，缺省值为“normal” | + | mode | 定义JS组件的开发模式。 | 对象 | 可缺省，缺省值为空 | + + 配置示例如下： + + ```json + "js": [{ + "name": "widget", + "pages": ["pages/index/index"], + "window": { + "designWidth": 720, + "autoDesignWidth": true + }, + "type": "form" + }] + ``` + +- abilities模块，用于对应卡片的FormAbility，内部字段结构说明： + + | 属性名称 | 含义 | 数据类型 | 是否可缺省 | + | ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ | + | name | 表示卡片的类名。字符串最大长度为127字节。 | 字符串 | 否 | + | description | 表示卡片的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 | + | isDefault | 表示该卡片是否为默认卡片，每个Ability有且只有一个默认卡片。
true：默认卡片。
false：非默认卡片。 | 布尔值 | 否 | + | type | 表示卡片的类型。取值范围如下：
Java：Java卡片。
JS：JS卡片。 | 字符串 | 否 | + | colorMode | 表示卡片的主题样式，取值范围如下：
auto：自适应。
dark：深色主题。
light：浅色主题。 | 字符串 | 可缺省，缺省值为“auto”。 | + | supportDimensions | 表示卡片支持的外观规格，取值范围：
1 * 2：表示1行2列的二宫格。
2 * 2：表示2行2列的四宫格。
2 * 4：表示2行4列的八宫格。
4 * 4：表示4行4列的十六宫格。 | 字符串数组 | 否 | + | defaultDimension | 表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 否 | + | landscapeLayouts | 表示卡片外观规格对应的横向布局文件，与supportDimensions中的规格一一对应。仅当卡片类型为Java卡片时，需要配置该标签。 | 字符串数组 | 否 | + | portraitLayouts | 表示卡片外观规格对应的竖向布局文件，与supportDimensions中的规格一一对应。仅当卡片类型为Java卡片时，需要配置该标签。 | 字符串数组 | 否 | + | updateEnabled | 表示卡片是否支持周期性刷新，取值范围：
true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，优先选择定时刷新。
false：表示不支持周期性刷新。 | 布尔类型 | 否 | + | scheduledUpdateTime | 表示卡片的定点刷新的时刻，采用24小时制，精确到分钟。 | 字符串 | 可缺省，缺省值为“0:0”。 | + | updateDuration | 表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数。
当取值为0时，表示该参数不生效。
当取值为正整数N时，表示刷新周期为30*N分钟。 | 数值 | 可缺省，缺省值为“0”。 | + | formConfigAbility | 表示用于调整卡片的设施或活动的名称。 | 字符串 | 可缺省，缺省值为空。 | + | formVisibleNotify | 标识是否允许卡片使用卡片可见性通知 | 字符串 | 可缺省，缺省值为空。 | + | jsComponentName | 表示JS卡片的Component名称。字符串最大长度为127字节。仅当卡片类型为JS卡片时，需要配置该标签。 | 字符串 | 否 | + | metaData | 表示卡片的自定义信息，包含customizeData数组标签。 | 对象 | 可缺省，缺省值为空。 | + | customizeData | 表示自定义的卡片信息。 | 对象数组 | 可缺省，缺省值为空。 | + + 配置示例如下： + + ```json + "abilities": [{ + "name": "FormAbility", + "description": "This is a FormAbility", + "formsEnabled": true, + "icon": "$media:icon", + "label": "$string:form_FormAbility_label", + "srcPath": "FormAbility", + "type": "service", + "forms": [{ + "colorMode": "auto", + "defaultDimension": "2*2", + "description": "This is a service widget.", + "formVisibleNotify": true, + "isDefault": true, + "jsComponentName": "widget", + "name": "widget", + "scheduledUpdateTime": "10:30", + "supportDimensions": ["2*2"], + "type": "JS", + "updateDuration": 1, + "updateEnabled": true + }] + }] + ``` + + +### 卡片信息的持久化 - 配置示例如下： - ```json - "js": [{ - "name": "widget", - "pages": ["pages/index/index"], - "window": { - "designWidth": 720, - "autoDesignWidth": true - }, - "type": "form" - }] - ``` - - - abilities模块，用于对应卡片的FormAbility，内部字段结构说明： - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ | -| name | 表示卡片的类名。字符串最大长度为127字节。 | 字符串 | 否 | -| description | 表示卡片的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 | -| isDefault | 表示该卡片是否为默认卡片，每个Ability有且只有一个默认卡片。
true：默认卡片。
false：非默认卡片。 | 布尔值 | 否 | -| type | 表示卡片的类型。取值范围如下：
Java：Java卡片。
JS：JS卡片。 | 字符串 | 否 | -| colorMode | 表示卡片的主题样式，取值范围如下：
auto：自适应。
dark：深色主题。
light：浅色主题。 | 字符串 | 可缺省，缺省值为“auto”。 | -| supportDimensions | 表示卡片支持的外观规格，取值范围：
1 * 2：表示1行2列的二宫格。
2 * 2：表示2行2列的四宫格。
2 * 4：表示2行4列的八宫格。
4 * 4：表示4行4列的十六宫格。 | 字符串数组 | 否 | -| defaultDimension | 表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 否 | -| landscapeLayouts | 表示卡片外观规格对应的横向布局文件，与supportDimensions中的规格一一对应。仅当卡片类型为Java卡片时，需要配置该标签。 | 字符串数组 | 否 | -| portraitLayouts | 表示卡片外观规格对应的竖向布局文件，与supportDimensions中的规格一一对应。仅当卡片类型为Java卡片时，需要配置该标签。 | 字符串数组 | 否 | -| updateEnabled | 表示卡片是否支持周期性刷新，取值范围：
true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，优先选择定时刷新。
false：表示不支持周期性刷新。 | 布尔类型 | 否 | -| scheduledUpdateTime | 表示卡片的定点刷新的时刻，采用24小时制，精确到分钟。 | 字符串 | 可缺省，缺省值为“0:0”。 | -| updateDuration | 表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数。
当取值为0时，表示该参数不生效。
当取值为正整数N时，表示刷新周期为30*N分钟。 | 数值 | 可缺省，缺省值为“0”。 | -| formConfigAbility | 表示用于调整卡片的设施或活动的名称。 | 字符串 | 可缺省，缺省值为空。 | -| formVisibleNotify | 标识是否允许卡片使用卡片可见性通知 | 字符串 | 可缺省，缺省值为空。 | -| jsComponentName | 表示JS卡片的Component名称。字符串最大长度为127字节。仅当卡片类型为JS卡片时，需要配置该标签。 | 字符串 | 否 | -| metaData | 表示卡片的自定义信息，包含customizeData数组标签。 | 对象 | 可缺省，缺省值为空。 | -| customizeData | 表示自定义的卡片信息。 | 对象数组 | 可缺省，缺省值为空。 | - - 配置示例如下： - ```json - "abilities": [{ - "name": "FormAbility", - "description": "This is a FormAbility", - "formsEnabled": true, - "icon": "$media:icon", - "label": "$string:form_FormAbility_label", - "srcPath": "FormAbility", - "type": "service", - "forms": [{ - "colorMode": "auto", - "defaultDimension": "2*2", - "description": "This is a service widget.", - "formVisibleNotify": true, - "isDefault": true, - "jsComponentName": "widget", - "name": "widget", - "scheduledUpdateTime": "10:30", - "supportDimensions": ["2*2"], - "type": "JS", - "updateDuration": 1, - "updateEnabled": true - }] - }] - ``` - -## 卡片信息的持久化 因大部分卡片提供方都不是常驻服务，只有在需要使用时才会被拉起获取卡片信息，且卡片管理服务支持对卡片进行多实例管理，卡片ID对应实例ID，因此若卡片提供方支持对卡片数据进行配置，则需要对卡片的业务数据按照卡片ID进行持久化管理，以便在后续获取、更新以及拉起时能获取到正确的卡片业务数据。 ```javascript @@ -227,10 +241,10 @@ FormExtensionAbility中相关生命周期说明如下： 由于临时卡片的数据具有非持久化的特殊性，某些场景比如卡片服务框架死亡重启，此时临时卡片数据在卡片管理服务中已经删除，且对应的卡片ID不会通知到提供方，所以卡片提供方需要自己负责清理长时间未删除的临时卡片数据。同时对应的卡片使用方可能会将之前请求的临时卡片转换为常态卡片。如果转换成功，卡片提供方也需要对对应的临时卡片ID进行处理，把卡片提供方记录的临时卡片数据转换为常态卡片数据，防止提供方在清理长时间未删除的临时卡片时，把已经转换为常态卡片的临时卡片信息删除，导致卡片信息丢失。 -## 开发卡片页面 +### 开发卡片页面 开发者可以使用hml+css+json开发JS卡片页面： -> ![icon-note.gif](public_sys-resources\icon-note.gif) **说明：** +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > 当前仅支持JS扩展的类Web开发范式来实现卡片的UI页面。 - hml: @@ -310,4 +324,4 @@ FormExtensionAbility中相关生命周期说明如下： 最终可以得到，如下卡片： -![fa-form-example](figures/fa-form-example.png) +![fa-form-example](figures/fa-form-example.png) \ No newline at end of file diff --git a/zh-cn/application-dev/ability/stage-formextension.md b/zh-cn/application-dev/ability/stage-formextension.md index f97e5b4334..71c2482cf9 100644 --- a/zh-cn/application-dev/ability/stage-formextension.md +++ b/zh-cn/application-dev/ability/stage-formextension.md @@ -1,4 +1,4 @@ -# FormExtensionAbility开发指导 +# Stage卡片开发指导 ## 卡片概述 @@ -22,52 +22,69 @@ 卡片提供方控制卡片实际显示的内容、控件布局以及点击事件。 -## FormExtensionAbility基本概念 +## 场景介绍 -FormExtensionAbility是基于Form模板的ExtensionAbility（以下简称“Form”）。ExtensionAbility是stage模型中新增的扩展组件基类，详见[Stage模型综述](stage-brief.md)。卡片提供方开发者可以通过FormExtensionAbility控制其自身卡片实际显示的内容及点击事件等。 +Stage卡片开发，即基于[Stage模型综述](stage-brief.md)的卡片提供方开发，主要涉及如下功能逻辑： -FormExtensionAbility中相关生命周期说明如下： +- 卡片生命周期回调函数FormExtension开发。 +- 创建卡片数据FormBindingData对象。 +- 通过FormProvider更新卡片。 +- 卡片页面开发。 -- onCreate +## 接口说明 - 卡片提供方接收创建卡片通知接口。 +FormExtension功能如下：FormExtension类，拥有context属性，具体的API详见[接口文档](../reference/apis/js-apis-formextension.md)。 -- onCastToNormal +**表1** FormExtension API接口功能介绍 - 卡片提供方接收临时卡片转常态卡片通知接口。 +| 接口名 | 描述 | +| :----------------------------------------------------------- | :------------------------------------------- | +| onCreate(want: Want): formBindingData.FormBindingData | 卡片提供方接收创建卡片的通知接口。 | +| onCastToNormal(formId: string): void | 卡片提供方接收临时卡片转常态卡片的通知接口。 | +| onUpdate(formId: string): void | 卡片提供方接收更新卡片的通知接口。 | +| onVisibilityChange(newStatus: { [key: string]: number }): void | 卡片提供方接收修改可见性的通知接口。 | +| onEvent(formId: string, message: string): void | 卡片提供方接收处理卡片事件的通知接口。 | +| onDestroy(formId: string): void | 卡片提供方接收销毁卡片的通知接口。 | +| onConfigurationUpdated(config: Configuration): void; | 当系统配置更新时调用。 | -- onUpdate +FormExtension类拥有context属性，context属性为FormExtensionContext类，具体的API详见[接口文档](../reference/apis/js-apis-formextensioncontext.md)。 - 卡片提供方接收更新卡片通知接口。 +**表2** FormExtensionContext API接口功能介绍 -- onDestroy +| 接口名 | 描述 | +| :----------------------------------------------------------- | :------------------------ | +| updateForm(formId: string, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\): void | 回调形式主动更新卡片。 | +| updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise\ | Promise形式主动更新卡片。 | - 卡片提供方接收删除卡片通知接口。 +FormProvider类具体的API详见[接口文档](../reference/apis/js-apis-formprovider.md)。 -- onEvent +**表3** FormProvider API接口功能介绍 - 卡片提供方接收删除卡片通知接口。 +| 接口名 | 描述 | +| :----------------------------------------------------------- | :------------------------------------------------ | +| setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void; | 设置指定卡片的下一次更新时间。 | +| setFormNextRefreshTime(formId: string, minute: number): Promise<void>; | 设置指定卡片的下一次更新时间，以promise方式返回。 | +| updateForm(formId: string, formBindingData: FormBindingData, callback: AsyncCallback<void>): void; | 更新指定的卡片。 | +| updateForm(formId: string, formBindingData: FormBindingData): Promise<void>; | 更新指定的卡片，以promise方式返回。 | -- onVisibilityChange +## 开发步骤 - 卡片提供方接收卡片可见性通知接口。 +### 创建卡片FormExtension -- onAcquireFormState +创建Stage模型的卡片，需实现FormExtension生命周期接口。具体示例代码如下： - 卡片提供方接收查询卡片状态通知接口。默认返回卡片初始状态。 - -## 创建Form - -1. 创建FormExtensionAbility - - 开发者在创建的TS文件中自定义类继承FormExtensionAbility，重写基类回调函数，代码示例如下： +1. 导入相关模块 ```javascript 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生命周期接口 + ```javascript export default class FormAbility extends FormExtension { onCreate(want) { console.log('FormAbility onCreate'); @@ -114,85 +131,86 @@ FormExtensionAbility中相关生命周期说明如下： } ``` -2. Form配置 - - Form需要在应用配置文件module.json中进行配置。 - - - extensionAbility模块，内部字段结构说明： - - | 属性名称 | 含义 | 数据类型 | 是否可缺省 | - | ----------- | ------------------------------------------------------------ | ---------- | -------------------- | - | name | 表示extensionAbility的名字。该标签不可缺省。 | 字符串 | 否 | - | srcEntrance | 表示extensionAbility所对应的JS的代码路径。该标签不可缺省。 | 字符串 | 否 | - | description | 表示extensionAbility的描述。可以是表示描述内容的字符串，也可以是对描述内容的资源索引以支持多语言。 | 字符串 | 可缺省，缺省值为空。 | - | icon | 表示extensionAbility的图标资源文件的索引。 | 字符串 | 可缺省，缺省值为空。 | - | label | 表示extensionAbility的标签信息，即extensionAbility对外显示的文字描述信息。取值可以是描述性内容，也可以是标识label的资源索引。 | 字符串 | 可缺省，缺省值为空。 | - | type | 表示extensionAbility的类型。取值form、service等 | 字符串 | 否 | - | permissions | 表示其他应用的Ability调用此Ability时需要申请的权限。通常采用反向域名格式，取值可以是系统预定义的权限，也可以是开发者自定义的权限。 | 字符串数组 | 可缺省，缺省值为空。 | - | metadata | 表示extensionAbility的元信息。用于描述extensionAbility的配置信息。 | 对象 | 可缺省，缺省值为空 | - - 对于FormExtensionAbility来说，type需要配置为form，并且需要填写metadata元信息，用于配置卡片的具体信息。 - +### 配置卡片配置文件 + +Form需要在应用配置文件module.json中进行配置。 + +- extensionAbility模块，内部字段结构说明： + + | 属性名称 | 含义 | 数据类型 | 是否可缺省 | + | ----------- | ------------------------------------------------------------ | ---------- | -------------------- | + | name | 表示extensionAbility的名字。该标签不可缺省。 | 字符串 | 否 | + | srcEntrance | 表示extensionAbility所对应的JS的代码路径。该标签不可缺省。 | 字符串 | 否 | + | description | 表示extensionAbility的描述。可以是表示描述内容的字符串，也可以是对描述内容的资源索引以支持多语言。 | 字符串 | 可缺省，缺省值为空。 | + | icon | 表示extensionAbility的图标资源文件的索引。 | 字符串 | 可缺省，缺省值为空。 | + | label | 表示extensionAbility的标签信息，即extensionAbility对外显示的文字描述信息。取值可以是描述性内容，也可以是标识label的资源索引。 | 字符串 | 可缺省，缺省值为空。 | + | type | 表示extensionAbility的类型。取值form、service等 | 字符串 | 否 | + | permissions | 表示其他应用的Ability调用此Ability时需要申请的权限。通常采用反向域名格式，取值可以是系统预定义的权限，也可以是开发者自定义的权限。 | 字符串数组 | 可缺省，缺省值为空。 | + | metadata | 表示extensionAbility的元信息。用于描述extensionAbility的配置信息。 | 对象 | 可缺省，缺省值为空 | + + 对于FormExtensionAbility来说，type需要配置为form，并且需要填写metadata元信息，用于配置卡片的具体信息。 + + 配置示例如下： + + ```json + "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" + }] + }] + ``` + +- 卡片profile模块，卡片metadata元信息，内部字段结构说明： + + | 属性名称 | 含义 | 数据类型 | 是否可缺省 | + | ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ | + | name | 表示卡片的类名。字符串最大长度为127字节。 | 字符串 | 否 | + | description | 表示卡片的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 | + | src | 表示卡片对应的UI代码的完整路径。 | 字符串 | 否 | + | window | | | | + | isDefault | 表示该卡片是否为默认卡片，每个Ability有且只有一个默认卡片。
true：默认卡片。
false：非默认卡片。 | 布尔值 | 否 | + | colorMode | 表示卡片的主题样式，取值范围如下：
auto：自适应。
dark：深色主题。
light：浅色主题。 | 字符串 | 可缺省，缺省值为“auto”。 | + | supportDimensions | 表示卡片支持的外观规格，取值范围：
1 * 2：表示1行2列的二宫格。
2 * 2：表示2行2列的四宫格。
2 * 4：表示2行4列的八宫格。
4 * 4：表示4行4列的十六宫格。 | 字符串数组 | 否 | + | defaultDimension | 表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 否 | + | updateEnabled | 表示卡片是否支持周期性刷新，取值范围：
true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，优先选择定时刷新。
false：表示不支持周期性刷新。 | 布尔类型 | 否 | + | scheduledUpdateTime | 表示卡片的定点刷新的时刻，采用24小时制，精确到分钟。 | 字符串 | 可缺省，缺省值为“0:0”。 | + | updateDuration | 表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数。
当取值为0时，表示该参数不生效。
当取值为正整数N时，表示刷新周期为30*N分钟。 | 数值 | 可缺省，缺省值为“0”。 | + | formConfigAbility | 表示用于调整卡片的设施或活动的名称。 | 字符串 | 可缺省，缺省值为空。 | + | formVisibleNotify | 标识是否允许卡片使用卡片可见性通知 | 字符串 | 可缺省，缺省值为空。 | + | metaData | 表示卡片的自定义信息，包含customizeData数组标签。 | 对象 | 可缺省，缺省值为空。 | + 配置示例如下： - - ```json - "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" - }] - }] - ``` - - - 卡片profile模块，卡片metadata元信息，内部字段结构说明： - - | 属性名称 | 含义 | 数据类型 | 是否可缺省 | - | ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ | - | name | 表示卡片的类名。字符串最大长度为127字节。 | 字符串 | 否 | - | description | 表示卡片的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 | - | src | 表示卡片对应的UI代码的完整路径。 | 字符串 | 否 | - | window | | | | - | isDefault | 表示该卡片是否为默认卡片，每个Ability有且只有一个默认卡片。
true：默认卡片。
false：非默认卡片。 | 布尔值 | 否 | - | colorMode | 表示卡片的主题样式，取值范围如下：
auto：自适应。
dark：深色主题。
light：浅色主题。 | 字符串 | 可缺省，缺省值为“auto”。 | - | supportDimensions | 表示卡片支持的外观规格，取值范围：
1 * 2：表示1行2列的二宫格。
2 * 2：表示2行2列的四宫格。
2 * 4：表示2行4列的八宫格。
4 * 4：表示4行4列的十六宫格。 | 字符串数组 | 否 | - | defaultDimension | 表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 否 | - | updateEnabled | 表示卡片是否支持周期性刷新，取值范围：
true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，优先选择定时刷新。
false：表示不支持周期性刷新。 | 布尔类型 | 否 | - | scheduledUpdateTime | 表示卡片的定点刷新的时刻，采用24小时制，精确到分钟。 | 字符串 | 可缺省，缺省值为“0:0”。 | - | updateDuration | 表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数。
当取值为0时，表示该参数不生效。
当取值为正整数N时，表示刷新周期为30*N分钟。 | 数值 | 可缺省，缺省值为“0”。 | - | formConfigAbility | 表示用于调整卡片的设施或活动的名称。 | 字符串 | 可缺省，缺省值为空。 | - | formVisibleNotify | 标识是否允许卡片使用卡片可见性通知 | 字符串 | 可缺省，缺省值为空。 | - | metaData | 表示卡片的自定义信息，包含customizeData数组标签。 | 对象 | 可缺省，缺省值为空。 | - - 配置示例如下： - - ```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": ["2*2"], - "defaultDimension": "2*2", - "updateEnabled": true, - "scheduledUpdateTime": "10:30", - "updateDuration": 1 - }] - } - ``` - -## 卡片信息的持久化 + ```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": ["2*2"], + "defaultDimension": "2*2", + "updateEnabled": true, + "scheduledUpdateTime": "10:30", + "updateDuration": 1 + }] + } + ``` + + +### 卡片信息的持久化 + 因大部分卡片提供方都不是常驻服务，只有在需要使用时才会被拉起获取卡片信息，且卡片管理服务支持对卡片进行多实例管理，卡片ID对应实例ID，因此若卡片提供方支持对卡片数据进行配置，则需要对卡片的业务数据按照卡片ID进行持久化管理，以便在后续获取、更新以及拉起时能获取到正确的卡片业务数据。 ```javascript @@ -234,9 +252,7 @@ FormExtensionAbility中相关生命周期说明如下： 由于临时卡片的数据具有非持久化的特殊性，某些场景比如卡片服务框架死亡重启，此时临时卡片数据在卡片管理服务中已经删除，且对应的卡片ID不会通知到提供方，所以卡片提供方需要自己负责清理长时间未删除的临时卡片数据。同时对应的卡片使用方可能会将之前请求的临时卡片转换为常态卡片。如果转换成功，卡片提供方也需要对对应的临时卡片ID进行处理，把卡片提供方记录的临时卡片数据转换为常态卡片数据，防止提供方在清理长时间未删除的临时卡片时，把已经转换为常态卡片的临时卡片信息删除，导致卡片信息丢失。 - - -## 开发卡片页面 +### 开发卡片页面 开发者可以使用hml+css+json开发JS卡片页面： > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -- GitLab