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