Breadcrumb
表示当前位置与上级路径。中文惯用名：面包屑。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.breadcrumb |
| 名称 | Breadcrumb |
| 二级分类 | 导航（navigation） |
| 用途 | 表示当前位置与上级路径 |
| 描述 | 中文惯用名：面包屑。 |
预览
静态结构：渲染为 <nav aria-label="breadcrumb" data-slot="breadcrumb"> → 列表 BreadcrumbList（data-slot="breadcrumb-list"，项之间插入 BreadcrumbSeparator，默认 ChevronRight 图标、aria-hidden）+ 项 BreadcrumbItem（data-slot="breadcrumb-item"）；非末项且带 href 渲染为链接 BreadcrumbLink（data-slot="breadcrumb-link"，站内路径的普通左键点击走渲染上下文路由，规则同 Link 组件），末项或缺少 href 的项渲染为当前页纯文本 BreadcrumbPage（data-slot="breadcrumb-page"，aria-current="page"）。本条 dsl 复用预览 BREADCRUMB_NODE（首页 / 组件 / 面包屑）。
DSL 结构
{
"type": "Breadcrumb",
"props": {
"items": [
{
"label": "首页",
"href": "/"
},
{
"label": "组件",
"href": "/components"
},
{
"label": "面包屑"
}
]
}
}何时用
何时使用
- 表达当前位置与上级路径：详情页、深层级设置的页面顶部。
- 提供快速回跳上级的入口：层级 2 层以上时每级都可点击返回。
- 帮助用户建立信息架构认知（从属关系），尤其在多级目录系统中。
何时不用
- 平级导航或模块跳转：使用 Menu、NavigationMenu。
- 表达流程进度：使用 Steps；长页面回到顶部：使用 BackTop。
- 单层页面（没有上级）：不渲染 Breadcrumb，避免占位噪声。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 可点击路径 | 上级为链接（hover 变色），末项纯文本 | 详情页顶部层级定位 |
| 省略中间层级 | 当前适配器无内建省略号（BreadcrumbEllipsis 未在适配器中暴露） | 层级过深时由调用方裁剪 items |
| 多级深层 | 3 级以上，逐级点击回跳 | 多级目录、组织 / 项目管理 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | BreadcrumbItemData[] | [] | 路径项（可含表达式解析后的数组）：{ label, href? }；末项始终渲染为当前页纯文本 |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- 末项不给 href（当前页不自链接），组件会自动渲染为纯文本 + aria-current="page"。
- 层级超过 3 级时省略中间层级（保留首级 + 直接父级），完整路径交给悬停提示或页面标题。
- 每级文案与目标页面标题一致，不用简称造成对不上号。
- 首页作为首级时统一写「首页」并给 href="/"，全站保持一致。
正例
- ✓ 组件详情页：首页 / 组件 / 面包屑，前两级可点击回跳。
- ✓ 项目设置页：首页 / 项目 / 设置，末项无 href 呈纯文本。
反例
- ✕ 给末项（当前页）也加 href（当前页自链接会误导用户）。
- ✕ 用 Breadcrumb 做模块间跳转导航（应使用 Menu / NavigationMenu）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。