HarmonyOS鸿蒙Next实战卡片开发 01

HarmonyOS鸿蒙Next实战卡片开发 01

HarmonyOS Next 实战卡片开发 01

介绍

Form Kit（卡片开发服务）提供一种界面展示形式，可以将应用的重要信息或操作前置到服务卡片（以下简称“卡片”），以达到服务直达、减少跳转层级的体验效果。卡片常用于嵌入到其他应用（当前被嵌入方即卡片使用方只支持系统应用，例如桌面）中作为其界面显示的一部分，并支持拉起页面、发送消息等基础的交互能力。

如：

直达服务

最后，工程下会多出主要的三个文件，作用如下

新建一个卡片

卡片的类型主要有两个：

  1. 静态卡片
    • 如果界面需要频繁刷新，不建议使用静态卡片，因为每一次刷新，都会导致卡片实例创建和销毁
  2. 动态卡片
    • 如果界面需要频繁刷新，建议使用动态卡片

卡片的配置

卡片的配置文件 在 entry/src/main/resources/base/profile/form_config.json 路径

我们实际开发中，可能需要尤为关注的主要有以下几个：

  • displayName 卡片对外显示的名称
  • description 卡片对外显示的描述
  • supportDimensions 卡片支持的尺寸 ，支持多个
  • defaultDimension 卡片默认显示的尺寸
  • isDynamic 是否是动态卡片
  • updateEnabled 是否允许 定时刷新或者定点刷新
  • scheduledUpdateTime 定点刷新，精确到分钟。 如 10:30
  • updateDuration 定时刷新，以30分钟为一个单位，如 1 表示 1 * 30分钟

对应的配置说明:

属性名称 含义 数据类型 是否可缺省
name 表示卡片的名称，字符串最大长度为127字节。 字符串 否
displayName 表示卡片的显示名称。取值可以是名称内容，也可以是对名称内容的资源索引，以支持多语言。字符串最小长度为1字节，最大长度为30字节。 字符串 否
description 表示卡片的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。字符串最大长度为255字节。 字符串 可缺省，缺省为空。
src 表示卡片对应的UI代码的完整路径。当为ArkTS卡片时，完整路径需要包含卡片文件的后缀，如："./ets/widget/pages/WidgetCard.ets"。当为JS卡片时，完整路径无需包含卡片文件的后缀，如："./js/widget/pages/WidgetCard" 字符串 否
uiSyntax 表示该卡片的类型，当前支持如下两种类型：- arkts：当前卡片为ArkTS卡片。- hml：当前卡片为JS卡片。 字符串 可缺省，缺省值为hml
window 用于定义与显示窗口相关的配置。 对象 可缺省，缺省值见表2。
isDefault 表示该卡片是否为默认卡片，每个UIAbility有且只有一个默认卡片。- true：默认卡片。- false：非默认卡片。 布尔值 否
colorMode 表示卡片的主题样式，取值范围如下：- auto：跟随系统的颜色模式值选取主题。- dark：深色主题。- light：浅色主题。 字符串 可缺省，缺省值为“auto”。
supportDimensions 表示卡片支持的外观规格，取值范围：- 1 * 2：表示1行2列的二宫格。- 2 * 2：表示2行2列的四宫格。- 2 * 4：表示2行4列的八宫格。- 4 * 4：表示4行4列的十六宫格。- 1 * 1：表示1行1列的圆形卡片。- 6 * 4：表示6行4列的二十四宫格。 字符串数组 否
defaultDimension 表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。 字符串 否
updateEnabled 表示卡片是否支持周期性刷新（包含定时刷新和定点刷新），取值范围：- true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，当两者同时配置时，定时刷新优先生效。- false：表示不支持周期性刷新。 布尔类型 否
scheduledUpdateTime 表示卡片的定点刷新的时刻，采用24小时制，精确到分钟。说明：updateDuration参数优先级高于scheduledUpdateTime，两者同时配置时，以updateDuration配置的刷新时间为准。 字符串 可缺省，缺省时不进行定点刷新。
updateDuration 表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数。当取值为0时，表示该参数不生效。当取值为正整数N时，表示刷新周期为30*N分钟。说明：updateDuration参数优先级高于scheduledUpdateTime，两者同时配置时，以updateDuration配置的刷新时间为准。 数值 可缺省，缺省值为“0”。
formConfigAbility 表示卡片的配置跳转链接，采用URI格式。 字符串 可缺省，缺省值为空。
metadata 表示卡片的自定义信息，参考Metadata数组标签。 对象 可缺省，缺省值为空。
dataProxyEnabled 表示卡片是否支持卡片代理刷新，取值范围：- true：表示支持代理刷新。- false：表示不支持代理刷新。设置为true时，定时刷新和下次刷新不生效，但不影响定点刷新。 布尔类型 可缺省，缺省值为false。
isDynamic 表示此卡片是否为动态卡片（仅针对ArkTS卡片生效）。- true：为动态卡片 。- false：为静态卡片。 布尔类型 可缺省，缺省值为true。
formVisibleNotify 表示是否允许卡片使用卡片可见性通知（仅对系统应用的卡片生效）。 布尔类型 可缺省，缺省值为false。
transparencyEnabled 表示是否支持卡片使用方设置此卡片的背景透明度（仅对系统应用的ArkTS卡片生效。）。- true：支持设置背景透明度 。- false：不支持设置背景透明度。 布尔类型 可缺省，缺省值为false。
fontScaleFollowSystem 表示卡片使用方设置此卡片的字体是否支持跟随系统变化。- true：支持跟随系统字体大小变化 。- false：不支持跟随系统字体大小变化。 布尔类型 可缺省，缺省值为true。
supportShapes 表示卡片的显示形状，取值范围如下：- rect：表示方形卡片。- circle：表示圆形卡片。 字符串 可缺省，缺省值为“rect”。

