服务卡片

服务卡片类似于iOS中的小组件，提供了在手机桌面端显示和更新卡片的能力

ArkTS卡片架构

卡片使用方，目前只有系统桌面

桌面上可以放置多个应用图标和卡片
应用图标点击后启动应用进程，不支持交互
卡片有不同的规格，可进行交互，如实现按钮进行卡片刷新、跳转到应用

卡片提供方，通常指我们的App

App可以同时包含卡片功能和正常业务功能
卡片功能中的FormExtensionAbility主要用于处理卡片的创建、销毁、刷新等生命周期回调
卡片功能中的页面是需要我们自定义的UI

ArkTS卡片运行机制

实现原理

卡片使用方和提供方都依赖 卡片管理服务SDK
卡片管理服务：用于管理系统中所添加卡片的常驻代理服务，提供formProvider接口能力，同时提供卡片对象的管理与使用以及卡片周期性刷新等能力。
卡片渲染服务：用于管理卡片渲染实例，渲染实例与卡片使用方上的卡片组件一一绑定。卡片渲染服务运行卡片页面代码widgets.abc进行渲染，并将渲染后的数据发送至卡片使用方对应的卡片组件

卡片渲染服务用于运行卡片页面代码widgets.abc，卡片渲染服务由卡片管理服务管理。
卡片使用方的每个卡片组件都对应了卡片渲染服务里的一个渲染实例，同一应用提供方的渲染实例运行在同一个虚拟机运行环境中，不同应用提供方的渲染实例运行在不同的虚拟机运行环境中，通过虚拟机运行环境隔离不同应用提供方卡片之间的资源与状态。
开发过程中需要注意的是globalThis对象的使用，相同应用提供方的卡片globalThis对象是同一个，不同应用提供方的卡片globalThis对象是不同的

ArkTS卡片相关模块

FormExtensionAbility：卡片扩展模块，提供卡片创建、销毁、刷新等生命周期回调
页面布局（Card.ets）：提供声明式范式的UI接口能力
卡片配置：包含FormExtensionAbility的配置和卡片的配置

创建一个ArkTS卡片

创建步骤

在 Module级别右键，创建一个 Service Widget，然后命名即可
创建完成后，工程中会新增相关文件：卡片生命周期管理文件（EntryFormAbility.ts）、卡片页面文件（WidgetCard.ets）和卡片配置文件（form_config.json)

配置文件

ArkTS卡片生命周期

主要需要实现FormExtensionAbility生命周期接口

ts 复制代码

import formInfo from '@ohos.app.form.formInfo';
import formBindingData from '@ohos.app.form.formBindingData';
import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
import formProvider from '@ohos.app.form.formProvider';

export default class EntryFormAbility extends FormExtensionAbility {
  onAddForm(want) {
    console.info('[EntryFormAbility] onAddForm');
    // 在入参want中可以取出卡片的唯一标识：formId
    let formId: string = want.parameters[formInfo.FormParam.IDENTITY_KEY];
    // 使用方创建卡片时触发，提供方需要返回卡片数据绑定类
    let obj = {
      'title': 'titleOnAddForm',
      'detail': 'detailOnAddForm'
    };
    let formData = formBindingData.createFormBindingData(obj);
    return formData;
  }

  onCastToNormalForm(formId) {
    // Called when the form provider is notified that a temporary form is successfully
    // converted to a normal form.
    // 使用方将临时卡片转换为常态卡片触发，提供方需要做相应的处理
    console.info(`[EntryFormAbility] onCastToNormalForm, formId: ${formId}`);
  }

  onUpdateForm(formId) {
    // 若卡片支持定时更新/定点更新/卡片使用方主动请求更新功能，则提供方需要重写该方法以支持数据更新
    console.info('[EntryFormAbility] onUpdateForm');
    let obj = {
      'title': 'titleOnUpdateForm',
      'detail': 'detailOnUpdateForm'
    };
    let formData = formBindingData.createFormBindingData(obj);
    formProvider.updateForm(formId, formData).catch((err) => {
      if (err) {
        // 异常分支打印
        console.error(`[EntryFormAbility] Failed to updateForm. Code: ${err.code}, message: ${err.message}`);
        return;
      }
    });
  }

  onChangeFormVisibility(newStatus) {
    // Called when the form provider receives form events from the system.
    // 需要配置formVisibleNotify为true，且为系统应用才会回调
    console.info('[EntryFormAbility] onChangeFormVisibility');
  }

  onFormEvent(formId, message) {
    // Called when a specified message event defined by the form provider is triggered.
    // 若卡片支持触发事件，则需要重写该方法并实现对事件的触发
    console.info('[EntryFormAbility] onFormEvent');
  }

  onRemoveForm(formId) {
    // Called to notify the form provider that a specified form has been destroyed.
    // 当对应的卡片删除时触发的回调，入参是被删除的卡片ID
    console.info('[EntryFormAbility] onRemoveForm');
  }

  onConfigurationUpdate(config) {
    // 当系统配置信息置更新时触发的回调
    console.info('[EntryFormAbility] configurationUpdate:' + JSON.stringify(config));
  }

  onAcquireFormState(want) {
    // Called to return a {@link FormState} object.
    // 卡片提供方接收查询卡片状态通知接口，默认返回卡片初始状态。
    return formInfo.FormState.READY;
  }
}

卡片事件能力

ArkTS卡片中提供了postCardAction()接口用于卡片内部和提供方应用间的交互
当前支持router、message和call三种类型的事件，仅在卡片中可以调用

router 在前台启动App并触发相关回调。详见使用router事件跳转到指定UIAbility
- App首次启动时，触发 UIAbility 的onCreate回调，在want参数中可以获取到相关信息
- App已经启动时，触发 UIAbility 的 onNewWant 回调
call 在后台拉起App并触发相关回调。详见使用call事件拉起指定UIAbility到后台
message 直接调起 FormExtensionAbility，触发 FormExtensionAbility的onFormEvent回调。详见通过message事件刷新卡片内容

卡片数据更新能力

ArkTS卡片框架提供了updateForm()和requestForm()接口主动触发卡片的页面刷新

updateForm()是App更新卡片的API，一般用于自有逻辑的更新。比如一些卡片事件回调回来，需要刷新卡片数据

requestForm()是系统更新卡片的API，一般用于定时、定点刷新卡片。详见使用方刷新卡片内容（仅对系统应用开放）

参考资料

服务卡片概述

鸿蒙应用开发-初见：服务卡片

服务卡片

实现原理

参考资料