• Home
Name Date Size #Lines LOC

..--

AppScope/06-May-2025-3936

EntryCard/entry/base/snapshot/06-May-2025-

entry/06-May-2025-1,9611,744

hvigor/06-May-2025-2422

persistentProxyForm/06-May-2025-1,4951,285

processProxyForm/06-May-2025-1,2861,108

screenshots/06-May-2025-

.gitignoreD06-May-2025112 88

README.mdD06-May-2025721 2011

README_zh.mdD06-May-202512.3 KiB190150

build-profile.json5D06-May-20251.5 KiB6766

hvigorfile.jsD06-May-2025168 21

hvigorwD06-May-20252.1 KiB6428

hvigorw.batD06-May-20252 KiB7356

oh-package.json5D06-May-2025761 2423

ohosTest.mdD06-May-20256.6 KiB2826

README.md

1# Stage Model Widget
2
3### Introduction
4
5This sample shows how to create and use the widget provider in the stage model.
6
7### Usage
8
91. The home screens of some devices do not support widgets. You can create, update, and delete widgets by using your own widget host.
10
112. The following figure shows the widget style. When the widget is updated, the temperature and time on the widget change.
12
13![eTSFormExample](screenshots/eTSFormExample.png)
14
15### Constraints
16
171. This sample can only be run on standard-system devices.
182. This sample is based on the stage model, which is supported from API version 9.
193. This sample requires DevEco Studio 3.1 Beta2 (Build Version: 3.1.0.400, built on April 7, 2023) to compile and run.
20

README_zh.md

