GitHubopen_in_new

Menu ​

Menu 支持下拉菜单、上下文菜单、子菜单和由对象驱动的菜单项渲染,并由组件组统一处理键盘与选择行为。

基本菜单 ​

下拉菜单和子菜单 ​

Selected: None

上下文菜单 ​

Right click here for context menu
Selected: None

选择 ​

单选值和多选值 ​

为 Menu 绑定 v-model,并为每个可选的 MenuItem 设置唯一的 value。单选值会选中一行;启用 multiple 后,模型值为数组。Menu 会根据每行的值推导其 checked 状态,以及 menuitemradio 或 menuitemcheckbox 角色。不要再单独维护每行的 checked 模型,也不要在点击处理程序中切换该值。

互斥选项使用 Radio presentation,独立选项使用 CheckBox presentation。将行插槽中的 checked 和 disabled 传给它们。若要在连续选择时保持菜单打开,请设置 :close-on-select="false"。

Sort by: name
Visible columns: size

调用方管理状态 ​

对于由现有布尔值管理的选项,省略 value:设置 role="menuitemcheckbox",绑定 checked,并在行的点击处理程序中更新状态。对于由调用方管理的单选组,设置 role="menuitemradio",根据共享值推导每行的 checked,并在激活时赋予相应值。

交互和呈现 ​

MenuItem 负责焦点、激活、无障碍状态和禁用行为。请在行上设置 disabled。Presentation 控件不会渲染原生 input,也不会增加焦点目标;它们只显示插槽状态。selected 控制行的强调样式,不能替代手动控制的复选框或单选项上的 checked。

上/下方向键会在可用行之间移动。Enter 或 Space 会激活当前聚焦的行;复选框会切换状态,单选项则会选中其值。Escape 会关闭菜单。子菜单使用右方向键进入、左方向键返回。

Presentation CheckBox 和 Radio 仅占用可见的方框或圆圈。独立控件的 target-size token 不会增加菜单内的占用空间。行尺寸、密度和菜单内边距 token 仍控制行间距;较大的内容可能会撑高菜单行。

其他组合 ​

内嵌 Select ​

选择 Select 选项会关闭 Select 菜单,但不会关闭外层 Menu。

Coffee: Espresso
Action: None

声明式条目 ​

链接 ​

让 MenuItem 本身渲染为可交互链接。不要在 MenuItem 内嵌套 <a>,否则会产生无效的交互标记。

使用 Vue Router 时,让 MenuItem 保持为渲染出的锚点,并通过 RouterLink 的 custom 插槽提供导航状态:

vue
<RouterLink custom to="/settings" v-slot="{ href, navigate }">
  <MenuItem :href="href" @click="navigate">
    设置
  </MenuItem>
</RouterLink>

外观 ​

行尺寸 ​

可在 Menu 上设置 size 统一调整所有菜单行,在 MenuItem 上设置以调整单行,或在 MenuSubMenu 上设置以调整一个分支。声明式菜单项和子菜单条目也接受 size。Select/Combobox 菜单会继承共享的行尺寸,其尺寸与输入框自身的尺寸相互独立。

尺寸比例、共享的 rowSize 默认值和密度行为,详见行尺寸。

颜色 ​

color 选择 standard 或 vibrant 调色板。显式属性优先于 menuDefaultsContextKey 中的 color,内置回退值为 standard。可在 M3VuePlugin 中设置 menuColor 作为应用默认值,或通过上下文配置子树。详见组件默认值。

子菜单会继承父菜单解析后的颜色,除非显式覆盖。Select 和 Combobox 菜单也使用相同的共享偏好,其 menuColor 属性优先。

密度 ​

菜单行会继承 --md-density,包括嵌套菜单以及 Select/Combobox 选项。每级密度会调整 4dp 的垂直留白;上下内边距最低为 4dp。标签、图标和多行内容保持原有尺寸。若要保留菜单的默认间距,可在菜单上设置 --md-density: 0。显式设置 --md-menus-menu-item-height、--md-menus-menu-item-top-space 和 --md-menus-menu-item-bottom-space 时,对应值会覆盖密度规则。

