仓颉 ArkUI MenuItemGroup 组件详解:菜单 MenuItem 分组的创建、参数配置与实战示例

原创2026-10-15 19:06:33401 阅读
文章标签:文档知识库

仓颉 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)
    }
}

代码要点解读:

  1. 分组嵌套:MenuItemGroup(header: "小标题", footer: "") 使用了 ?ResourceStr 重载,header 传入字符串字面量 "小标题",footer 传入空字符串表示无尾部说明。分组内部通过 => 箭头语法声明 MenuItem 子组件。
  2. 多级子菜单:分组内的 MenuItem 通过配置 builder: {=> bind(this.SubMenu, this)()} 绑定子菜单构建器,实现鼠标 hover 时弹出二级菜单,这与 MenuItem 文档 中 builder 参数“使用时结合 @Builder 和 bind 方法使用”的说明一致。
  3. 选中态联动:分组内的菜单项调用 .selectIcon(true).selected(select).onChange(...),selected 关联 @State 状态变量,选中状态变化时触发 onChange 回调。
  4. 菜单绑定:通过 .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。

注意事项与最佳实践

  1. 不能脱离 Menu 单独使用:MenuItemGroup 与 Menu 一样,需要配合 bindMenu 或 bindContextMenu 使用,不支持作为普通组件单独放置于页面布局中。
  2. 子组件仅限 MenuItem:分组内部只应放置 MenuItem,不要混入其他业务组件,以保持菜单的语义与布局规则。
  3. 标题与尾部参数:简单文本场景优先使用 ?ResourceStr 重载(header/footer 可省略,默认 "");需要自定义 UI 时改用 ?CustomBuilder 重载,但此时 header/footer 为必填命名参数。
  4. 多级菜单的实现:在分组内通过 MenuItem 的 builder 参数配合 @Builder 与 bind 方法可挂载子菜单;需注意 CustomBuilder 内不支持再使用 bindMenu、bindContextMenu 弹出菜单,多级菜单应使用 Menu 组件实现。
  5. 系统能力与版本:MenuItemGroup 的系统能力为 SystemCapability.ArkUI.ArkUI.Full,起始版本为 22,使用时需确认目标设备的系统版本满足要求。

总结

MenuItemGroup 是仓颉 ArkUI 菜单体系中负责结构化分组的核心容器,通过 header/footer 命名参数提供分组标题与尾部说明,通过 child 承载 MenuItem 菜单项。它依赖 Menu 容器与 bindMenu/bindContextMenu 绑定能力弹出,并遵循 Menu 容器统一的宽度计算规则。掌握其两种 init 重载的差异与完整用法,即可在鸿蒙应用中构建出带分组标题、多级子菜单与选中态联动的专业级菜单界面。

登录后查看全文
CangjieCorpus