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

# Tabs

导航`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

在同一上下文中切换多个同级内容面板。

## 何时使用

内容类别同级且用户只需查看其中一个面板时使用 Tabs。

**推荐**

- 标签短且互不重叠。
- 默认激活最常用或最安全的面板。

**避免**

- 不要用 Tabs 隐藏必须按顺序完成的步骤。

## 代码演示


### 基础用法
```tsx preview
import { Tabs } from '@rockshin/tao-ui';

function TabsExample() {
  return (
    <Tabs
      items={[
        { key: 'general', label: 'General', children: 'General settings.' },
        { key: 'security', label: 'Security', children: 'Security settings.' },
        { key: 'billing', label: 'Billing', children: 'Billing settings.' },
      ]}
    />
  );
}

export default TabsExample;
```

### 卡片变体与尺寸
```tsx preview
import { Stack, Tabs } from '@rockshin/tao-ui';

const items = [
  { key: 'general', label: 'General', children: 'General settings.' },
  { key: 'security', label: 'Security', children: 'Security settings.' },
];

function TabVariants() {
  return (
    <Stack gap="lg">
      <Tabs items={items} size="small" />
      <Tabs items={items} variant="card" size="medium" />
      <Tabs items={items} variant="card" size="large" />
    </Stack>
  );
}

export default TabVariants;
```

### 受控与禁用标签页
```tsx preview
import { Tabs } from '@rockshin/tao-ui';
import { useState } from 'react';

function ControlledTabs() {
  const [activeKey, setActiveKey] = useState('general');

  return (
    <Tabs
      activeKey={activeKey}
      onChange={setActiveKey}
      items={[
        { key: 'general', label: 'General', children: 'General settings.' },
        { key: 'security', label: 'Security', children: 'Security settings.' },
        {
          key: 'billing',
          label: 'Billing',
          children: 'Unavailable.',
          disabled: true,
        },
      ]}
    />
  );
}

export default ControlledTabs;
```

### 外部控制标签页
通过 `activeKey` 与 `onChange` 把标签页状态纳入应用逻辑。
```tsx preview
import { Stack, Tabs } from '@rockshin/tao-ui';

import { useState } from 'react';

const basicItems = [
  { key: 'general', label: 'General', children: 'General settings content.' },
  {
    key: 'security',
    label: 'Security',
    children: 'Security settings content.',
  },
  {
    key: 'notifications',
    label: 'Notifications',
    children: 'Notification preferences.',
  },
];

export default function TabsControlled() {
  function Demo() {
    const [key, setKey] = useState('security');
    return (
      <Stack gap="md">
        <Tabs items={basicItems} activeKey={key} onChange={setKey} />
        <p style={{ color: 'var(--tao-color-text-secondary)', fontSize: 13 }}>
          activeKey: {key}
        </p>
      </Stack>
    );
  }
  return <Demo />;
}
```

### 禁用标签页
禁用暂不可访问的内容入口，其他标签仍可切换。
```tsx preview
import { Tabs } from '@rockshin/tao-ui';

export default function TabsDisabledTab() {
  return (
    <Tabs
      items={[
        { key: 'a', label: 'Active', children: 'This tab works.' },
        { key: 'b', label: 'Also Active', children: 'This too.' },
        {
          key: 'c',
          label: 'Disabled',
          children: 'Cannot reach.',
          disabled: true,
        },
      ]}
    />
  );
}
```

### 卡片标签尺寸
组合卡片变体与不同尺寸，对比密度与内容区域。
```tsx preview
import { Stack, Tabs } from '@rockshin/tao-ui';

const basicItems = [
  { key: 'general', label: 'General', children: 'General settings content.' },
  {
    key: 'security',
    label: 'Security',
    children: 'Security settings content.',
  },
  {
    key: 'notifications',
    label: 'Notifications',
    children: 'Notification preferences.',
  },
];

export default function TabsCardSizes() {
  return (
    <Stack gap="lg">
      <div>
        <p
          style={{
            fontSize: 13,
            color: 'var(--tao-color-text-secondary)',
            marginBottom: 8,
          }}
        >
          small
        </p>
        <Tabs items={basicItems} variant="card" size="small" />
      </div>
      <div>
        <p
          style={{
            fontSize: 13,
            color: 'var(--tao-color-text-secondary)',
            marginBottom: 8,
          }}
        >
          medium
        </p>
        <Tabs items={basicItems} variant="card" size="medium" />
      </div>
      <div>
        <p
          style={{
            fontSize: 13,
            color: 'var(--tao-color-text-secondary)',
            marginBottom: 8,
          }}
        >
          large
        </p>
        <Tabs items={basicItems} variant="card" size="large" />
      </div>
    </Stack>
  );
}
```

### 全局尺寸与局部覆盖
继承 Provider 的尺寸，并在需要时为某组标签显式覆盖。
```tsx preview
import { Tabs, TaoProvider } from '@rockshin/tao-ui';

const basicItems = [
  { key: 'general', label: 'General', children: 'General settings content.' },
  {
    key: 'security',
    label: 'Security',
    children: 'Security settings content.',
  },
  {
    key: 'notifications',
    label: 'Notifications',
    children: 'Notification preferences.',
  },
];

export default function TabsProviderInherit() {
  return (
    <TaoProvider size="large">
      <Tabs items={basicItems} variant="card" />
    </TaoProvider>
  );
}
```

### 切换时销毁内容
比较保留内容和销毁内容的行为；在面板中输入后切换可观察状态是否保留。
```tsx preview
import { Tabs } from '@rockshin/tao-ui';

export default function TabsDestroyInactive() {
  return (
    <Tabs
      items={[
        {
          key: 'a',
          label: 'Tab A',
          children: 'Only this panel is in DOM when active.',
        },
        { key: 'b', label: 'Tab B', children: 'Destroyed when not active.' },
        {
          key: 'c',
          label: 'Tab C',
          children: 'Also destroyed when not active.',
        },
      ]}
      destroyInactiveTabPane
    />
  );
}
```

## API


### [#](#tabs)Tabs



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| className | 节点类名 | `string | undefined` | `-` |