浮动表面 ​

共享主题颜色、边框、阴影,以及包含嵌套菜单和对话框的交互式示例,请参阅浮动表面 token。

参考 ​

属性

名称说明默认值
shape可选

Corner style; inherits the shared shape default.

M3Shape | undefined
-
role可选

Listbox mode retains the menu surface while the caller owns option navigation.

menulistbox
"menu"
size可选

Row size; inherits the nearest row size or defaults to medium.

RowSize | undefined
undefined
color可选

Visual color style of the menu surface.

MenuColor | undefined
-
items可选

Optional declarative menu content rendered from plain objects.

MenuContentItem[] | undefined
undefined
multiple可选

Enables checkbox semantics and array-based model values for items with `value`.

boolean | undefined
false
open可选

-

boolean | undefined
false
modelValue可选

-

MenuModelValue
-

事件4

名称类型说明
update:open[value: boolean]-
closed[]-
update:modelValue[value: MenuModelValue]-
select[event: MouseEvent, itemElement: HTMLElement]-

插槽1

名称参数说明
default-Menu content; usually MenuContainer and MenuGap.

样式84

Token说明
--md-menu-container-elevationElevation
回退值var(--md-sys-elevation-level2)

Controls container elevation.

--md-menu-container-shadow-colorColor
回退值var(--md-sys-color-shadow)

Controls container shadow color.

--md-menus-active-container-shapeShape
回退值var(--md-shape-popover)

Controls active container shape.

--md-menus-container-shapeShape
回退值var(--md-shape-popover)

Controls container shape.

--md-menus-gapLayout
回退值0.125rem

Controls gap.

--md-menus-group-paddingLayout
回退值--dp(4)

Controls group padding.

--md-menus-inactive-container-shapeShape
回退值var(--md-shape-chip)

Controls inactive container shape.

--md-menus-menu-item-between-spaceLayout
回退值--dp(12)

Controls menu item between space.

--md-menus-menu-item-bottom-spaceLayout
回退值--dp(12)

Controls menu item bottom space.

--md-menus-menu-item-first-child-shapeShape
回退值calc(var(--md-menus-container-shape,var(--md-shape-popover))- --dp(3))

Controls menu item first child shape.

--md-menus-menu-item-heightLayout
回退值--dp(48)

Controls menu item height.

--md-menus-menu-item-label-text-fontTypography
回退值var(--md-sys-typescale-label-large-font)

Controls menu item label text font.

--md-menus-menu-item-label-text-line-heightTypography
回退值var(--md-sys-typescale-label-large-line-height)

Controls menu item label text line height.

--md-menus-menu-item-label-text-sizeLayout
回退值var(--md-sys-typescale-label-large-size)

Controls menu item label text size.

--md-menus-menu-item-label-text-trackingTypography
回退值var(--md-sys-typescale-label-large-tracking)

Controls menu item label text tracking.

--md-menus-menu-item-label-text-weightTypography
回退值var(--md-sys-typescale-label-large-weight)

Controls menu item label text weight.

--md-menus-menu-item-last-child-shapeShape
回退值calc(var(--md-menus-container-shape,var(--md-shape-popover))- --dp(3))

Controls menu item last child shape.

--md-menus-menu-item-leading-icon-sizeLayout
回退值Typography, density and icon scale (default reference: --dp(20))

Controls menu item leading icon size.

--md-menus-menu-item-leading-spaceLayout
回退值--dp(12)

Controls menu item leading space.

--md-menus-menu-item-shapeShape
回退值var(--md-shape-popover-item)

Controls menu item shape.

--md-menus-menu-item-supporting-text-fontTypography
回退值var(--md-sys-typescale-body-small-font)

Controls menu item supporting text font.

--md-menus-menu-item-supporting-text-line-heightTypography
回退值var(--md-sys-typescale-body-small-line-height)

Controls menu item supporting text line height.

--md-menus-menu-item-supporting-text-sizeLayout
回退值var(--md-sys-typescale-body-small-size)

