> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/tabs.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Tabs 标签页

在同一区域切换不同内容。


## 基础用法

通过 `items` 定义标签和内容，点击标签切换当前面板。线形标签未选中时使用正文色，悬停和按下时分别使用主题亮色和深色，默认颜色过渡为 300ms；选中标签使用主题色和铺满标签宽度的下划线，标签栏底部显示完整分割线。


概览

设置

概览内容

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tabs/basic.tsx"
import { Tabs } from '@ifhover/leaf-ui';

const items = [
  { key: 'overview', label: '概览', children: '概览内容' },
  { key: 'settings', label: '设置', children: '设置内容' },
];

export function TabsBasic() {
  return <Tabs aria-label="内容分类" items={items} />;
}
```

展开代码


## 示例

### 不同尺寸

通过 `size` 设置标签控件尺寸。线形标签的小、默认尺寸使用相同字号，通过上下间距区分高度；大尺寸同时增大字号和上下间距。每行展示一种形态，每列对比小、默认和大三种尺寸。窄屏下可横向滚动查看。


小尺寸默认尺寸大尺寸线形

概览

设置

概览内容

概览

设置

概览内容

概览

设置

概览内容

卡片

概览

设置

概览内容

概览

设置

概览内容

概览

设置

概览内容

分段

概览

设置

概览内容

概览

设置

概览内容

概览

设置

概览内容

sizes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tabs/sizes.tsx"
import { Grid, ScrollArea, Tabs, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const items = [
  { key: 'overview', label: '概览', children: '概览内容' },
  { key: 'settings', label: '设置', children: '设置内容' },
];

const sizes = [
  { value: 'sm', label: '小尺寸' },
  { value: 'md', label: '默认尺寸' },
  { value: 'lg', label: '大尺寸' },
] as const;

const appearances = [
  { value: 'line', label: '线形' },
  { value: 'card', label: '卡片' },
  { value: 'segmented', label: '分段' },
] as const;

export function TabsSizes() {
  return (
    <ScrollArea orientation="horizontal" aria-label="标签页样式与尺寸对照">
      <Grid
        columns={4}
        gap={24}
        align="center"
        style={{ gridTemplateColumns: 'max-content repeat(3, minmax(240px, 1fr))' }}
      >
        <span aria-hidden="true" />
        {sizes.map((size) => (
          <Text key={size.value} tone="muted">
            {size.label}
          </Text>
        ))}
        {appearances.map((appearance) => (
          <Fragment key={appearance.value}>
            <Text tone="muted">{appearance.label}</Text>
            {sizes.map((size) => (
              <Tabs
                key={size.value}
                aria-label={`${size.label}${appearance.label}`}
                size={size.value}
                type={appearance.value}
                items={items}
              />
            ))}
          </Fragment>
        ))}
      </Grid>
    </ScrollArea>
  );
}
```

展开代码

### 不同形态

通过 `type` 选择标签页外观；卡片（`card`）和分段（`segmented`）形态可通过 `tone` 切换主题浅底或实底，通过 `shape` 切换圆角矩形与胶囊形态。


线形

概览

设置

概览内容

卡片

概览

设置

概览内容

分段

概览

设置

概览内容

实底胶囊

概览

设置

概览内容

appearances.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tabs/appearances.tsx"
import { Space, Tabs, Text } from '@ifhover/leaf-ui';

const items = [
  { key: 'overview', label: '概览', children: '概览内容' },
  { key: 'settings', label: '设置', children: '设置内容' },
];

