关于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接口。通过这些接口，开发者可以实现丰富的交互功能，提升用户体验。希望本文对你有所帮助！
