f7937527创建于 2025年9月10日历史提交

菜单控制

为组件绑定弹出式菜单，支持长按、点击或鼠标右键来触发菜单的弹出，菜单项以垂直列表形式显示。

说明：

从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

CustomBuilder不支持使用bindMenu和bindContextMenu弹出菜单。可以使用Menu组件来实现多级菜单。

弹出菜单的文本内容不支持长按选中。

当窗口大小发生变化以及点击菜单内容区时，菜单自动隐藏。

如果组件是可拖动节点且未指定bindContextMenu的preview，菜单弹出时会显示拖拽预览图，且菜单选项和预览图不会相互避让。开发者可根据使用场景设置preview或将目标节点设置为不可拖动。

从API version 12开始，菜单支持长按500ms弹出子菜单，支持按压态跟随手指移动。

仅支持使用Menu组件且子组件包含MenuItem或MenuItemGroup的场景。

仅支持MenuPreviewMode设置为NONE的菜单。

菜单最大宽度受设备所占栅格限制，即使设置宽度100%，也不会占满屏幕。

菜单绑定的组件对象销毁时，菜单消失。

bindContextMenu仅支持在子窗中显示，bindMenu可以通过配置MenuOptions中的showInSubWindow属性设置是否在子窗中显示。

bindMenu

bindMenu(content: Array<MenuElement> | CustomBuilder, options?: MenuOptions): T

给组件绑定菜单，点击后弹出菜单。弹出的菜单项支持图标+文本排列以及自定义组件两种功能。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
content	Array<MenuElement> \| CustomBuilder	是	配置菜单项图标和文本的数组，或者自定义组件。
options	MenuOptions	否	配置弹出菜单的参数。

返回值：

类型	说明
T	返回当前组件。

bindMenu¹¹⁺

bindMenu(isShow: boolean, content: Array<MenuElement> | CustomBuilder, options?: MenuOptions): T

给组件绑定菜单，菜单的显隐通过控制绑定的isShow触发。弹出的菜单项支持图标+文本排列以及自定义组件两种功能。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
isShow¹¹⁺	boolean	是	支持开发者通过状态变量控制显隐，值为true时弹出菜单，值为false时关闭菜单，默认值为false。菜单必须等待页面全部构建才能展示，因此不能在页面构建中设置为true，否则会导致显示位置及形状错误，该参数从API version18开始支持!!语法双向绑定变量。
content	Array<MenuElement> \| CustomBuilder	是	配置菜单项图标和文本的数组，或者自定义组件。
options	MenuOptions	否	配置弹出菜单的参数。

返回值：

类型	说明
T	返回当前组件。

bindContextMenu⁸⁺

bindContextMenu(content: CustomBuilder, responseType: ResponseType, options?: ContextMenuOptions): T

给组件绑定菜单，控制菜单显隐的触发方式为长按或右键点击，弹出的菜单项需自定义。若需通过代码逻辑控制菜单显隐，请使用bindContextMenu¹²⁺。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
content	CustomBuilder	是	自定义菜单内容构造器。
responseType	ResponseType	是	菜单弹出条件，长按或者右键点击。不支持鼠标长按。
options	ContextMenuOptions	否	配置弹出菜单的参数。

返回值：

类型	说明
T	返回当前组件。

bindContextMenu¹²⁺

bindContextMenu(isShown: boolean, content: CustomBuilder, options?: ContextMenuOptions): T

给组件绑定菜单，菜单的显隐通过控制绑定的isShown触发。

当isShown为true时，弹出菜单；为false时，隐藏菜单。菜单项支持自定义。

菜单弹出位置仅有placement设置决定，与点击位置无关。

系统能力： SystemCapability.ArkUI.ArkUI.Full

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

参数：

参数名	类型	必填	说明
isShown	boolean	是	支持开发者通过状态变量控制显隐，值为true时弹出菜单，值为false时关闭菜单，默认值为false。菜单必须等待页面全部构建完成后才能展示，如果在页面构建前或构建中设置为true，可能导致显示位置及形状错误、无法正常弹出显示等问题。不支持长按触发拖拽。该参数从API version 18开始支持!!语法双向绑定变量。
content	CustomBuilder	是	自定义菜单内容构造器。
options	ContextMenuOptions	否	配置弹出菜单的参数。

