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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/tabs.md.

Tabs 标签页

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

基础用法

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

概览内容
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
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
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
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
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
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
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
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

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

属性类型默认值说明
itemsreadonly TabItem[]必填标签页列表;为空时不渲染组件
activeKeystring—受控的当前标签 key,配合 onChange 更新。
defaultActiveKeystring首个可用项非受控模式的初始标签 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'标签尺寸。
blockbooleanfalse标签等宽铺满可用宽度
activationMode'automatic' | 'manual''automatic'方向键直接激活 / 回车或空格激活
destroyInactivebooleanfalse切走时卸载内容
extraReactNode—标签栏附加内容
onClose(key: string, event: MouseEvent<HTMLButtonElement>) => void—请求关闭,由应用移除 items 中的项;可阻止默认切换
onAdd() => void—添加页签,传入后显示添加按钮
addLabelstring—添加按钮的可访问名称
overflowbooleantrue溢出时显示两侧滚动按钮
sortablebooleanfalse启用排序,配合 onReorder 使用
onReorder(items: TabItem[]) => void—返回排序后的页签

TabItem

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

属性类型默认值说明
keystring必填唯一标识
labelReactNode必填标签名称
childrenReactNode—可选的面板内容;省略时只显示标签栏
disabledbooleanfalse禁用交互。
iconReactNode—前置图标
closablebooleanfalse展示关闭按钮,需配合 onClose