面包屑

面包屑显示应用程序中当前页面或资源的链接层次结构。

安装

npx nextui-cli@latest add breadcrumbs

上述命令仅适用于单独安装。如果已全局安装 @nextui-org/react，则可以跳过此步骤。

导入

NextUI 导出了 2 个与面包屑相关的组件

• Breadcumbs：主组件，是其他组件的包装器。
• BreadcrumbItem：表示面包屑项的组件。

用法

禁用

禁用的面包屑会显示项目，但会阻止导航，以确保布局一致。最后一个项目表示当前页面，不会被禁用。

尺寸

颜色

变体

下划线

圆角

路由

<BreadcrumbItem> 组件适用于框架和客户端路由器，如 Next.js 和 React Router。请参阅 路由 指南以了解如何设置此项。

受控

您可以使用 isCurrent 和 onAction 属性来控制当前/活动项。

注意：如果需要，您可以使用 onPress 属性来处理面包屑项上的点击事件。

菜单类型

可以将 Breadcrumbs 组件用作水平菜单。当您希望显示可能的导航列表并让用户从中选择一个时，这很有用。

开始和结束内容

你可以通过使用 startContent 和 endContent 属性向面包屑的开头或结尾添加任何元素。上面的示例使用 startContent 属性向面包屑的开头添加图标。

自定义分隔符

你可以通过使用 separator 属性自定义面包屑之间的分隔符。

自定义项目

BreadcrumbItem 组件接受任何元素作为其子元素。这允许你自定义面包屑项目的显示。

上面的示例使用 下拉菜单 组件在面包屑中创建一个下拉菜单。

组件 Breadcrumbs 仅选择 BreadcrumbItem 组件作为其子组件。这意味着您无法将任何其他组件直接放置在 Breadcrumbs 组件中。

// ❌ This will not work,
// The Button will not be picked by the Breadcrumbs component.
<Breadcrumbs>
  <BreadcrumbItem>Item 1</BreadcrumbItem>
  <Button>Item 2</Button>
</Breadcrumbs>

// ✅ Instead, you can wrap the Button inside a BreadcrumbItem.
<Breadcrumbs>
  <BreadcrumbItem>Item 1</BreadcrumbItem>
  <BreadcrumbItem>
    <Button>Item 2</Button>
  </BreadcrumbItem>
</Breadcrumbs>

折叠项

组件 Breadcrumb 提供 3 个属性来控制项的折叠

• maxItems：指定要显示的面包屑的最大数量。当数量超过最大数量时，将仅显示第一个 itemsBeforeCollapse 和最后一个 itemsAfterCollapse，中间用省略号 (...) 隔开。
• itemsBeforeCollapse：如果超过最大数量，则在省略号 (...) 之前要显示的项数。
• itemsAfterCollapse：如果超过最大数量，则在省略号 (...) 之后要显示的项数。

注意：省略号项将使用第一个折叠项作为其 href 属性。

自定义省略号项

你可以使用 renderEllipsis 属性自定义省略号项。此属性接受一个返回 React 元素的函数。

插槽

• 面包屑插槽

• base：面包屑的主要插槽。它包装 list 插槽。

• list：面包屑列表包装器。

• ellipsis：省略号项的插槽。仅当面包屑折叠时才可见。

• separator：自定义分隔符的插槽，可以使用 separator 属性设置。

• 面包屑项插槽

• base：面包屑项的主要插槽。它包装 item 插槽。

• item：面包屑项包装器。

• separator：项分隔符的插槽。

自定义面包屑样式

你可以使用 classNames 属性自定义 Breadcrumbs 样式，使用 itemClasses 属性自定义其项目。

数据属性

BreadcrumbItem 在 item 元素上具有以下属性

• data-current：当面包屑项目为当前项目时。基于面包屑 isCurrent 属性或项目是否为最后一个项目。
• data-disabled：当面包屑项目被禁用时。基于面包屑 isDisabled 属性。
• data-focus：当面包屑项目被聚焦时。基于 useFocusRing。
• data-focus-visible：当面包屑项目通过键盘获得焦点时。基于 useFocusRing。

无障碍

• 作为项目的有序列表实现。
• 支持在面包屑上进行鼠标、触摸和键盘交互。
• 通过 <a> 元素或通过 ARIA 的自定义元素类型支持导航链接。
• 本地化 ARIA 标签支持地标导航区域。
• 支持禁用面包屑。
• 最后一项使用 aria-current 自动标记为当前页面。

API

面包屑属性

面包屑函数

面包屑事件

面包屑项属性

面包屑项事件

类型

渲染省略号函数

export type RenderEllipsisItemProps = {
  /**
   * The collapsed items.
   */
  items: BreadcrumbItemProps[];
  /**
   * The max number of items.
   */
  maxItems: number;
  /**
   * The picked item to render the ellipsis.
   */
  collapsedItem: ReactNode;
  /**
   * The default ellipsis icon.
   */
  ellipsisIcon: ReactNode;
  /**
   * Number of items to show before the ellipsis.
   */
  itemsBeforeCollapse: number;
  /**
   * Number of items to show after the ellipsis.
   */
  itemsAfterCollapse: number;
  /**
   * The separator between each breadcrumb. It is a chevron by default.
   */
  separator: ReactNode;
};

renderEllipsis: (props: RenderEllipsisItemProps) => ReactNode;