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