当前位置：首页 > article >正文

关于HarmonyOS Next中卡片的使用方法

article 2025/1/5 6:20:20

关于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 参数说明

名称	类型	必填	说明
action	string	是	支持三种预定义的类型：router、message和call。
moduleName	string		action为router/call类型时跳转的模块名。
bundleName	string		action为router/call类型时跳转的包名。
abilityName	string		action为router/call类型时跳转的UIAbility名。
uri11+	string		action为router类型时跳转的URI标识符。uri和abilityName同时存在时，abilityName优先。
params	Object		当前action携带的额外参数，使用JSON格式的键值对形式。call类型时需填入`method`参数，且类型为字符串。

不推荐通过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 参数说明

名称	参数类型	必填	装饰器类型	说明
want	Want	是	@Prop	待发布功能组件的want信息。
componentId	string	是	-	应用内功能组件ID，组件ID对应的界面与待添加的服务卡片界面相似。
AddFormOptions	AddFormOptions	否	-	添加卡片选项。

3.2.2 AddFormMenuOptions对象说明

名称	参数类型	必填	说明
formBindingData	FormBindingData	否	卡片数据。
callback	AsyncCallback	否	返回结果的回调。
style	FormMenuItemStyle	否	菜单自定义样式信息。

3.2.3 FormMenuItemStyle对象说明

名称	参数类型	必填	说明
options	MenuItemOptions	否	包含设置MenuItem的各项信息。

说明：仅在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"
      }]
    }]
  }]
}