React Bootstrap logoReact Bootstrap

Menu

基础导航

基于 Bootstrap 5 的菜单组件，Menu 套件（Menu、MenuItem、MenuSubMenu、MenuGroup、MenuDivider）用于构建垂直与水平导航菜单，支持内嵌展开与弹出式子菜单、任意层级嵌套、分组与分隔线、图标、禁用与危险状态、单选与多选、受控/非受控的选中与展开状态、深色主题、折叠图标轨道与完整键盘导航

Component Demo

Basic usage and examples of the Menu component

基础用法

Menu 渲染 `ul[role="menu"]`，MenuItem 渲染 `li[role="menuitem"]`，选中条目渲染高亮背景与主题色文本； 未设置 eventKey 的条目会按渲染位置自动生成 key

内嵌子菜单

mode="inline" 时子菜单在标题下方内嵌展开，支持任意层级嵌套；展开状态由 openKeys / defaultOpenKeys 维护，每一级默认缩进 inlineIndent 像素

垂直弹出子菜单

mode="vertical" 时点击标题在右侧弹出子菜单，弹出层靠近视口边缘会自动翻转方向， 点击条目后自动关闭

水平菜单

mode="horizontal" 时根条目横向排列，子菜单在标题下方弹出，默认 hover 触发（带 100ms 打开与 150ms 关闭延迟），点击标题可固定展开；弹出层内的嵌套子菜单内嵌展开

分组与分隔线

MenuGroup 渲染分组标题与条目列表，MenuDivider 渲染 `hr` 分隔线，两者都不可选中

深色主题

theme="dark" 切换深色配色：文本、悬停背景、禁用与分组颜色全部适配，弹出层同步渲染深色背景； 内嵌模式本身不带背景，可放入任意深色容器中

选中状态

当前选中：home

defaultActiveKey 提供非受控的初始选中，点击条目自动维护；传入 activeKey 后变为受控组件， 选中状态完全由 onSelect 驱动的外部 state 决定；selectable="false" 可整体关闭选中

多选

multiple 开启多选，点击已选中的条目会取消选中，activeKey / defaultActiveKey 使用数组形式

禁用与危险

disabled 条目与子菜单渲染禁用样式并设置 `aria-disabled`，不可选中也不可展开； danger 条目渲染危险色文本，适合删除类操作

折叠模式

inlineCollapsed 将菜单收缩为 collapsedWidth 宽度的图标轨道：条目只显示图标（与展开状态保持相同的左侧间距、左右留白对称）并自动生成悬停提示， 子菜单在右侧弹出飞入层，默认 hover 触发；折叠与展开由外部 state 驱动

自定义内容

条目内容完全自由：可以嵌入链接、徽标等任意元素，超长文本自动截断并显示省略号（配合 title 提供完整提示）， 也可以用 className 定制样式

API Documentation

Complete API reference for the Menu component

Props

Menu

属性名类型默认值描述
asElementType'ul'根元素标签，默认渲染 `ul` 并设置 `role="menu"`
modeMenuMode'vertical'菜单模式：`vertical` 子菜单在右侧弹出，`inline` 子菜单内嵌展开，`horizontal` 根条目水平排列且子菜单向下弹出
themeMenuTheme'light'主题，`"dark"` 渲染深色配色，弹出层同时应用深色背景
triggerMenuTrigger-弹出式子菜单的触发方式，默认 horizontal 为 `hover`、vertical/inline 为 `click`；折叠模式下固定为 hover
inlineCollapsedbooleanfalse折叠模式：仅显示图标，悬停子菜单时在右侧弹出飞入层；根菜单宽度收缩为 collapsedWidth
collapsedWidthnumber56折叠模式下根菜单的宽度（px），默认 56 保证图标左右留白与展开状态对称
inlineIndentnumber24内嵌子菜单每一级的缩进距离（px）
selectablebooleantrue是否可选中，为 `false` 时条目不渲染选中样式且不触发选中回调
multiplebooleanfalse多选模式，点击已选中的条目会取消选中，activeKey 使用数组形式
activeKeyEventKey | EventKey[]-受控选中 key（multiple 时为数组），与 MenuItem 的 eventKey 匹配
defaultActiveKeyEventKey | EventKey[]-非受控模式下的初始选中 key（multiple 时为数组），设置后点击条目自动维护选中状态
openKeysEventKey[][]受控展开的子菜单 key 列表，与 MenuSubMenu 的 eventKey 匹配
defaultOpenKeysEventKey[][]非受控模式下的初始展开子菜单 key 列表，设置后点击标题自动维护展开状态
onSelect(eventKey: EventKey, event: SyntheticEvent) => void-选中回调，点击 MenuItem 且事件未被阻止时触发
onOpenChange(openKeys: EventKey[]) => void-展开状态变化回调，在内嵌子菜单切换展开时触发
classNamestring-自定义类名