返回值：

类型	说明
T	返回当前组件。

MenuElement

菜单项的图标、文本和交互信息。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
value	ResourceStr	是	菜单项文本。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
icon¹⁰⁺	ResourceStr	否	菜单项图标。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
enabled¹¹⁺	boolean	否	菜单条目是否可进行交互。默认值：true，菜单条目可以进行交互。值为false时，菜单条目不可以进行交互。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
action	() => void	是	点击菜单项的事件回调。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
symbolIcon¹²⁺	SymbolGlyphModifier	否	设置菜单项图标。通过Modifier配置菜单项图标，若同时配置symbolIcon和icon的情况下，icon图标不显示。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

MenuOptions¹⁰⁺

继承自ContextMenuOptions。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
title	ResourceStr	否	菜单标题。说明：仅在content设置为Array<MenuElement> 时生效。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
showInSubWindow¹¹⁺	boolean	否	是否在子窗口显示菜单。值为true表示在子窗口显示菜单，值为false表示不在子窗显示菜单。默认值：2in1设备上为true，其他设备为false。说明：仅对2in1设备生效。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

ContextMenuOptions¹⁰⁺

菜单项的信息。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
offset	Position	否	菜单弹出位置的偏移量，不会导致菜单显示超出屏幕范围。默认值：{ x: 0，y: 0 }，不支持设置百分比。说明：菜单类型为相对⽗组件区域弹出时，⾃动根据菜单位置属性 (placement)将区域的宽或⾼计⼊偏移量中。当菜单相对父组件出现在上侧时（placement设置为Placement.TopLeft，Placement.Top，Placement.TopRight），x为正值，菜单相对组件向右进行偏移，y为正值，菜单相对组件向上进行偏移。当菜单相对父组件出现在下侧时（placement设置为Placement.BottomLeft，Placement.Bottom，Placement.BottomRight），x为正值，菜单相对组件向右进行偏移，y为正值，菜单相对组件向下进行偏移。当菜单相对父组件出现在左侧时（placement设置为Placement.LeftTop，Placement.Left，Placement.LeftBottom），x为正值，菜单相对组件向左进行偏移，y为正值，菜单相对组件向下进行偏移。当菜单相对父组件出现在右侧时（placement设置为Placement.RightTop，Placement.Right，Placement.RightBottom），x为正值，菜单相对组件向右进行偏移，y为正值，菜单相对组件向下进行偏移。未设置、异常值或者undefined时按默认{ x: 0, y: 0 }处理。若传入偏移量超出屏幕范围外，则会就近约束到屏幕范围内。如果菜单调整了显示位置（与placement初始值主方向不⼀致），则偏移值 (offset) 失效。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
placement	Placement	否	菜单组件优先显示的位置，当前位置显示不下时，会自动调整位置。说明： placement值设置为undefined、null或没有设置此选项时，按未设置placement处理，当使用bindMenu，按默认值：Placement.BottomLeft设置，当使用bindContextMenu⁸⁺，菜单跟随点击位置弹出；当使用bindContextMenu¹²⁺，按默认值：Placement.BottomLeft设置。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
enableArrow	boolean	否	是否显示箭头。如果菜单的大小和位置不足以放置箭头时，不会显示箭头。默认值：false，不显示箭头。说明： enableArrow为true时，placement未设置或者值为非法值，默认在目标物上方显示，否则按照placement的位置优先显示。当前位置显示不下时，会自动调整位置，enableArrow为undefined时，不显示箭头。bindContextMenu从API version 10开始支持该属性；bindMenu从API version 12开始支持该属性。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
enableHoverMode¹⁸⁺	boolean	否	菜单组件是否响应悬停态（半折叠状态）变化，即在悬停态下是否触发避让折痕区域。默认值：false，2in1设备默认为true。未设置或者值为非法值时，生效默认值。说明： 1、如果菜单的弹出位置在悬停态折痕区域，菜单组件不会响应悬停态。 2、2in1设备从API version 20开始生效。 3、2in1设备仅在窗口瀑布模式下生效。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。
arrowOffset	Length	否	箭头在菜单处的偏移。偏移量必须合法且转换为具体数值时大于0才会生效，另外该值生效时不会导致箭头超出菜单四周的安全距离。默认值：0 单位：vp 说明：箭头距菜单四周的安全距离为菜单圆角大小与箭头宽度的一半之和。根据配置的placement来计算是在水平还是垂直方向上偏移。箭头在菜单水平方向时，偏移量为箭头至最左侧箭头安全距离处的距离。箭头在菜单垂直方向时，偏移量为箭头至最上侧箭头安全距离处的距离。根据配置的placement的不同，箭头展示的默认位置不同：在菜单不发生避让的情况下，placement设置为Placement.Top、Placement.Bottom时，箭头显示在水平方向且默认居中； placement设置为Placement.Left、Placement.Right时，箭头显示在垂直方向且默认居中； placement设置为Placement.TopLeft、Placement.BottomLeft时，箭头默认显示在水平方向，且距离菜单左侧边缘距离为箭头安全距离； placement设置为Placement.TopRight、Placement.BottomRight时，箭头默认显示在水平方向，且距离菜单右侧距离为箭头安全距离； placement设置为Placement.LeftTop、Placement.RightTop时，箭头默认显示在垂直方向，且距离菜单上侧距离为箭头安全距离； placement设置为Placement.LeftBottom、Placement.RightBottom时，箭头默认显示在垂直方向，且距离菜单下侧距离为箭头安全距离； bindContextMenu从API version 10开始支持该属性；bindMenu从API version 12开始支持该属性。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
preview¹¹⁺	MenuPreviewMode\| CustomBuilder	否	长按悬浮菜单或使用bindContextMenu¹²⁺显示菜单的预览内容样式，可以为目标组件的截图，也可以为用户自定义的内容。默认值：MenuPreviewMode.NONE，无预览内容。说明： - 不支持responseType为ResponseType.RightClick时触发，如果responseType为ResponseType.RightClick，则不会显示预览内容。 - 当未设置preview参数或preview参数设置为MenuPreviewMode.NONE时，enableArrow参数生效。 - 当preview参数设置为MenuPreviewMode.IMAGE或CustomBuilder时，enableArrow为true时也不显示箭头。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
previewAnimationOptions¹¹⁺	ContextMenuAnimationOptions	否	控制长按预览显示动画开始倍率和结束倍率（相对预览原图比例）。默认值：{ scale: [0.95, 1.1], transition: undefined, hoverScale: undefined }。说明：倍率设置参数小于等于0时，不生效。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
onAppear	() => void	否	菜单弹出时的事件回调。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
onDisappear	() => void	否	菜单消失时的事件回调。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
aboutToAppear	() => void	否	菜单显示动效前的事件回调。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
aboutToDisappear	() => void	否	菜单退出动效前的事件回调。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
backgroundColor¹¹⁺	ResourceColor	否	菜单背板颜色。默认值：Color.Transparent。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
backgroundBlurStyle¹¹⁺	BlurStyle	否	菜单背板模糊材质。默认值：BlurStyle.COMPONENT_ULTRA_THICK。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
transition¹²⁺	TransitionEffect	否	设置菜单显示和退出的过渡效果。说明：菜单退出动效过程中，进行横竖屏切换，菜单会避让。二级菜单不继承自定义动效。弹出过程可以点击二级菜单，退出动效执行过程不允许点击二级菜单。详细描述见TransitionEffect对象说明。动效曲线使用弹簧曲线，在动效退出时，由于弹簧曲线的回弹震荡，菜单消失后有较长的拖尾，使得其他事件无法响应。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
borderRadius¹²⁺	Length \| BorderRadiuses \| LocalizedBorderRadiuses	否	设置菜单的边框圆角半径。默认值：2in1设备上默认值8vp，其他设备上默认值20vp。说明：支持百分比。当水平方向两个圆角半径之和的最大值超出菜单宽度或垂直方向两个圆角半径之和的最大值超出菜单高度时，采用菜单默认圆角半径值。当设置Length类型且传参为异常值时，菜单圆角取默认值。当设置BorderRadiuses或LocalizedBorderRadiuses类型且传参为异常值时，菜单默认没有圆角。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
previewBorderRadius¹⁹⁺	BorderRadiusType	否	设置预览图边框圆角半径。默认值：16vp 说明：当水平方向上两个圆角半径之和的最大值超过预览图的宽度，或者垂直方向上两个圆角半径之和的最大值超过预览图的高度时，应采用预览图所能允许的最大圆角半径值。圆角设置越大，圆角动画变化越快。原子化服务API：从API version 19开始，该接口支持在原子化服务中使用。
layoutRegionMargin¹³⁺	Margin	否	设置预览图与菜单布局时距上下左右边界的最小边距。说明：仅支持vp、px、fp、lpx、百分比。当margin设置异常值或负值时，按默认值处理。若preview为CustomBuilder，设置margin.left或margin.right时，预览图取消最大栅格的宽度限制。注意应避免设置过大的margin导致布局区域变小，使得预览图和菜单无法正常布局。当水平方向上margin之和超过布局最大宽度时，margin.left和margin.right均不生效，按默认值处理。当垂直方向上margin之和超过布局最大高度时，margin.top和margin.bottom均不生效，按默认值处理。距左右和上下的最小边距默认分别为12vp和16vp。原子化服务API：从API version 13开始，该接口支持在原子化服务中使用。
backgroundBlurStyleOptions¹⁸⁺	BackgroundBlurStyleOptions	否	背景模糊效果。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。
backgroundEffect¹⁸⁺	BackgroundEffectOptions	否	背景效果参数。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。
hapticFeedbackMode¹⁸⁺	HapticFeedbackMode	否	菜单弹出时振动效果。默认值：HapticFeedbackMode.DISABLED，菜单弹出时不振动。说明：只有一级菜单可配置弹出时振动效果。仅当应用具备 ohos.permission.VIBRATE 权限，且用户启用了触感反馈时才会生效。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。

