# Breadcrumbs 面包屑 · HeroUI

> 面包屑导航，用于展示当前页面在层级结构中的位置。

- 页面: https://jiguang132.com/zh/systems/heroui/docs/components/breadcrumbs
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## 引入

```tsx
import { Breadcrumbs } from '@heroui/react';
```

### 用法


> 示例 `breadcrumbs-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/breadcrumbs


### 组件结构

导入 Breadcrumbs 组件后，可通过点语法访问各个子部分。

```tsx
import { Breadcrumbs } from '@heroui/react';

export default () => (
  <Breadcrumbs>
    <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
    <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
    <Breadcrumbs.Item>Current Page</Breadcrumbs.Item>
  </Breadcrumbs>
)
```

### 导航层级


> 示例 `breadcrumbs-level-2`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/breadcrumbs


> 示例 `breadcrumbs-level-3`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/breadcrumbs


### 自定义分隔符


> 示例 `breadcrumbs-custom-separator`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/breadcrumbs


### 禁用状态


> 示例 `breadcrumbs-disabled`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/breadcrumbs


### 自定义渲染函数


> 示例 `breadcrumbs-custom-render-function`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/breadcrumbs


## 样式

### 传入 Tailwind CSS 类

```tsx
import { Breadcrumbs } from '@heroui/react';

function CustomBreadcrumbs() {
  return (
    <Breadcrumbs className="gap-2">
      <Breadcrumbs.Item href="#" className="text-blue-600">
        Home
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>Current</Breadcrumbs.Item>
    </Breadcrumbs>
  );
}
```

### 自定义组件类

要自定义 Breadcrumbs 的组件类，可使用 `@layer components` 指令。
  
[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .breadcrumbs {
    @apply gap-4 text-lg;
  }

  .breadcrumbs__link {
    @apply font-semibold;
  }

  .breadcrumbs__separator {
    @apply text-blue-500;
  }
}
```

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

Breadcrumbs 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/breadcrumbs.css)）：

#### 基础类

- `.breadcrumbs` - 面包屑根容器
- `.breadcrumbs__item` - 单个面包屑项的包裹层
- `.breadcrumbs__link` - 面包屑链接元素
- `.breadcrumbs__separator` - 项之间的分隔图标

#### 状态类

- `.breadcrumbs__link[data-current="true"]` - 当前页指示（非链接）

### 交互状态

组件同时支持 CSS 伪类与 data 属性，便于灵活编写样式：

- **当前页**：链接上的 `[data-current="true"]`
- **悬停**：链接元素支持常规悬停态
- **禁用**：`isDisabled` prop 会禁用所有链接

## API 参考

### Breadcrumbs Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `separator` | `ReactNode` | chevron-right icon | 面包屑项之间的自定义分隔符 |
| `isDisabled` | `boolean` | `false` | 是否禁用所有面包屑链接 |
| `className` | `string` | - | 额外的 CSS 类 |
| `children` | `ReactNode` | - | 面包屑项 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |

### Breadcrumbs.Item Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `href` | `string` | - | 链接 URL（当前页可省略） |
| `className` | `string` | - | 额外的 CSS 类 |
| `children` | `ReactNode \| RenderFunction` | - | 项内容或渲染函数 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, BreadcrumbRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |

## 无障碍

Breadcrumbs 基于 React Aria Components 的 Breadcrumbs 原语，提供：

- 导航地标的合适 ARIA 属性
- 通过 `aria-current="page"` 标示当前页
- 键盘导航支持
- 屏幕阅读器对导航上下文的播报

最后一项（无 `href`）会自动作为当前页指示。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt