跳到主要内容

Breadcrumb

  • 组件说明：面包屑导航，显示用户当前位置层级路径，支持快速返回上级。
  • 交互特征：非当前项可点击，hover 显示灰色背景；当前项不可点击。
  • 实现约定：推荐优先使用 items 数据源；如需自定义节点样式，使用 itemRender，不再对外暴露底层组合件。
  • Figma 规范

基础用法​

结果
Loading...
实时编辑器
render(
  <Breadcrumb
    items={[
      { title: 'Home', href: '#' },
      { title: 'Category', href: '#' },
      { title: 'Current Page' },
    ]}
  />,
)

Icon Text 样式​

Figma 支持 3 种 Style：Icon Text（图标+文字）、Icon（仅图标）、Text（仅文字）。

结果
Loading...
实时编辑器
render(
  <Breadcrumb
    items={[
      { title: 'Home', href: '#', icon: <IconPlaceholder size={20} /> },
      { title: 'Category', href: '#', icon: <IconPlaceholder size={20} /> },
      { title: 'Current Page', icon: <IconPlaceholder size={20} /> },
    ]}
  />,
)

Icon 样式​

仅图标时，通过 itemRender 自定义渲染内容。

结果
Loading...
实时编辑器
render(
  <Breadcrumb
    itemRender={({ isCurrent, item }) => {
      const content = <IconPlaceholder size={20} />

      if (isCurrent) {
        return (
          <span
            aria-label={String(item.title)}
            className="inline-flex items-center justify-center"
          >
            {content}
          </span>
        )
      }

      return (
        <a
          href={item.href}
          aria-label={String(item.title)}
          className="inline-flex items-center justify-center"
        >
          {content}
        </a>
      )
    }}
    items={[
      { title: 'Home', href: '#' },
      { title: 'Category', href: '#' },
      { title: 'Current' },
    ]}
  />,
)

带省略号（4+ 级）​

超过 4 级时自动折叠成 前二 + ... + 后二。...（Figma Style=Compressed）可交互：hover/点击高亮，选中后展开下拉，列出被折叠的中间项并按层级缩进。

结果
Loading...
实时编辑器
render(
  <Breadcrumb
    items={[
      { title: 'Home', href: '#' },
      { title: 'Category', href: '#' },
      { title: 'Sub Category', href: '#' },
      { title: 'Deep', href: '#' },
      { title: 'Workspace', href: '#' },
      { title: 'Current Page' },
    ]}
  />,
)

超长 title 截断​

使用 items API 默认渲染时，title 文本最大宽度为 260px（Figma Label maxWidth=260 + textTruncation=ENDING），超出部分以末尾省略号显示。当 title 为 string 时，会自动设置原生 title 属性，hover 可查看全文。组合模式（直接传入 children）不受影响，由使用方自行控制截断。

结果
Loading...
实时编辑器
render(
  <Breadcrumb
    items={[
      {
        title: '这是一段明显超过 260px 最大宽度的面包屑标题文本，用于演示末尾省略号截断效果',
        href: '#',
      },
      { title: '当前页' },
    ]}
  />,
)

Figma 样式矩阵​

Style说明推荐实现方式
Icon Text图标+文字items + icon
Icon仅图标items + itemRender
Text仅文字items

Props​

属性类型默认值说明
itemsBreadcrumbItemData[]-推荐用法，数据驱动渲染面包屑
itemRender({ item, index, isCurrent, items }) => ReactNode-自定义节点渲染
separatorReactNode-自定义分隔符
classNamestring-自定义样式类

数据结构​

字段类型默认值说明
keyReact.Key-唯一标识，未提供时回退为索引
titleReactNode-当前层级显示内容
hrefstring-点击跳转地址
iconReactNode-前置图标
currentbooleanfalse是否标记为当前页
separatorReactNode-当前项后使用的自定义分隔符
type'item' | 'ellipsis''item'数据类型，ellipsis 用于省略占位

高级用法​

当默认节点不满足需求时，通过 itemRender 统一接管单项渲染，而不是直接操作底层结构组件。

结果
Loading...
实时编辑器
render(
  <Breadcrumb
    itemRender={({ isCurrent, item }) => (
      <span
        className="inline-flex items-center gap-[var(--Spacing_8)] text-[length:var(--Font-Size-Body)] leading-[var(--Line-Height-Body)]"
        style={{ fontWeight: isCurrent ? 600 : 400 }}
      >
        <span className="flex items-center justify-center">{item.icon}</span>
        {item.title}
      </span>
    )}
    items={[
      { title: 'Home', href: '#', icon: <IconPlaceholder size={20} /> },
      { title: 'Projects', href: '#', icon: <IconPlaceholder size={20} /> },
      { title: 'Current', icon: <IconPlaceholder size={20} /> },
    ]}
  />,
)