HarmonyOS Next 实战卡片开发 01

HarmonyOS Next 实战卡片开发 01

介绍

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

如：

直达服务

要完成的案例

新建一个卡片

卡片的类型主要有两个：

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

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

新建一个卡片效果

卡片的配置

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

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

1. displayName 卡片对外显示的名称

2. description 卡片对外显示的描述

   

   3. supportDimensions 卡片支持的尺寸 ，支持多个
   4. defaultDimension 卡片默认显示的尺寸
   5. isDynamic 是否是动态卡片
   6. updateEnabled 是否允许 定时刷新或者定点刷新
   7. scheduledUpdateTime 定点刷新，精确到分钟。 如 10:30
   8. updateDuration 定时刷新，以30分钟为一个单位，如 1 表示 1 * 30分钟

{
  "forms": [
    {
      "name": "widget",
      "displayName": "$string:widget_display_name",
      "description": "$string:widget_desc",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "colorMode": "auto",
      "isDynamic": true,
      "isDefault": true,
      "updateEnabled": false,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 1,
      "defaultDimension": "2*4",
      "supportDimensions": [
        "2*4"
      ]
    }
  ]
}

对应的配置说明:

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

卡片开发支持的能力

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

• 开发文档中，卡片可以使用的能力会有对应的文档说明

  

• 考虑到文档存在不完善的情况，以模拟器+真机实际测试为准

  

简单测试

entry/src/main/ets/widget/pages/WidgetCard.ets

主要的限制

• 当导入模块时，仅支持导入标识“支持在ArkTS卡片中使用”的模块。

• 不支持导入共享包。

• 不支持使用native语言开发。

• 仅支持声明式范式的部分组件、事件、动效、数据管理、状态管理和API能力。

• 卡片的事件处理和使用方的事件处理是独立的，建议在使用方支持左右滑动的场景下卡片内容不要使用左右滑动功能的组件，以防手势冲突影响交互体验。

• 暂不支持极速预览。

• 暂不支持断点调试能力。

• 暂不支持Hot Reload热重载。

• 暂不支持setTimeOut。

卡片的生命周期

卡片的生命周期文件在

entry/src/main/ets/entryformability/EntryFormAbility.ets

支持以下生命周期：

import { formBindingData, FormExtensionAbility, formInfo } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';

export default class EntryFormAbility extends FormExtensionAbility {
  onAddForm(want: Want) {
    let formData = '';
    return formBindingData.createFormBindingData(formData);
  }

  onCastToNormalForm(formId: string) {
  }

  onUpdateForm(formId: string) {
  }

  onFormEvent(formId: string, message: string) {
  }

  onRemoveForm(formId: string) {
  }

  onAcquireFormState(want: Want) {
    return formInfo.FormState.READY;
  }
};

卡片通信

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

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

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

解释

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

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

   

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

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

   

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

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

卡片Ability向卡片组件通信

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

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

卡片Ability

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

entry/src/main/ets/entryformability/EntryFormAbility.ets

import { formBindingData, FormExtensionAbility, formInfo } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';

export default class EntryFormAbility extends FormExtensionAbility {
  onAddForm(want: Want) {
    class FormData {
      // 每一张卡片创建时都会被分配一个唯一的id
      formId: string = want.parameters!['ohos.extra.param.key.form_identity'].toString();
    }

    let formData = new FormData()
    // 返回数据给卡片
    return formBindingData.createFormBindingData(formData);
  }

  onCastToNormalForm(formId: string) {
  }

  onUpdateForm(formId: string) {
  }

  onFormEvent(formId: string, message: string) {
  }

  onRemoveForm(formId: string) {
  }

  onAcquireFormState(want: Want) {
    return formInfo.FormState.READY;
  }
};

卡片组件

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

const localStorage = new LocalStorage()

@Entry(localStorage)
@Component
struct WidgetCard {
  // 接收onAddForm中返回的卡片Id
  @LocalStorageProp("formId")
  formId: string = "xxx"

  build() {
    Column() {
      Button(this.formId)
    }
    .width("100%")
    .height("100%")
    .justifyContent(FlexAlign.Center)
  }
}

效果

postCardAction

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

