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> This component is not supported on wearables. 19> 20> For details about how to develop a service widget, see the [service widget development guidelines](../../../form/formkit-overview.md). 21 22 23## Modules to Import 24 25``` 26import { AddFormMenuItem } from '@kit.ArkUI'; 27``` 28 29 30## Child Components 31 32Not supported 33 34## Attributes 35The [universal attributes](ts-component-general-attributes.md) are not supported. 36 37## AddFormMenuItem 38 39 40AddFormMenuItem( 41 want: Want, 42 componentId: string, 43 options?: AddFormOptions 44): void 45 46 47**Decorator**: @Builder 48 49**Atomic service API**: This API can be used in atomic services since API version 12. 50 51**System capability**: SystemCapability.ArkUI.ArkUI.Full 52 53**Parameters** 54 55| Name | Type | Mandatory| Description | 56| -------------- | ------------------------------- | ---- | ---------------------------------------------------------------- | 57| want | [Want](../../apis-ability-kit/js-apis-app-ability-want.md#want) | Yes | Want information of the functional component. | 58| componentId | string | Yes | In-application functional component ID, which corresponds to a UI similar to the UI of the service widget to add.| 59| options| [AddFormOptions](#addformoptions) | No | Options for adding the service widget. | 60 61## AddFormOptions 62 63**Atomic service API**: This API can be used in atomic services since API version 12. 64 65**System capability**: SystemCapability.ArkUI.ArkUI.Full 66 67**Parameters** 68| Name | Type | Mandatory| Description | 69| --------------- | ---- | ---- | ---------------------------------------------------------------- | 70| formBindingData | [formBindingData.FormBindingData](../../apis-form-kit/js-apis-app-form-formBindingData.md#formbindingdata) | No| Service widget data.| 71| callback | AsyncCallback\<string> | No| Callback used to return the result. The value **0** means that the service widget is added successfully, and a non-zero value means that the service widget fails to be added. For details about the error codes, see [Form Error Codes](../../apis-form-kit/errorcode-form.md). | 72| style | [FormMenuItemStyle](#formmenuitemstyle) | No| Custom menu style.| 73 74 75## FormMenuItemStyle 76 77**Atomic service API**: This API can be used in atomic services since API version 12. 78 79**System capability**: SystemCapability.ArkUI.ArkUI.Full 80 81**Parameters** 82| Name | Type | Mandatory| Description| 83| --------------- | ----------------- | ---- | ---- | 84| options | [MenuItemOptions](ts-basic-components-menuitem.md#menuitemoptions) | No | Information about the menu item.| 85 86> **NOTE** 87> 88> If **style** is left empty or unspecified, the default icon and menu text are applied. 89 90## Events 91Menu click events are supported. 92 93## Example 94 95```ts 96// index.ets 97import { AddFormMenuItem } from '@kit.ArkUI'; 98import { formBindingData } from '@kit.FormKit'; 99import { hilog } from '@kit.PerformanceAnalysisKit'; 100 101const tag = 'AddFormMenuItem'; 102 103@Entry 104@Component 105struct Index { 106 @State message: string = 'Long press show menu'; 107 private compId: string = 'addforms@d46313145'; 108 109 @Builder 110 MyMenu() { 111 Menu() { 112 AddFormMenuItem( 113 { 114 bundleName: 'com.example.myapplication', // Bundle name 115 abilityName: 'EntryFormAbility', // Module ability name. 116 parameters: { 117 'ohos.extra.param.key.form_dimension': 2, // Widget size: 1 for 1 x 2, 2 for 2 x 2, 3 for 2 x 4, 4 for 4 x 4, 7 for 6 x 4, 6 for 1 x 1. 118 'ohos.extra.param.key.form_name': 'widget', // Widget name. 119 'ohos.extra.param.key.module_name': 'entry' // Module name of the widget. 120 }, 121 }, 122 this.compId, 123 { 124 formBindingData: formBindingData.createFormBindingData({}), 125 // formBindingData: formBindingData.createFormBindingData({ data: 'share' }), 126 callback: (error, formId) => { 127 hilog.info(0x3900, tag, `callback info: error = ${JSON.stringify(error)}, formId = ${formId}`); 128 if (error?.code === 0) { 129 hilog.info(0x3900, tag, "Added to the home screen.") 130 } else { 131 hilog.info(0x3900, tag, "Failed to add to the home screen. Try another method.") 132 } 133 }, 134 style: { 135 // options: { 136 // startIcon: $r("app.media.icon"), // Menu icon, which can be provided by yourself. The default value is "sys.media.ic_public_add." 137 // content: "Add to home screen", // Menu content, which can be provided by yourself. The default value is "sys.string.ohos_add_form_to_desktop." 138 // endIcon: $r("app.media.icon") // Menu icon, which can be provided by yourself. 139 // } 140 } 141 } 142 ) 143 } 144 } 145 146 build() { 147 Row() { 148 Column() { 149 Image($r("app.media.startIcon")) // Custom image. 150 .id(this.compId) 151 .width(200) 152 .height(200) 153 .bindContextMenu(this.MyMenu, ResponseType.LongPress, { 154 placement: Placement.TopLeft 155 }) 156 } 157 .width('100%') 158 } 159 .height('100%') 160 } 161} 162``` 163 164```ts 165// WidgetCard.ets 166const local = new LocalStorage() 167 168@Entry(local) 169@Component 170struct WidgetCard { 171 @LocalStorageProp('data') data: string = 'defaultdata'; // Define the service widget data to be updated. 172 /* 173 * The action type. 174 */ 175 readonly ACTION_TYPE: string = 'router'; 176 /* 177 * The ability name. 178 */ 179 readonly ABILITY_NAME: string = 'EntryAbility'; 180 /* 181 * The message. 182 */ 183 readonly MESSAGE: string = 'add detail'; 184 /* 185 * The width percentage setting. 186 */ 187 readonly FULL_WIDTH_PERCENT: string = '100%'; 188 /* 189 * The height percentage setting. 190 */ 191 readonly FULL_HEIGHT_PERCENT: string = '100%'; 192 193 build() { 194 Row() { 195 Column() { 196 Text(this.data) 197 .fontSize($r('app.float.font_size')) 198 .fontWeight(FontWeight.Medium) 199 .fontColor($r('app.color.item_title_font')) 200 } 201 .width(this.FULL_WIDTH_PERCENT) 202 } 203 .height(this.FULL_HEIGHT_PERCENT) 204 .backgroundImage($r('app.media.startIcon')) 205 .backgroundImageSize({ width: '100%', height: '100%' }) 206 .onClick(() => { 207 postCardAction(this, { 208 action: this.ACTION_TYPE, 209 abilityName: this.ABILITY_NAME, 210 params: { 211 message: this.MESSAGE 212 } 213 }); 214 }) 215 } 216} 217``` 218 219**UI of the FormMenu component** 220 221 222 223**Result of using Add to home screen with the FormMenu component** 224 225The figure below shows the results when **formbindingdata** is empty (left), and when it is set to **{ data: 'share' }** (right). 226 227 228