export function TabsAppearances() {
  return (
    <Space direction="vertical" align="stretch" size="lg">
      <Space direction="vertical" align="stretch" size="sm">
        <Text tone="muted">线形</Text>
        <Tabs aria-label="线形" type="line" items={items} />
      </Space>
      <Space direction="vertical" align="stretch" size="sm">
        <Text tone="muted">卡片</Text>
        <Tabs aria-label="卡片" type="card" items={items} />
      </Space>
      <Space direction="vertical" align="stretch" size="sm">
        <Text tone="muted">分段</Text>
        <Tabs aria-label="分段" type="segmented" items={items} />
      </Space>
      <Space direction="vertical" align="stretch" size="sm">
        <Text tone="muted">实底胶囊</Text>
        <Tabs aria-label="实底胶囊" type="segmented" tone="solid" shape="pill" items={items} />
      </Space>
    </Space>
  );
}
```

展开代码

### 视图切换

省略选项的 `children` 时只显示标签栏，通过 `activeKey` 和 `onChange` 切换组件外的内容。

默认方向键会激活下一个可用标签，Home / End 跳至首尾可用项；设置 `activationMode="manual"` 后，方向键只移动焦点，再按 Enter 或空格激活。


本周

本月

全年

显示本周内容。

view-switcher.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tabs/view-switcher.tsx"
import { Flex, Tabs, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function TabsViewSwitcher() {
  const [view, setView] = useState('week');
  return (
    <Flex direction="column" gap="md">
      <Tabs
        type="card"
        block
        aria-label="统计周期"
        activeKey={view}
        onChange={setView}
        items={[
          { key: 'week', label: '本周' },
          { key: 'month', label: '本月' },
          { key: 'year', label: '全年', disabled: true },
        ]}
      />
      <Text role="status">{view === 'week' ? '显示本周内容。' : '显示本月内容。'}</Text>
    </Flex>
  );
}
```

展开代码

### 保留输入状态

内容首次访问时挂载，默认保留已访问页面的输入状态；设置 `destroyInactive` 可在切走时卸载内容。


草稿

其他内容

preserved.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tabs/preserved.tsx"
import { Input, Tabs } from '@ifhover/leaf-ui';

const items = [
  {
    key: 'draft',
    label: '草稿',
    children: <Input aria-label="草稿内容" placeholder="输入内容后切换标签" />,
  },
  { key: 'preview', label: '其他内容', children: '切回草稿查看输入内容。' },
];

export function TabsPreserved() {
  return <Tabs aria-label="保留输入状态" items={items} />;
}
```

展开代码

### 新增与关闭

`onAdd` 和 `onClose` 只发出操作请求，由应用更新 `items`。列表为空时整个组件（包括添加按钮）都会隐藏，需要保留外部操作以恢复列表。


标签 1

标签 2

内容 1

清空标签恢复标签

closable.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tabs/closable.tsx"
import { Button, Flex, type TabItem, Tabs, Text } from '@ifhover/leaf-ui';
import { useRef, useState } from 'react';

const initialItems: TabItem[] = [
  { key: '1', label: '标签 1', children: '内容 1', closable: true },
  { key: '2', label: '标签 2', children: '内容 2', closable: true },
];

export function TabsClosable() {
  const nextId = useRef(3);
  const [items, setItems] = useState(initialItems);
  const addTab = () => {
    const key = String(nextId.current++);
    setItems((list) => [
      ...list,
      { key, label: `标签 ${key}`, children: `内容 ${key}`, closable: true },
    ]);
  };
  return (
    <Flex direction="column" gap="md">
      <Tabs
        aria-label="可编辑标签页"
        items={items}
        onAdd={addTab}
        addLabel="新增标签页"
        onClose={(key) => setItems((list) => list.filter((item) => item.key !== key))}
      />
      {items.length === 0 && (
        <Text role="status" tone="muted">
          暂无标签页，恢复后可继续添加。
        </Text>
      )}
      <Flex gap="sm" wrap>
        <Button variant="outline" disabled={items.length === 0} onClick={() => setItems([])}>
          清空标签
        </Button>
        <Button variant="outline" onClick={() => setItems(initialItems)}>
          恢复标签
        </Button>
      </Flex>
    </Flex>
  );
}
```

展开代码

### 标签排序

设置 `sortable`，将 `onReorder` 返回的列表写回 `items`。拖动手柄可调整顺序；也可聚焦手柄，按空格开始、方向键移动，再按空格确认，Escape 取消。


标签一

标签二

标签三

内容一

当前顺序：标签一、标签二、标签三

恢复顺序

