NavDropdown

基础导航

基于 Bootstrap 5 的下拉导航组件，NavDropdown 将下拉菜单嵌入 Nav 中，渲染为 `li.nav-item.dropdown`，支持深色菜单、菜单对齐、多个展开方向、禁用状态、受控展开与激活状态同步，可与 Nav 的 activeKey/eventKey 联动

Component Demo

Basic usage and examples of the NavDropdown component

基础用法

NavDropdown 的 eventKey 与 Nav 的激活状态联动：选择 DropdownItem 后其 eventKey 会同步到 Nav，NavDropdown 因此显示 active 状态

展开方向

drop 分别渲染 `dropup`、`dropend`、`dropstart` 类，控制菜单的展开方向

深色菜单

menuVariant="dark" 渲染 `dropdown-menu-dark` 深色菜单类

禁用

disabled 禁用触发按钮，点击不再展开菜单，同时渲染 `disabled` 类与 `aria-disabled`

受控展开

当前展开状态：false。传入 show 后 NavDropdown 变为受控组件，展开状态完全由 onToggle 驱动的外部 state 决定

激活联动

当前激活的 key：home。当 activeKey 与 NavDropdown 的 eventKey（或最近选择的 DropdownItem eventKey）匹配时，NavDropdown 自动渲染 active 状态

API Documentation

Complete API reference for the NavDropdown component

Props

属性名	类型	默认值	描述
`title`	`ReactNode`	-	触发按钮文案，渲染在 `a.nav-link.dropdown-toggle` 内（必填）
`children`	`ReactNode`	-	菜单内容，通常由多个 DropdownItem 组成
`eventKey`	`EventKey`	-	关联 Nav 激活状态的 key，与 Nav 的 activeKey 匹配后 NavDropdown 显示 active
`id`	`string`	-	触发按钮 id，同时作为菜单的 `aria-labelledby` 关联
`disabled`	`boolean`	`false`	禁用触发按钮，点击不再展开菜单，同时渲染 `disabled` 类与 `aria-disabled`
`menuVariant`	`DropdownMenuVariant`	-	菜单变体，`"dark"` 渲染 `dropdown-menu-dark` 深色菜单类
`align`	`DropdownAlignOption`	-	菜单对齐，`"start"`/`"end"` 渲染 `dropdown-menu-start`/`dropdown-menu-end` 类；对象形式按断点生成响应式的 `dropdown-menu-{断点}-{对齐}` 类
`drop`	`DropdownDirection`	`'down'`	展开方向，`"up"`/`"end"`/`"start"` 分别渲染 `dropup`、`dropend`、`dropstart` 类
`autoClose`	`DropdownAutoClose`	`true`	自动关闭策略：`true` 选择菜单项或点击外部都关闭；`"inside"` 仅选择菜单项时关闭；`"outside"` 仅点击外部时关闭；`false` 永不自动关闭
`flip`	`boolean`	`true`	是否允许菜单靠近视口边缘时翻转到相反方向
`focusFirstItemOnShow`	`'keyboard' \| boolean`	`false`	展开时是否聚焦第一个菜单项，`"keyboard"` 表示仅通过键盘展开时聚焦
`show`	`boolean`	-	受控的展开状态，需配合 onToggle 更新
`defaultShow`	`boolean`	`false`	非受控模式下的初始展开状态
`onSelect`	`SelectCallback`	-	选择回调，点击 DropdownItem 且事件未被阻止时触发
`onToggle`	`ToggleCallback`	-	展开状态变化回调，配合 `show` 实现受控模式
`popperConfig`	`DropdownPositionConfig`	-	自定义定位配置，可分别覆盖 `flip`（是否允许翻转）、`offset` 与 `padding`
`renderMenuOnMount`	`boolean`	`false`	是否在首次渲染时就挂载菜单，默认首次展开时才挂载
`className`	`string`	-	自定义类名

Type Definitions

EventKey

导航激活 key 类型

export type EventKey = number | string | null;

NavDropdownProps

下拉导航组件属性接口

export interface NavDropdownProps extends Omit<
  DropdownProps,
  'as' | 'children' | 'onSelect' | 'title'
> {
  children?: ReactNode;
  disabled?: boolean;
  eventKey?: EventKey;
  id?: string;
  menuVariant?: DropdownMenuVariant;
  onSelect?: SelectCallback;
  title: ReactNode;
}