卡片组件向卡片Ability通信

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

onUpdateForm中通过updateForm来返回数据

卡片组件

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

entry/src/main/ets/widget/pages/WidgetCard.ets

const localStorage = new LocalStorage()

@Entry(localStorage)
@Component
struct WidgetCard {
  // 接收onAddForm中返回的卡片Id
  @LocalStorageProp("formId")
  formId: string = "xxx"
  @LocalStorageProp("num")
  num: number = 100

  build() {
    Column() {
      Button(this.formId)
      Button("message" + this.num)
        .onClick(() => {
          postCardAction(this, {
            action: 'message',
              // 提交过去的参数
            params: { num: this.num, aa: 200, formId: this.formId }
          });
        })

    }
    .width("100%")
    .height("100%")
    .justifyContent(FlexAlign.Center)
  }
}

卡片Ability

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

entry/src/main/ets/entryformability/EntryFormAbility.ets

import { formBindingData, FormExtensionAbility, formInfo, formProvider } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';

export default class EntryFormAbility extends FormExtensionAbility {
  onAddForm(want: Want) {
    class FormData {
      // 每一张卡片创建时都会被分配一个唯一的id
      formId: string = want.parameters!['ohos.extra.param.key.form_identity'].toString();
    }

    let formData = new FormData()
    // 返回数据给卡片
    return formBindingData.createFormBindingData(formData);
  }

 // ...

  onFormEvent(formId: string, message: string) {
    //   接收到卡片通过message事件传递的数据
    // message {"num":100,"aa":200,"params":{"num":100,"aa":200},"action":"message"}
    interface IData {
      num: number
      aa: number
    }

    interface IRes extends IData {
      params: IData,
      action: "message"
      formId: string
    }

    const params = JSON.parse(message) as IRes

    interface IRet {
      num: number
    }

    const data: IRet = {
      num: params.num + 100
    }

    const formInfo = formBindingData.createFormBindingData(data)
    // 返回数据给对应的卡片
    formProvider.updateForm(params.formId, formInfo)
  }

};

效果

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

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

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

当触发router事件时，

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

卡片组件

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

   

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

   

entry/src/main/ets/widget/pages/WidgetCard.ets

const localStorage = new LocalStorage()

@Entry(localStorage)
@Component
struct WidgetCard {
  // 接收onAddForm中返回的卡片Id
  @LocalStorageProp("formId")
  formId: string = "xxx"
  @LocalStorageProp("num")
  num: number = 100

  build() {
    Column() {
      // Button(this.formId)
      // Button("message" + this.num)
      //   .onClick(() => {
      //     postCardAction(this, {
      //       action: 'message',
      //       params: { num: this.num, aa: 200, formId: this.formId }
      //     });
      //   })

      Button("A页面")
        .onClick(() => {
          postCardAction(this, {
            action: 'router',
            abilityName: 'EntryAbility', // 只能跳转到当前应用下的UIAbility
            params: {
              targetPage: 'pages/PageA',
            }
          });
        })
      Button("B页面")
        .onClick(() => {
          postCardAction(this, {
            action: 'router',
            abilityName: 'EntryAbility', // 只能跳转到当前应用下的UIAbility
            params: {
              targetPage: 'pages/PageB',
            }
          });
        })

    }
    .width("100%")
    .height("100%")
    .justifyContent(FlexAlign.Center)
  }
}

应用EntryAbility

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

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { router, window } from '@kit.ArkUI';
import { formInfo } from '@kit.FormKit';