extensions.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tabs/extensions.tsx"
import { Button, Flex, type TabItem, Tabs, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const initialItems: TabItem[] = [
  { key: 'one', label: '标签一', children: '内容一' },
  { key: 'two', label: '标签二', children: '内容二' },
  { key: 'three', label: '标签三', children: '内容三' },
];

export function ExtensionDemo() {
  const [items, setItems] = useState(initialItems);
  return (
    <Flex direction="column" gap="md">
      <Tabs aria-label="可排序标签页" items={items} sortable onReorder={setItems} />
      <Text role="status" tone="muted">
        当前顺序：{items.map((item) => item.label).join('、')}
      </Text>
      <Flex>
        <Button variant="outline" onClick={() => setItems(initialItems)}>
          恢复顺序
        </Button>
      </Flex>
    </Flex>
  );
}
```

展开代码

### 底部标签

设置 `placement="bottom"`，将标签放在内容下方。


概览

设置

概览内容

capabilities.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tabs/capabilities.tsx"
import { Tabs } from '@ifhover/leaf-ui';

const items = [
  { key: 'overview', label: '概览', children: '概览内容' },
  { key: 'settings', label: '设置', children: '设置内容' },
];

export function Capabilities() {
  return <Tabs aria-label="底部标签" placement="bottom" items={items} />;
}
```

展开代码


## API

### Tabs API

配置标签数据、当前标签与面板保留行为。

| 属性                 | 类型                                                            | 默认值           | 说明                                     |
| ------------------ | ------------------------------------------------------------- | ------------- | -------------------------------------- |
| `items`            | `readonly `[`TabItem`](#tabitem)`[]`                          | 必填            | 标签页列表；为空时不渲染组件                         |
| `activeKey`        | `string`                                                      | —             | 受控的当前标签 key，配合 onChange 更新。            |
| `defaultActiveKey` | `string`                                                      | 首个可用项         | 非受控模式的初始标签 key，后续变化不重置选中项。             |
| `onChange`         | `(key: string) => void`                                       | —             | 激活项变化                                  |
| `type`             | `'line' \| 'card' \| 'segmented'`                             | `'line'`      | 标签形态                                   |
| `tone`             | `'soft' \| 'solid'`                                           | `'soft'`      | 卡片或分段形态的选中高亮风格：soft 为主题浅底，solid 为主题实底。 |
| `shape`            | `'default' \| 'pill'`                                         | `'default'`   | 卡片或分段形态的标签圆角：default 为圆角矩形，pill 为胶囊形。  |
| `placement`        | `'top' \| 'bottom'`                                           | `'top'`       | 标签栏位置                                  |
| `size`             | `'sm' \| 'md' \| 'lg'`                                        | `'md'`        | 标签尺寸。                                  |
| `block`            | `boolean`                                                     | `false`       | 标签等宽铺满可用宽度                             |
| `activationMode`   | `'automatic' \| 'manual'`                                     | `'automatic'` | 方向键直接激活 / 回车或空格激活                      |
| `destroyInactive`  | `boolean`                                                     | `false`       | 切走时卸载内容                                |
| `extra`            | `ReactNode`                                                   | —             | 标签栏附加内容                                |
| `onClose`          | `(key: string, event: MouseEvent<HTMLButtonElement>) => void` | —             | 请求关闭，由应用移除 items 中的项；可阻止默认切换           |
| `onAdd`            | `() => void`                                                  | —             | 添加页签，传入后显示添加按钮                         |
| `addLabel`         | `string`                                                      | —             | 添加按钮的可访问名称                             |
| `overflow`         | `boolean`                                                     | `true`        | 溢出时显示两侧滚动按钮                            |
| `sortable`         | `boolean`                                                     | `false`       | 启用排序，配合 onReorder 使用                   |
| `onReorder`        | `(items: `[`TabItem`](#tabitem)`[]) => void`                  | —             | 返回排序后的页签                               |

### TabItem

定义单个标签的标识、名称和内容。

| 属性         | 类型          | 默认值     | 说明                 |
| ---------- | ----------- | ------- | ------------------ |
| `key`      | `string`    | 必填      | 唯一标识               |
| `label`    | `ReactNode` | 必填      | 标签名称               |
| `children` | `ReactNode` | —       | 可选的面板内容；省略时只显示标签栏  |
| `disabled` | `boolean`   | `false` | 禁用交互。              |
| `icon`     | `ReactNode` | —       | 前置图标               |
| `closable` | `boolean`   | `false` | 展示关闭按钮，需配合 onClose |