MenuPreviewMode¹¹⁺

菜单的预览样式。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
NONE	0	不显示预览内容。
IMAGE	1	预览内容为触发长按悬浮菜单组件的截图。

ContextMenuAnimationOptions¹¹⁺

长按预览时显示的样式信息。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
scale	AnimationRange<number>	否	动画开始和结束时相对预览原图缩放比例。默认值：[0.95, 1.1] 说明：缩放比例需要根据实际开发场景设置，建议设置值为小于预览图宽度或布局的最大限制。
transition¹²⁺	TransitionEffect	否	设置菜单显示和退出的过渡效果。说明：在菜单退出动效过程中，横竖屏切换时，菜单会避让。二级菜单不继承自定义动效。弹出过程中可以点击二级菜单，但在退出动效执行过程中不允许点击。详细描述见TransitionEffect对象说明。
hoverScale¹²⁺	AnimationRange<number>	否	设置预览自定义长按场景下，浮起原组件截图的缩放动画开始和结束时相对预览原图缩放比例，且有与预览图的切换的过渡动效。说明：倍率设置参数小于等于0时，不生效。 bindContextMenu¹²⁺场景下，不生效。设置transition接口时，不生效。使用此接口且同时使用scale接口时，scale接口起始值不生效。为保障最佳体验，最终预览图尺寸不建议小于原组件截图尺寸。当前预览动效宽高会受组件截图和自定义预览大小影响，请根据实际使用情况自行保障展示效果。

