Nav

基础导航

基于 Bootstrap 5 的导航组件，Nav 系列（Nav、NavItem、NavLink）用于构建基础导航，支持 tabs/pills/underline 三种样式变体、填充与两端对齐、垂直布局、激活/禁用状态、受控/非受控激活 key 与自定义元素渲染，并可嵌入 NavDropdown 下拉菜单

Component Demo

Basic usage and examples of the Nav component

基础用法

激活
链接
另一个链接
禁用

Nav 渲染 `ul.nav`，NavItem 渲染 `li.nav-item`，NavLink 渲染 `a.nav-link`，与 Bootstrap 的导航结构一一对应；Nav 位于 Navbar 内时会自动追加 `navbar-nav` 类

样式变体

variant 分别渲染 `nav-tabs`、`nav-pills` 与 `nav-underline` 类，并自动为容器设置 `role="tablist"`

填充与两端对齐

fill 按内容比例分配宽度，justify 让所有条目等宽，分别对应 `nav-fill` 与 `nav-justified` 类

vertical 渲染 `flex-column`，传入断点时渲染响应式的 `flex-{breakpoint}-column` 类（如 flex-lg-column）

链接型导航

链接型
另一个链接
禁用链接

设置了 href 的 NavLink 渲染为 `a` 元素；未设置时渲染为 `button`，两者都携带 `nav-link` 类

激活与禁用

激活链接渲染 `active` 类并设置 `aria-current="page"`；禁用链接同时设置 `aria-disabled` 与 `tabIndex=-1`，禁用按钮使用原生 disabled 属性。设置了 defaultActiveKey 的 Nav 会根据点击自动维护激活状态

受控导航

当前激活的 key：home。传入 activeKey 后 Nav 变为受控组件，切换状态完全由 onSelect 驱动的外部 state 决定

嵌入下拉菜单

NavDropdown 渲染为 `li.nav-item.dropdown`，触发按钮为 `a.nav-link.dropdown-toggle`，菜单内容由 DropdownItem 组成，可与 Nav 无缝组合

API Documentation

Complete API reference for the Nav component

Props

Nav

属性名	类型	默认值	描述
`as`	`ElementType`	`'ul'`	根元素标签，默认渲染 `ul.nav`
`variant`	`NavVariant`	-	样式变体，`tabs`/`pills`/`underline` 分别渲染 `nav-tabs`/`nav-pills`/`nav-underline` 类，并自动为容器设置 `role="tablist"`
`activeKey`	`EventKey`	-	受控激活 key，与 NavLink 的 eventKey（未设置时回退到 href）匹配后自动设置激活样式，需配合 onSelect 更新
`defaultActiveKey`	`EventKey`	-	非受控模式下的初始激活 key，设置后点击 NavLink 会自动维护激活状态；未设置时 Nav 仅做静态展示
`onSelect`	`(eventKey: EventKey, event: SyntheticEvent) => void`	-	选择回调，在 NavLink 点击且未被阻止时触发
`fill`	`boolean`	`false`	渲染 `nav-fill` 类，让每个条目按内容比例填满可用宽度
`justify`	`boolean`	`false`	渲染 `nav-justified` 类，让每个条目等宽填满可用宽度
`vertical`	`boolean \| NavBreakpoint`	`false`	垂直布局，为 `true` 时渲染 `flex-column`，传入断点时渲染 `flex-{breakpoint}-column`
`role`	`string`	-	无障碍角色，设置 variant 时默认自动设置为 `tablist`
`className`	`string`	-	自定义类名

NavItem

属性名	类型	默认值	描述
`as`	`ElementType`	`'li'`	渲染的元素标签，默认渲染 `li.nav-item`
`className`	`string`	-	自定义类名

NavLink

属性名	类型	默认值	描述
`active`	`boolean`	`false`	强制激活状态，未设置时由 Nav 的 activeKey 与 eventKey（或 href）匹配得出
`as`	`ElementType`	-	渲染的元素标签，默认设置了 `href` 渲染 `a`，否则渲染 `button`
`disabled`	`boolean`	`false`	禁用状态，渲染 `disabled` 类与 `aria-disabled`；按钮同时设置原生 disabled，链接同时设置 `tabIndex={-1}`
`eventKey`	`EventKey`	`href`	关联 Nav 激活状态的 key，未设置时回退为 href
`href`	`string`	-	链接地址，设置后渲染为 `a` 标签；值为 `"#"` 时点击自动 `preventDefault`
`onSelect`	`(eventKey: EventKey, event: SyntheticEvent) => void`	-	点击回调，触发后事件继续冒泡到 Nav
`type`	`'button' \| 'reset' \| 'submit'`	`'button'`	渲染为按钮时的 type 属性

Type Definitions

EventKey

导航激活 key 类型

export type EventKey = number | string | null;

NavBreakpoint

垂直布局断点类型

export type NavBreakpoint = 'lg' | 'md' | 'sm' | 'xl' | 'xxl';

NavVariant

导航样式变体类型

export type NavVariant = 'pills' | 'tabs' | 'underline';

NavProps

导航容器组件属性接口

export interface NavProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'> {
  activeKey?: EventKey;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  defaultActiveKey?: EventKey;
  fill?: boolean;
  justify?: boolean;
  onSelect?: (eventKey: EventKey, event: SyntheticEvent) => void;
  variant?: NavVariant;
  vertical?: boolean | NavBreakpoint;
}

NavItemProps

导航条目组件属性接口

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

NavLinkProps

导航链接组件属性接口

export interface NavLinkProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'> {
  active?: boolean;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  disabled?: boolean;
  eventKey?: EventKey;
  href?: string;
  onSelect?: (eventKey: EventKey, event: SyntheticEvent) => void;
  type?: 'button' | 'reset' | 'submit';
}

NavContextValue

导航上下文，供 NavItem 与 NavLink 消费

export interface NavContextValue {
  activeEventKey?: EventKey;
  onSelect: (eventKey: EventKey, event: SyntheticEvent) => void;
  role?: string;
}