docs/en/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-menu.md-代码预览-docs:基于OpenHarmony生态的开发者文档项目 - AtomGit

The Menu component is a vertical list of items presented to the user.

NOTE

This component is supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The Menu component must be used together with the bindMenu or bindContextMenu method. It does not work when used alone.

Child Components

This component contains the MenuItem and MenuItemGroup child components.

APIs

Menu()

Creates a fixed container for a menu. This API does not have any parameters.

NOTE

Rules for calculating the width of menus and menu items:

During the layout, the width of each menu item is expected to be the same. If a child component has its width set, the size calculation rule prevails.

If no width is set for the Menu component, it applies a default two-column width to the MenuItem and MenuItemGroup child components. If a menu item's content area exceeds the two-column width, the Menu component automatically expands the menu item's content area.

When an explicit width is set for the Menu component, its child components MenuItem and MenuItemGroup adopt a fixed width (equal to the Menu component's configured width minus the padding).

The minimum width is 64 vp.

Universal attributes unsupported by Menu: outline attributes and the shadow attribute

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Attributes

In addition to the universal attributes, the following attributes are supported.

font¹⁰⁺

font(value: Font)

Sets the size of all text within the menu.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	Font	Yes	Size of all text within the menu. Default value: { size: 16, family: 'HarmonyOS Sans', weight: FontWeight.Medium, style: FontStyle.Normal }

fontColor¹⁰⁺

fontColor(value: ResourceColor)

Sets the font color of all text within the menu.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	ResourceColor	Yes	Font color of all text within the menu.

radius¹⁰⁺

radius(value: Dimension | BorderRadiuses)

Sets the radius of the menu border corners.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	Dimension \| BorderRadiuses	Yes	Radius of the menu border corners. Default value: 8vp for 2-in-1 devices and 20vp for other devices Since API version 12, if the sum of the two maximum corner radii in the horizontal direction exceeds the menu width, or if the sum of the two maximum corner radii in the vertical direction exceeds the menu height, the default corner radius will be used for all four corners of the menu. When the Dimension type is used: Invalid input values will trigger a fallback to the default corner radius. When the BorderRadiuses type is used: Invalid input values will result in the menu having no rounded corners by default.

menuItemDivider¹²⁺

menuItemDivider(options: DividerStyleOptions | undefined)

Sets the style of the menu item divider. If this attribute is not set, the divider will not be displayed.

If the sum of startMargin and endMargin exceeds the component width, both startMargin and endMargin will be set to 0.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
options	DividerStyleOptions \| undefined	Yes	Style of the menu item divider. - strokeWidth: stroke width of the divider. - color: color of the divider. - startMargin: distance between the divider and the start edge of the menu item. - endMargin: distance between the divider and the end edge of the menu item. - mode: mode of the divider, which is FLOATING_ABOVE_MENU by default.

menuItemGroupDivider¹²⁺

menuItemGroupDivider(options: DividerStyleOptions | undefined)

Sets the style of the top and bottom dividers for the menu item group. If this attribute is not set, the dividers will be displayed by default.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
options	DividerStyleOptions \| undefined	Yes	Style of the top and bottom dividers for the menu item group. - strokeWidth: stroke width of the divider. The default value is 1 px. - color: color of the divider. The default value is #33000000. - startMargin: distance between the divider and the start edge of the menu item group. The default value is 16 vp. - endMargin: distance between the divider and the end edge of the menu item group. The default value is 16 vp. - mode: mode of the divider, which is FLOATING_ABOVE_MENU by default.

subMenuExpandingMode¹²⁺

subMenuExpandingMode(mode: SubMenuExpandingMode)

Sets the submenu expanding mode of the menu.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
mode	SubMenuExpandingMode	Yes	Submenu expanding mode of the menu. Default value: SubMenuExpandingMode.SIDE_EXPAND

subMenuExpandSymbol²⁰⁺

subMenuExpandSymbol(symbol: SymbolGlyphModifier)

Sets the submenu expand symbol of the menu.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
symbol	SymbolGlyphModifier	Yes	Submenu expand symbol of the menu. 1. SubMenuExpandingMode.SIDE_EXPAND: The expand symbol is not displayed. 2. SubMenuExpandingMode.EMBEDDED_EXPAND: The symbol rotates 180° clockwise upon expansion. Default value: $r('sys.symbol.chevron_down').fontSize('24vp')<br>3. SubMenuExpandingMode.STACK_EXPAND: The symbol rotates 90° clockwise upon expansion.<br>Default value: $ r('sys.symbol.chevron_forward').fontSize('20vp').padding('2vp')

fontSize^(deprecated)

fontSize(value: Length)

Sets the size of all text within the menu.

NOTE

This API is supported since API version 9 and deprecated since API version 10. You are advised to use font instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	Length	Yes	Size of all text within the menu. If the value of the Length type is a number, the unit is fp. Percentage values are not supported.

SubMenuExpandingMode¹²⁺

Enumerates the submenu expanding modes.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Value	Description
SIDE_EXPAND	0	Default mode. Submenus are expanded on the side on the same plane.
EMBEDDED_EXPAND	1	Embedded mode. Submenus are expanded while embedded within the main menu.
STACK_EXPAND	2	Stack mode. Submenus are expanded above the main menu.

Example

This example demonstrates how to implement a multi-level menu by configuring the builder parameter in MenuItem.

@Entry
@Component
struct Index {
  @State select: boolean = true;
  // Replace $r('app.media.xxx') with the image resource file you use.
  private iconStr: ResourceStr = $r("app.media.view_list_filled");
  private iconStr2: ResourceStr = $r("app.media.arrow_right_filled");

  @Builder
  SubMenu() {
    Menu() {
      MenuItem({ content: "Copy", labelInfo: "Ctrl+C" })
      MenuItem({ content: "Paste", labelInfo: "Ctrl+V" })
    }
  }

  @Builder
  MyMenu(){
    Menu() {
      MenuItem({ startIcon: $r("app.media.icon"), content: "Menu item" })
      MenuItem({ startIcon: $r("app.media.icon"), content: "Menu item" })
        .enabled(false)
      MenuItem({
        startIcon: this.iconStr,
        content: "Menu item",
        endIcon: this.iconStr2,
        builder: ():void=>this.SubMenu()
      })
      MenuItemGroup({ header: 'Subtitle' }) {
        MenuItem({
          startIcon: this.iconStr,
          content: "Menu item",
          endIcon: this.iconStr2,
          builder: ():void=>this.SubMenu()
        })
        MenuItem({
          startIcon: $r("app.media.app_icon"),
          content: "Menu item",
          endIcon: this.iconStr2,
          builder: ():void=>this.SubMenu()
        })
      }
      MenuItem({
        startIcon: this.iconStr,
        content: "Menu item",
      })
    }
  }

  build() {
    Row() {
      Column() {
        Text('click to show menu')
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .bindMenu(this.MyMenu)
      .width('100%')
    }
    .height('100%')
  }
}

Example 2: Setting the Symbol Icon

This example demonstrates how to implement a menu with symbol icons by configuring symbolStartIcon and symbolEndIcon.

// xxx.ets
import { SymbolGlyphModifier } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  @State startIconModifier: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_mic')).fontSize('24vp');
  @State endIconModifier: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_trash')).fontSize('24vp');
  @State selectIconModifier: SymbolGlyphModifier =
    new SymbolGlyphModifier($r('sys.symbol.checkmark')).fontSize('24vp');
  @State select: boolean = true;

  @Builder
  SubMenu() {
    Menu() {
      MenuItem({ content: "Copy", labelInfo: "Ctrl+C" })
      MenuItem({ content: "Paste", labelInfo: "Ctrl+V" })
    }
  }

  @Builder
  MyMenu() {
    Menu() {
      MenuItem({ symbolStartIcon: this.startIconModifier, content: "Menu item" })
      MenuItem({ symbolStartIcon: this.startIconModifier, content: "Menu item" })
        .enabled(false)
      MenuItem({
        symbolStartIcon: this.startIconModifier,
        content: "Menu item",
        symbolEndIcon: this.endIconModifier,
        builder: (): void => this.SubMenu()
      })
      MenuItemGroup({ header: 'Subtitle' }) {
        MenuItem({
          symbolStartIcon: this.startIconModifier,
          content: "Menu item",
          symbolEndIcon: this.endIconModifier,
          builder: (): void => this.SubMenu()
        })
        MenuItem({
          symbolStartIcon: this.startIconModifier,
          content: "Menu item",
          symbolEndIcon: this.endIconModifier,
          builder: (): void => this.SubMenu()
        })
      }
      MenuItem({
        content: "Menu item",
      }).selected(this.select).selectIcon(this.selectIconModifier)
    }
  }

  build() {
    Row() {
      Column() {
        Text('click to show menu')
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .bindMenu(this.MyMenu)
      .width('100%')
    }
    .height('100%')
  }
}

en-us_image_0000001174582862

This example demonstrates how to configure the expand symbol color for menu submenus using subMenuExpandSymbol.

import { SymbolGlyphModifier } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  @State startIconModifier: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_star'))
  @State endIconModifier: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_mic'))
  @State expandSymbolModifier: SymbolGlyphModifier =
    new SymbolGlyphModifier($r('sys.symbol.chevron_down')).fontColor([Color.Red]).fontSize('24vp')

  @Builder
  SubMenu() {
    Menu() {
      MenuItem({
        symbolStartIcon: this.startIconModifier,
        content: "Icons"
      })
      MenuItem({
        symbolStartIcon: this.startIconModifier,
        content: "List"
      })
    }.backgroundColor(Color.Grey)
  }

  @Builder
  MyMenu() {
    Menu() {
      MenuItem({
        symbolStartIcon: this.startIconModifier,
        symbolEndIcon: this.endIconModifier,
        content: "New folder",
        builder: (): void => this.SubMenu(),
      })
      MenuItem({
        symbolStartIcon: this.startIconModifier,
        content: "Sort by",
        builder: (): void => this.SubMenu(),
      })
      MenuItem({
        symbolStartIcon: this.startIconModifier,
        content: "View mode",
        builder: (): void => this.SubMenu(),
      })
    }
    .subMenuExpandingMode(SubMenuExpandingMode.EMBEDDED_EXPAND)
    .backgroundColor(Color.Grey)
    .subMenuExpandSymbol(this.expandSymbolModifier)
  }

  build() {
    Button('click to show menu')
      .position({ top: 40, left: 40 })
      .bindMenu(this.MyMenu)
  }
}

Example 4: Using the Divider Style

This example demonstrates how to implement the divider style using menuItemGroupDivider.

import { LengthMetrics } from '@kit.ArkUI'

@Entry
@Component
struct Index {

  @Builder
  MyMenu() {
    Menu() {
      MenuItem({ content: "Item Content" })
      MenuItem({ content: "Item Content" })
      MenuItem({ content: "Item Content" })
      MenuItemGroup() {
        MenuItem({ content: "Group Child" })
        MenuItem({ content: "Group Child" })
      }
      MenuItem({ content: "Item Content" })
    }
    .menuItemDivider({
      strokeWidth: LengthMetrics.vp(5),
      color: '#d5d5d5',
      mode: DividerMode.EMBEDDED_IN_MENU
    })
    .menuItemGroupDivider({
      strokeWidth: LengthMetrics.vp(5),
      color: '#707070',
      mode: DividerMode.EMBEDDED_IN_MENU
    })
  }

  build() {
    RelativeContainer() {
      Button("show menu")
        .bindMenu(this.MyMenu())
    }
    .height('100%')
    .width('100%')
  }
}

dividerStyleMode

Menu

Child Components

APIs

Attributes

font¹⁰⁺

fontColor¹⁰⁺

radius¹⁰⁺

menuItemDivider¹²⁺

menuItemGroupDivider¹²⁺

subMenuExpandingMode¹²⁺

subMenuExpandSymbol²⁰⁺

fontSize^(deprecated)

SubMenuExpandingMode¹²⁺

Example

Example 1: Implementing a Multi-Level Menu

Example 2: Setting the Symbol Icon

Example 3: Setting the Menu Submenu Expand Symbol

Example 4: Using the Divider Style

Menu

Child Components

APIs

Attributes

font10+

fontColor10+

radius10+

menuItemDivider12+

menuItemGroupDivider12+

subMenuExpandingMode12+

subMenuExpandSymbol20+

fontSize(deprecated)

SubMenuExpandingMode12+

Example

Example 1: Implementing a Multi-Level Menu

Example 2: Setting the Symbol Icon

Example 3: Setting the Menu Submenu Expand Symbol

Example 4: Using the Divider Style

font¹⁰⁺

fontColor¹⁰⁺

radius¹⁰⁺

menuItemDivider¹²⁺

menuItemGroupDivider¹²⁺

subMenuExpandingMode¹²⁺

subMenuExpandSymbol²⁰⁺

fontSize^(deprecated)

SubMenuExpandingMode¹²⁺