AnimationRange¹¹⁺

type AnimationRange<T> = [from: T, to: T]

动画开始和结束时相对预览原图缩放比例。

系统能力： SystemCapability.ArkUI.ArkUI.Full

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

取值范围	说明
[from: T, to: T]	from表示动画开始时相对预览原图缩放比例，to表示动画结束时相对预览原图缩放比例。

HapticFeedbackMode¹⁸⁺

菜单弹出时振动效果。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
DISABLED	0	菜单弹出时不振动。
ENABLED	1	菜单弹出时振动。
AUTO	2	菜单振动效果跟随系统，当前为菜单有蒙层时振动。

BorderRadiusType¹⁹⁺

type BorderRadiusType = Length | BorderRadiuses | LocalizedBorderRadiuses

圆角类型。

原子化服务API： 从API version 19开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

类型	说明
Length	长度类型，用于描述尺寸单位。
BorderRadiuses	圆角类型，用于描述组件边框圆角半径。
LocalizedBorderRadiuses	圆角类型，用于描述组件边框圆角半径。

示例

示例1（弹出普通菜单）

从API version 7开始，该示例为bindMenu通过配置MenuElement弹出普通菜单。

// xxx.ets
@Entry
@Component
struct MenuExample {
  build() {
    Column() {
      Text('click for Menu')
        .bindMenu([
          {
            value: 'Menu1',
            action: () => {
              console.info('handle Menu1 select');
            }
          },
          {
            value: 'Menu2',
            action: () => {
              console.info('handle Menu2 select');
            }
          },
        ])
    }
    .width('100%')
    .margin({ top: 5 })
  }
}