export default class EntryAbility extends UIAbility {
  // 要跳转的页面 默认是首页
  targetPage: string = "pages/Index"

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 判断是否带有formId 因为我们直接点击图标，也会拉起应用，此时不会有formId
    if (want.parameters && want.parameters[formInfo.FormParam.IDENTITY_KEY] !== undefined) {
      // 获取卡片的formId
      const formId = want.parameters![formInfo.FormParam.IDENTITY_KEY].toString();
      // 获取卡片传递过来的参数
      interface IData {
        targetPage: string
      }

      const params: IData = (JSON.parse(want.parameters?.params as string))
      this.targetPage = params.targetPage
      //   我们也可以在这里通过 updateForm(卡片id，数据) 来返回内容给卡片
    }
  }

  // 如果应用已经在运行，卡片的router事件不会再触发onCreate，会触发onNewWant
  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    const formId = want.parameters![formInfo.FormParam.IDENTITY_KEY].toString();
    // 获取卡片传递过来的参数
    interface IData {
      targetPage: string
    }

    const params: IData = (JSON.parse(want.parameters?.params as string))
    this.targetPage = params.targetPage
    // 跳转页面
    router.pushUrl({
      url: this.targetPage
    })
    //   我们也可以在这里通过 updateForm(卡片id，数据) 来返回内容给卡片
  }


  onWindowStageCreate(windowStage: window.WindowStage): void {

    // 跳转到对应的页面
    windowStage.loadContent(this.targetPage, (err) => {
      if (err.code) {
        return;
      }
    });
  }


  onForeground(): void {
    // Ability has brought to foreground
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground');
  }

  onBackground(): void {
    // Ability has back to background
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground');
  }
}

效果

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

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

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

时的任务

需要注意的是：

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

entry/src/main/module.json5

{
  "module": {
	// ...
    "requestPermissions": [
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING"
      }
    ],

2. 卡片组件触发call事件，参数中必须携带method属性，用来区分不同的方法
3. 应用EntryAbility在onCreate中，通过 callee来监听不同的method事件

卡片组件

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

const localStorage = new LocalStorage()

@Entry(localStorage)
@Component
struct WidgetCard {
  // 接收onAddForm中返回的卡片Id
  @LocalStorageProp("formId")
  formId: string = "xxx"
  @LocalStorageProp("num")
  num: number = 100

  build() {
    Column() {
      Button("call事件" + this.num)
        .onClick(() => {
          postCardAction(this, {
            action: 'call',
            abilityName: 'EntryAbility', // 只能跳转到当前应用下的UIAbility
            params: {
              // 如果事件类型是call，必须传递method属性，用来区分不同的事件
              method: "inc",
              formId: this.formId,
              num: this.num,
            }
          });
        })
    }
    .width("100%")
    .height("100%")
    .justifyContent(FlexAlign.Center)
  }
}

应用EntryAbility

entry/src/main/ets/entryability/EntryAbility.ets

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

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { router, window } from '@kit.ArkUI';
import { formBindingData, formInfo, formProvider } from '@kit.FormKit';
import { rpc } from '@kit.IPCKit';

// 占位 防止语法出错，暂无实际作用
class MyParcelable implements rpc.Parcelable {
  marshalling(dataOut: rpc.MessageSequence): boolean {
    return true
  }

  unmarshalling(dataIn: rpc.MessageSequence): boolean {
    return true
  }
}


export default class EntryAbility extends UIAbility {
  // 要跳转的页面 默认是首页
  targetPage: string = "pages/Index"

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    //   监听call事件中的特定方法
    this.callee.on("inc", (data: rpc.MessageSequence) => {
      // data中存放的是我们的参数
      interface IRes {
        formId: string
        num: number
      }

      // 读取参数
      const params = JSON.parse(data.readString() as string) as IRes

      interface IData {
        num: number
      }

      // 修改数据
      const info: IData = {
        num: params.num + 100
      }
      // 响应数据
      const dataInfo = formBindingData.createFormBindingData(info)
      formProvider.updateForm(params.formId, dataInfo)

      // 防止语法报错，暂无实际应用
      return new MyParcelable()
    })

  }


  onWindowStageCreate(windowStage: window.WindowStage): void {

    // 跳转到对应的页面
    windowStage.loadContent(this.targetPage, (err) => {
      if (err.code) {
        return;
      }
    });
  }


  onForeground(): void {
    // Ability has brought to foreground
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground');
  }

  onBackground(): void {
    // Ability has back to background
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground');
  }
}

效果

总结

本文主要介绍了 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装饰器接收数据；首选项可在任意地方通

   信。

完整代码

https://gitee.com/ukSir/HarmonyOS-Next-Card.git

作者

作者：万少

链接：https://www.nutpi.net/

來源：坚果派 著作权归作者所有。

商业转载请联系作者获得授权，非商业转载请注明出处。