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

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

news 来源：原创 2025/7/15 6:40:52

关于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事件用于静态卡片跳转到对应的UIAbilityFormLink({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跳转到对应的UIAbilityFormLink({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接口。通过这些接口，开发者可以实现丰富的交互功能，提升用户体验。希望本文对你有所帮助！