zh-cn_image_0000001174582862

示例2（弹出自定义菜单）

该示例为bindMenu通过配置CustomBuilder弹出自定义菜单。同时，通过配置hapticFeedbackMode实现弹出时的振动效果。

@Entry
@Component
struct MenuExample {
  @State listData: number[] = [0, 0, 0];

  @Builder MenuBuilder() {
    Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
      ForEach(this.listData, (item:number, index) => {
        Column() {
          Row() {
            Image($r("app.media.icon")).width(20).height(20).margin({ right: 5 })
            Text(`Menu${index as number + 1}`).fontSize(20)
          }
          .width('100%')
          .height(30)
          .justifyContent(FlexAlign.Center)
          .align(Alignment.Center)
          .onClick(() => {
            console.info(`Menu${index as number + 1} Clicked!`);
          })

          if (index != this.listData.length - 1) {
            Divider().height(10).width('80%').color('#ccc')
          }
        }.padding(5).height(40)
      })
    }.width(100)
  }

  build() {
    Column() {
      Text('click for menu')
        .fontSize(20)
        .margin({ top: 20 })
        .bindMenu(this.MenuBuilder, { hapticFeedbackMode: HapticFeedbackMode.ENABLED })
    }
    .height('100%')
    .width('100%')
    .backgroundColor('#f0f0f0')
  }
}

zh-cn_image_0000001186807708

示例3（长按弹出菜单）

该示例为bindContextMenu通过配置responseType.LongPress弹出菜单。

// xxx.ets
@Entry
@Component
struct ContextMenuExample {
  @Builder MenuBuilder() {
    Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
      Text('Test menu item 1')
        .fontSize(20)
        .width(100)
        .height(50)
        .textAlign(TextAlign.Center)
      Divider().height(10)
      Text('Test menu item 2')
        .fontSize(20)
        .width(100)
        .height(50)
        .textAlign(TextAlign.Center)
    }.width(100)
  }

  build() {
    Column() {
      Text('LongPress for menu')
    }
    .width('100%')
    .margin({ top: 5 })
    .bindContextMenu(this.MenuBuilder, ResponseType.LongPress)
  }
}

longMenu

示例4（右键弹出指向型菜单）

该示例为bindContextMenu通过配置responseType.RightClick、enableArrow弹出指向型菜单。同时，通过配置hapticFeedbackMode实现弹出时的振动效果。

// xxx.ets
@Entry
@Component
struct DirectiveMenuExample {
  @Builder MenuBuilder() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Text('Options')
      Divider().strokeWidth(2).margin(5).color('#F0F0F0')
      Text('Hide')
      Divider().strokeWidth(2).margin(5).color('#F0F0F0')
      Text('Exit')
    }
    .width(200)
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Column() {
        Text("DirectiveMenuExample")
          .fontSize(20)
          .width('100%')
          .height("25%")
          .backgroundColor('#F0F0F0')
          .textAlign(TextAlign.Center)
          .bindContextMenu(this.MenuBuilder, ResponseType.RightClick, {
            enableArrow: true,
            placement: Placement.Bottom,
            hapticFeedbackMode: HapticFeedbackMode.ENABLED
          })
      }
    }
    .width('100%')
    .height('100%')
  }
}

