---
title: "Breadcrumb 面包屑"
description: "显示当前页在层级中位置的导航路径"
category: Navigation
status: beta
since: 0.3.4
tags: [breadcrumb, navigation, hierarchy]
syncStatus: reviewed
verified: true
---

## 用法

### 链接与手动条目
带 `href` 的条目渲染为原生链接；其余可交互条目渲染为按钮并派发 `click`。
::::TuffDemoWrapper{demo="BreadcrumbBreadcrumbTrailDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  const items = [
    { label: '首页', href: '/', icon: 'i-carbon-home' },
    { label: '资料库' },
    { label: '数据' },
  ]

  function onBreadcrumbClick(item: { label: string }, index: number) {
    console.log(item.label, index)
  }
  </script>

  <template>
    <TxBreadcrumb :items="items" @click="onBreadcrumbClick" />
  </template>
---
::::

### 分隔图标

```vue
<template>
  <TxBreadcrumb :items="items" separator-icon="i-carbon-caret-right" />
</template>
```

### 最佳实践

- `items` 从最上层父级排到当前页。
- 真实路由用 `href`，保留原生链接的右键菜单与复制链接。
- 无 `href` 的条目只用于需要自定义行为的虚拟层级；`href` 链接不派发 `click`。
- 标签保持简短，只描述层级，不重复完整页面标题。
- 不要禁用当前项；最后一项本身不可交互。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `items` | `BreadcrumbItem[]` | 必填 | 有序条目，最后一项为当前页。 |
| `separatorIcon` | `string` | `'i-carbon-chevron-right'` | 条目之间的分隔图标。 |

### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `click` | `(item: BreadcrumbItem, index: number)` | 点击未禁用、无 `href` 的非当前条目时触发。 |

### 类型

`BreadcrumbItem`，`items` 中的一项：

| 字段 | 类型 | 说明 |
|------|------|------|
| `label` | `string` | 显示文本。 |
| `href` | `string` | 原生链接目标；当前项与禁用项忽略。 |
| `icon` | `string` | 文本前的 `TxIcon` 名称。 |
| `disabled` | `boolean` | 禁止交互，并标记 `aria-disabled`。 |

## 概述

- 根节点是 `<nav aria-label="Breadcrumb">`，内含有序列表。
- 最后一项渲染为 `<span aria-current="page">`，即使带 `href` 也不可交互。
- 其余未禁用的条目：带 `href` 渲染为 `<a>`，走原生导航；无 `href` 渲染为 `<button>`。
- 禁用项渲染为 `<span aria-disabled="true">`，不派发事件。
- 分隔符只出现在条目之间，带 `aria-hidden`。
- 图标名使用 `i-` 前缀的图标类，如 `i-carbon-home`。

## 技术实现

- 源码：`packages/tuffex/packages/components/src/breadcrumb/`。

<TuffDocSourceLink />