Controls menu item supporting text size.

--md-menus-menu-item-supporting-text-trackingTypography
回退值var(--md-sys-typescale-body-small-tracking)

Controls menu item supporting text tracking.

--md-menus-menu-item-supporting-text-weightTypography
回退值var(--md-sys-typescale-body-small-weight)

Controls menu item supporting text weight.

--md-menus-menu-item-top-spaceLayout
回退值--dp(12)

Controls menu item top space.

--md-menus-menu-item-trailing-icon-sizeLayout
回退值Typography, density and icon scale (default reference: --dp(20))

Controls menu item trailing icon size.

--md-menus-menu-item-trailing-spaceLayout
回退值--dp(12)

Controls menu item trailing space.

--md-menus-menu-item-trailing-supporting-text-fontTypography
回退值var(--md-sys-typescale-label-large-font)

Controls menu item trailing supporting text font.

--md-menus-menu-item-trailing-supporting-text-line-heightTypography
回退值var(--md-sys-typescale-label-large-line-height)

Controls menu item trailing supporting text line height.

--md-menus-menu-item-trailing-supporting-text-sizeLayout
回退值var(--md-sys-typescale-label-large-size)

Controls menu item trailing supporting text size.

--md-menus-menu-item-trailing-supporting-text-trackingTypography
回退值var(--md-sys-typescale-label-large-tracking)

Controls menu item trailing supporting text tracking.

--md-menus-menu-item-trailing-supporting-text-weightTypography
回退值var(--md-sys-typescale-label-large-weight)

Controls menu item trailing supporting text weight.

--md-menus-popover-paddingLayout
回退值0.25rem

Controls popover padding.

--md-menus-standard-container-colorColor
回退值var(--md-sys-color-surface-container-low)

Controls standard container color.

--md-menus-standard-menu-item-disabled-label-text-colorDisabled
回退值var(--md-sys-color-on-surface)

Controls standard menu item disabled label text color.

--md-menus-standard-menu-item-disabled-label-text-opacityDisabled
回退值0.38

Controls standard menu item disabled label text opacity.

--md-menus-standard-menu-item-disabled-leading-icon-colorDisabled
回退值var(--md-sys-color-on-surface)

Controls standard menu item disabled leading icon color.

--md-menus-standard-menu-item-disabled-leading-icon-opacityDisabled
回退值0.38

Controls standard menu item disabled leading icon opacity.

--md-menus-standard-menu-item-disabled-supporting-text-colorDisabled
回退值var(--md-sys-color-on-surface)

Controls standard menu item disabled supporting text color.

--md-menus-standard-menu-item-disabled-supporting-text-opacityDisabled
回退值0.38

Controls standard menu item disabled supporting text opacity.

--md-menus-standard-menu-item-disabled-trailing-icon-colorDisabled
回退值var(--md-sys-color-on-surface)

Controls standard menu item disabled trailing icon color.

--md-menus-standard-menu-item-disabled-trailing-icon-opacityDisabled
回退值0.38

Controls standard menu item disabled trailing icon opacity.

--md-menus-standard-menu-item-disabled-trailing-supporting-text-colorDisabled
回退值var(--md-sys-color-on-surface)

Controls standard menu item disabled trailing supporting text color.

--md-menus-standard-menu-item-disabled-trailing-supporting-text-opacityDisabled
回退值0.38

Controls standard menu item disabled trailing supporting text opacity.

--md-menus-standard-menu-item-hovered-state-layer-colorState
回退值var(--md-sys-color-on-surface)

Controls standard menu item hovered state layer color.

--md-menus-standard-menu-item-label-text-colorColor
回退值var(--md-sys-color-on-surface)

Controls standard menu item label text color.

--md-menus-standard-menu-item-leading-icon-colorColor
回退值var(--md-sys-color-on-surface-variant)

Controls standard menu item leading icon color.

--md-menus-standard-menu-item-selected-container-colorState
回退值var(--md-sys-color-tertiary-container)

