1# FormMenu
2
3The **FormMenu** component encapsulates an **Add to home screen** menu, which allows users to long-press a component in the application to add it to their home screen for direct access. During application usage, this component acts as a portal for retention and re-engagement, encouraging users to conveniently add features to their home screen.
4
5This component facilitates the quick addition of service widgets to the home screen through a long-press menu within the application:
6
71. You pass the widget data and the ID of the in-application functional component to the service widget framework.
8
92. The click event captures a snapshot and the position of the in-application functional component based on the component ID, which is used for the transition animation when the widget is added to the home screen.
10
113. The service widget framework triggers the addition of the service widget to the home screen by sending the addition data to the home screen, initiating the service widget placement operation.
12
13
14> **NOTE**
15>
16> This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version.
17
18
19## Modules to Import
20
21```
22import { AddFormMenuItem } from '@kit.ArkUI';
23```
24
25
26## Child Components
27
28Not supported
29
30## Attributes
31The [universal attributes](ts-universal-attributes-size.md) are not supported.
32
33## AddFormMenuItem
34
35
36AddFormMenuItem(
37  want: Want,
38  componentId: string,
39  options?: AddFormOptions
40): void;
41
42
43**Decorator**: @Component
44
45**Atomic service API**: This API can be used in atomic services since API version 12.
46
47**System capability**: SystemCapability.ArkUI.ArkUI.Full
48
49**Parameters**
50
51| Name          | Type                       | Mandatory| Decorator| Description                                                            |
52| -------------- | ------------------------------- | ---- | ---------- | ---------------------------------------------------------------- |
53| want           | [Want](../../apis-ability-kit/js-apis-app-ability-want.md)                            | Yes  | \@Prop     | Want information of the functional component.                                        |
54| componentId    | string                          | Yes  | -          | In-application functional component ID, which corresponds to a UI similar to the UI of the service widget to add.|
55| AddFormOptions| [AddFormOptions](#addformoptions) | No  | -          | Options for adding the service widget.                                                        |
56
57## AddFormOptions
58
59**Atomic service API**: This API can be used in atomic services since API version 12.
60
61**System capability**: SystemCapability.ArkUI.ArkUI.Full
62
63**Parameters**
64| Name            | Type               | Mandatory| Description                                                     |
65| --------------- | ---- | ---- | ---------------------------------------------------------------- |
66| formBindingData | [formBindingData.FormBindingData](../../apis-form-kit/js-apis-app-form-formBindingData.md#formbindingdata) | No| Service widget data.|
67| callback        | AsyncCallback\<string>                                                                                                | No| Callback used to return the result. |
68| style           | [FormMenuItemStyle](#formmenuitemstyle)                                                                              | No| Custom menu style.|
69
70
71## FormMenuItemStyle
72
73**Atomic service API**: This API can be used in atomic services since API version 12.
74
75**System capability**: SystemCapability.ArkUI.ArkUI.Full
76
77**Parameters**
78| Name           | Type          | Mandatory| Description|
79| --------------- | ----------------- | ---- | ---- |
80| options | [MenuItemOptions](ts-basic-components-menuitem.md#menuitemoptions) | No  | Information about the menu item.|
81
82> **NOTE**
83>
84> If **style** is left empty or unspecified, the default icon and menu text are applied.
85
86## Events
87Menu click events are supported.
88
89## Example
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', // Bundle name
111          abilityName: 'EntryFormAbility', // Module ability name.
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:
123          (error, formId) => {
124            hilog.info(0x3900, tag, 'callback info: error: ' + error + ' formId:' + formId);
125          },
126          style: {
127            // options: {
128            // startIcon: $r("app.media.icon"), // Menu icon, which can be provided by yourself. The default value is "sys.media.ic_public_add."
129            //   content: "Add to home screen",  //  Menu content, which can be provided by yourself. The default value is "sys.string.ohos_add_form_to_desktop."
130            //   endIcon: $r("app.media.icon") // Menu icon, which can be provided by yourself.
131            // }
132          }
133        }
134      )
135    }
136  }
137
138  build() {
139    Row() {
140      Column() {
141        Image($r("app.media.startIcon"))   // Custom image.
142          .id(this.compId)
143          .width(200)
144          .height(200)
145          .bindContextMenu(this.MyMenu, ResponseType.LongPress, {
146            placement: Placement.TopLeft
147          })
148      }
149      .width('100%')
150    }
151    .height('100%')
152  }
153}
154```
155
156```ts
157// WidgetCard.ets
158const local = new LocalStorage()
159
160@Entry(local)
161@Component
162struct WidgetCard {
163  @LocalStorageProp('data') data: string = 'defaultdata'; // Define the service widget data to be updated.
164  /*
165   * The action type.
166   */
167  readonly ACTION_TYPE: string = 'router';
168  /*
169   * The ability name.
170   */
171  readonly ABILITY_NAME: string = 'EntryAbility';
172  /*
173   * The message.
174   */
175  readonly MESSAGE: string = 'add detail';
176  /*
177   * The width percentage setting.
178   */
179  readonly FULL_WIDTH_PERCENT: string = '100%';
180  /*
181   * The height percentage setting.
182   */
183  readonly FULL_HEIGHT_PERCENT: string = '100%';
184
185  build() {
186    Row() {
187      Column() {
188        Text(this.data)
189          .fontSize($r('app.float.font_size'))
190          .fontWeight(FontWeight.Medium)
191          .fontColor($r('app.color.item_title_font'))
192      }
193      .width(this.FULL_WIDTH_PERCENT)
194    }
195    .height(this.FULL_HEIGHT_PERCENT)
196    .backgroundImage($r('app.media.startIcon'))
197    .backgroundImageSize({ width: '100%', height: '100%' })
198    .onClick(() => {
199      postCardAction(this, {
200        action: this.ACTION_TYPE,
201        abilityName: this.ABILITY_NAME,
202        params: {
203          message: this.MESSAGE
204        }
205      });
206    })
207  }
208}
209```
210
211**UI of the FormMenu component**
212
213![en-us_image_0000001616959836](figures/en-us_image_add_form_to_desktop.jpeg)
214
215**Result of using Add to home screen with the FormMenu component**
216
217On the left is the result of using **Add to home screen** with **formbdingdata** empty, and on the right is the result with **formbdingdata** as **{ data: 'share' }**.
218
219![en-us_image_0000001616959836](figures/en-us_image_add_form_to_desktop_result.jpeg)
220