zh-cn_image_0000001689126950

示例5（长按弹出菜单的截图预览样式）

该示例为bindContextMenu通过配置responseType.LongPress、preview的MenuPreviewMode类型弹出菜单预览样式。

// xxx.ets
@Entry
@Component
struct Index {
  private iconStr: ResourceStr = $r("app.media.icon");

  @Builder
  MyMenu() {
    Menu() {
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
    }
  }

  build() {
    Column({ space: 50 }) {
      Column() {
        Column() {
          Text('preview-image')
            .width(200)
            .height(100)
            .textAlign(TextAlign.Center)
            .margin(100)
            .fontSize(30)
            .bindContextMenu(this.MyMenu, ResponseType.LongPress,
              { preview: MenuPreviewMode.IMAGE,
                previewAnimationOptions: {scale: [0.8, 1.0]},
              })
            .backgroundColor("#ff3df2f5")
        }
      }.width('100%')
    }
  }
}

preview-image

示例6（长按弹出菜单的自定义预览样式）

该示例为bindContextMenu通过配置responseType.LongPress、preview的CustomBuilder类型弹出菜单自定义预览样式。

// xxx.ets
@Entry
@Component
struct Index {
  private iconStr: ResourceStr = $r("app.media.icon");

  @Builder
  MyMenu() {
    Menu() {
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
    }
  }

  @Builder
  MyPreview() {
    Column() {
      Image($r('app.media.icon'))
        .width(200)
        .height(200)
    }
  }

  build() {
    Column({ space: 50 }) {
      Column() {
        Column() {
          Text('preview-builder')
            .width(200)
            .height(100)
            .textAlign(TextAlign.Center)
            .margin(100)
            .fontSize(30)
            .bindContextMenu(this.MyMenu, ResponseType.LongPress,
              {
                preview: this.MyPreview
              })
        }
      }.width('100%')
    }
  }
}

preview-builder

示例7（设置状态变量弹出菜单）

该示例为bindContextMenu通过配置isShown弹出菜单预览样式。

// xxx.ets
@Entry
@Component
struct Index {
  private iconStr: ResourceStr = $r("app.media.icon");
  @State isShown: boolean = false;

  @Builder
  MyMenu() {
    Menu() {
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
    }
  }

  @Builder
  MyPreview() {
    Column() {
      Image($r('app.media.icon'))
        .width(200)
        .height(200)
    }
  }

  build() {
    Column({ space: 50 }) {
      Column() {
        Column() {
          Text('preview-builder')
            .width(200)
            .height(100)
            .textAlign(TextAlign.Center)
            .margin(100)
            .fontSize(30)
            .bindContextMenu(this.isShown, this.MyMenu,
              {
                preview: this.MyPreview,
                aboutToDisappear: ()=>{
                    this.isShown = false;
                }
              })
          Button('click')
            .onClick(()=>{
                this.isShown = true;
             })
        }
      }.width('100%')
    }
  }
}

preview-builder

示例8（设置菜单和预览的动效）

该示例为bindContextMenu通过配置transition，实现自定义菜单以及菜单预览时的显示和退出动效。

// xxx.ets
@Entry
@Component
struct MenuExample {
  @Builder
  MenuBuilder() {
    Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
      Text('Menu item 1')
        .fontSize(12)
        .width(200)
        .height(30)
        .textAlign(TextAlign.Center)
      Divider().height(10)
      Text('Menu item 2')
        .fontSize(12)
        .width(100)
        .height(30)
        .textAlign(TextAlign.Center)
    }.width(100)
  }

  @Builder
  MyPreview() {
    Column() {
      Image($r('app.media.startIcon'))
        .width(50)
        .height(50)
    }
  }

  @State isShow: boolean = false;
  private iconStr: ResourceStr = $r("app.media.startIcon");

  @Builder
  MyMenu() {
    Menu() {
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
    }
  }

  build() {
    Column() {
      Button('LongPress bindContextMenu')
        .margin({ top: 15 })
        .bindContextMenu(
          this.MenuBuilder,
          ResponseType.LongPress, {
          transition: TransitionEffect.OPACITY.animation({ duration: 4000, curve: Curve.Ease }).combine(
            TransitionEffect.rotate({ z: 1, angle: 180 })),
          preview: this.MyPreview,
          previewAnimationOptions: {
            scale: [0.8, 1.0],
            transition: TransitionEffect.OPACITY.animation({ duration: 4000, curve: Curve.Ease }).combine(
              TransitionEffect.rotate({ z: 1, angle: 180 }))
          }
        })
    }
    .width('100%')
    .margin({ top: 5 })
  }
}

