Tabs

基础导航

基于 Bootstrap 5 的导航与标签页组件，Nav 系列（Nav、NavItem、NavLink）用于构建基础导航，Tabs 系列（Tabs、Tab、TabContainer、TabContent、TabPane）用于构建带内容面板的标签页，支持三种样式变体、填充与两端对齐、垂直布局、激活/禁用状态与淡入动画

Component Demo

Basic usage and examples of the Tabs 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"`

激活与禁用

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

填充与两端对齐

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

Flex 布局

className 可直接传入任意 `justify-content-*` 类；vertical 渲染 `flex-column`，传入断点时渲染响应式的 `flex-断点-column` 类（如 flex-sm-column）

链接与按钮

自定义标签

另一个自定义标签

未设置 href 时 NavLink 自动渲染为 `button`；通过 as 属性可将任意一层替换为自定义标签，便于接入路由组件

Tabs 标签页

首页内容：这是通过 Tabs 与 Tab 声明的第一个面板。

个人资料内容：点击上方标签切换面板，无需 Bootstrap JS。

禁用标签无法被选中，也不会渲染可交互的触发按钮。

胶囊样式的标签页，切换时带有淡入动画。

通过 variant 与 transition 属性分别控制样式与动画。

Tabs 将每个 Tab 的 title 渲染为标签按钮、children 渲染为面板内容；设置 id 后自动生成 `{id}-tab-{key}` 与 `{id}-tabpane-{key}` 关联 id

受控标签页

首页内容：当前激活的 key 由外部 state 控制。

个人资料内容：切换标签会触发 onSelect 回调。

消息内容：activeKey 与 onSelect 配合即可实现受控标签页。

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

TabContainer 自由组合

第一个面板的内容。

第二个面板的内容。

禁用面板的内容，永远不会显示。

TabContainer 通过上下文把 Nav 中的 NavLink 与 TabContent 中的 TabPane 按 eventKey 关联起来，导航与面板可以自由布局；transition 为面板启用淡入动画

路由集成

使用 react-router 等路由库时，可直接将路由 Link 作为条目内容，配合 `nav-link` 类即可实现客户端路由跳转

API Documentation

Complete API reference for the Tabs 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`

NavItem

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

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/TabContainer 激活状态的 key，未设置时回退为 href
`href`	`string`	-	链接地址，设置后渲染为 `a` 标签；值为 `"#"` 时点击自动 `preventDefault`
`onSelect`	`(eventKey: EventKey, event: SyntheticEvent) => void`	-	点击回调，触发后事件继续冒泡到 Nav 或 TabContainer
`type`	`'button' \| 'reset' \| 'submit'`	`'button'`	渲染为按钮时的 type 属性

Tab

属性名	类型	默认值	描述
`title`	`ReactNode`	-	标签触发按钮的文案
`onSelect`	`(eventKey: EventKey, event: SyntheticEvent) => void`	-	选择回调，在标签被选中时触发
`eventKey`	`EventKey`	-	关联 TabContainer 激活状态的 key
`disabled`	`boolean`	`false`	禁用该标签，触发按钮不可交互
`tabClassName`	`string`	-	标签触发按钮的自定义类名
`className`	`string`	-	标签条目（nav-item）的自定义类名
`children`	`ReactNode`	-	面板内容，由 Tabs 自动提取到对应 TabPane 中

TabContainer

属性名	类型	默认值	描述
`activeKey`	`EventKey`	-	受控激活 key，控制 Nav 与 TabPane 的激活状态
`defaultActiveKey`	`EventKey`	-	非受控模式下的初始激活 key
`id`	`string`	-	无障碍 id 前缀，为 NavLink 生成 `{id}-tab-{eventKey}`、为 TabPane 生成 `{id}-tabpane-{eventKey}` 并互相关联
`onSelect`	`(eventKey: EventKey, event: SyntheticEvent) => void`	-	选择回调，在 NavLink 点击且 key 不为 null 时触发
`transition`	`boolean`	`false`	面板淡入动画的默认值，TabPane 可通过同名属性单独覆盖
`as`	`ElementType`	`'div'`	根元素标签

TabContent

属性名	类型	默认值	描述
`as`	`ElementType`	`'div'`	渲染的元素标签，默认渲染 `div.tab-content`

TabPane

属性名	类型	默认值	描述
`active`	`boolean`	`false`	独立使用（不在 TabContainer 内）时手动控制激活状态
`as`	`ElementType`	`'div'`	渲染的元素标签，默认渲染 `div.tab-pane`
`eventKey`	`EventKey`	-	与 TabContainer 的 activeKey 匹配后自动渲染 active/show 类
`transition`	`boolean`	-	是否启用淡入动画，覆盖 TabContainer 的 transition 设置

Tabs

属性名	类型	默认值	描述
`activeKey`	`EventKey`	-	受控激活 key，控制标签与面板的切换
`defaultActiveKey`	`EventKey`	-	非受控模式下的初始激活 key
`onSelect`	`(eventKey: EventKey, event: SyntheticEvent) => void`	-	选择回调，在标签切换时触发
`id`	`string`	-	无障碍 id 前缀，用于关联标签与面板
`variant`	`NavVariant`	`'tabs'`	标签页样式变体，`tabs`/`pills`/`underline` 分别渲染 `nav-tabs`/`nav-pills`/`nav-underline`
`fill`	`boolean`	`false`	渲染 `nav-fill` 类，让标签按内容比例填满可用宽度
`justify`	`boolean`	`false`	渲染 `nav-justified` 类，让标签等宽填满可用宽度
`transition`	`boolean`	`false`	是否启用面板淡入动画
`className`	`string`	-	根容器自定义类名
`navClassName`	`string`	-	导航（nav）自定义类名
`contentClassName`	`string`	-	面板容器（tab-content）自定义类名
`children`	`ReactNode`	-	标签页内容，由若干个 Tab 组件组成

Common Props

属性名	类型	默认值	描述
`children`	`ReactNode`	-	组件内容
`className`	`string`	-	自定义类名
`...rest`	`HTMLAttributes`	-	透传原生元素属性（如 `onClick`、`style`、`role` 等）

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;
}

TabContainerProps

标签页容器组件属性接口

export interface TabContainerProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'> {
  activeKey?: EventKey;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  defaultActiveKey?: EventKey;
  id?: string;
  onSelect?: (eventKey: EventKey, event: SyntheticEvent) => void;
  transition?: boolean;
}

TabContentProps

标签页面板容器组件属性接口

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

TabPaneProps

标签页面板组件属性接口

export interface TabPaneProps extends HTMLAttributes<HTMLElement> {
  active?: boolean;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  eventKey?: EventKey;
  transition?: boolean;
}

TabProps

标签页条目组件属性接口

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

TabsProps

标签页组件属性接口

export interface TabsProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'> {
  activeKey?: EventKey;
  children?: ReactNode;
  className?: string;
  contentClassName?: string;
  defaultActiveKey?: EventKey;
  fill?: boolean;
  id?: string;
  justify?: boolean;
  navClassName?: string;
  onSelect?: (eventKey: EventKey, event: SyntheticEvent) => void;
  transition?: boolean;
  variant?: NavVariant;
}

TabsContextValue

标签页上下文，供 Nav、NavLink 与 TabPane 消费

export interface TabsContextValue {
  activeEventKey?: EventKey;
  id?: string;
  onSelect: (eventKey: EventKey, event: SyntheticEvent) => void;
  transition: boolean;
}