---
title: Tabs 标签页
description: Tabs 将内容组织为多个区块，并允许用户在它们之间导航。
icon: new
links:
  rac: Tabs
  source: tabs/tabs.tsx
  styles: tabs.css
  storybook: Components/Navigation/Tabs
  figma: true
---

## 用法

```tsx
import { Tabs } from '@heroui/react';
```

<ComponentPreview
  isBgSolid
  name="tabs-basic"
/>

## 组件结构

导入 Tabs 组件后，可通过点语法访问所有子部分。

```tsx
import { Tabs } from '@heroui/react';

export default () => (
  <Tabs>
    <Tabs.ListContainer>
      <Tabs.List aria-label="Options">
        <Tabs.Tab>
          <Tabs.Separator /> {/* Optional */}
          <Tabs.Indicator />
        </Tabs.Tab>
      </Tabs.List>
    </Tabs.ListContainer>
    <Tabs.Panel/>
  </Tabs>
)
```

## 示例

### 垂直布局

<ComponentPreview
  isBgSolid
  name="tabs-vertical"
/>

### 溢出

当标签列表超出可用空间时，`Tabs.ListContainer` 会自动渲染滚动箭头与渐隐边缘，使用户可以导航到被隐藏的标签。水平与垂直方向均支持此行为。

<ComponentPreview
  isBgSolid
  name="tabs-overflow"
/>

### 禁用 Tab

<ComponentPreview
  isBgSolid
  name="tabs-disabled"
/>

### 带分隔线

在每个 `<Tabs.Tab>` 内（第一项除外）添加 `<Tabs.Separator />`，用于在标签之间显示分隔线。

<ComponentPreview
  isBgSolid
  name="tabs-with-separator"
/>

### 次要类型

<ComponentPreview
  isBgSolid
  name="tabs-secondary"
/>

### 次要类型（垂直）

<ComponentPreview
  isBgSolid
  name="tabs-secondary-vertical"
/>

### 渲染函数

<ComponentPreview
  name="tabs-render-function"
/>

## 自定义样式

### Tailwind CSS

<ComponentPreview name="tabs-custom-styles" />

### 全局 CSS

若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

```css
@layer components {
  .tabs__list {
    @apply rounded-xl border border-border bg-surface p-1;
  }

  .tabs__tab {
    @apply rounded-lg font-medium;
  }

  .tabs__indicator {
    @apply rounded-lg bg-foreground shadow-sm;
  }

  .tabs--secondary > .tabs__list-container > .tabs__list {
    @apply border-b border-border bg-transparent p-0;
  }

  .tabs--secondary > .tabs__list-container .tabs__indicator {
    @apply rounded-none bg-accent;
  }
}
```

## 样式参考

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

Tabs 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tabs.css)）：

#### 基础类 [!toc]
- `.tabs` - Tabs 根容器
- `.tabs__list-container` - 标签列表容器外层包裹
- `.tabs__list-container__scroller` - 标签列表的可滚动容器（处理溢出与渐隐边缘）
- `.tabs__list-container__scroll-prev` - 向前（左 / 上）滚动的箭头按钮
- `.tabs__list-container__scroll-next` - 向后（右 / 下）滚动的箭头按钮
- `.tabs__list` - 标签列表容器
- `.tabs__tab` - 单个标签按钮
- `.tabs__separator` - 标签之间的分隔线
- `.tabs__panel` - 标签面板内容
- `.tabs__indicator` - 标签指示器

#### 方向属性 [!toc]
- `.tabs[data-orientation="horizontal"]` - 水平标签布局（默认）
- `.tabs[data-orientation="vertical"]` - 垂直标签布局

#### 变体类 [!toc]
- `.tabs--secondary` - 次要类型变体，使用下划线指示器

### 交互状态

组件同时支持 CSS 伪类与 data 属性：

- **Selected**：`[aria-selected="true"]`
- **Hover**：`:hover` 或 `[data-hovered="true"]`
- **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]`
- **Disabled**：`[aria-disabled="true"]`

## API 参考

### Tabs

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉样式变体。Primary 使用填充指示器，Secondary 使用下划线指示器 |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 标签布局方向 |
| `selectedKey` | `string` | - | 受控选中标签的 key |
| `defaultSelectedKey` | `string` | - | 默认选中标签的 key |
| `onSelectionChange` | `(key: Key) => void` | - | 选中变化回调 |
| `className` | `string` | - | 附加 CSS 类 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabsRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

### Tabs.List

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `aria-label` | `string` | - | 标签列表的无障碍标签 |
| `className` | `string` | - | 附加 CSS 类 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabListRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

### Tabs.Tab

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `id` | `string` | - | 标签唯一标识 |
| `isDisabled` | `boolean` | `false` | 是否禁用该标签 |
| `className` | `string` | - | 附加 CSS 类 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

### Tabs.Separator

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |

### Tabs.Panel

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `id` | `string` | - | 与对应 Tab id 匹配的面板标识 |
| `className` | `string` | - | 附加 CSS 类 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabPanelRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

## 相关案例

<RelatedShowcases component="Tabs" />

## 相关组件

<RelatedComponents component="tabs" />