Controls standard menu item selected container color.

--md-menus-standard-menu-item-selected-hovered-state-layer-colorState
回退值var(--md-sys-color-on-tertiary-container)

Controls standard menu item selected hovered state layer color.

--md-menus-standard-menu-item-selected-label-text-colorState
回退值var(--md-sys-color-on-tertiary-container)

Controls standard menu item selected label text color.

--md-menus-standard-menu-item-selected-leading-icon-colorState
回退值var(--md-sys-color-on-tertiary-container)

Controls standard menu item selected leading icon color.

--md-menus-standard-menu-item-selected-supporting-text-colorState
回退值var(--md-sys-color-on-tertiary-container)

Controls standard menu item selected supporting text color.

--md-menus-standard-menu-item-selected-trailing-icon-colorState
回退值var(--md-sys-color-on-tertiary-container)

Controls standard menu item selected trailing icon color.

--md-menus-standard-menu-item-selected-trailing-supporting-text-colorState
回退值var(--md-sys-color-on-tertiary-container)

Controls standard menu item selected trailing supporting text color.

--md-menus-standard-menu-item-supporting-text-colorColor
回退值var(--md-sys-color-on-surface-variant)

Controls standard menu item supporting text color.

--md-menus-standard-menu-item-trailing-icon-colorColor
回退值var(--md-sys-color-on-surface-variant)

Controls standard menu item trailing icon color.

--md-menus-standard-menu-item-trailing-supporting-text-colorColor
回退值var(--md-sys-color-on-surface-variant)

Controls standard menu item trailing supporting text color.

--md-menus-standard-section-label-text-colorColor
回退值var(--md-sys-color-on-surface-variant)

Controls standard section label text color.

--md-menus-vibrant-container-colorColor
回退值var(--md-sys-color-tertiary-container)

Controls vibrant container color.

--md-menus-vibrant-menu-item-disabled-label-text-colorDisabled
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item disabled label text color.

--md-menus-vibrant-menu-item-disabled-label-text-opacityDisabled
回退值0.38

Controls vibrant menu item disabled label text opacity.

--md-menus-vibrant-menu-item-disabled-leading-icon-colorDisabled
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item disabled leading icon color.

--md-menus-vibrant-menu-item-disabled-leading-icon-opacityDisabled
回退值0.38

Controls vibrant menu item disabled leading icon opacity.

--md-menus-vibrant-menu-item-disabled-supporting-text-colorDisabled
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item disabled supporting text color.

--md-menus-vibrant-menu-item-disabled-supporting-text-opacityDisabled
回退值0.38

Controls vibrant menu item disabled supporting text opacity.

--md-menus-vibrant-menu-item-disabled-trailing-icon-colorDisabled
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item disabled trailing icon color.

--md-menus-vibrant-menu-item-disabled-trailing-icon-opacityDisabled
回退值0.38

Controls vibrant menu item disabled trailing icon opacity.

--md-menus-vibrant-menu-item-disabled-trailing-supporting-text-colorDisabled
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item disabled trailing supporting text color.

--md-menus-vibrant-menu-item-disabled-trailing-supporting-text-opacityDisabled
回退值0.38

Controls vibrant menu item disabled trailing supporting text opacity.

--md-menus-vibrant-menu-item-hovered-state-layer-colorState
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item hovered state layer color.

--md-menus-vibrant-menu-item-label-text-colorColor
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item label text color.

--md-menus-vibrant-menu-item-leading-icon-colorColor
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item leading icon color.

--md-menus-vibrant-menu-item-selected-container-colorState
回退值var(--md-sys-color-tertiary)

Controls vibrant menu item selected container color.

--md-menus-vibrant-menu-item-selected-hovered-state-layer-colorState
回退值var(--md-sys-color-on-tertiary)

Controls vibrant menu item selected hovered state layer color.

--md-menus-vibrant-menu-item-selected-label-text-colorState
回退值var(--md-sys-color-on-tertiary)

Controls vibrant menu item selected label text color.

