关于Harmony OS中卡片的使用方法

关于Harmony OS中卡片的使用方法

在Harmony OS中，静态卡片是一种非常有用的组件，用于提供应用内功能组件的交互和信息展示。本文将详细介绍如何在Harmony OS中使用静态卡片以及相关的API接口。

1. 概述

静态卡片是Harmony OS中的一种交互组件，用于静态卡片内部和提供方应用间的交互。它支持三种类型的事件：router、message和call。这些事件可以触发不同的操作，如跳转到指定的UIAbility、自定义消息触发后调用FormExtensionAbility的onFormEvent回调以及后台启动提供方应用等。

静态卡片只能在静态卡片中使用，并且该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

2. 子组件

静态卡片组件仅支持单个子组件。

3. 接口

3.1 FormLink(options: FormLinkOptions)

FormLink是一个用于创建静态卡片交互组件的接口。它接受一个参数options，定义卡片信息。

3.1.1 参数说明

不推荐通过params传递卡片内部的状态变量。

3.1.2 原子化服务API与系统能力

• 从API version 11开始，该接口支持在原子化服务中使用。
• 从API version 11开始，该接口支持在原子化服务中使用。
• 系统能力：SystemCapability.ArkUI.ArkUI.Full

3.2 AddFormMenuItem(want: Want, componentId: string, options?: AddFormOptions): void

AddFormMenuItem是一个用于实现应用内长按组件生成“添加至桌面”菜单的接口。开发者将卡片数据以及应用内功能组件ID传给卡片框架，点击事件会根据组件ID获取应用内功能组件的快照和位置，用于添加到桌面时的过渡动效。

3.2.1 参数说明

3.2.2 AddFormMenuOptions对象说明

3.2.3 FormMenuItemStyle对象说明

说明：仅在style配置为空或不配置时，使用默认的图标和menu文字。

3.3 事件

支持菜单点击事件。

4. 示例代码

以下是一个简单的示例代码，展示了如何使用FormLink接口创建静态卡片并处理不同类型的事件：

@Entry
@Component
struct FormLinkDemo {
  build() {
    Column() {
      Text("这是一个静态卡片")
        .fontSize(20)
        .margin(10)

      // router事件用于静态卡片跳转到对应的UIAbility
      FormLink({
        action: "router",
        abilityName: "com.example.MainAbility",
        params: {
          'message': 'testForRouter' // 自定义要发送的message
        }
      }) {
        Button("router event").width(120)
      }.margin(10)

      // message事件触发FormExtensionAbility的onFormEvent生命周期
      FormLink({
        action: "message",
        abilityName: "com.example.MainAbility",
        params: {
          'messageEvent': 'messageEvent' // 自定义要发送的message
        }
      }) {
        Button("message event").width(120)
      }.margin(10)

      // call事件用于触发UIAbility中对应的方法
      FormLink({
        action: "call",
        abilityName: "com.example.MainAbility",
        params: {
          'method': 'funA', // 在EntryAbility中调用的方法名
          'num': 1 // 需要传递的其他参数
        }
      }) {
        Button("call event").width(120)
      }.margin(10)

      // router事件用于静态卡片deeplink跳转到对应的UIAbility
      FormLink({
        action: "router",
        uri: 'example://uri.ohos.com/link_page',
        params: {
          'message': 'router msg for static uri deeplink' // 自定义要发送的message
        }
      }) {
        Button("deeplink event").width(120)
      }.margin(10)
    }
    .justifyContent(FlexAlign.Center)
    .width('100%')
    .height('100%')
  }
}

5. 权限与配置

在使用FormLink接口时，需要确保应用具有相应的权限。例如，当使用call事件时，需要具备后台运行权限（ohos.permission.KEEP_BACKGROUND_RUNNING）。此外，还需要在module.json5文件中进行相应的配置：

{
  "abilities": [{
    "skills": [{
      "uris": [{
        "scheme": "example",
        "host": "uri.ohos.com",
        "path": "link_page"
      }]
    }]
  }]
}

6. 总结

本文介绍了在Harmony OS中使用静态卡片的方法，包括如何创建静态卡片、处理不同类型的事件以及相关的API接口。通过这些接口，开发者可以实现丰富的交互功能，提升用户体验。希望本文对你有所帮助！