Breadcrumb#
导航
@rockshin/tao-ui展示用户当前所处的页面或视图层级。
#何时使用
当用户需要理解并返回多层级上下文时,将 Breadcrumb 放在页面内容顶部。
推荐
- 标签保持简短且易识别。
- 祖先节点使用链接,当前节点使用普通文本。
避免
- 不要把 Breadcrumb 当作主导航。
#代码演示
#基础用法
TSX
import { Breadcrumb } from '@rockshin/tao-ui';
function BreadcrumbExample() {
return (
<Breadcrumb
items={[
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'Components', href: '#breadcrumb-example-1' },
{ title: 'Breadcrumb' },
]}
/>
);
}
export default BreadcrumbExample;#分隔符与路径折叠
TSX
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';
function BreadcrumbSeparators() {
const items = [
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'Settings', href: '#breadcrumb-example-1' },
{ title: 'Profile' },
];
return (
<Stack gap="md">
<Breadcrumb separator="/" items={items} />
<Breadcrumb separator="›" items={items} />
<Breadcrumb
maxItems={3}
items={[
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'Workspace', href: '#breadcrumb-example-1' },
{ title: 'Projects', href: '#breadcrumb-example-1' },
{ title: 'tao-ui', href: '#breadcrumb-example-1' },
{ title: 'Settings' },
]}
/>
</Stack>
);
}
export default BreadcrumbSeparators;#禁用项与尺寸
TSX
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';
function BreadcrumbStates() {
const items = [
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'Archived', href: '#breadcrumb-example-1', disabled: true },
{ title: 'Item' },
];
return (
<Stack gap="md">
<TaoProvider size="small">
<Breadcrumb items={items} />
</TaoProvider>
<TaoProvider size="medium">
<Breadcrumb items={items} />
</TaoProvider>
<TaoProvider size="large">
<Breadcrumb items={items} />
</TaoProvider>
</Stack>
);
}
export default BreadcrumbStates;#自定义分隔符
通过 separator 调整路径分隔符,不改变链接和当前页语义。
TSX
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function BreadcrumbCustomSeparator() {
return (
<Stack gap="md">
<Breadcrumb
separator="/"
items={[
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'Docs', href: '#breadcrumb-example-1' },
{ title: 'Guide' },
]}
/>
<Breadcrumb
separator="›"
items={[
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'Settings', href: '#breadcrumb-example-1' },
{ title: 'Profile' },
]}
/>
</Stack>
);
}#折叠长路径
maxItems 折叠中间路径,点击省略入口查看被隐藏的层级。
TSX
import { Breadcrumb } from '@rockshin/tao-ui';
export default function BreadcrumbCollapsed() {
return (
<Breadcrumb
maxItems={3}
items={[
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'Group', href: '#breadcrumb-example-1' },
{ title: 'Section', href: '#breadcrumb-example-1' },
{ title: 'Subsection', href: '#breadcrumb-example-1' },
{ title: 'Current Page' },
]}
/>
);
}#不可用的路径项
将不可跳转的层级标为 disabled,当前页仍显示完整名称。
TSX
import { Breadcrumb } from '@rockshin/tao-ui';
export default function BreadcrumbDisabled() {
return (
<Breadcrumb
items={[
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'Archived', href: '#breadcrumb-example-1', disabled: true },
{ title: 'Item' },
]}
/>
);
}#自定义链接渲染
使用 itemRender 接入应用的链接组件,保留普通链接可访问行为。
TSX
import { Breadcrumb } from '@rockshin/tao-ui';
export default function BreadcrumbCustomLink() {
return (
<Breadcrumb
items={[
{ title: 'Home', key: 'home' },
{ title: 'Library', key: 'library' },
{ title: 'Data' },
]}
itemRender={(item, { isLast }) =>
isLast ? (
item.title
) : (
// Any custom element works — e.g. a router <Link>. Slot merges the
// breadcrumb link styles onto it instead of adding another <a>.
<a href="#breadcrumb-example-1">{item.title}</a>
)
}
/>
);
}#路径尺寸
用 TaoProvider 的 size 匹配紧凑工具栏或宽松页面标题区。
small
medium
large
TSX
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function BreadcrumbSizes() {
return (
<Stack gap="md">
{(['small', 'medium', 'large'] as const).map((size) => (
<div key={size}>
<p
style={{
fontSize: 13,
color: 'var(--tao-color-text-secondary)',
marginBottom: 4,
}}
>
{size}
</p>
<TaoProvider size={size}>
<Breadcrumb
items={[
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'List', href: '#breadcrumb-example-1' },
{ title: 'Detail' },
]}
/>
</TaoProvider>
</div>
))}
</Stack>
);
}#API
#Breadcrumb
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| items | Breadcrumb path, root first. The last item renders as the current page. | BreadcrumbItemType[] (必填) | - |
| separator | Separator between items. Defaults to a chevron, like shadcn. | ReactNode | - |
| maxItems | Collapse the middle of long paths into an ellipsis once the number of
items exceeds this value. Shows the first item and the last
maxItems - 1 items. | number | undefined | - |
| itemRender | Custom renderer for an item's content. Return a React element (e.g. a
router <Link>) and its props are merged onto the breadcrumb link via
Radix Slot — no extra <a> wrapper is added. | ((item: BreadcrumbItemType, info: { index: number; isLast: boolean; items: BreadcrumbItemType[]; }) => ReactNode) | undefined | - |
| className | 节点类名 | string | undefined | - |
| style | 节点样式 | CSSProperties | undefined | - |