1# FormMenu
2
3本组件封装了一个“添加至桌面”菜单，用于实现应用内长按组件生成“添加至桌面”菜单，点击该菜单，触发卡片添加至桌面操作。通过桌面访问该应用快捷卡片，可以直接访问该组件功能。在应用使用过程中，该组件作为留存和复访入口，可吸引用户将功能快捷添加到桌面。
4
5本组件支持应用内支持长按菜单快捷添加卡片到桌面：
6
71. 开发者将卡片数据以及应用内功能组件ID传给卡片框架。
8
92. 点击事件会根据组件ID获取应用内功能组件的快照和位置，用于添加到桌面时的过渡动效。
10
113. 卡片框架通过将加桌数据通知给桌面，触发卡片添加到桌面操作。
12
13
14> **说明：**
15>
16> 该组件从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
17
18
19## 导入模块
20
21```
22import { AddFormMenuItem } from '@kit.ArkUI';
23```
24
25
26## 子组件
27
28无
29
30## 属性
31不支持[通用属性](ts-universal-attributes-size.md)。
32
33## AddFormMenuItem
34
35
36AddFormMenuItem(
37  want: Want,
38  componentId: string,
39  options?: AddFormOptions
40): void
41
42
43**装饰器类型：**@Component
44
45**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
46
47**系统能力：** SystemCapability.ArkUI.ArkUI.Full
48
49**参数：**
50
51| 名称           | 参数类型                        | 必填 | 装饰器类型 | 说明                                                             |
52| -------------- | ------------------------------- | ---- | ---------- | ---------------------------------------------------------------- |
53| want           | [Want](../../apis-ability-kit/js-apis-app-ability-want.md#want)                            | 是   | \@Prop     | 待发布功能组件的want信息。                                         |
54| componentId    | string                          | 是   | -          | 应用内功能组件ID，组件ID对应的界面与待添加的服务卡片界面相似。 |
55| AddFormOptions| [AddFormOptions](#addformoptions) | 否   | -          | 添加卡片选项。                                                         |
56
57## AddFormOptions
58
59**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
60
61**系统能力：** SystemCapability.ArkUI.ArkUI.Full
62
63**参数：**
64| 名称             | 参数类型                | 必填 | 说明                                                      |
65| --------------- | ---- | ---- | ---------------------------------------------------------------- |
66| formBindingData | [formBindingData.FormBindingData](../../apis-form-kit/js-apis-app-form-formBindingData.md#formbindingdata) | 否 | 卡片数据。 |
67| callback        | AsyncCallback\<string>                                                                                                | 否 | 返回结果的回调。  |
68| style           | [FormMenuItemStyle](#formmenuitemstyle)                                                                              | 否 | 菜单自定义样式信息。|
69
70
71## FormMenuItemStyle
72
73**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
74
75**系统能力：** SystemCapability.ArkUI.ArkUI.Full
76
77**参数：**
78| 名称            | 参数类型           | 必填 | 说明 |
79| --------------- | ----------------- | ---- | ---- |
80| options | [MenuItemOptions](ts-basic-components-menuitem.md#menuitemoptions对象说明) | 否   | 包含设置MenuItem的各项信息。|
81
82> **说明：**
83>
84> 仅在 style配置为空或不配置时，使用默认的图标和menu文字。
85
86## 事件
87支持菜单点击事件。
88
89## 示例
90
91```ts
92// index.ets
93import { AddFormMenuItem } from '@kit.ArkUI';
94import { formBindingData } from '@kit.FormKit';
95import { hilog } from '@kit.PerformanceAnalysisKit';
96
97const tag = 'AddFormMenuItem';
98
99@Entry
100@Component
101struct Index {
102  @State message: string = 'Long press show menu';
103  private compId: string = 'addforms@d46313145';
104
105  @Builder
106  MyMenu() {
107    Menu() {
108      AddFormMenuItem(
109        {
110          bundleName: 'com.example.myapplication', // 包名
111          abilityName: 'EntryFormAbility', // 模块ability名称
112          parameters: {
113            'ohos.extra.param.key.form_dimension': 2,
114            'ohos.extra.param.key.form_name': 'widget',
115            'ohos.extra.param.key.module_name': 'entry'
116          },
117        },
118        this.compId,
119        {
120          formBindingData: formBindingData.createFormBindingData({}),
121          // formBindingData: formBindingData.createFormBindingData({ data: 'share' }),
122          callback: (error, formId) => {
123            hilog.info(0x3900, tag, `callback info：error = ${JSON.stringify(error)}, formId = ${formId}`);
124            if (error?.code === 0) {
125              hilog.info(0x3900, tag, "添加至桌面成功")
126            } else {
127              hilog.info(0x3900, tag, "添加至桌面失败，请尝试其它添加方式")
128            }
129          },
130          style: {
131            // options: {
132            //   startIcon: $r("app.media.icon"), // 菜单图标,可以自己提供。系统默认采用"sys.media.ic_public_add"
133            //   content: "添加到桌面",  // 菜单内容，可以自己提供。默认使用"sys.string.ohos_add_form_to_desktop"
134            //   endIcon: $r("app.media.icon") // 菜单图标，可以自己提供
135            // }
136          }
137        }
138      )
139    }
140  }
141
142  build() {
143    Row() {
144      Column() {
145        Image($r("app.media.startIcon"))   // 自定义图片
146          .id(this.compId)
147          .width(200)
148          .height(200)
149          .bindContextMenu(this.MyMenu, ResponseType.LongPress, {
150            placement: Placement.TopLeft
151          })
152      }
153      .width('100%')
154    }
155    .height('100%')
156  }
157}
158```
159
160```ts
161// WidgetCard.ets
162const local = new LocalStorage()
163
164@Entry(local)
165@Component
166struct WidgetCard {
167  @LocalStorageProp('data') data: string = 'defaultdata'; // 定义需要刷新的卡片数据
168  /*
169   * The action type.
170   */
171  readonly ACTION_TYPE: string = 'router';
172  /*
173   * The ability name.
174   */
175  readonly ABILITY_NAME: string = 'EntryAbility';
176  /*
177   * The message.
178   */
179  readonly MESSAGE: string = 'add detail';
180  /*
181   * The width percentage setting.
182   */
183  readonly FULL_WIDTH_PERCENT: string = '100%';
184  /*
185   * The height percentage setting.
186   */
187  readonly FULL_HEIGHT_PERCENT: string = '100%';
188
189  build() {
190    Row() {
191      Column() {
192        Text(this.data)
193          .fontSize($r('app.float.font_size'))
194          .fontWeight(FontWeight.Medium)
195          .fontColor($r('app.color.item_title_font'))
196      }
197      .width(this.FULL_WIDTH_PERCENT)
198    }
199    .height(this.FULL_HEIGHT_PERCENT)
200    .backgroundImage($r('app.media.startIcon'))
201    .backgroundImageSize({ width: '100%', height: '100%' })
202    .onClick(() => {
203      postCardAction(this, {
204        action: this.ACTION_TYPE,
205        abilityName: this.ABILITY_NAME,
206        params: {
207          message: this.MESSAGE
208        }
209      });
210    })
211  }
212}
213```
214
215**高级自定义控件界面**
216
217![zh-cn_image_0000001616959836](figures/zh-cn_image_add_form_to_desktop.jpeg)
218
219**调用高级自定义控件桌面加桌结果**
220
221左侧是formbdingdata为空加桌结果，右侧是formbindingdata为{ data: 'share' }的加桌结果。
222
223![zh-cn_image_0000001616959836](figures/zh-cn_image_add_form_to_desktop_result.jpeg)