diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-configuration.md b/zh-cn/application-dev/application-models/arkts-ui-widget-configuration.md index 6185654060f640e55da4100a86ad6c0509634bd9..183ac67bf051d5902269f08344160fffcd81f347 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-configuration.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-configuration.md @@ -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 | 表示该卡片的类型,当前支持如下两种类型:
- arkts:当前卡片为ArkTS卡片。
- hml:当前卡片为JS卡片。 | 字符串 | 可缺省,缺省值为hml | - | window | 用于定义与显示窗口相关的配置。 | 对象 | 可缺省 | + | window | 用于定义与显示窗口相关的配置。 | 对象 | 可缺省,缺省值见表2。 | | isDefault | 表示该卡片是否为默认卡片,每个UIAbility有且只有一个默认卡片。
- true:默认卡片。
- false:非默认卡片。 | 布尔值 | 否 | - | colorMode | 表示卡片的主题样式,取值范围如下:
- auto:自适应。
- dark:深色主题。
- light:浅色主题。 | 字符串 | 可缺省,缺省值为“auto”。 | + | 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:表示不支持周期性刷新。 | 布尔类型 | 否 | @@ -56,6 +56,13 @@ | dataProxyEnabled | 表示卡片是否支持[卡片代理刷新](./arkts-ui-widget-update-by-proxy.md),取值范围:
- true:表示支持代理刷新。
- false:表示不支持代理刷新。
设置为true时,[定时刷新和下次刷新不生效,但不影响定点刷新](./arkts-ui-widget-update-by-time.md) | 布尔类型 | 可缺省,缺省值为false。 | | isDynamic | 表示此卡片是否为动态卡片(仅针对ArkTS卡片生效)。
- true:为动态卡片。
- false:为静态卡片,当卡片添加成功后,将以静态图显示。 | 布尔类型 | 可缺省,缺省值为true。 | + **表2** window对象的内部结构说明 + + | 属性名称 | 含义 | 数据类型 | 是否可缺省 | + | -------- | -------- | -------- | -------- | + | designWidth | 标识页面设计基准宽度。以此为基准,根据实际设备宽度来缩放元素大小。 | 数值 | 可缺省,缺省值为720px。 | + | autoDesignWidth | 标识页面设计基准宽度是否自动计算。当配置为true时,designWidth将会被忽略,设计基准宽度由设备宽度与屏幕密度计算得出。 | 布尔值 | 可缺省,缺省值为false。 | + 配置示例如下: diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-creation.md b/zh-cn/application-dev/application-models/arkts-ui-widget-creation.md index 34cbeedd2fa4a2df106b9b32e4f5d1b2917200a6..71c48410fea0aee1420ae1dab44b9dfa81ff1e63 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-creation.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-creation.md @@ -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) diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md index 0289fc67984d9cce33aed0ddc3d537fa3a7c7a40..0cb866cfd4b67db3e3091ad43355aca9484154c4 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md @@ -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'; diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-formextensionability.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-formextensionability.md index 5ce615a7a3d201f0179fe871654cf614f8d88a21..dd1c84a41983ed354da06789357626beb1d3126a 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-event-formextensionability.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-formextensionability.md @@ -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(); diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md index d4d7063c8fcdf15ea244e4259eaccf34f5a1eb1e..5ee24405260ed7ace73a2d17b51fe22b0ced315f 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md @@ -22,11 +22,13 @@ action参数说明: | **Key** | **Value** | **样例描述** | | -------- | -------- | -------- | | "action" | string | action的类型,支持三种预定义的类型:
- "router":跳转到提供方应用的指定UIAbility。
- "message":自定义消息,触发后会调用提供方FormExtensionAbility的[onFormEvent()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onformevent)生命周期回调。
- "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" / "call" 类型时跳转的包名,可选。 | -| "moduleName" | string | "router" / "call" 类型时跳转的模块名,可选。 | -| "abilityName" | string | "router" / "call" 类型时跳转的UIAbility名,必填。 | -| "params" | Object | 当前action携带的额外参数,内容使用JSON格式的键值对形式。"call" 类型时需填入参数'method',且类型需要为string类型,用于触发UIAbility中对应的方法,必填。 | +| "bundleName" | string | "action"为"router" / "call" 类型时跳转的包名,可选。 | +| "moduleName" | string | "action"为"router" / "call" 类型时跳转的模块名,可选。 | +| "abilityName" | string | "action"为"router" / "call" 类型时跳转的UIAbility名,必填。 | +| "params" | Object | 当前action携带的额外参数,内容使用JSON格式的键值对形式。必填。 | +>![icon-note.gif](public_sys-resources/icon-note.gif) **说明:** +>"action"为"call" 类型时,"params"需填入参数'method',且类型需为string类型,用于触发UIAbility中对应的方法。 `postCardAction()`接口示例代码: diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-router.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-router.md index 19fe644cd4c7bc00b692483ff2e57b853da23eef..f32017a7ed10f405f292bd6ad26139df5613d189 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-event-router.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-router.md @@ -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参数 diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-interaction-overview.md b/zh-cn/application-dev/application-models/arkts-ui-widget-interaction-overview.md index 8b16e5df4ed5b58dec26b233fe826dfed8bc0458..0ef91cf7071c85c6b5570a0b8e1665b7da757fb3 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-interaction-overview.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-interaction-overview.md @@ -1,6 +1,6 @@ # 卡片数据交互说明 -ArkTS卡片框架提供了updateForm()接口和requestForm()接口主动触发卡片的页面刷新。 +ArkTS卡片框架提供了updateForm()接口和requestForm()接口主动触发卡片的页面刷新,通过[LocalStorageProp](../quick-start/arkts-localstorage.md#localstorageprop)确认需要刷新的卡片数据。 ![WidgetLocalStorageProp](figures/WidgetLocalStorageProp.png) diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-lifecycle.md b/zh-cn/application-dev/application-models/arkts-ui-widget-lifecycle.md index 9b34f5c1d5300ff97d1efb23e00e2bd3345bf000..f3c90861a5d6cdd0ab39b940acd7d49defd9a374 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-lifecycle.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-lifecycle.md @@ -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'; diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-proxy.md b/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-proxy.md index cac283478e8ecb04d9e449dc46f38e3d40075d7e..12030b09d65dda9f8bcc970cd9d6aed8827cb3f9 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-proxy.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-proxy.md @@ -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 @@ 数据提供方提供的共享数据有两种类型: -- 过程数据,不会一直存储,有老化期,普通应用可以订阅。 +- 过程数据,不会一直存储,有老化期,所有应用都可以订阅。 - 持久化数据,仅系统应用可以订阅。 diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-status.md b/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-status.md index 59835a5d040fb802c25c73d12d746b2a19cd3bd2..fc550230a7a8b1188217f51fcef89f5009aeb400 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-status.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-status.md @@ -4,7 +4,7 @@ 相同的卡片可以添加到桌面上实现不同的功能,比如添加两张桌面的卡片,一张显示杭州的天气,一张显示北京的天气,设置每天早上7点触发定时刷新,卡片需要感知当前的配置是杭州还是北京,然后将对应城市的天气信息刷新到卡片上,以下示例介绍了如何根据卡片的状态动态选择需要刷新的内容。 -- 卡片配置文件:配置每天早上7点触发定时刷新 +- 卡片配置文件:配置每天早上7点触发定时刷新。 ```json { diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-time.md b/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-time.md index 0ffb74d98e2501afbbef89b567d8bed8945775b9..853cf48b68af6c9ec58b6110f6e5960c6d9955a3 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-time.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-time.md @@ -1,7 +1,5 @@ # 卡片定时刷新和定点刷新 -在使用定时和定点刷新功能之前,需要在form_config.json配置文件中设置`updateEnabled`字段为`true`,以启用周期性刷新功能。 - 当前卡片框架提供了如下几种按时间刷新卡片的方式: @@ -9,6 +7,7 @@ > **说明:** > + > 在使用定时和定点刷新功能之前,需要在form_config.json配置文件中设置`updateEnabled`字段为`true`,以启用周期性刷新功能。 > 当配置了`updateDuration`(定时刷新)后,该设置会优先于`scheduledUpdateTime`(定点刷新)生效,即使同时配置了两者,定点刷新也会被忽略。 ```json diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-working-principles.md b/zh-cn/application-dev/application-models/arkts-ui-widget-working-principles.md index e516a2add182c3f9627fc257c75714b4a9d55ba4..e40413e81bc389fd857b19081dc3b7bdd17159de 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-working-principles.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-working-principles.md @@ -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卡片的优势 diff --git a/zh-cn/application-dev/application-models/figures/WidgetModules.png b/zh-cn/application-dev/application-models/figures/WidgetModules.png index fe11622a2c1586fca143996158e6d39732193206..e9a91b92b7ff81b5ab8a014aeeb779eb0653f25a 100644 Binary files a/zh-cn/application-dev/application-models/figures/WidgetModules.png and b/zh-cn/application-dev/application-models/figures/WidgetModules.png differ diff --git a/zh-cn/application-dev/application-models/figures/WidgetPrinciple.png b/zh-cn/application-dev/application-models/figures/WidgetPrinciple.png index c8ecff746db659593e94a3aada2918f1b8bee6cc..c5dedca77157d72109f5c130ab84f30d73c72fae 100644 Binary files a/zh-cn/application-dev/application-models/figures/WidgetPrinciple.png and b/zh-cn/application-dev/application-models/figures/WidgetPrinciple.png differ diff --git a/zh-cn/application-dev/application-models/figures/WidgetRender.png b/zh-cn/application-dev/application-models/figures/WidgetRender.png index ea682368d70d8a7f208cc7482de7fcb1407155f7..e4273aacd523e2715c629d765710af67dab9f738 100644 Binary files a/zh-cn/application-dev/application-models/figures/WidgetRender.png and b/zh-cn/application-dev/application-models/figures/WidgetRender.png differ diff --git a/zh-cn/application-dev/application-models/js-ui-widget-development.md b/zh-cn/application-dev/application-models/js-ui-widget-development.md index 7ef75f5fb7aeb381dea35b14255d704ebc13863d..85be9e3325327ce6ae69da98e88a909c167757be 100644 --- a/zh-cn/application-dev/application-models/js-ui-widget-development.md +++ b/zh-cn/application-dev/application-models/js-ui-widget-development.md @@ -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事件并获取参数