文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载导读本文面向基于仓颉Cangjie语言开发 OpenHarmony 应用ArkUI 声明式 UI的开发者系统讲解组件级菜单控制的三个通用属性接口bindMenu含 MenuElement 数组版与 CustomBuilder 自定义版与bindContextMenu。通过本文你将掌握如何为任意组件绑定垂直列表形式的弹出菜单配置长按、点击或鼠标右键等触发方式并借助ContextMenuOptions精细控制菜单位置、箭头、偏移、背板样式、预览图与显示/退出动效直接用于生产级 UI 交互开发。菜单控制总览菜单控制为组件绑定弹出式菜单菜单以垂直列表形式显示菜单项可通过长按、点击或鼠标右键触发。它由三个通用方法组成均返回组件实例本身T因此可以链式调用方法功能触发方式bindContextMenu(builder, responseType, options)绑定上下文菜单支持预览与动效长按或鼠标右键bindMenu(content: ?ArrayMenuElement)绑定普通菜单声明式菜单项点击bindMenu(builder: ?CustomBuilder)绑定自定义菜单Builder 构建点击三个接口的系统能力均为SystemCapability.ArkUI.ArkUI.Full起始版本为 22使用前需导入模块import kit.ArkUI.*说明原文档注意事项开发时务必遵守CustomBuilder 中不支持再使用bindMenu、bindContextMenu弹出菜单多级菜单可使用 Menu 组件。弹出菜单的文本内容不支持长按选中。若组件是可拖动节点绑定bindContextMenu且未指定preview时菜单弹出会浮起拖拽预览图且菜单选项和预览图不会发生避让。开发者可根据使用场景设置preview或将目标节点设置为不可拖动节点。菜单支持长按 500ms 弹出子菜单支持按压态跟随手指移动。前提a. 仅支持使用 Menu 组件且子组件包含 MenuItem 或 MenuItemGroup 的场景b. 仅支持 MenuPreviewMode 为 NONE 的菜单。bindContextMenu绑定带预览的上下文菜单public func bindContextMenu(builder!: ?CustomBuilder, responseType!: ?ResponseType, options!: ?ContextMenuOptions None): T功能绑定上下文菜单到组件。系统能力SystemCapability.ArkUI.ArkUI.Full起始版本22。参数说明参数名类型必填默认值说明builder?CustomBuilder是-命名参数。自定义构建器。初始值{ }。responseType?ResponseType是-命名参数。响应类型。初始值ResponseType.LongPress。options?ContextMenuOptions否None命名参数。上下文菜单选项。初始值ContextMenuOptions()。返回值T返回调用此接口的组件实例本身。ResponseType触发响应类型public enum ResponseType : EquatableResponseType { | RightClick | LongPress | ... }RightClick通过鼠标右键触发菜单弹出主要面向鼠标/触控板等指针输入场景。LongPress通过长按触发菜单弹出触屏默认交互。枚举提供operator func 与operator func !用于相等性比较。需要特别注意的是preview预览功能不支持ResponseType.RightClick触发若 responseType 为 RightClick则不会显示预览内容详见下文 ContextMenuOptions 的 preview 参数。bindMenu绑定声明式菜单MenuElement 数组public func bindMenu(content: ?ArrayMenuElement): T功能绑定菜单到组件。系统能力SystemCapability.ArkUI.ArkUI.Full起始版本22。参数说明参数名类型必填默认值说明content?ArrayMenuElement是-命名参数。菜单元素数组。返回值T返回调用此接口的组件实例本身。MenuElement菜单项配置类public class MenuElement { public init(value!: ?ResourceStr, action!: () - Unit) }MenuElement用于配置菜单项图标和文本构造参数如下参数名类型必填说明value?ResourceStr是命名参数。菜单项文本。action() - Unit是命名参数。点击菜单项的事件回调。该版本通过“文本 点击回调”的声明式数组即可快速构建菜单适合菜单项固定、逻辑简单的场景。当默认placement未设置时bindMenu按Placement.BottomLeft组件下侧、与左侧边缘对齐作为初始位置。bindMenu绑定自定义菜单CustomBuilderpublic func bindMenu(builder!: ?CustomBuilder): T功能绑定自定义菜单到组件。系统能力SystemCapability.ArkUI.ArkUI.Full起始版本22。参数说明参数名类型必填默认值说明builder?CustomBuilder是-命名参数。自定义构建器。初始值{ }。返回值T返回通用方法接口类型。其中CustomBuilder的类型定义为() - Unit公共类型定义即无参无返回值的构建函数。与 MenuElement 数组版相比CustomBuilder 版可自由组合任意组件作为菜单内容例如在菜单内嵌入带图标的按钮、行布局甚至图片。ContextMenuOptions上下文菜单选项深度解析bindContextMenu的options参数是菜单能力的核心所在其类定义见 cj-common-types.md如下public class ContextMenuOptions { public var offset: ?Position public var placement: OptionPlacement public var enableArrow: ?Bool public var arrowOffset: ?Length public var preview: ?CustomBuilder public var previewAnimationOptions: ?ContextMenuAnimationOptions public var onAppear: ?() - Unit public var onDisappear: ?() - Unit public var aboutToAppear: ?() - Unit public var aboutToDisappear: ?() - Unit public var backgroundColor: ?ResourceColor public var backgroundBlurStyle: ?BlurStyle public var transition: ?TransitionEffect public var borderRadius: ?BorderRadiuses None public var layoutRegionMargin: ?Margin None public init( offset!: ?Position None, placement!: OptionPlacement Option.None, enableArrow!: ?Bool None, arrowOffset!: ?Length None, preview!: Option() - Unit Option.None, previewAnimationOptions!: ?ContextMenuAnimationOptions None, onAppear!: ?() - Unit None, onDisappear!: ?() - Unit None, aboutToAppear!: ?() - Unit None, aboutToDisappear!: ?() - Unit None, backgroundColor!: ?ResourceColor None, backgroundBlurStyle!: ?BlurStyle Option.None, transition!: ?TransitionEffect None, borderRadius!: ?BorderRadiuses None, layoutRegionMargin!: ?Margin None ) }各参数的含义与取值规则如下位置与箭头相关参数类型说明与规则offset?Position菜单弹出位置的偏移量不会导致菜单显示超出屏幕范围。菜单类型为相对父组件区域弹出时自动根据 placement 将区域的宽或高计入偏移量中。偏移方向随 placement 而定菜单出现在上侧TopLeft/Top/TopRight时x 正值为向右偏移、y 正值为向上偏移出现在下侧BottomLeft/Bottom/BottomRight时x 正值为向右、y 正值为向下出现在左侧时 x 正值为向左、y 正值为向下出现在右侧时 x 正值为向右、y 正值为向下。若菜单最终调整了显示位置与 placement 初始主方向不一致offset 将失效。placementOptionPlacement菜单优先显示的位置当前位置显示不下时自动调整位置。placement 值设置为 undefined、null 或未设置时按未设置处理bindMenu场景下默认Placement.BottomLeft。Placement 枚举包含Left、Right、Top、Bottom、TopLeft、TopRight、BottomLeft、BottomRight、LeftTop、LeftBottom、RightTop、RightBottom、None等取值中心/边缘对齐的完整语义见公共类型定义。enableArrow?Bool是否显示箭头。如果菜单的大小和位置不足以放置箭头时不会显示箭头。enableArrow为 true 且 placement 未设置或非法时默认在目标物上方显示enableArrow 为 undefined 时不显示箭头。arrowOffset?Length箭头在菜单处的偏移单位vp。偏移量必须合法且转换为具体数值时大于 0 才生效且不会导致箭头超出菜单四周的安全距离安全距离 菜单圆角大小 箭头宽度的一半。箭头默认位置随 placement 变化Top/Bottom 时水平居中Left/Right 时垂直居中TopLeft/BottomLeft 时位于水平方向且距左侧边缘为安全距离TopRight/BottomRight 时距右侧为安全距离LeftTop/RightTop 时距上侧为安全距离LeftBottom/RightBottom 时距下侧为安全距离。预览preview相关参数类型说明与规则preview?CustomBuilder长按悬浮菜单或使用bindContextMenu显示菜单时的预览内容样式用户自定义内容。规则不支持ResponseType.RightClick触发时显示预览未设置 preview 时enableArrow生效设置 preview 为 CustomBuilder 时即使enableArrow为 true 也不显示箭头。previewAnimationOptions?ContextMenuAnimationOptions控制长按预览显示动画的开始倍率和结束倍率相对预览原图比例详见下文。ContextMenuAnimationOptions类定义public class ContextMenuAnimationOptions { public var scale: ?VArrayFloat64, $2 public var transition: ?TransitionEffect public var hoverScale: ?VArrayFloat64, $2 public init(scale!: ?VArrayFloat64, $2 None, transition!: ?TransitionEffect None, hoverScale!: ?VArrayFloat64, $2 None) }scale动画开始和结束时相对预览原图的缩放比例。缩放比例需根据实际开发场景设置建议小于预览图宽度或布局的最大限制。transition菜单显示和退出的过渡效果见 TransitionEffect。菜单退出动效过程中进行横竖屏切换时菜单会避让二级菜单不继承自定义动效弹出过程可点击二级菜单退出动效执行过程不允许点击二级菜单。hoverScale预览自定义长按场景下浮起原组件截图的缩放动画开始和结束倍率且与预览图之间有切换过渡动效。倍率设置小于等于 0 时不生效设置了 transition 接口时不生效同时使用 scale 时scale 的起始值不生效。为保障最佳体验最终预览图尺寸不建议小于原组件截图尺寸。事件回调与外观样式参数类型说明onAppear?() - Unit菜单弹出时的事件回调。onDisappear?() - Unit菜单消失时的事件回调。aboutToAppear?() - Unit菜单显示动效前的事件回调。aboutToDisappear?() - Unit菜单退出动效前的事件回调。backgroundColor?ResourceColor弹窗背板颜色初始值为Color.Transparent。backgroundBlurStyle?BlurStyle弹窗背板模糊材质如BlurStyle.BackgroundUltraThick见 BlurStyle 枚举。transition?TransitionEffect菜单显示和退出的过渡效果。borderRadius?BorderRadiuses菜单显示区域的圆角。layoutRegionMargin?Margin菜单的布局区域边距。示例1弹出自定义菜单bindMenu CustomBuilder该示例通过bindMenu配置 CustomBuilder 弹出自定义菜单同时展示了 MenuElement 数组版与 bindContextMenu 的用法源码文档package ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* import ohos.hilog.* Entry Component class EntryView { Builder func builder() { Column { Button(Builder 内容) .width(300.px) .onClick({ evt Hilog.info(1, info, Builder 中的按钮被点击) }) } .width(300.px) } func build() { Column(space: 20) { Button(BindMenu).bindMenu( [ MenuElement( value: 菜单1, action: { Hilog.info(1, info, 菜单1被点击) } ), MenuElement( value: 菜单2, action: { Hilog.info(1, info, 菜单2被点击) } ) ] ) Button(BindMenu-Custom) .bindMenu(builder: builder) Button(BindContextMenu-长按) .bindContextMenu(builder: builder, responseType: ResponseType.RightClick) } } }示例要点用Builder声明builder()自定义构建器内部可自由组织任意 UI此处为 Column 内嵌带点击事件的 Button。bindMenu(builder: builder)通过 Builder 引用把自定义菜单绑定到按钮。bindContextMenu(builder: builder, responseType: ResponseType.RightClick)演示了上下文菜单的右键触发用法。示例2弹出普通菜单bindMenu MenuElement该示例通过bindMenu配置MenuElement弹出普通菜单源码文档package ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* import ohos.hilog.* Entry Component class EntryView { func build() { Scroll() { Column(space: 10) { Button(BindMenu).bindMenu( [ MenuElement( value: 菜单1, action: { Hilog.info(1, info, MenuElement test: 菜单1被点击) } ), MenuElement( value: 菜单2, action: { Hilog.info(1, info, MenuElement test: 菜单2被点击) } ) ] ) Button(BindMenu).bindMenu( [ MenuElement( value: 菜单1, action: { Hilog.info(1, info, MenuElement test: 菜单1被点击) } ), MenuElement( value: 菜单2, action: { Hilog.info(1, info, MenuElement test: 菜单2被点击) } ) ] ) } } } }示例要点每个MenuElement只需提供value菜单项文本与action点击回调代码极其精简。组件外层使用ScrollColumn(space: 10)布局多个按钮各自绑定独立菜单互不干扰。示例3不同菜单的显示、变化和过渡效果该示例系统演示了enableArrow、placement、arrowOffset、offset、backgroundColor、backgroundBlurStyle的显示效果为bindContextMenu配置transition实现自定义菜单及菜单预览时的显示/退出动效为bindContextMenu配置preview中的hoverScale实现组件截图到自定义预览图的“一镜到底”过渡动效源码文档package ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* import ohos.resource_manager.* import ohos.hilog.* import ohos.resource.__GenerateResource__ Entry Component class EntryView { Builder func myBuilder() { Row() { Image(r(app.media.startIcon)).size(width: 30.vp, height: 30.vp) Text(Builder 内容) .width(300.px) .onClick({ evt Hilog.info(1, info, Builder test: builder clicked!!!) }) } .width(150) } Builder func MyPreview() { Column() { Image(r(app.media.background)) .width(120) .height(120) } } func build() { Scroll() { Column(space: 10) { Text(enableArrow, placement, arrowOffset) Button(BindContextMenu-1).bindContextMenu( builder: myBuilder, responseType: ResponseType.LongPress, options: ContextMenuOptions( enableArrow: true, placement: Placement.Bottom, arrowOffset: 20.vp ) ) Text( offset, backgroundColor, backgroundBlurStyle, aboutToAppear - onAppear - aboutToDisappear - onDisappear ) Button(BindContextMenu-2) .bindContextMenu( builder: myBuilder, responseType: ResponseType.LongPress, options: ContextMenuOptions( offset: Position(x: 80.0, y: 80.0), backgroundColor: Color.Blue, backgroundBlurStyle: BlurStyle.BackgroundUltraThick, onAppear: { Hilog.info(1, info, ContextMenuOptions test: onAppear)}, onDisappear: { Hilog.info(1, info, ContextMenuOptions test: onDisappear)}, aboutToAppear: { Hilog.info(1, info, ContextMenuOptions test: aboutToAppear)}, aboutToDisappear: { Hilog.info(1, info, ContextMenuOptions test: aboutToDisappear)} ) ) Text(preview, transition) Text(BindContextMenu-3) .width(200) .height(80) .backgroundColor(Color.Gray) .textAlign(TextAlign.Center) .margin(20) .bindContextMenu( builder: myBuilder, responseType: ResponseType.LongPress, options: ContextMenuOptions( preview: bind(this.MyPreview, this), transition: TransitionEffect.SLIDE_SWITCH ) ) Text(preview, previewAnimationOptions[scale, transition]) Text(BindContextMenu-4) .width(200) .height(80) .backgroundColor(Color.Gray) .textAlign(TextAlign.Center) .margin(20) .bindContextMenu( builder: myBuilder, responseType: ResponseType.LongPress, options: ContextMenuOptions( preview: bind(this.MyPreview, this), previewAnimationOptions: ContextMenuAnimationOptions( transition: TransitionEffect .OPACITY .animation(AnimateParam(duration: 4000, curve: Curve.Ease)) ) ) ) Text(previewAnimationOptions: [hoverScale]) Text(BindContextMenu-5) .width(200) .height(80) .backgroundColor(Color.Gray) .textAlign(TextAlign.Center) .margin(20) .bindContextMenu( builder: myBuilder, responseType: ResponseType.LongPress, options: ContextMenuOptions( preview: bind(this.MyPreview, this), previewAnimationOptions: ContextMenuAnimationOptions() ) ) } } } }示例要点BindContextMenu-1enableArrow: trueplacement: Placement.BottomarrowOffset: 20.vp演示箭头、菜单位置与箭头偏移的组合效果。BindContextMenu-2offset: Position(x: 80.0, y: 80.0)调整弹出位置backgroundColor: Color.Blue与backgroundBlurStyle: BlurStyle.BackgroundUltraThick定制背板颜色与模糊材质同时注册onAppear、onDisappear、aboutToAppear、aboutToDisappear四个回调可观察“显示动效前 → 弹出 → 退出动效前 → 消失”的生命周期时序。BindContextMenu-3preview: bind(this.MyPreview, this)指定自定义预览内容transition: TransitionEffect.SLIDE_SWITCH设置菜单显示/退出滑动切换动效。BindContextMenu-4通过previewAnimationOptions.transition配置透明度过渡动效TransitionEffect.OPACITY配AnimateParam(duration: 4000, curve: Curve.Ease)4 秒缓动动画。BindContextMenu-5仅配置previewAnimationOptions: ContextMenuAnimationOptions()借助默认的hoverScale语义实现组件截图浮起并过渡到自定义预览图的“一镜到底”效果。实践要点与适用边界接口选择菜单项固定且逻辑简单时优先使用bindMenu(ArrayMenuElement)需要复杂内容图片、图标、自定义布局时使用bindMenu(CustomBuilder)需要长按/右键触发、预览图或进出场动效时使用bindContextMenu。触发方式ResponseType.LongPress适合触屏ResponseType.RightClick适合鼠标preview在 RightClick 场景下不生效。箭头与预览互斥设置preview为 CustomBuilder 后即使enableArrow为 true 也不显示箭头。位置避让placement 仅表示“优先位置”空间不足时会自动调整一旦调整了主方向offset失效设计动效时应避免依赖固定偏移。多级菜单CustomBuilder 内不可再嵌套bindMenu/bindContextMenu多级菜单需使用 Menu 组件配合 MenuItem / MenuItemGroup且仅支持 MenuPreviewMode 为 NONE 的菜单支持长按 500ms 弹出子菜单。相关资源菜单控制通用属性原始文档cj-universal-attribute-menu.mdMenuElement/ContextMenuOptions/ContextMenuAnimationOptions/ResponseType/Placement/CustomBuilder等公共类型定义cj-common-types.md多级菜单组件cj-menu-menu.md、cj-menu-menuitem.md、cj-menu-menuitemgroup.md过渡效果 TransitionEffectcj-animation-transition.md赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐仓颉语言 ArkUI 菜单控制Menu开发指南bindMenu 与 bindContextMenu 的模态、样式与生命周期详解仓颉语言 ArkUI 菜单控制Menu开发指南bindMenu 与 bindContextMenu 的模态、样式与生命周期详解 本文是面向鸿蒙 OpenH文档知识库教程OpenHarmony仓颉 ArkUI 图形绘制通用属性实战指南fill、stroke 与 antiAlias 全解析仓颉 ArkUI 图形绘制通用属性实战指南fill、stroke 与 antiAlias 全解析 本文聚焦仓颉语言 ArkUI 框架中的图形绘制通用属性Gr文档知识库教程OpenHarmony仓颉 ArkUI-CJ 焦点控制通用属性详解focusable、defaultFocus、tabIndex 与 FocusControl.requestFocus 实战仓颉 ArkUI CJ 焦点控制通用属性详解focusable、defaultFocus、tabIndex 与 FocusControl.requestFoc文档知识库教程OpenHarmony上一篇Laravel Activitylog在 Laravel 应用中记录用户与模型活动事件的完整指南下一篇15分钟实战指南基于FastAPIVue3打造现代化管理平台的完整攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
