#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
配置标签数据、当前标签与面板保留行为。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | readonly 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[]) => void | — | 返回排序后的页签 |
#TabItem
定义单个标签的标识、名称和内容。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
key | string | 必填 | 唯一标识 |
label | ReactNode | 必填 | 标签名称 |
children | ReactNode | — | 可选的面板内容;省略时只显示标签栏 |
disabled | boolean | false | 禁用交互。 |
icon | ReactNode | — | 前置图标 |
closable | boolean | false | 展示关闭按钮,需配合 onClose |