MenuItem

属性名类型默认值描述
eventKeyEventKey-条目 key，用于选中与展开状态匹配；未设置时按渲染位置自动生成
iconReactNode-条目图标，渲染在文本左侧
disabledbooleanfalse禁用状态，渲染禁用样式与 `aria-disabled`，点击不触发选中
dangerbooleanfalse危险状态，渲染危险色文本
titlestring-悬停提示；折叠模式下当内容为字符串时自动取内容文本
onSelect(eventKey: EventKey, event: SyntheticEvent) => void-条目选择回调，在点击且事件未被阻止时触发，之后继续触发 Menu 的 onSelect
asElementType'li'渲染的元素标签，默认渲染 `li[role="menuitem"]`
classNamestring-自定义类名

MenuSubMenu

属性名类型默认值描述
titleReactNode-子菜单标题（必填），渲染在标题行文本位置
eventKeyEventKey-子菜单 key，用于展开状态匹配；未设置时按渲染位置自动生成
iconReactNode-子菜单标题图标
disabledbooleanfalse禁用状态，标题行不可点击展开
asElementType'li'渲染的元素标签，默认渲染 `li`
classNamestring-自定义类名

MenuGroup

属性名类型默认值描述
labelReactNode-分组标题（必填），渲染为不可选中的说明文本；折叠模式下自动隐藏
asElementType'li'渲染的元素标签，默认渲染 `li`
classNamestring-自定义类名

MenuDivider

属性名类型默认值描述
asElementType'li'渲染的元素标签，默认渲染 `li`，内部为 `hr` 分隔线
classNamestring-自定义类名

Type Definitions

EventKey

菜单 key 类型

export type EventKey = null | number | string;

MenuMode

菜单模式类型

export type MenuMode = 'horizontal' | 'inline' | 'vertical';

MenuTheme

菜单主题类型

export type MenuTheme = 'dark' | 'light';

MenuTrigger

弹出式子菜单触发方式类型

export type MenuTrigger = 'click' | 'hover';

MenuProps

菜单容器组件属性接口

import type { ElementType, HTMLAttributes, ReactNode, SyntheticEvent } from 'react';

export interface MenuProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'> {
  activeKey?: EventKey | EventKey[];
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  collapsedWidth?: number;
  defaultActiveKey?: EventKey | EventKey[];
  defaultOpenKeys?: EventKey[];
  inlineCollapsed?: boolean;
  inlineIndent?: number;
  mode?: MenuMode;
  multiple?: boolean;
  onOpenChange?: (openKeys: EventKey[]) => void;
  onSelect?: (eventKey: EventKey, event: SyntheticEvent) => void;
  openKeys?: EventKey[];
  selectable?: boolean;
  theme?: MenuTheme;
  trigger?: MenuTrigger;
}

MenuItemProps

菜单条目组件属性接口

import type { ElementType, HTMLAttributes, ReactNode, SyntheticEvent } from 'react';

export interface MenuItemProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect' | 'title'> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  danger?: boolean;
  disabled?: boolean;
  eventKey?: EventKey;
  icon?: ReactNode;
  onSelect?: (eventKey: EventKey, event: SyntheticEvent) => void;
  title?: string;
}

MenuSubMenuProps

子菜单组件属性接口

import type { ElementType, HTMLAttributes, ReactNode, SyntheticEvent } from 'react';

export interface MenuSubMenuProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect' | 'title'> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  disabled?: boolean;
  eventKey?: EventKey;
  icon?: ReactNode;
  title: ReactNode;
}

MenuGroupProps

菜单分组组件属性接口

import type { ElementType, HTMLAttributes, ReactNode, SyntheticEvent } from 'react';

export interface MenuGroupProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  label: ReactNode;
}

MenuDividerProps

菜单分隔线组件属性接口

import type { ElementType, HTMLAttributes, ReactNode, SyntheticEvent } from 'react';

export interface MenuDividerProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
}

MenuContextValue

菜单上下文，供所有子组件消费

import type { ElementType, HTMLAttributes, ReactNode, SyntheticEvent } from 'react';

export interface MenuContextValue {
  activeKeys: EventKey[];
  inlineCollapsed: boolean;
  inlineIndent: number;
  level: number;
  mode: MenuMode;
  multiple: boolean;
  onItemSelect: (eventKey: EventKey, event: SyntheticEvent) => void;
  onOpenChange: (openKeys: EventKey[]) => void;
  openKeys: EventKey[];
  popup: boolean;
  selectable: boolean;
  theme: MenuTheme;
  trigger: MenuTrigger;
}