From 5ce12d5b29b73c7793b35549501116eb3cd78a0b Mon Sep 17 00:00:00 2001 From: Don-Talk <1131050326@qq.com> Date: Wed, 15 Jun 2022 03:42:50 +0000 Subject: [PATCH 1/7] update README.md. --- README.md | 33 +++++++++------------------------ 1 file changed, 9 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index a772a94..2f1fcd2 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,22 @@ # FormDemo -#### 介绍 -FormDemo +### 简介 +本仓主要存放OpenHarmony卡片相关文档、示例代码，旨在为开发者提供更好的卡片开发入门环境。 -#### 软件架构 -软件架构说明 +### 目录 +├── FormExtAbility     #Stage模型下的卡片开发示例代码 -#### 安装教程 -1. xxxx -2. xxxx -3. xxxx +### 说明 +#### FormExtAbility +该示例代码实现了卡片的基本功能：页面跳转、手动刷新数据、定时刷新数据功能。 -#### 使用说明 -1. xxxx -2. xxxx -3. xxxx -#### 参与贡献 +### 使用说明 -1. Fork 本仓库 -2. 新建 Feat_xxx 分支 -3. 提交代码 -4. 新建 Pull Request +#### FormExtAbility -#### 特技 -1. 使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md -2. Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com) -3. 你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目 -4. [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目 -5. Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help) -6. Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) -- Gitee From d08b3f9cbadc65dc73ad86cefcc6eb5553d3edff Mon Sep 17 00:00:00 2001 From: Don-Talk <1131050326@qq.com> Date: Wed, 15 Jun 2022 03:45:56 +0000 Subject: [PATCH 2/7] update README.md. --- README.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 2f1fcd2..c9413ef 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,16 @@ # FormDemo -### 简介 +## 简介 本仓主要存放OpenHarmony卡片相关文档、示例代码，旨在为开发者提供更好的卡片开发入门环境。 -### 目录 +## 目录 ├── FormExtAbility     #Stage模型下的卡片开发示例代码 -### 说明 -#### FormExtAbility +## 说明 +### FormExtAbility 该示例代码实现了卡片的基本功能：页面跳转、手动刷新数据、定时刷新数据功能。 -### 使用说明 - -#### FormExtAbility - - - -- Gitee From fb8393573b7ff47e2c8df2945460cf5d0ef816d8 Mon Sep 17 00:00:00 2001 From: Don-Talk <1131050326@qq.com> Date: Wed, 15 Jun 2022 06:15:18 +0000 Subject: [PATCH 3/7] update README.md. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index c9413ef..e82e71e 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ ## 说明 ### FormExtAbility 该示例代码实现了卡片的基本功能：页面跳转、手动刷新数据、定时刷新数据功能。 +将该应用安装到设备上，在设备桌面长按该应用图标，弹出卡片管理，点击卡片管理进入卡片选择页面。 -- Gitee From 9992dd77758760b5944e2caf63b2719066e6c610 Mon Sep 17 00:00:00 2001 From: dWX1140490 Date: Wed, 15 Jun 2022 16:25:06 +0800 Subject: [PATCH 4/7] modify package.json format --- FormExtAbility/package.json | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/FormExtAbility/package.json b/FormExtAbility/package.json index 8649b9c..2a18fb6 100644 --- a/FormExtAbility/package.json +++ b/FormExtAbility/package.json @@ -1,14 +1,14 @@ { - "devDependencies":{}, - "name":"formapplication", - "ohos":{ - "org":"huawei", - "directoryLevel":"project", - "buildTool":"hvigor" + "devDependencies": {}, + "name": "formapplication", + "ohos": { + "org": "huawei", + "directoryLevel": "project", + "buildTool": "hvigor" }, - "version":"1.0.0", - "dependencies":{ - "@ohos/hvigor-ohos-plugin":"1.0.6", - "@ohos/hvigor":"1.0.6" + "version": "1.0.0", + "dependencies": { + "@ohos/hvigor-ohos-plugin": "1.0.6", + "@ohos/hvigor": "1.0.6" } -} \ No newline at end of file +} -- Gitee From c22ee6d02c00fadd8ab507dd058d561d8899d0fa Mon Sep 17 00:00:00 2001 From: dWX1140490 Date: Wed, 15 Jun 2022 17:46:42 +0800 Subject: [PATCH 5/7] modify index.ets --- .../entry/src/main/ets/pages/index.ets | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/FormExtAbility/entry/src/main/ets/pages/index.ets b/FormExtAbility/entry/src/main/ets/pages/index.ets index c73d6e8..761a887 100644 --- a/FormExtAbility/entry/src/main/ets/pages/index.ets +++ b/FormExtAbility/entry/src/main/ets/pages/index.ets @@ -35,25 +35,6 @@ struct Index { build() { Row() { Column() { - Text(this.message) - .fontSize(50) - .fontWeight(FontWeight.Bold) - .onClick(()=>{ - let want = { - "bundleName": "com.test.fts", - "abilityName": "MainAbility" - } - //AppStorage - - let context = globalThis.context - Logger.log("195 routerPage came in !!!") - - context.startAbility(want,err =>{ - Logger.log("routerPage err :" + JSON.stringify(err)) - }) - - }) - Button() { Text('next page') -- Gitee From 179d97dbf37e94c0bc098b85ccf53de510b8fda9 Mon Sep 17 00:00:00 2001 From: dWX1140490 Date: Wed, 15 Jun 2022 17:52:06 +0800 Subject: [PATCH 6/7] modify index.ets --- FormExtAbility/entry/src/main/ets/pages/index.ets | 1 - 1 file changed, 1 deletion(-) diff --git a/FormExtAbility/entry/src/main/ets/pages/index.ets b/FormExtAbility/entry/src/main/ets/pages/index.ets index 761a887..b7a5f81 100644 --- a/FormExtAbility/entry/src/main/ets/pages/index.ets +++ b/FormExtAbility/entry/src/main/ets/pages/index.ets @@ -30,7 +30,6 @@ async function routePage() { @Entry @Component struct Index { - @State message: string = 'Hello FormExtAbility' build() { Row() { -- Gitee From 571f2285b69e7dbd4ee9bfd5c9ee718e6f242e8d Mon Sep 17 00:00:00 2001 From: dWX1140490 Date: Mon, 27 Jun 2022 15:51:24 +0800 Subject: [PATCH 7/7] =?UTF-8?q?add=20Stage=E6=A8=A1=E5=9E=8B=E4=B8=AD?= =?UTF-8?q?=E5=8D=A1=E7=89=87=E7=9A=84=E5=9F=BA=E6=9C=AC=E7=94=A8=E6=B3=95?= =?UTF-8?q?.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...72\346\234\254\347\224\250\346\263\225.md" | 545 ++++++++++++++++++ 1 file changed, 545 insertions(+) create mode 100644 "Stage\346\250\241\345\236\213\344\270\255\345\215\241\347\211\207\347\232\204\345\237\272\346\234\254\347\224\250\346\263\225.md" diff --git "a/Stage\346\250\241\345\236\213\344\270\255\345\215\241\347\211\207\347\232\204\345\237\272\346\234\254\347\224\250\346\263\225.md" "b/Stage\346\250\241\345\236\213\344\270\255\345\215\241\347\211\207\347\232\204\345\237\272\346\234\254\347\224\250\346\263\225.md" new file mode 100644 index 0000000..d523c31 --- /dev/null +++ "b/Stage\346\250\241\345\236\213\344\270\255\345\215\241\347\211\207\347\232\204\345\237\272\346\234\254\347\224\250\346\263\225.md" @@ -0,0 +1,545 @@ +# 基于Stage模型的卡片基本用法 + +## 卡片概述 + +卡片是一种界面展示形式，可以将应用的重要信息或操作前置到卡片，以达到服务直达，减少体验层级的目的。 + +卡片常用于嵌入到其他应用（当前只支持系统应用，例如Launcher）中作为其界面的一部分显示，并支持拉起页面，发送消息等基础的交互功能。 + +卡片的基本概念： + +- 卡片提供方：提供卡片显示内容原子化服务，控制卡片的显示内容、控件布局以及控件点击事件。 +- 卡片使用方：显示卡片内容的宿主应用，负责显示卡片，控制卡片在宿主中展示的位置。 +- 卡片管理服务：用于管理系统中所添加卡片的常驻代理服务，包括卡片对象的管理与使用，以及卡片周期性刷新等。 + +> 卡片使用方和提供方不要求常驻运行，在需要添加/删除/请求更新卡片时，卡片管理服务会拉起卡片提供方获取卡片信息。 +> +> 开发者仅需作为卡片提供方进行卡片内容的开发，卡片使用方和卡片管理服务由系统自动处理。 + + + +## 场景介绍 + +Stage卡片开发，即基于[Stage模型](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/ability/stage-brief.md)的卡片提供方开发，主要涉及如下功能逻辑： + +- 卡片生命周期回调函数FormExtension开发。 +- 创建卡片数据FormBindingData对象。 +- 通过FormProvider更新卡片。 +- 卡片页面开发。 + + + +## 接口说明 + +#### FormExtension + +> 该接口提供了卡片生命周期函数。 +> +> 在卡片提供方应用中的FormAbility.ts文件中继承FormExtension并实现这些卡片生命周期函数。 + +| 接口名 | 描述 | +| ------------------------------------------------------------ | -------------------------------------------- | +| 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; | 当系统配置更新时调用。 | + +FormExtension类还拥有成员context ，为FormExtensionContext类。 + + + +#### FormExtensionContext + +> 卡片上下文环境类 + +| 接口名 | 描述 | +| ------------------------------------------------------------ | ------------------------- | +| updateForm(formId: string, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback): void | 回调形式主动更新卡片。 | +| updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise | Promise形式主动更新卡片。 | + + + +#### FormProvider + +> 卡片提供者，可以更新卡片信息、设置卡片下一次刷新时间。 + +| 接口名 | 描述 | +| ------------------------------------------------------------ | ------------------------------------------------- | +| setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback): void; | 设置指定卡片的下一次更新时间。 | +| setFormNextRefreshTime(formId: string, minute: number): Promise; | 设置指定卡片的下一次更新时间，以promise方式返回。 | +| updateForm(formId: string, formBindingData: FormBindingData, callback: AsyncCallback): void; | 更新指定的卡片。 | +| updateForm(formId: string, formBindingData: FormBindingData): Promise; | 更新指定的卡片，以promise方式返回。 | + + + +## 卡片开发指导 + +### 创建卡片提供者 + +1. 打开DevEco 3.0.0.900新建一个Stage模型、API9的项目 + + ![](http://image.huawei.com/tiny-lts/v1/images/3b78cf3e9312bee3f4124a143008212b_968x606.png) + +2. 选择一个module，此处以entry为例。选中entry文件夹，右键New-->Extension Ability -->Service Widget + + ![](http://image.huawei.com/tiny-lts/v1/images/1d0feaf7e21e28e021929196389af16a_983x725.png) + +3. 任选一种卡片模板，输入卡片名称，选择卡片尺寸（部分卡片模板支撑选择多种尺寸），输入卡片Ability名称，默认FormAbility。 + + ![](http://image.huawei.com/tiny-lts/v1/images/a640bc1e6cd52bdce1c5f5de0a63fed3_979x605.png) + +4. 点击Finish，完成卡片的创建之后，会生成如下文件。 + + ![](http://image.huawei.com/tiny-lts/v1/images/cfd8c47a0ef9e7533907ef02f092cc67_1018x677.png) + +5. 安装应用到设备上。 + + 在设备的桌面上长按应用图标，会显示卡片管理，点击卡片管理即可看到该应用支持的卡片，选择卡片添加到桌面。 + + + +### 卡片页面文件说明 + +> JS卡片页面通过hml+css+json开发 + +- index.hml文件：卡片的显示页面，在该页面中可以为组件设置onClick属性，其值对应到index.json文件的actions字段中 + +- index.css文件：存放index.hml页面中使用的的css样式 + +- index.json文件：存放卡片页面index.hml中的变量及事件。 + + 内部字段结构说明： + + - data：存放的是index.hml中使用到的变量 + + - actions: 存放的是index.hml中使用的事件，有两种类型：router和message。 + + > router类型事件：用于卡片提供方进行跳转，须相应配置abilityName属性用于存放目标Ability名称。 + > + > message类型事件：用于卡片与卡片提供方进行交互，会触发卡片生命周期中的`onEvent`方法。 + + 示例： + + ```typescript + "actions": { + "routerPage": { + "action": "router", + "abilityName": "ohos.samples.FormApplication.MainAbility", + "params": { + "message": "add detail" + } + }, + "onUpdateEvent": { + "action": "message", + "params": { + "name" : "onUpdateEvent", + "message": "add detail" + } + }, + } + ``` + + + +### 卡片配置文件 + +#### module.json5 + +卡片需要在应用配置文件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"，资源为卡片的具体配置信息的索引。 + +示例： + +```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", + }, + ], + }, +] +``` + + + +#### form_config.json + +卡片的具体配置信息。在上述 FormExtensionAbility 的元信息中，指定了的卡片具体配置信息的资源索引，如使用 $profile:form_config 指定开发视图的 resources/base/profile/ 目录下的 form_config.json 作为卡片profile配置文件。 + +内部字段结构说明： + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ | +| 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 | 表示卡片的配置跳转链接，采用URI格式。 | 字符串 | 可缺省，缺省值为空。 | +| formVisibleNotify | 标识是否允许卡片使用卡片可见性通知。 | 字符串 | 可缺省，缺省值为空。 | +| metaData | 表示卡片的自定义信息，包含customizeData数组标签。 | 对象 | 可缺省，缺省值为空。 | + +示例： + +```json +{ + "forms": [ + { + "name": "widget", + "description": "This is a service widget.", + "src": "./js/widget/pages/index/index", + "formConfigAbility": "ability://ohos.samples.FormApplication.MainAbility", + "window": { + "designWidth": 720, + "autoDesignWidth": true + }, + "colorMode": "auto", + "isDefault": true, + "updateEnabled": true, + "scheduledUpdateTime": "11:32", + "updateDuration" : 1, + "defaultDimension": "2*4", + "supportDimensions": ["2*4", "4*4"] + } + ] +} +``` + + + +### 页面拉起功能 + +1. 在index.hml页面设置点击事件`routerEvent`，其值对应index.json文件中actions字段中。 + + ```html + +
+
+ ``` + +2. 在index.json中的actions标签下定义`routerEvent`事件 + + > action字段填router，表明是跳转事件 + > abilityName填写要调转的Ability名 + + ```json + "actions": { + "routerPage": { + "action": "router", + "abilityName": "ohos.samples.FormApplication.MainAbility", + "params": { + "message": "add detail" + } + }, + } + ``` + + + + +### 数据交互功能 + +> 在index.hml页面中展示两个数据：temperature 和 time +> +> ```html +> {{ $t('strings.temperature') }}{{temperature}} ℃ +> {{ $t('strings.time') }} {{time}} +> ``` +> +> 数据 temperature 和 time 已在index.json中定义： +> +> ```json +> { +> "data": { +> "temperature": "0", +> "time": "00:00:00" +> } +> } +> ``` +> +> 可以通过以下方式来实现卡片的数据交互。 + + + +#### 手动刷新数据 + +> 通过调用message类型的事件触发卡片生命周期函数onEvent，在onEvent函数中可以获取到当前卡片实例的Id及传入的事件信息。 +> +> 在onEvent函数中根据事件名来进行不同的操作，当传入的是更新数据的事件名时，调用formProvider接口的updateForm方法来更新卡片数据。 + +![](http://image.huawei.com/tiny-lts/v1/images/90697a0fc35c97b1a2c110c8f41709d6_945x872.png) + +1. 在index.hml文件中创建按钮，绑定`onUpdateEvent`事件 + + ```html + + ``` + +2. 在index.json文件中声明`onUpdateEvent`事件，action类型为`message` + + ```json + { + "data": { + "temperature": "0", + "time": "00:00:00" + }, + "actions":{ + "onUpdateEvent": { + "action": "message", + "params": { + "name" : "onUpdateEvent", + "message": "add detail" + } + } + } + + } + ``` + +3. 在FormAbility.ts中的onEvent方法中，获取事件名onUpdateEvent，然后进行卡片数据更新操作。 + + - onUpdateEvent： 调用卡片页面数据刷新函数，刷新卡片数据一次 + - openRefresh： 设置定时器，每间隔1s调用一次卡片数据刷新函数来实现卡片页面数据持续刷新 + - closeRefresh： 清除定时器，关闭卡片页面数据持续刷新 + + ```typescript + import formBindingData from '@ohos.application.formBindingData'; + import formProvider from '@ohos.application.formProvider'; + + var timer : number = 0 + + //卡片页面数据刷新函数 + async function updateFormData(formId: string){ + let obj = { + "temperature" : getTemperature(formId, formInfo.updateCount).toString(), + "time" : getTime() + } + let formData = formBindingData.createFormBindingData(obj) + formProvider.updateForm(formId,formData).catch(err=>{ + Logger.error("updateOne err : " + JSON.stringify(err)) + }) + } + + onEvent(formId, message) { + console.log(`FormAbility onEvent, formId = ${formId}, message: ${JSON.stringify(message)}`); + let jsonParams = JSON.parse(message) + //获取事件名 + let eventName = jsonParams.params.name + + switch(eventName){ + + case "onUpdateEvent" : + updateFormData(formId); + break; + + case "openRefresh" : + let count = 1 + timer = setInterval(()=>{ + this.onUpdate(formId) + },1000) + break; + + case "closeRefresh" : + clearInterval(timer) + break; + + default : + console.log("(onEvent) formId :" + formId + " message : " + message ) + break; + } + } + ``` + + + +#### 定点刷新数据 + +在卡片配置文件`form_config.json`中可以配置`scheduledUpdateTime`属性来实现卡片定点刷新数据， + +`scheduledUpdateTime`表示卡片的定点刷新的时刻，采用24小时制，精确到分钟。 + +时间到达`scheduledUpdateTime`参数设置的时刻时，会触发卡片生命周期的`onUpdate`方法，在`onUpdate`方法中执行卡片数据更新操作。 + +示例： + +- form_config.json + + ```json + { + "forms": [ + { + //... + "scheduledUpdateTime": "11:32", + "updateDuration" : 0, + //... + } + ] + } + ``` + +- FormAbility.ts + + ```typescript + onUpdate(formId) { + console.log(`FormAbility onUpdate, formId: ${formId}`); + //卡片数据更新方法 + updateFormData(formId); + } + ``` + + + +#### 定时刷新数据 + +在卡片配置文件`form_config.json`中可以配置来实现卡片定时刷新数据， + +`updateDuration`属性表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数（正整数或0）。 + +当取值为0时，表示该参数不生效。 + +当取值为正整数N时，表示刷新周期为30*N分钟，每隔30*N分钟会触发卡片生命周期的`onUpdate`方法，在`onUpdate`方法中执行卡片数据更新操作。 + +当取值为正整数N时，定点刷新数据不生效。 + + + +示例： + +- form_config.json + + ```json + { + "forms": [ + { + ... + "scheduledUpdateTime": "11:32", + "updateDuration" : 1, + ... + } + ] + } + ``` + +- FormAbility.ts + + ```typescript + onUpdate(formId) { + console.log(`FormAbility onUpdate, formId: ${formId}`); + //卡片数据更新方法 + updateFormData(formId); + } + ``` + + + +### 卡片信息持久化 + +> 因大部分卡片提供方都不是常驻服务，只有在需要使用时才会被拉起获取卡片信息，且卡片管理服务支持对卡片进行多实例管理，卡片ID对应实例ID。 +> +> 因此若卡片提供方支持对卡片数据进行配置，则需要对卡片的业务数据按照卡片ID进行持久化管理， +> +> 以便在后续获取、更新以及拉起时能获取到正确的卡片业务数据， +> +> 且需要适配onDestroy卡片销毁通知接口，在其中实现卡片实例数据的删除。 + +卡片根据业务数据是否需要持久化分为以下两类： + +- 常态卡片：卡片使用方会持久化的卡片； +- 临时卡片：卡片使用方不会持久化的卡片； + +卡片管理服务调用卡片提供者创建卡片时，默认创建的是临时卡片。如果需要将临时卡片转化为常态卡片，可参考轻量级数据存储，将卡片示例的业务数据进行存储调用。 + +```typescript +import dataStorage from '@ohos.data.storage'; + +async function storeFormInfo(formId: string, formName: string, tempFlag: boolean) { + let formInfo = { + "formName": formName, + "tempFlag": tempFlag, + "updateCount": 0 + }; + try { + const storage = await dataStorage.getStorage(DATA_STORAGE_PATH); + // put form info + await storage.put(formId, JSON.stringify(formInfo)); + Logger.log(`storeFormInfo, put form info successfully, formId: ${formId}`); + await storage.flush(); + } catch (err) { + Logger.error(`failed to storeFormInfo, err: ${JSON.stringify(err)}`); + } +} +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- Gitee