表2 window对象的内部结构说明

属性名称 含义 数据类型 是否可缺省
designWidth 标识页面设计基准宽度。以此为基准，根据实际设备宽度来缩放元素大小。 数值 可缺省，缺省值为720px。
autoDesignWidth 标识页面设计基准宽度是否自动计算。当配置为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。 布尔值 可缺省，缺省值为false。

卡片开发支持的能力

大部分情况下，页面支持的能力和卡片支持的能力大致一样。但是实际开发中，结合两方面来考量：

  • 开发文档中，卡片可以使用的能力会有对应的文档说明
  • 考虑到文档存在不完善的情况，以模拟器+真机实际测试为准

主要的限制

  • 当导入模块时，仅支持导入标识“支持在ArkTS卡片中使用”的模块。
  • 不支持导入共享包。
  • 不支持使用native语言开发。
  • 仅支持声明式范式的部分组件、事件、动效、数据管理、状态管理和API能力。
  • 卡片的事件处理和使用方的事件处理是独立的，建议在使用方支持左右滑动的场景下卡片内容不要使用左右滑动功能的组件，以防手势冲突影响交互体验。
  • 暂不支持极速预览。
  • 暂不支持断点调试能力。
  • 暂不支持Hot Reload热重载。
  • 暂不支持setTimeOut。

卡片的生命周期

卡片的生命周期文件在

支持以下生命周期：

描述 触发时机
onAddForm 卡片被创建时触发
onCastToNormalForm 卡片转换成常态卡片时触发
onUpdateForm 卡片被更新时触发（调用 updateForm 时）
onChangeFormVisibility 卡片可见性修改时触发
onFormEvent 卡片发起特定事件时触发（message）
onRemoveForm 卡片被卸载时触发
onConfigurationUpdate 当系统配置更新时调用
onAcquireFormState 卡片状态发生改变时触发
onStop 卡片进程退出时触发

卡片通信

实际场景中，因为卡片的运行是可以独立于应用或者页面。所以开发难点其实是在于卡片之间或者卡片和应用之间的通信。

为了方便理解，我们做出以下区分

  1. 应用或者页面
  2. 卡片

