Breadcrumb 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

展示当前页面的层级路径，帮助用户理解所在位置并返回上级页面。

使用选择

用于表达当前页面的层级路径。平级内容切换用 Tab，应用导航用 Sidebar；路由跳转由页面处理。

• items 生成路径，最后一项自动成为不可交互的当前页。

• 显式 children 使用 Button as="item" 与 Text as="separator"，会替换 items；parts 仅配置默认生成的内容。

• 根导航默认名称随LocaleProvider更新，显式ariaLabel优先；路径文字与业务内容保持调用方原文。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Breadcrumb } from '@snowui-design-system/components';</script> <Breadcrumb	ariaLabel="SnowUI component page path"	items={[		{ label: 'Components' },		{ label: 'Navigation' },		{ label: 'Breadcrumb' }	]}/>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

功能概览

• 默认 items API + 显式组合高级 API。

• 最后一个 as="item" 自动作为当前页面。

• 可通过 variant 给内部 Button as="item" 提供默认 Button 变体。

• 非当前 item 默认整体透明度 40%，hover 时恢复 100%。

• item 属于同一导航复合控件，默认关闭 Button hover 放大；显式 scaleOnHover={true} 可按实例重新开启。

• 当前页面 item 输出 aria-current="page"，不可 hover、不可点击、不可键盘激活。

• separator 默认使用 14px / 20px 与 black/10%。

子级角色

SnowUI 组件使用 as="item" / as="separator"；原生元素使用 data-as="item" / data-as="separator"。

基础用法

<Breadcrumb>    <Button as="item" href="/dashboards">Dashboards</Button>    <Text as="separator">/</Text>    <Button as="item">Default</Button></Breadcrumb>

统一 Button 变体

<Breadcrumb variant="borderless">    <Button as="item" href="/dashboards">Dashboards</Button>    <Text as="separator">/</Text>    <Button as="item" variant="outline">Custom</Button>    <Text as="separator">/</Text>    <Button as="item">Default</Button></Breadcrumb>

Breadcrumb variant 只作为 item Button 的默认值：未写 variant 的 item 使用 Breadcrumb 的 variant，显式写了 variant 的 Button 保持自己的变体。若 Breadcrumb 不写 variant，Button 继续使用 Button 默认变体。

多级路径

<Breadcrumb>    <Button as="item" href="/">Home</Button>    <Text as="separator">/</Text>    <Button as="item" href="/dashboards">Dashboards</Button>    <Text as="separator">/</Text>    <Button as="item" href="/dashboards/default">Default</Button></Breadcrumb>

最后一个 item 会被自动标记为当前页，即使写了 href 也不会触发点击或跳转。

行为规则

1. 当前页面固定为 Breadcrumb 内最后一个 as="item" / data-as="item"。

2. 不提供 currentIndex，不支持指定任意一项为当前页。

3. 当前项自动设置 aria-current="page"、data-current="page"、tabindex="-1"。

4. 当前项不会触发 Button hover、click、Enter 或 Space。

5. separator 自动设置 aria-hidden="true"。

6. Breadcrumb 的 variant 只影响 Button as="item" 的默认 Button 变体，且不覆盖子级显式 variant。

7. Breadcrumb 为 item 提供 scaleOnHover=false 默认值；子级 Button 的显式值优先。

布局模型

主布局模型：内联外壳布局。定义见 ../../../specs/maintainers/LayoutProtocol.md §12.4（源码参考：specs/maintainers/LayoutProtocol.md）。

• Breadcrumb 根是 nav 容器，内部内容整体 Hug。

• 根容器使用 inline-flex，允许换行。

• 子级 Button 保留自身内联外壳布局。

• 子级 Text 保留自身文本流布局。

• Breadcrumb 只管理根 gap、separator 样式、非当前透明度与最后一项当前态。

• 路径元素之间的有效行／列间距至少为 4 CSS px；显式 gap={0}、根字号或间距缩放不压低下限，较大首选间距保持。根容器继续允许路径片段换行，不把整条导航强制改成 singleLine；各 Button 内部的图文单行仍由 Button 拥有。

布局变量链：