preview-builder

示例9（设置symbol类型图标）

该示例为bindMenu通过配置MenuElement的symbolIcon弹出菜单。

// xxx.ets
import { SymbolGlyphModifier } from '@kit.ArkUI';
@Entry
@Component
struct MenuExample {
  @State symbolIconModifier1: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_photo')).fontSize('24vp');
  @State symbolIconModifier2: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_photo')).fontSize('24vp');
  build() {
    Column() {
      Text('click for Menu')
    }
    .width('100%')
    .margin({ top: 5 })
    .bindMenu([
      {
        value: 'Menu1',
        symbolIcon:this.symbolIconModifier1,
        action: () => {
          console.info('handle Menu1 select');
        }
      },
      {
        value: 'Menu2',
        symbolIcon:this.symbolIconModifier2,
        action: () => {
          console.info('handle Menu2 select');
        }
      },
    ])
  }
}

preview-symbol

示例10（设置一镜到底动效）

该示例为bindContextMenu通过配置preview中hoverScale，实现组件截图到自定义预览图的一镜到底过渡动效。

// xxx.ets
@Entry
@Component
struct Index {
  private iconStr: ResourceStr = $r("app.media.app_icon");

  @Builder
  MyMenu() {
    Menu() {
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
    }
  }

  @Builder
  MyPreview() {
    Column() {
      Image($r('app.media.example'))
        .width(200)
        .height(200)
    }
  }

  build() {
    Column({ space: 50 }) {
      Column() {
        Column() {
          Image($r('app.media.example'))
            .width(100)
            .height(100)
            .margin(100)
            .bindContextMenu(this.MyMenu, ResponseType.LongPress,
              {
                preview: this.MyPreview,
                previewAnimationOptions: {
                  hoverScale: [1.0, 0.95]
                }
              })
        }
      }.width('100%')
    }
  }
}

preview-builder

示例11（自定义背景模糊效果参数）

该示例为bindMenu通过配置backgroundBlurStyleOptions，实现自定义菜单背景模糊效果。

// xxx.ets
@Entry
@Component
struct MenuExample {
  build() {
    Stack() {
      Image($r('app.media.bg'))
      Column() {
        Text('click for Menu')
          .bindMenu([
            {
              value: 'Menu1',
              action: () => {
                console.info('handle Menu1 select')
              }
            },
            {
              value: 'Menu2',
              action: () => {
                console.info('handle Menu2 select')
              }
            },
          ],
            {
              backgroundBlurStyle: BlurStyle.BACKGROUND_THIN,
              backgroundBlurStyleOptions: {
                colorMode:ThemeColorMode.LIGHT,
                blurOptions:{grayscale:[20,20]},
                policy: BlurStyleActivePolicy.ALWAYS_ACTIVE,
                adaptiveColor: AdaptiveColor.AVERAGE,
                scale: 1
              },
            }
          )
      }
      .width('100%')
      .margin({ top: 5 })
    }
  }
}

preview-builder

示例12（自定义背景效果参数）

该示例为bindMenu通过配置backgroundEffect，实现自定义菜单背景效果。