--md-menus-vibrant-menu-item-selected-leading-icon-colorState
回退值var(--md-sys-color-on-tertiary)

Controls vibrant menu item selected leading icon color.

--md-menus-vibrant-menu-item-selected-supporting-text-colorState
回退值var(--md-sys-color-on-tertiary)

Controls vibrant menu item selected supporting text color.

--md-menus-vibrant-menu-item-selected-trailing-icon-colorState
回退值var(--md-sys-color-on-tertiary)

Controls vibrant menu item selected trailing icon color.

--md-menus-vibrant-menu-item-selected-trailing-supporting-text-colorState
回退值var(--md-sys-color-on-tertiary)

Controls vibrant menu item selected trailing supporting text color.

--md-menus-vibrant-menu-item-supporting-text-colorColor
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item supporting text color.

--md-menus-vibrant-menu-item-trailing-icon-colorColor
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item trailing icon color.

--md-menus-vibrant-menu-item-trailing-supporting-text-colorColor
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant menu item trailing supporting text color.

--md-menus-vibrant-section-label-text-colorColor
回退值var(--md-sys-color-on-tertiary-container)

Controls vibrant section label text color.

原生弹出层关闭时会立即触发 update:open(false)。如果清理操作需要等到 Menu 自身的透明度和缩放退出动画结束后再执行,请使用 closed。插槽菜单内容内部的动画不计入等待范围。

Menu.show(focusFirst = false, source?) 也可在 Menu 已打开时调用。传入新的 source 会更新 CSS 锚点并保持 Menu 打开;不会触发 update:open(false) 或 closed,并会关闭所有子菜单。传入相同的 source 或省略 source 会保留当前锚点。每次以 focusFirst: true 调用都会明确请求聚焦首个菜单项;false 则保留当前焦点。Menu 关闭后,若再次调用时未传入 source,不会复用先前显式指定的 source。

插槽1

名称参数说明
default-Menu section content, such as labels, items, and dividers.

属性

名称说明默认值
shape可选

Corner style; inherits the shared shape default.

M3Shape | undefined
-
size可选

Row size; inherits the nearest row size or defaults to medium.

RowSize | undefined
undefined
value可选

Optional value that participates in Menu selection state.

MenuItemValue | undefined
undefined
href可选

Optional href. When provided, the item renders as an anchor.

string | undefined
undefined
disabled可选

Disables item interaction.

boolean | undefined
false
closeOnSelect可选

Whether selecting this item should close the menu chain. Ignored for submenu triggers.

boolean | undefined
true
selected可选

Marks item as selected/active.

boolean | undefined
false
role可选

Accessible menu item role for selectable items.

optionmenuitemmenuitemradiomenuitemcheckbox
undefined
checked可选

Checked state for radio/checkbox menu items.

boolean | undefined
false
submenu可选

Marks the item as a submenu trigger for future nested menus.

boolean | undefined
false
submenuOpen可选

Current open state of the submenu trigger, if applicable.

boolean | undefined
false

插槽6

名称参数说明
leading-Optional leading content, such as an icon.
default-Main menu item text.
trailing-Optional trailing icon content.
badge-Optional badge content.
trailingText-Optional trailing supporting text.
supporting-Optional supporting text shown below the main label.

属性

名称说明默认值
shape可选

-

M3Shape | undefined
-
size可选

Row size; inherits the nearest row size or defaults to medium.

RowSize | undefined
-
color可选

Visual color style of the nested menu surface. Defaults to the parent menu color.

MenuColor | undefined
-
debugSafeTriangle可选

Visualize the safe triangle used by pointer navigation.

boolean | undefined
-
open可选

-

boolean | undefined
false

事件1

名称类型说明
update:open[value: boolean]-

插槽2

名称参数说明
trigger-Trigger content. Usually a MenuItem with submenu state.
default-Nested menu content; usually MenuContainer and MenuGap.

插槽1

名称参数说明
default-Section label content.

结构