解释

  1. 卡片组件和卡片的Ability之间通过message和onAddForm通信

    • 卡片Ability通过onAddForm中的返回值向卡片组件通信
    • 卡片组件通过触发 message 事件向卡片Ability 通信

  2. 卡片组件和应用的Ability之间同router和call事件

    • 卡片组件通过触发卡片组件通过触发call和router事件向 应用Ability 通信
    • 应用通过updateForm向卡片组件通信

  3. 卡片通过LocalStorage装饰器接收数据

  4. 首选项可以在以上的任意地方进行通信

卡片Ability向卡片组件通信

卡片在创建时，会触发onAddForm生命周期，此时返回数据可以直接传递给卡片

另外卡片在被卸载时，会触发onRemoveForm生命周期

卡片Ability

formBindingData：提供卡片数据绑定的能力，包括FormBindingData对象的创建、相关信息的描述

卡片组件

卡片组件通过LocalStorage来接收onAddForm中返回的数据

效果

postCardAction

卡片主动向外通信都是通过触发postCardAction来实现的。postCardAction支持三种事件类型

事件类型 描述
router 会拉起应用，前台会展示页面，会触发应用的onCreate和onNewWant生命周期
call 会拉起应用，但是会在后台的形式运行。需要申请后台运行权限，可以进行比较耗时的任务
message 不会拉起应用，一定时间内（10s）如果没有更新的事件，会被销毁，适合做不太耗时的任务

卡片组件向卡片Ability通信

卡片页面中可以通过postCardAction接口触发message事件拉起FormExtensionAbility中的onUpdateForm

onUpdateForm中通过updateForm来返回数据

卡片组件

记得要携带formId过去，因为返回数据时需要根据formId找到对应的卡片

卡片Ability

当卡片组件发起message事件时，我们可以通过onFormEvent监听到

效果

卡片组件发起向应用EntryAbility通信 router

router事件的特定是会拉起应用，前台会展示页面，会触发应用的onCreate和onNewWant生命周期

我们可以利用这个特性做唤起特定页面并且传递数据。

当触发router事件时，

  1. 如果应用没有在运行，便触发 onCreate事件
  2. 如果应用正在运行，便触发onNewWant事件

卡片组件

  1. 提前新建好两个页面 pageA和pageB

  2. 卡片组件新建两个按钮，实现拉起应用并且显示特定页面

应用EntryAbility

分布在应用的onCreate和onNewWant编写逻辑实现跳转页面

效果

此时实现的效果是，不管有没有启动过页面，我们都可以直接点击卡片跳转到对应的页面

卡片组件发起向应用EntryAbility通信 call

卡片还可以通过postCardAction的触发call事件，call会拉起应用，但是会在后台的形式运行。需要申请后台运行权限，可以进行比较耗时的任务

需要注意的是：

  1. 申请后台运行应用权限

卡片组件

卡片组件触发call事件，参数中必须携带method属性，用来区分不同的方法

应用EntryAbility

应用EntryAbility在onCreate中，通过 callee来监听不同的method事件。然后根据需求来处理业务

效果

总结

本文主要介绍了 HarmonyOS Next 中的卡片开发，包括卡片的基本概念、类型、新建卡片、配置、支持的能力、生命周期、通信等方面的内容。

  1. 卡片概述
    • Form Kit 提供将应用重要信息或操作前置到服务卡片的界面展示形式，可减少跳转层级，常用于嵌入系统应用（如桌面），支持拉起页面、发送消息等交互能力。
    • 主要有静态卡片（不建议界面频繁刷新时使用）和动态卡片（适用于界面频繁刷新）。
  2. 卡片开发支持的能力
    • 页面支持的能力与卡片大致相同，但实际开发需结合开发文档说明和模拟器及真机测试为准。
    • 卡片开发存在诸多限制，如仅支持导入特定模块、不支持导入共享包、不支持 native 语言开发、仅支持声明式范式的部分组件等，还暂不支持极速预览、断点调试、Hot Reload 热重载和 setTimeOut 等功能。
  3. 卡片的生命周期
    • 卡片的生命周期文件为EntryFormAbility.ets，支持多个生命周期，如onAddForm（卡片创建时触发）、onCastToNormalForm（转换成常态卡片时触发）、onUpdateForm（卡片更新时触发）等，每个生命周期有其特定的触发时机。
  4. 卡片通信
    • 实际场景中，需区分应用或页面与卡片之间的通信。卡片组件和卡片 Ability 之间通过 message 和onAddForm通信；卡片组件和应用的 Ability 之间通过router和call事件以及updateForm通信；卡片通过LocalStorage装饰器接收数据；首选项可在任意地方通信。

