Form Kit（卡片开发服务）提供了一种在桌面、锁屏等系统应用上嵌入显示应用信息的开发框架和API，可以将应用内用户关注的重要信息或常用操作抽取到服务卡片（简称“卡片”）上，通过将卡片添加到桌面、锁屏等系统应用上，以达到信息展示、服务直达的便捷体验效果。
从API 18起，Form Kit提供formProvider.openFormManager接口，可从应用内拉起卡片管理页面，将卡片添加至桌面。
FormMenu组件封装了一个“添加至桌面”菜单，用于实现应用内长按组件生成“添加至桌面”菜单，点击该菜单，触发卡片添加至桌面操作。

解决方案

可以通过以下四种方式将卡片添加至桌面。

桌面长按应用图标，点击卡片，拉起卡片管理页面，将卡片添加至桌面。
桌面双指捏合，进入桌面管理，点击下方卡片，拉起卡片页面，将卡片添加至桌面。

应用内调用formProvider.openFormManager接口，拉起卡片管理页面，将卡片添加至桌面。formProvider.openFormManager接口根据传入的want参数，拉起卡片管理页面并优先显示参数对应的卡片。若want参数错误，则无法拉起卡片管理页面；若want参数的parameters字段不完整或指定的卡片不存在，则默认展示form_config.json中配置的默认卡片。

want参数需包含字段包括：
- bundleName：卡片所属应用的包名。
- abilityName：卡片所属的ability名称。
- parameters：展示卡片的参数，详见下文。
parameters需包含的字段包括：
- ohos.extra.param.key.form_dimension：卡片尺寸，参考FormDimension。
- ohos.extra.param.key.form_name：卡片名称，即form_config.json中卡片对应的name。
- ohos.extra.param.key.module_name：卡片所属的模块名称。

示例代码如下：

import { formProvider } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { Want } from '@kit.AbilityKit';
import { promptAction } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0x0000;

@Entry
@Component
struct Index {
  build() {
    Row() {
      Column() {
        // 添加拉起卡片管理页面按钮
        Button('添加卡片')
          .onClick(() => {
            const want: Want = {
              bundleName: 'com.example.myapplication', // 包名
              abilityName: 'EntryFormAbility', // 模块ability名称
              parameters: {
                'ohos.extra.param.key.form_dimension': 2, // 卡片尺寸
                'ohos.extra.param.key.form_name': 'widget', // 卡片名称
                'ohos.extra.param.key.module_name': 'entry' // 卡片所属的模块名称
              },
            };
            try {
              // 点击按钮后调用openFormManager方法，拉起卡片管理页面
              formProvider.openFormManager(want);
            } catch (error) {
              promptAction.openToast({ message: (error as BusinessError).message });
              hilog.info(DOMAIN, 'testTag', 'catch error ', 'code:', (error as BusinessError).code, 'message:',
                (error as BusinessError).message);
            }
          })
          .margin({ top: 10, bottom: 10 });
      }
      .width('100%');
    }
    .height('100%');
  }
}

实现效果图：

点击放大

使用FormMenu组件，通过长按组件弹出“添加至桌面”菜单，将卡片添加至桌面。以Menu组件为菜单容器，通过AddFormMenuItem添加菜单子项，根据AddFormMenuItem中传入的参数want，将指定的卡片添加至桌面，添加时会根据传入的组件ID获取组件快照和位置，用于添加桌面时的过渡动效。若want参数或组件ID错误、指定的卡片不存在或未在form_config.json中配置，则无法将卡片添加至桌面。

want参数需包含字段包括：
- bundleName：卡片所属应用的包名。
- abilityName：卡片所属的ability名称。
- parameters：展示卡片的参数，详见下文。
parameters需包含的字段包括：
- ohos.extra.param.key.form_dimension：卡片尺寸，参考FormDimension。
- ohos.extra.param.key.form_name：卡片名称，即form_config.json中卡片对应的name。
- ohos.extra.param.key.module_name：卡片所属的模块名称。

示例代码如下：

import { AddFormMenuItem } from '@kit.ArkUI';
import { formBindingData } from '@kit.FormKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const tag = 'AddFormMenuItem';

@Entry
@Component
struct FormMenuDemo {
  private compId: string = 'addforms@d46313145';

  @Builder
  MyMenu() {
    Menu() {
      AddFormMenuItem(
        {
          bundleName: 'com.example.myapplication', // 包名
          abilityName: 'EntryFormAbility', // 模块ability名称
          parameters: {
            'ohos.extra.param.key.form_dimension': 2, // 卡片尺寸
            'ohos.extra.param.key.form_name': 'widgetImage', // 卡片名称
            'ohos.extra.param.key.module_name': 'entry' // 卡片所属的模块名称
          },
        },
        this.compId,
        {
          formBindingData: formBindingData.createFormBindingData({}),
          callback: (error, formId) => {
            hilog.info(0x3900, tag, `callback info：error = ${JSON.stringify(error)}, formId = ${formId}`);
            if (error?.code === 0) {
              hilog.info(0x3900, tag, '添加至桌面成功');
            } else {
              hilog.info(0x3900, tag, '添加至桌面失败，请尝试其它添加方式');
            }
          }
        }
      );
    };
  }

  build() {
    Row() {
      Column({ space: 36 }) {
        Text('长按图片添加卡片到桌面')
          .fontSize('18fp');

        Image($r('app.media.startIcon')) // 自定义图片
          .id(this.compId)
          .width(150)
          .height(150)
          // 绑定菜单
          .bindContextMenu(this.MyMenu, ResponseType.LongPress, {
            placement: Placement.TopLeft
          });
      }
      .width('100%');
    }
    .height('100%');
  }
}

实现效果图：

点击放大

总结

将卡片添加至桌面，可以在桌面或应用内添加：

桌面添加卡片，可以通过长按应用图标，或双指捏合进入的桌面管理中拉起卡片管理页面，在卡片管理页面将卡片添加至桌面。
应用内添加卡片，需应用通过调用formProvider.openFormManager接口或使用FormMenu组件，将对应卡片添加至桌面。

常见FAQ

Q：桌面实际有空间，但卡片加桌时提示桌面空间已满。

A：卡片在加桌时，桌面布局会判断当前页与下一页是否有空间添加卡片。若当前页与下一页没有可容纳卡片的空间，则会新建一屏；当桌面达到18屏，且桌面布局判断无满足空间添加卡片时，系统会提示桌面空间已满。

Q：卡片添加到桌面后，卡片下方显示的名称是否可以修改？

A：卡片下方显示的内容是应用名称，不支持修改。

目录

如何将卡片添加至桌面

问题现象

背景知识

解决方案

总结

常见FAQ