Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
未验证 提交 005aa6fb 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!21740 卡片指导文档修改（Beta） 

Merge pull request !21740 from wangkailong/cherry-pick-1690875342
上级 3c235901 a34fdd9c
隐藏空白更改
内联 并排
Showing with 58 addition and 23 deletion
zh-cn/application-dev/application-models/arkts-ui-widget-configuration.md
浏览文件 @ 005aa6fb
......@@ -16,7 +16,7 @@
"extensionAbilities": [
{
"name": "EntryFormAbility",
"srcEntry": "./ets/entryformability/EntryFormAbility.ts",
"srcEntry": "./ets/entryformability/EntryFormAbility.ets",
"label": "$string:EntryFormAbility_label",
"description": "$string:EntryFormAbility_desc",
"type": "form",
......@@ -42,9 +42,9 @@
| description | 表示卡片的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 |
| src | 表示卡片对应的UI代码的完整路径。当为ArkTS卡片时，完整路径需要包含卡片文件的后缀，如："./ets/widget/pages/WidgetCard.ets"。当为JS卡片时，完整路径无需包含卡片文件的后缀，如："./js/widget/pages/WidgetCard" | 字符串 | 否 |
| uiSyntax | 表示该卡片的类型，当前支持如下两种类型：<br/>-&nbsp;arkts：当前卡片为ArkTS卡片。<br/>-&nbsp;hml：当前卡片为JS卡片。 | 字符串 | 可缺省，缺省值为hml |
| window | 用于定义与显示窗口相关的配置。 | 对象 | 可缺省 |
| window | 用于定义与显示窗口相关的配置。 | 对象 | 可缺省，缺省值见表2。 |
| isDefault | 表示该卡片是否为默认卡片，每个UIAbility有且只有一个默认卡片。<br/>-&nbsp;true：默认卡片。<br/>-&nbsp;false：非默认卡片。 | 布尔值 | 否 |
| colorMode | 表示卡片的主题样式，取值范围如下：<br/>-&nbsp;auto：自适应。<br/>-&nbsp;dark：深色主题。<br/>-&nbsp;light：浅色主题。 | 字符串 | 可缺省，缺省值为“auto”。 |
| colorMode | 表示卡片的主题样式，取值范围如下：<br/>-&nbsp;auto：跟随系统的颜色模式值选取主题。<br/>-&nbsp;dark：深色主题。<br/>-&nbsp;light：浅色主题。 | 字符串 | 可缺省，缺省值为“auto”。 |
| supportDimensions | 表示卡片支持的外观规格，取值范围：<br/>-&nbsp;1&nbsp;\*&nbsp;2：表示1行2列的二宫格。<br/>-&nbsp;2&nbsp;\*&nbsp;2：表示2行2列的四宫格。<br/>-&nbsp;2&nbsp;\*&nbsp;4：表示2行4列的八宫格。<br/>-&nbsp;4&nbsp;\*&nbsp;4：表示4行4列的十六宫格。 | 字符串数组 | 否 |
| defaultDimension | 表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 否 |
| updateEnabled | 表示卡片是否支持周期性刷新（包含定时刷新和定点刷新），取值范围：<br/>-&nbsp;true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，当两者同时配置时，定时刷新优先生效。<br/>-&nbsp;false：表示不支持周期性刷新。 | 布尔类型 | 否 |
......@@ -56,6 +56,13 @@
| dataProxyEnabled | 表示卡片是否支持[卡片代理刷新](./arkts-ui-widget-update-by-proxy.md)，取值范围：<br/>-&nbsp;true：表示支持代理刷新。<br/>-&nbsp;false：表示不支持代理刷新。<br/>设置为true时，[定时刷新和下次刷新不生效，但不影响定点刷新](./arkts-ui-widget-update-by-time.md) | 布尔类型 | 可缺省，缺省值为false。 |
| isDynamic | 表示此卡片是否为动态卡片（仅针对ArkTS卡片生效）。<br/>-&nbsp;true：为动态卡片。<br/>-&nbsp;false：为静态卡片，当卡片添加成功后，将以静态图显示。 | 布尔类型 | 可缺省，缺省值为true。 |
**表2** window对象的内部结构说明
| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
| -------- | -------- | -------- | -------- |
| designWidth | 标识页面设计基准宽度。以此为基准，根据实际设备宽度来缩放元素大小。 | 数值 | 可缺省，缺省值为720px。 |
| autoDesignWidth | 标识页面设计基准宽度是否自动计算。当配置为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。 | 布尔值 | 可缺省，缺省值为false。 |
配置示例如下：
......
zh-cn/application-dev/application-models/arkts-ui-widget-creation.md
浏览文件 @ 005aa6fb
......@@ -11,6 +11,6 @@
3. 在选择卡片的开发语言类型（Language）时，选择ArkTS选项，然后单击“Finish”，即可完成ArkTS卡片创建。
![WidgetProjectCreate3](figures/WidgetProjectCreate3.png)
ArkTS卡片创建完成后，工程中会新增如下卡片相关文件：卡片生命周期管理文件（EntryFormAbility.ts）、卡片页面文件（WidgetCard.ets）和卡片配置文件（form_config.json）。
ArkTS卡片创建完成后，工程中会新增如下卡片相关文件：卡片生命周期管理文件（EntryFormAbility.ets）、卡片页面文件（WidgetCard.ets）和卡片配置文件（form_config.json）。
![WidgetProjectView](figures/WidgetProjectView.png)
zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md
浏览文件 @ 005aa6fb
......@@ -48,7 +48,7 @@
}
```
- 在UIAbility中接收call事件并获取参数，根据传递的method不同，执行不同的方法。其余数据可以通过readString的方式获取。需要注意的是，UIAbility需要onCreate生命周期中监听所需的方法。
- 在UIAbility中接收call事件并获取参数，根据传递的method不同，执行不同的方法。其余数据可以通过[readString](../reference/apis/js-apis-rpc.md#readstring)方法获取。需要注意的是，UIAbility需要onCreate生命周期中监听所需的方法。
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
......
zh-cn/application-dev/application-models/arkts-ui-widget-event-formextensionability.md
浏览文件 @ 005aa6fb
......@@ -4,7 +4,7 @@
在卡片页面中可以通过**postCardAction**接口触发message事件拉起FormExtensionAbility，然后由FormExtensionAbility刷新卡片内容，下面是这种刷新方式的简单示例。
- 在卡片页面通过注册Button的onClick点击事件回调，并在回调中调用**postCardAction**接口触发事件至FormExtensionAbility。
- 在卡片页面通过注册Button的onClick点击事件回调，并在回调中调用**postCardAction**接口触发事件至FormExtensionAbility。卡片页面中使用[LocalStorageProp](../quick-start/arkts-localstorage.md#localstorageprop)装饰需要刷新的卡片数据。
```ts
let storage = new LocalStorage();
......
zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md
浏览文件 @ 005aa6fb
......@@ -22,11 +22,13 @@ action参数说明：
| **Key** | **Value** | **样例描述** |
| -------- | -------- | -------- |
| "action" | string | action的类型，支持三种预定义的类型：<br/>-&nbsp;"router"：跳转到提供方应用的指定UIAbility。<br/>-&nbsp;"message"：自定义消息，触发后会调用提供方FormExtensionAbility的[onFormEvent()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onformevent)生命周期回调。<br/>-&nbsp;"call"：后台启动提供方应用。触发后会拉起提供方应用的指定UIAbility（仅支持[launchType](uiability-launch-type.md)为singleton的UIAbility，即启动模式为单实例的UIAbility），但不会调度到前台。提供方应用需要具备后台运行权限([ohos.permission.KEEP_BACKGROUND_RUNNING](../security/permission-list.md#ohospermissionkeep_background_running))。 |
| "bundleName" | string | "router"&nbsp;/&nbsp;"call"&nbsp;类型时跳转的包名，可选。 |
| "moduleName" | string | "router"&nbsp;/&nbsp;"call"&nbsp;类型时跳转的模块名，可选。 |
| "abilityName" | string | "router"&nbsp;/&nbsp;"call"&nbsp;类型时跳转的UIAbility名，必填。 |
| "params" | Object | 当前action携带的额外参数，内容使用JSON格式的键值对形式。"call"&nbsp;类型时需填入参数'method'，且类型需要为string类型，用于触发UIAbility中对应的方法，必填。 |
| "bundleName" | string | "action"为"router"&nbsp;/&nbsp;"call"&nbsp;类型时跳转的包名，可选。 |
| "moduleName" | string | "action"为"router"&nbsp;/&nbsp;"call"&nbsp;类型时跳转的模块名，可选。 |
| "abilityName" | string | "action"为"router"&nbsp;/&nbsp;"call"&nbsp;类型时跳转的UIAbility名，必填。 |
| "params" | Object | 当前action携带的额外参数，内容使用JSON格式的键值对形式。必填。 |
>![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
>"action"为"call"&nbsp;类型时，"params"需填入参数'method'，且类型需为string类型，用于触发UIAbility中对应的方法。
`postCardAction()`接口示例代码：
......
zh-cn/application-dev/application-models/arkts-ui-widget-event-router.md
浏览文件 @ 005aa6fb
......@@ -57,7 +57,7 @@
let selectPage = "";
let currentWindowStage = null;
export default class CameraAbility extends UIAbility {
export default class EntryAbility extends UIAbility {
// 如果UIAbility第一次启动，在收到Router事件后会触发onCreate生命周期回调
onCreate(want, launchParam) {
// 获取router事件中传递的targetPage参数
......
zh-cn/application-dev/application-models/arkts-ui-widget-interaction-overview.md
浏览文件 @ 005aa6fb
# 卡片数据交互说明
ArkTS卡片框架提供了updateForm()接口和requestForm()接口主动触发卡片的页面刷新。
ArkTS卡片框架提供了updateForm()接口和requestForm()接口主动触发卡片的页面刷新，通过[LocalStorageProp](../quick-start/arkts-localstorage.md#localstorageprop)确认需要刷新的卡片数据。
![WidgetLocalStorageProp](figures/WidgetLocalStorageProp.png)
......
zh-cn/application-dev/application-models/arkts-ui-widget-lifecycle.md
浏览文件 @ 005aa6fb
......@@ -4,7 +4,7 @@
创建ArkTS卡片，需实现[FormExtensionAbility](../reference/apis/js-apis-app-form-formExtensionAbility.md)生命周期接口。
1. 在EntryFormAbility.ts中，导入相关模块。
1. 在EntryFormAbility.ets中，导入相关模块。
```ts
import formInfo from '@ohos.app.form.formInfo';
......@@ -13,7 +13,7 @@
import formProvider from '@ohos.app.form.formProvider';
```
2. 在EntryFormAbility.ts中，实现[FormExtensionAbility](../reference/apis/js-apis-app-form-formExtensionAbility.md)生命周期接口，其中在onAddForm的入参want中可以通过[FormParam](../reference/apis/js-apis-app-form-formInfo.md#formparam)取出卡片的相关信息。
2. 在EntryFormAbility.ets中，实现[FormExtensionAbility](../reference/apis/js-apis-app-form-formExtensionAbility.md)生命周期接口，其中在onAddForm的入参want中可以通过[FormParam](../reference/apis/js-apis-app-form-formInfo.md#formparam)取出卡片的相关信息。
```typescript
import formInfo from '@ohos.app.form.formInfo';
......
zh-cn/application-dev/application-models/arkts-ui-widget-update-by-proxy.md
浏览文件 @ 005aa6fb
......@@ -7,11 +7,15 @@
**图1** 代理刷新运行原理
![UpdateWidgetByProxyPrinciple](figures/UpdateWidgetByProxyPrinciple.png)
如图1，与[ArkTS卡片实现原理图](../application-models/arkts-ui-widget-working-principles.md#实现原理)相比，新增了数据管理服务和数据提供方。
如图1，与[ArkTS卡片实现原理图](../application-models/arkts-ui-widget-working-principles.md#实现原理)相比，卡片代理刷新原理新增了数据管理服务和数据提供方。
- 数据管理服务：该场景下主要提供了多应用间的数据共享的机制。
- 数据提供方（仅支持系统应用）：系统应用作为数据提供方，需要开启数据共享能力，同时需要自定义`key + subscriberId`作为共享数据的标识。
> **说明：**
>
> 只有系统提供了作为数据提供方的应用，同时提供公开可获得的共享数据标识，才能正常使用该特性。
卡片提供方处理流程（图中蓝色箭头）：
1. 卡片提供方在卡片提供方的配置文件`form_config.json`中配置`dataProxyEnabled`字段为`true`，以开启卡片代理刷新功能。
......@@ -32,7 +36,7 @@
数据提供方提供的共享数据有两种类型：
- 过程数据，不会一直存储，有老化期，普通应用可以订阅。
- 过程数据，不会一直存储，有老化期，所有应用都可以订阅。
- 持久化数据，仅系统应用可以订阅。
......
zh-cn/application-dev/application-models/arkts-ui-widget-update-by-status.md
浏览文件 @ 005aa6fb
......@@ -4,7 +4,7 @@
相同的卡片可以添加到桌面上实现不同的功能，比如添加两张桌面的卡片，一张显示杭州的天气，一张显示北京的天气，设置每天早上7点触发定时刷新，卡片需要感知当前的配置是杭州还是北京，然后将对应城市的天气信息刷新到卡片上，以下示例介绍了如何根据卡片的状态动态选择需要刷新的内容。
- 卡片配置文件：配置每天早上7点触发定时刷新
- 卡片配置文件：配置每天早上7点触发定时刷新。
```json
{
......
zh-cn/application-dev/application-models/arkts-ui-widget-update-by-time.md
浏览文件 @ 005aa6fb
# 卡片定时刷新和定点刷新
在使用定时和定点刷新功能之前，需要在form_config.json配置文件中设置`updateEnabled`字段为`true`，以启用周期性刷新功能。
当前卡片框架提供了如下几种按时间刷新卡片的方式：
......@@ -9,6 +7,7 @@
> **说明：**
>
> 在使用定时和定点刷新功能之前，需要在form_config.json配置文件中设置`updateEnabled`字段为`true`，以启用周期性刷新功能。
> 当配置了`updateDuration`（定时刷新）后，该设置会优先于`scheduledUpdateTime`（定点刷新）生效，即使同时配置了两者，定点刷新也会被忽略。
```json
......
zh-cn/application-dev/application-models/arkts-ui-widget-working-principles.md
浏览文件 @ 005aa6fb
......@@ -17,7 +17,7 @@
**图2** ArkTS卡片渲染服务运行原理
![WidgetRender](figures/WidgetRender.png)
与JS卡片相比，ArkTS卡片支持在卡片中运行逻辑代码，为确保ArkTS卡片发生问题后不影响卡片使用方应用的使用，ArkTS卡片新增了卡片渲染服务用于运行卡片页面代码widgets.abc，卡片渲染服务由卡片管理服务管理。卡片使用方的每个卡片组件都对应了卡片渲染服务里的一个渲染实例，同一应用提供方的渲染实例运行在同一个虚拟机运行环境中，不同应用提供方的渲染实例运行在不同的虚拟机运行环境中，通过虚拟机运行环境隔离不同应用提供方卡片之间的资源与状态。开发过程中需要注意的是[globalThis](uiability-data-sync-with-ui.md#使用globalthis进行数据同步)对象的使用，相同应用提供方的卡片globalThis对象是同一个，不同应用提供方的卡片globalThis对象是不同的。
与JS卡片相比，ArkTS卡片支持在卡片中运行逻辑代码，为确保ArkTS卡片发生问题后不影响卡片使用方应用的使用，ArkTS卡片新增了卡片渲染服务用于运行卡片页面代码widgets.abc，卡片渲染服务由卡片管理服务管理。卡片使用方的每个卡片组件都对应了卡片渲染服务里的一个渲染实例，同一应用提供方的渲染实例运行在同一个ArkTS虚拟机运行环境中，不同应用提供方的渲染实例运行在不同的ArkTS虚拟机运行环境中，通过ArkTS虚拟机运行环境隔离不同应用提供方卡片之间的资源与状态。开发过程中需要注意的是[globalThis](uiability-data-sync-with-ui.md#使用globalthis进行数据同步)对象的使用，相同应用提供方的卡片globalThis对象是同一个，不同应用提供方的卡片globalThis对象是不同的。
## ArkTS卡片的优势
......
zh-cn/application-dev/application-models/js-ui-widget-development.md
浏览文件 @ 005aa6fb
......@@ -94,7 +94,7 @@ Stage卡片开发，即基于[Stage模型](stage-model-development-overview.md)
创建Stage模型的卡片，需实现FormExtensionAbility生命周期接口。先参考[DevEco Studio服务卡片开发指南](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-development-service-widget-0000001263280425)生成服务卡片模板。
1. 在EntryFormAbility.ts中，导入相关模块。
1. 在EntryFormAbility.ets中，导入相关模块。
```ts
......@@ -105,7 +105,7 @@ Stage卡片开发，即基于[Stage模型](stage-model-development-overview.md)
import dataPreferences from '@ohos.data.preferences';
```
2. 在EntryFormAbility.ts中，实现FormExtension生命周期接口。
2. 在EntryFormAbility.ets中，实现FormExtension生命周期接口。
```ts
......@@ -174,7 +174,7 @@ Stage卡片开发，即基于[Stage模型](stage-model-development-overview.md)
"extensionAbilities": [
{
"name": "EntryFormAbility",
"srcEntry": "./ets/entryformability/EntryFormAbility.ts",
"srcEntry": "./ets/entryformability/EntryFormAbility.ets",
"label": "$string:EntryFormAbility_label",
"description": "$string:EntryFormAbility_desc",
"type": "form",
......@@ -545,6 +545,29 @@ onUpdateForm(formId) {
}
```
说明：
"data"中JSON Value支持多级嵌套数据，在更新数据时，需要注意携带完整数据。
例如:当前卡片显示07.18日Mr.Zhang的课程信息，示例如下。
```ts
"data": {
"Day": "07.18",
"teacher": {
"name": "Mr.Zhang",
"course": "Math"
}
}
```
当卡片内容需要更新为07.18日Mr.Li的课程信息时，需要传递待更新的完整数据，不能值传递单个数据项，如只传name或只传course，示例如下。
```ts
"teacher": {
"name": "Mr.Li",
"course": "English"
}
```
- 在UIAbility中接收router事件并获取参数
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或