更多关于HarmonyOS鸿蒙Next实战卡片开发 01的实战教程也可以访问 https://www.itying.com/category-93-b0.html

7 回复

老师写的太好了，点赞。

更多关于HarmonyOS鸿蒙Next实战卡片开发 01的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


博主你好，我现在在卡片方面遇到一点问题，我的项目是天气类型的项目，当应用杀掉后台之后，开了定时更新，也无法获取到应用内部的数据，当应用关闭进程之后，卡片应该怎么实现半小时刷新一次数据呢？应用内部数据的刷新，只有当进入应用之后，会自动刷新获取最新数据。

请问一下，卡片销毁时，如何将卡片的id发送到app。我需要将销毁的卡片id从应用的首选项中删除。onRemoveForm的生命周期中，貌似那不到this，所以触发不了call事件

使用首选项来管理卡片id，该功能的我的卡片第三篇文章有演示。

https://developer.huawei.com/consumer/cn/forum/topic/0207165837073249234?fid=0109140870620153026

言简意赅！！！

HarmonyOS鸿蒙Next实战卡片开发主要涉及使用ArkUI框架进行卡片的设计与实现。卡片是鸿蒙系统中的一种轻量级UI组件，用于在桌面上展示关键信息或提供快捷操作。开发过程中，开发者需要使用ArkTS语言进行卡片逻辑的编写，并通过ArkUI的组件库构建卡片界面。

卡片的开发流程包括以下几个步骤：

  1. 创建卡片工程：在DevEco Studio中创建新的卡片工程，选择相应的模板和配置。

  2. 设计卡片布局：使用ArkUI的组件（如Text、Image、Button等）设计卡片的布局。布局文件通常以.ets为后缀，开发者可以通过XML或代码的方式定义卡片的UI结构。

  3. 编写卡片逻辑：在ArkTS中编写卡片的业务逻辑，处理用户交互、数据更新等操作。卡片逻辑通常放在EntryAbility或EntryFormAbility中实现。

  4. 卡片数据绑定：通过ArkUI的数据绑定机制，将卡片的数据与UI组件进行关联，实现数据的动态更新。

  5. 卡片生命周期管理：鸿蒙系统为卡片提供了完整的生命周期管理，开发者需要重写onCreate、onDestroy等生命周期方法，确保卡片在不同状态下的正确行为。

  6. 卡片调试与测试：通过DevEco Studio的模拟器或真机进行卡片的调试与测试，确保卡片的功能和性能符合预期。

  7. 卡片发布：完成开发后，将卡片打包并发布到鸿蒙应用市场或设备的桌面。

HarmonyOS鸿蒙Next的卡片开发强调模块化、轻量化和高效性，开发者可以通过ArkUI框架快速构建出功能丰富、性能优异的卡片应用。

在HarmonyOS鸿蒙Next中，卡片开发是提升用户体验的重要功能。首先，通过DevEco Studio创建项目，选择“Service Widget”模板。接着，在resources/base/layout目录下设计卡片布局，使用XML定义界面元素。然后，在entry/src/main/ets/widget中编写逻辑代码，处理数据绑定和交互事件。最后，通过form_config.json配置卡片的尺寸和更新策略。开发完成后，使用模拟器或真机进行测试，确保卡片功能正常。

回到顶部