// xxx.ets
@Entry
@Component
struct MenuExample {
  build() {
    Stack() {
      Image($r('app.media.bg'))
      Column() {
        Text('click for Menu')
          .bindMenu([
            {
              value: 'Menu1',
              action: () => {
                console.info('handle Menu1 select');
              }
            },
            {
              value: 'Menu2',
              action: () => {
                console.info('handle Menu2 select');
              }
            },
          ],
            {
              backgroundBlurStyle: BlurStyle.BACKGROUND_THIN,
              backgroundEffect: {
                radius: 60,
                saturation: 10,
                brightness: 1,
                color: '#661A1A1A',
                adaptiveColor: AdaptiveColor.AVERAGE,
                blurOptions:{grayscale:[20,20]}
              }
            }
          )
      }
      .width('100%')
      .margin({ top: 5 })
    }
  }
}

preview-builder

示例13（设置预览图边框圆角半径）

该示例为bindContextMenu通过配置responseType.LongPress、preview的MenuPreviewMode类型弹出菜单预览样式、previewBorderRadius设置预览图边框圆角半径。

// xxx.ets
@Entry
@Component
struct Index {
  private iconStr: ResourceStr = $r("app.media.startIcon");

  @Builder
  MyMenu() {
    Menu() {
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
      MenuItem({ startIcon: this.iconStr, content: "菜单选项" })
    }
  }

  build() {
    Column({ space: 50 }) {
      Column() {
        Column() {
          Text('preview-image')
            .width(200)
            .height(100)
            .textAlign(TextAlign.Center)
            .margin(100)
            .fontSize(30)
            .bindContextMenu(this.MyMenu, ResponseType.LongPress,
              {
                preview: MenuPreviewMode.IMAGE,
                previewBorderRadius: 50
              })
            .backgroundColor("#ff7fcdff")
        }
      }.width('100%')
    }
  }
}

hoverScaleInterruption

示例14 （bindMenu传入带参数的CustomBuilder）

该示例通过在bindMenu中传入带参数的CustomBuilder来配置菜单的具体属性。

// xxx.ets
@Entry
@Component
struct Index {
  @State menuItermList: string[] = ['新建', '历史', '书签', '设置']

  @Builder
  MenuBuilder(itemList: string[]) {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center }) {
      ForEach(itemList, (item: string, index) => {
        Row() {
          Text(item)
            .width('100%')
            .height(32)
            .fontWeight(400)
            .fontSize(14)
            .fontColor(Color.Black)
            .textAlign(TextAlign.Center)
        }
        .onClick(() => {
       console.info('handle' + item + 'Clicked!')!')
        })
        if (index != itemList.length - 1) {
          Divider().height(10).width('80%').color('#ccc')
        }
      })
    }
    .width(100)
  }

  build() {
    Column() {
      Text('click for Menu')
        .bindMenu(this.MenuBuilder(this.menuItermList))
    }
    .height('100%')
    .width('100%')
    .backgroundColor('#f0f0f0')
  }
}

bindMenu-CustomBuilder

菜单控制

bindMenu

bindMenu11+

bindContextMenu8+

bindContextMenu12+

MenuElement

MenuOptions10+

ContextMenuOptions10+

MenuPreviewMode11+

ContextMenuAnimationOptions11+

AnimationRange11+

HapticFeedbackMode18+

BorderRadiusType19+

示例

示例1（弹出普通菜单）

示例2（弹出自定义菜单）

示例3（长按弹出菜单）

示例4（右键弹出指向型菜单）

示例5（长按弹出菜单的截图预览样式）

示例6（长按弹出菜单的自定义预览样式）

示例7（设置状态变量弹出菜单）

示例8（设置菜单和预览的动效）

示例9（设置symbol类型图标）

示例10（设置一镜到底动效）

示例11（自定义背景模糊效果参数）

示例12（自定义背景效果参数）

示例13（设置预览图边框圆角半径）

示例14 （bindMenu传入带参数的CustomBuilder）

bindMenu¹¹⁺

bindContextMenu⁸⁺

bindContextMenu¹²⁺

MenuOptions¹⁰⁺

ContextMenuOptions¹⁰⁺

MenuPreviewMode¹¹⁺

ContextMenuAnimationOptions¹¹⁺

AnimationRange¹¹⁺

HapticFeedbackMode¹⁸⁺

BorderRadiusType¹⁹⁺