1# Stage模型卡片
2
3### 介绍
4
5本示例展示了Stage模型卡片提供方的创建与使用。
6
7用到了卡片扩展模块接口，[@ohos.app.form.FormExtensionAbility](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-form-kit/js-apis-app-form-formExtensionAbility-sys.md) 。
8
9卡片信息和状态等相关类型和枚举接口，[@ohos.app.form.formInfo](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-form-kit/js-apis-app-form-formInfo-sys.md) 。
10
11卡片提供方相关接口的能力接口，[@ohos.app.form.formProvider](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-form-kit/js-apis-app-form-formProvider-sys.md) 。
12
13应用组件间的信息传递接口，[@ohos.app.ability.Want](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-ability-kit/js-apis-app-ability-want.md) 。
14
15### 效果预览
16
17| 卡片应用主页面 | 卡片应用修改订阅条件页面 | 卡片应用发布数据页面 | 卡片应用卡片预览图页面 |
18|-------| ------- | ------- | ------- |
19| ![ProcessProxyForm_main](./screenshots/ProcessProxyForm_main.jpeg) | ![ProcessProxyForm_modifyCondition](./screenshots/ProcessProxyForm_modifyCondition.jpeg) | ![ProcessProxyForm_push](./screenshots/ProcessProxyForm_push.jpeg) | ![ProcessProxyForm_preview](./screenshots/ProcessProxyForm_preview.jpeg) |
20| **formProvider应用主界面** | **formProvider应用修改订阅条件** | **formProvider应用发布数据** | **formProvider应用卡片样式** |
21| ![mainInterface](./screenshots/mainInterface.jpeg) | ![modifySubscriptionConditions](./screenshots/modifySubscriptionConditions.jpeg) | ![dataRelease](./screenshots/dataRelease.jpeg) | ![cardStyle](./screenshots/cardStyle.jpeg) |
22| **添加卡片** | | | |
23|![eTSFormExample](screenshots/eTSFormExample.png)| | | |
24
25使用说明
26
271.部分设备的桌面不支持卡片，可以通过自己的开发卡片使用方，进行卡片的创建、更新和删除等操作。
28
292.卡片的样式如"添加卡片"所示。当卡片更新时，卡片上的温度和时间会产生变化。
30
313.安装[卡片应用](./processProxyForm/)或[formProvider应用](./persistentProxyForm/)，长按卡片应用图标或formProvider应用图标弹出菜单，点击"服务卡片"选项可以添加服务卡片至桌面（第3张，第4张卡片为formProvider应用卡片；第5张，第6张为卡片应用卡片）；
32
334.长按数据卡片弹出菜单，点击"移除"可以将已添加至桌面的数据卡片从桌面上移除；
34
355.点击打开卡片应用图标或formProvider应用图标，点击"修改订阅条件"按键，界面将跳转至修改订阅条件界面，对应选择想要发布的数据完成对订阅条件的修改，离开页面或退出应用后再次打开修改订阅条件页面，页面单选框会显示当前订阅的城市；
36
376.在卡片应用或formProvider应用应用中点击"发布数据"按键，界面将跳转至数据发布界面，对应选择想要发布的数据并点击"发布数据"完成数据发布(若选择发布的城市与当前订阅城市不一致，则不能将数据更新至卡片)；
38
39### 工程目录
40```
41entry/src/main
42|---module.json5                           // 添加卡片拓展能力
43|---/ets/pages
44|   |---index.ets                          // 首页
45|   |---second.ets                         // 第二跳转页
46|---/ets/FormAbility
47|   |---FormAbility.ts                     // 定义卡片对象首次被创建时需要做的操作
48|---js/widget/index                        // 定义卡片内容
49|   |---index.hml
50|   |---index.css
51|   |---index.json
52|---resources/base/profile
53|   |---form_config.json                   // 配置卡片（卡片名称，引入js卡片，卡片窗口大小等）
54persistentProxyForm/src/main/
55|---common
56|  |---StatePersistence.ts                // 订阅条件数据持久化
57|  └---Logger.ts
58|---ets
59|  └---dataShare
60|  | └---DataShare.ts
61|  |---entryability
62|  |  └---PersistentEntryAbility.ts
63|  |---entryformability
64|  |  └---EntryFormAbility.ts
65|  |---pages
66|  |  |---Index.ets                        // PersistentEntryAbility页面
67|  |  |---ModifyConditionIndex.ets         // 修改订阅条件页面
68|  |  └---PublishIndex.ets                 // 发布数据页面
69|  └---widget
70|     └---pages
71|        └---WidgetCard.ets                // ArkTS卡片
72|---js
73|  |---common
74|  |---i18n
75|  └---widgetJS
76|     └---pages
77|        └---index
78|           |---index.css                  // JS卡片样式
79|           |---index.hml                  // JS卡片
80|           └---index.json                 // JS卡片默认值
81└---resources
82processProxyForm/src/main/
83|---common
84|  |---StatePersistence.ts                 // 订阅条件数据持久化
85|  └---Logger.ts
86|---ets
87|  |---entryability
88|  |  └---ProcessEntryAbility.ts
89|  |---entryformability
90|  |  └---ProcessEntryFormAbility.ts
91|  |---pages
92|  |  |---Index.ets                         // ProcessEntryAbility页面
93|  |  |---ModifyConditionIndex.ets          // 修改订阅条件页面
94|  |  └---PushIndex.ets                     // 发布数据页面
95|  └---widget
96|     └---pages
97|        └---WidgetCard.ets                 // ArkTS卡片
98|---js
99|  |---common
100|  |---i18n
101|  └---jsWidget
102|     └---pages
103|        └---index
104|           |---index.css                    // JS卡片样式
105|           |---index.hml                    // JS卡片
106|           └---index.json                   // JS卡片默认值
107└---resources                                // 资源信息
108```
109#### 相关概念
110
111Ability：Ability是应用所具备能力的抽象，也是应用程序的重要组成部分。Ability是系统调度应用的最小单元，是能够完成一个独立功能的组件。
112
113### 具体实现
114
1151、在module.json5文件添加拓展能力，类型为卡片，并设置卡片入口srcEntrance和卡片元数据metadata。[源码参考](entry/src/main/module.json5) 例如："metadata": [
116{
117"name": "ohos.extension.form",
118"resource": "$profile:form_config"
119}。
1202、初始化卡片：通过实现@ohos.app.form.FormExtensionAbility卡片操作类，在卡片对象首次被创建时，初始化卡片绑定数据为空，并将卡片状态设置为就绪状态READY。 例如：onCreate(){
121formBindingData.createFormBindingData({}) onAcquireFormState(want) {
122return formInfo.FormState.READY }。
1233、配置卡片：用js编写相应的卡片，将卡片配置到resources/base/profile/form_config, [源码参考](entry/src/main/resources/base/profile/form_config.json) 。
124
125- 修改数据卡片的订阅条件的功能封装在ModifyConditionIndex.ets中，源码参考：[ModifyConditionIndex.ets](./persistentProxyForm/src/main/ets/pages/ModifyConditionIndex.ets)及[ModifyConditionIndex.ets](./processProxyForm/src/main/ets/pages/ModifyConditionIndex.ets)。
126    - 使用modifyCondition来获取所有已经建立出的卡片对象。
127    - 修改订阅条件：使用updateCardDisplayContent遍历所有卡片对象，并根据界面获取的订阅条件数据修改订阅条件。
128    - 退出页面或应用后再次打开修改订阅条件页面，可以保留上次订阅的城市选择，源码参考：[StatePersistence.ts](./persistentProxyForm/src/main/common/StatePersistence.ts)及[StatePersistence.ts](./processProxyForm/src/main/common/StatePersistence.ts)。
129- 发布数据的功能封装在PublishIndex.ets及PushIndex.ets中，源码参考：[PublishIndex.ets](./persistentProxyForm/src/main/ets/pages/PublishIndex.ets)及[PushIndex.ets](./processProxyForm/src/main/ets/pages/PushIndex.ets)。
130    - [PublishIndex.ets](./persistentProxyForm/src/main/ets/pages/PublishIndex.ets)使用updateRDB来修改rdb数据库中的对应数据。
131    - [PushIndex.ets](./processProxyForm/src/main/ets/pages/PushIndex.ets)使用getRunningFormInfosByFilter获取已经建立出的卡片对象，并使用updateCardDisplayContent遍历所有卡片对象，使用createDataShareHelper创建DataShareHelper对象，并根据界面获取的数据信息使用publish进行数据的发布以实现发布数据的功能
132- 在dataShare模块中，建立rdb数据库，并提供对应update方法。
133    - 在onCreate中初始化数据库中的数据。
134    - 在update中实现对应的数据更新方法。
135
136### 相关权限
137
138[ohos.permission.START_ABILITIES_FROM_BACKGROUND](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/AccessToken/permissions-for-system-apps.md#ohospermissionstart_abilities_from_background)
139
140[ohos.permission.START_INVISIBLE_ABILITY](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/AccessToken/permissions-for-system-apps.md#ohospermissionstart_invisible_ability)
141
142[ohos.permission.GET_BUNDLE_INFO_PRIVILEGED](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/AccessToken/permissions-for-system-apps.md#ohospermissionget_bundle_info_privileged)
143
144[ohos.permission.GET_BUNDLE_INFO](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/AccessToken/permissions-for-all.md#ohospermissionget_bundle_info)
145
146[ohos.permission.REQUIRE_FORM](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/AccessToken/permissions-for-system-apps.md#ohospermissionrequire_form)
147
148### 依赖
149
1501.本应用中[Form.test.ets](./entry/src/ohosTest/ets/test/Form.test.ets)需要安装在仿桌面应用上进行测试。launcher应用地址：[Launcher](https://gitee.com/openharmony/applications_app_samples/tree/master/code/SystemFeature/ApplicationModels/Launcher)
151
1522.本应用中[Form.test.ets](./entry/src/ohosTest/ets/test/Form.test.ets)需要安装[卡片应用](./processProxyForm/)以及[formProvider应用](./persistentProxyForm/)进行测试。（以上两个应用为本工程的feature module）
153
154### 约束与限制
155
1561.本示例仅支持标准系统上运行，支持设备：RK3568。
157
1582.本示例为Stage模型，支持API10版本SDK，SDK版本号(API Version 10 Release),镜像版本号(4.0 Release)。
159
1603.本示例需要使用DevEco Studio 版本号(4.0 Release)及以上版本才可编译运行。
161
1624.本示需要使用Full SDK编译。使用Full SDK时需要手动从镜像站点获取，并在DevEco Studio中替换，具体操作可参考[替换指南]( https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/faqs/full-sdk-switch-guide.md)。
163
1645.本示例所配置的权限为system_core级别(相关权限级别可通过[权限定义列表](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/AccessToken/permissions-for-system-apps.md)查看)，需要手动配置对应级别的权限签名(具体操作可查看[自动化签名方案](https://docs.openharmony.cn/pages/v4.0/zh-cn/application-dev/security/hapsigntool-overview.md/))。
165
1666.本示例类型为系统应用，需要手动配置对应级别的应用类型("app-feature": "hos_system_app")。具体可参考profile配置文件[bundle-info对象内部结构]( https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/app-provision-structure.md#bundle-info%E5%AF%B9%E8%B1%A1%E5%86%85%E9%83%A8%E7%BB%93%E6%9E%84)
167
1687.本示例使用了ServiceExtensionAbility，需要手动配置特权应用能力申请"app-privilege-capabilities": ["AllowAppUsePrivilegeExtension"]，否则安装失败。具体操作指南可参考[应用特权配置指南]( https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/subsystems/subsys-app-privilege-config-guide.md)。在文件最后添加内容：
169    "app-privilege-capabilities" : [
170        "AllowAppUsePrivilegeExtension"
171    ]
172
1738.本示例中使用到DataShareExtensionAbility，需要将本示例加入到白名单中再进行安装。详细内容如下
174{
175    "bundleName": "ohos.samples.formextability",
176    "app_signature" : [],
177    "associatedWakeUp": true,
178    "allowAppUsePrivilegeExtension": true
179}
180
181### 下载
182
183如需单独下载本工程，执行如下命令：
184```
185git init
186git config core.sparsecheckout true
187echo code/SystemFeature/Widget/FormExtAbility/ > .git/info/sparse-checkout
188git remote add origin https://gitee.com/openharmony/applications_app_samples.git
189git pull origin master
190```