仓颉 ArkUI MenuItemGroup 组件详解:菜单 MenuItem 分组的创建、参数配置与实战示例
仓颉 ArkUI MenuItemGroup 组件详解:菜单 MenuItem 分组的创建、参数配置与实战示例
本篇文章聚焦仓颉(Cangjie)语言 ArkUI 声明式 UI 框架中的 MenuItemGroup 菜单分组组件,系统讲解其在 Menu 菜单体系中的定位、两种 init 构造重载的差异、header/footer/child 命名参数的配置方式,以及如何通过 bindMenu/bindContextMenu 绑定到业务组件实现带分组标题的多级菜单。读完本文,你将能够在鸿蒙应用开发中熟练使用 MenuItemGroup 组织结构化菜单,并理解其与 Menu、MenuItem 组件之间的层级关系与宽度计算规则。
组件定位:MenuItemGroup 在菜单体系中的角色
MenuItemGroup 是一个用来展示菜单 MenuItem 分组的容器组件,它自身不承载交互逻辑,而是将若干 MenuItem 菜单项组织在一个带标题(header)和尾部说明(footer)的分组内,用于表达菜单项之间的从属或归类关系。
从 ArkUI 的组件层级来看,三者的关系如下:
- Menu:以垂直列表形式显示的菜单容器,是整个菜单体系的根;
MenuItemGroup:Menu 的直接子组件,负责对 MenuItem 进行分组;- MenuItem:Menu 与 MenuItemGroup 的叶子节点,是具体可操作的菜单项。
层级关系可以表示为:
Menu
├── MenuItem
└── MenuItemGroup
├── MenuItem
└── MenuItem
在 Menu 组件文档中明确说明,Menu 的子组件包含 MenuItem、MenuItemGroup 两类;而 MenuItemGroup 的子组件则仅包含 MenuItem。因此,分组场景下正确的写法是在 Menu { } 内嵌套 MenuItemGroup { },再在分组内放置 MenuItem。
导入模块
使用 MenuItemGroup 前需要导入 ArkUI 组件库:
import kit.ArkUI.*
该导入语句与 Menu、MenuItem 组件的导入方式一致,均来自 kit.ArkUI 包。
创建组件:两种 init 构造重载
MenuItemGroup 提供两个重载的 init 构造方法,二者的核心区别在于 header 与 footer 参数的类型:第一种使用 ?CustomBuilder(自定义构建器),第二种使用 ?ResourceStr(字符串资源)。开发时可根据标题内容是否包含自定义 UI 来决定选用哪种。
init(?CustomBuilder, ?CustomBuilder, () -> Unit)
该重载允许通过 CustomBuilder 为分组自定义标题与尾部区域,适合标题区域需要嵌入图标、复杂排版等自定义 UI 的场景。
public init(header!: ?CustomBuilder, footer!: ?CustomBuilder, child!: () -> Unit = {=>})
- 功能: 创建一个用来展示菜单
MenuItem的分组。 - 系统能力: SystemCapability.ArkUI.ArkUI.Full
- 起始版本: 22
参数说明:
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| header | ?CustomBuilder | 是 | - | 命名参数。 设置对应 group 的标题显示信息。初始值:{ => }。 |
| footer | ?CustomBuilder | 是 | - | 命名参数。 设置对应 group 的尾部显示信息。初始值:{ => }。 |
| child | () -> Unit | 否 | {=>} | 命名参数。 声明容器内的子组件。 |
init(?ResourceStr, ?ResourceStr, () -> Unit)
该重载的 header、footer 为 ?ResourceStr 类型,直接传入字符串或资源引用即可,是最常用的简单分组写法:
public init(header!: ?ResourceStr = None, footer!: ?ResourceStr = None, child!: () -> Unit = {=>})
- 功能: 创建一个用来展示菜单
MenuItem的分组。 - 系统能力: SystemCapability.ArkUI.ArkUI.Full
- 起始版本: 22
参数说明:
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| header | ?ResourceStr | 否 | None | 命名参数。 设置对应 group 的标题显示信息。初始值:""。 |
| footer | ?ResourceStr | 否 | None | 命名参数。 设置对应 group 的尾部显示信息。初始值:""。 |
| child | () -> Unit | 否 | {=>} | 命名参数。 声明容器内的子组件。 |
两种重载的差异与选型建议
| 维度 | init(?CustomBuilder, ...) | init(?ResourceStr, ...) |
|---|---|---|
| header/footer 类型 | 自定义构建器,可承载任意 UI 结构 | 字符串或资源引用,仅承载文本 |
| header/footer 必填性 | 必填(命名参数) | 可选,默认 None |
| 适用场景 | 分组标题需要图标、多行文本等自定义样式 | 简单的文本标题与尾部说明 |
两种重载中 child 参数均为 () -> Unit 类型且默认值为 {=>},用于声明分组内的 MenuItem 子组件集合。
关键类型说明
理解 MenuItemGroup 的参数类型,需要掌握两个基础类型:
- ResourceStr:在 cj-common-types.md 中定义为
public interface ResourceStr {},是一个字符串类型的入参接口,String通过extend String <: ResourceStr扩展为其子类,同时资源引用AppResource也实现了该接口。因此header/footer既可以传普通字符串字面量(如"小标题"),也可以传资源引用(如@r(app.string.xxx))。 - CustomBuilder:在 cj-common-types.md 中定义为
public type CustomBuilder = () -> Unit,即() -> Unit函数类型的别名,通常配合@Builder装饰的函数使用。
通用属性与通用事件
MenuItemGroup 支持全部通用属性与全部通用事件,这意味着通用的尺寸、布局、背景、边框、透明度、变换等属性以及点击、触摸、焦点、悬停等事件都可以直接应用于分组组件。这与 Menu、MenuItem 的说明保持一致。
实战示例:带分组标题的完整菜单
MenuItemGroup 无法脱离 Menu 单独使用。按照 Menu 组件文档 的说明,Menu 组件需配合 bindMenu 或 bindContextMenu 方法使用,不支持作为普通组件单独使用。
以下示例完整展示了 MenuItemGroup 在真实菜单中的用法,包含分组标题、分组内多级菜单项以及选中态切换:
package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.arkui.state_macro_manage.*
import ohos.i18n.*
import ohos.resource_manager.*
import ohos.resource.*
@Entry
@Component
class EntryView {
@State
var select: Bool = true
let iconStr: AppResource = @r(app.media.startIcon)
var iconStr2: AppResource = @r(app.media.right)
@Builder
func SubMenu() {
Menu() {
MenuItem(startIcon: "", content: "复制", endIcon: "", labelInfo: "Ctrl+C")
MenuItem(startIcon: "", content: "粘贴", endIcon: "", labelInfo: "Ctrl+V")
}
}
@Builder
func MyMenu() {
Menu() {
MenuItem(startIcon: @r(app.media.startIcon), content: @r(app.string.contentName),
endIcon: @r(app.media.blank), labelInfo: @r(app.string.emptyName))
MenuItem(startIcon: @r(app.media.startIcon), content: @r(app.string.contentName),
endIcon: @r(app.media.blank), labelInfo: @r(app.string.emptyName)).enabled(false)
MenuItem(
startIcon: this.iconStr,
content: @r(app.string.contentName),
endIcon: this.iconStr,
labelInfo: @r(app.string.emptyName),
builder: {=> bind(this.SubMenu, this)()}
)
MenuItemGroup(header: "小标题", footer: "") {
=>
MenuItem(
startIcon: this.iconStr,
content: @r(app.string.contentName),
endIcon: @r(app.string.emptyName),
labelInfo: @r(app.string.emptyName),
builder: {=> bind(this.SubMenu, this)()}
)
MenuItem(
startIcon: @r(app.media.startIcon),
content: @r(app.string.contentName),
endIcon: @r(app.media.right),
labelInfo: @r(app.string.emptyName),
builder: {=> bind(this.SubMenu, this)()}
)
MenuItem(
startIcon: "",
content: "菜单选项",
endIcon: "",
labelInfo: "",
).selectIcon(true).selected(
select).onChange({
selected => iconStr2 = @r(app.media.foreground)
})
}
}
}
func build() {
Row() {
Column() {
Text("click to show menu")
.fontSize(50)
.fontWeight(FontWeight.Bold)
}.bindMenu(builder: this.MyMenu).width(50.percent)
}.height(100.percent)
}
}
代码要点解读:
- 分组嵌套:
MenuItemGroup(header: "小标题", footer: "")使用了?ResourceStr重载,header传入字符串字面量"小标题",footer传入空字符串表示无尾部说明。分组内部通过=>箭头语法声明MenuItem子组件。 - 多级子菜单:分组内的
MenuItem通过配置builder: {=> bind(this.SubMenu, this)()}绑定子菜单构建器,实现鼠标 hover 时弹出二级菜单,这与 MenuItem 文档 中builder参数“使用时结合 @Builder 和 bind 方法使用”的说明一致。 - 选中态联动:分组内的菜单项调用
.selectIcon(true).selected(select).onChange(...),selected关联@State状态变量,选中状态变化时触发onChange回调。 - 菜单绑定:通过
.bindMenu(builder: this.MyMenu)将整个菜单绑定到Column组件,点击该区域即弹出菜单。
与 Menu、MenuItem 的关系及宽度计算规则
MenuItemGroup 作为 Menu 的子组件参与菜单布局。根据 Menu 组件文档 中关于菜单和菜单项宽度计算规则的说明,分组组件同样遵循以下规则:
- 布局过程中期望每个菜单项的宽度一致。若子组件设置了宽度,则以尺寸计算规则为准;
- 不设置宽度的情况:菜单组件会对子组件
MenuItem、MenuItemGroup设置默认 2 栅格的宽度,若菜单项内容区比 2 栅格宽,则会自适应撑开; - 设置宽度的情况:菜单组件会对子组件
MenuItem、MenuItemGroup设置减去 padding 后的固定宽度; - 设置
Menu边框width时,支持设置的最小宽度为 64vp。
这意味着 MenuItemGroup 的宽度由 Menu 容器统一调度,开发者无需(也不应)为分组单独设置宽度,将精力放在分组标题与菜单项内容的组织上即可。
菜单绑定方式回顾
MenuItemGroup 本身没有独立的绑定方法,它通过宿主 Menu 的绑定能力弹出。在 菜单控制接口文档 中提供了两种绑定方式:
- bindMenu(?CustomBuilder):绑定自定义菜单到组件,响应绑定组件的点击事件,菜单弹出无蒙层,为非模态;
- bindContextMenu(?CustomBuilder, ?ResponseType, ?ContextMenuOptions):绑定上下文菜单到组件,通过
ResponseType.RightClick(鼠标右键)或ResponseType.LongPress(长按)触发,弹出菜单显示在独立子窗口内,可显示在应用窗口外部。
以右键弹出为例:
Button("click for Menu")
.bindContextMenu(
builder: this.MyMenu,
responseType: ResponseType.RightClick
)
其中 MyMenu 即上文包含 MenuItemGroup 的 @Builder 菜单构建器。两种绑定接口的起始版本均为 22,系统能力均为 SystemCapability.ArkUI.ArkUI.Full。
注意事项与最佳实践
- 不能脱离 Menu 单独使用:
MenuItemGroup与Menu一样,需要配合bindMenu或bindContextMenu使用,不支持作为普通组件单独放置于页面布局中。 - 子组件仅限 MenuItem:分组内部只应放置
MenuItem,不要混入其他业务组件,以保持菜单的语义与布局规则。 - 标题与尾部参数:简单文本场景优先使用
?ResourceStr重载(header/footer可省略,默认"");需要自定义 UI 时改用?CustomBuilder重载,但此时header/footer为必填命名参数。 - 多级菜单的实现:在分组内通过
MenuItem的builder参数配合@Builder与bind方法可挂载子菜单;需注意CustomBuilder内不支持再使用bindMenu、bindContextMenu弹出菜单,多级菜单应使用Menu组件实现。 - 系统能力与版本:
MenuItemGroup的系统能力为 SystemCapability.ArkUI.ArkUI.Full,起始版本为 22,使用时需确认目标设备的系统版本满足要求。
总结
MenuItemGroup 是仓颉 ArkUI 菜单体系中负责结构化分组的核心容器,通过 header/footer 命名参数提供分组标题与尾部说明,通过 child 承载 MenuItem 菜单项。它依赖 Menu 容器与 bindMenu/bindContextMenu 绑定能力弹出,并遵循 Menu 容器统一的宽度计算规则。掌握其两种 init 重载的差异与完整用法,即可在鸿蒙应用中构建出带分组标题、多级子菜单与选中态联动的专业级菜单界面。