元素部件选择器
<div>
root
[data-scope="menu"][data-part="root"]
left_click鼠标左键单击复制
<div>
surface
[data-scope="menu"][data-part="surface"]
left_click鼠标左键单击复制
<div>
container
[data-scope="menu"][data-part="container"]
left_click鼠标左键单击复制
<hr>
divider
[data-scope="menu"][data-part="divider"]
left_click鼠标左键单击复制
<div>
gap
[data-scope="menu"][data-part="gap"]
left_click鼠标左键单击复制
<div>
label
[data-scope="menu"][data-part="label"]
left_click鼠标左键单击复制
<div>
submenu
[data-scope="menu"][data-part="submenu"]

结构

元素部件选择器
<component>
root
[data-scope="menu-item"][data-part="root"]
left_click鼠标左键单击复制
<span>
leading条件显示
[data-scope="menu-item"][data-part="leading"]
left_click鼠标左键单击复制
<span>
content
[data-scope="menu-item"][data-part="content"]
left_click鼠标左键单击复制
<span>
label
[data-scope="menu-item"][data-part="label"]
left_click鼠标左键单击复制
<span>
supporting条件显示
[data-scope="menu-item"][data-part="supporting"]
left_click鼠标左键单击复制
<span>
suffix条件显示
[data-scope="menu-item"][data-part="suffix"]
left_click鼠标左键单击复制
<span>
trailing条件显示
[data-scope="menu-item"][data-part="trailing"]
left_click鼠标左键单击复制
<span>
badge条件显示
[data-scope="menu-item"][data-part="badge"]
left_click鼠标左键单击复制
<span>
trailing-text条件显示
[data-scope="menu-item"][data-part="trailing-text"]
left_click鼠标左键单击复制

Composable ​

useMenu ​

完整类型签名function useMenu(options: UseMenuOptions): UseMenuReturn

来源:src/composables/useMenu.ts

字段类型必填说明默认值
menuIdstring是Unique ID for the menu instance.-
role(() => "menu" | "listbox") | undefined否Listbox callers own navigation over their complete logical collection.-
menuRefRef<HTMLElement | undefined, HTMLElement | undefined>是Ref to the menu DOM element.-
openRef<boolean, boolean>是Reactive open state.-
modelValueRef<MenuModelValue, MenuModelValue>是Reactive model value for selection.-
multiple() => boolean是Whether multi-select is enabled.-
onSelect((event: MouseEvent, itemElement: HTMLElement) => void) | undefined否Notify parent of item selection.-
exitElements(() => readonly (HTMLElement | null | undefined)[]) | undefined否Component-owned elements whose exit motion must finish with the menu root.-
onClosed(() => void) | undefined否Runs after the menu's visual exit finishes.-
parentCloseAll(() => void) | undefined否Parent menu context (for nested menus).-
parentSubmenu{ close: () => void; closeAndFocusTrigger: () => void; } | null | undefined否Parent submenu context.-
字段类型必填说明默认值
show(focusFirst?: boolean, source?: HTMLElement) => Promise<void>是Show or reanchor the menu; focusFirst explicitly focuses the first enabled item.-
hide() => void是Hide the menu.-
toggle() => void是Toggle menu open state.-
registerSubmenu(close: () => void) => () => void是Register a submenu closer. Returns unregister function.-
closeSubmenus(except?: () => void) => void是Close all submenus except the given one.-
closeMenuChain() => void是Close the entire menu chain (including parent menus).-
isValueSelected(value: MenuItemValue) => boolean是Check if a menu item value is currently selected.-
toggleValue(value: MenuItemValue) => void是Toggle a menu item value in the selection.-
onMenuKeydown(event: KeyboardEvent) => void是Keyboard handler for the menu element.-
onMenuClick(event: MouseEvent) => void是Click handler for the menu element.-
onMenuFocusIn(event: FocusEvent) => void是Focus-in handler for the menu element.-
onMenuToggle(event: Event) => void是Popover toggle handler for the menu element.-
focusItem(index: number) => void是Focus a specific menu item by index (wrapping).-
getMenuItemElements() => HTMLElement[]是Get all enabled menu item elements owned by this menu.-