syncfusion-blazor-breadcrumb

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion Blazor Breadcrumb Component

Syncfusion Blazor Breadcrumb 组件

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Build navigation breadcrumbs for single-page applications (SPAs) to show the user's current position in a hierarchy
Auto-generate breadcrumb trails based on the current URL path
Create custom navigation sequences with dynamic item management (add/remove items at runtime)
Handle overflow scenarios with many breadcrumb items (collapsed, menu, wrap, scroll modes)
Customize visual appearance with icons, images, separators, or templates
Implement templated breadcrumb layouts using Chip components or custom renderers
Enable/disable navigation based on business logic or user roles

The Syncfusion Blazor Breadcrumb component provides built-in URL parsing, responsive overflow handling, and templating capabilities to simplify hierarchical navigation UIs.

在以下场景中使用本技能：

为单页应用（SPAs）构建导航面包屑，展示用户在层级结构中的当前位置
根据当前URL路径自动生成面包屑导航轨迹
创建自定义导航序列，支持运行时动态管理导航项（添加/移除）
处理面包屑项过多的溢出场景（折叠、菜单、换行、滚动等模式）
通过图标、图片、分隔符或模板自定义视觉外观
使用Chip组件或自定义渲染器实现模板化面包屑布局
根据业务逻辑或用户角色启用/禁用导航功能

Syncfusion Blazor Breadcrumb组件提供内置的URL解析、响应式溢出处理和模板化功能，可简化层级导航UI的开发。

Component Overview

组件概述

The Blazor Breadcrumb component is a navigation control that displays a hierarchy of pages or sections visited within an application.

Key Features:

Auto-generated items from current URL path
Manual item declaration using
```
BreadcrumbItem
```
tag directive
Multiple overflow modes (Collapsed, Menu, Wrap, Scroll, Hidden, None)
Icon and image support via
```
IconCss
```
property
Template-based customization for items and separators
Dynamic item management (add/remove at runtime)
URL navigation (relative or absolute)
Responsive design with CSS customization

Blazor Breadcrumb组件是一款导航控件，用于显示用户在应用内访问过的页面或区域的层级结构。

核心特性：

从当前URL路径自动生成导航项
使用
BreadcrumbItem
标签指令手动声明导航项
多种溢出模式（折叠、菜单、换行、滚动、隐藏、无）
通过
IconCss
属性支持图标和图片
基于模板的项和分隔符自定义
运行时动态管理导航项（添加/移除）
URL导航（相对或绝对路径）
支持CSS自定义的响应式设计

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

NuGet package installation (
```
Syncfusion.Blazor.Navigations
```
)
Namespace imports and service registration
Theme stylesheet and script configuration
Basic
```
<SfBreadcrumb>
```
component initialization
First render with URL-based navigation

📄 阅读： references/getting-started.md

NuGet包安装（
```
Syncfusion.Blazor.Navigations
```
）
命名空间导入与服务注册
主题样式表和脚本配置
基础
```
<SfBreadcrumb>
```
组件初始化
基于URL导航的首次渲染

Item Configuration

项配置

📄 Read: references/breadcrumb-items-configuration.md

```
BreadcrumbItem
```
properties (
```
Text
```
,
```
Url
```
,
```
IconCss
```
)
Declaring items using
```
<BreadcrumbItem>
```
tag directive
Auto-generating items from the current page URL
Generating items from an absolute URL using the
```
Url
```
property
Dynamically adding and removing items at runtime using the
```
Items
```
property

📄 阅读： references/breadcrumb-items-configuration.md

```
BreadcrumbItem
```
属性（
```
Text
```
、
```
Url
```
、
```
IconCss
```
）
使用
```
<BreadcrumbItem>
```
标签指令声明导航项
从当前页面URL自动生成导航项
使用
```
Url
```
属性从绝对URL生成导航项
通过
```
Items
```
属性在运行时动态添加和移除导航项

Icons and Visual Elements

图标与视觉元素

📄 Read: references/icons-and-visual-elements.md

Adding font icons with
```
e-icons
```
CSS class
Image customization via
```
IconCss
```
property with custom CSS classes
SVG image support for breadcrumb items
Icon-only breadcrumb items (no text)
Displaying icons selectively (e.g., first item only)

📄 阅读： references/icons-and-visual-elements.md

使用
```
e-icons
```
CSS类添加字体图标
通过
```
IconCss
```
属性结合自定义CSS类实现图片自定义
面包屑项支持SVG图片
仅显示图标的面包屑项（无文本）
选择性显示图标（例如仅第一个项）

Navigation and Routing

导航与路由

📄 Read: references/navigation-and-routing.md

Relative URL navigation in breadcrumb items
Absolute URL navigation for external links
Disabling navigation with
```
EnableNavigation="false"
```
Enabling navigation for the active (last) item with
```
EnableActiveItemNavigation="true"
```

📄 阅读： references/navigation-and-routing.md

面包屑项中的相对URL导航
外部链接的绝对URL导航
使用
```
EnableNavigation="false"
```
禁用导航
使用
```
EnableActiveItemNavigation="true"
```
启用最后一个（活动）项的导航

Overflow Modes

溢出模式

📄 Read: references/overflow-modes.md

Limiting displayed items with
```
MaxItems
```
property
```
Collapsed
```
mode: Hide middle items, show first/last with expand button
```
Menu
```
mode: Remaining items in a dropdown submenu
```
Wrap
```
mode: Items wrap to multiple lines
```
Scroll
```
mode: Horizontal scroll bar for overflow
```
Hidden
```
mode: Hidden items revealed on parent click
```
None
```
mode: All items on a single line

📄 阅读： references/overflow-modes.md

使用
```
MaxItems
```
属性限制显示的项数量
```
Collapsed
```
模式：隐藏中间项，显示首尾项及展开按钮
```
Menu
```
模式：将剩余项放入下拉子菜单
```
Wrap
```
模式：项换行显示
```
Scroll
```
模式：通过横向滚动条处理溢出
```
Hidden
```
模式：点击父项显示隐藏的项
```
None
```
模式：所有项显示在单行

Templates and Customization

模板与自定义

📄 Read: references/templates-and-customization.md

```
ItemTemplate
```
for rendering custom item UI
```
SeparatorTemplate
```
for customizing item separators
Template
```
context
```
parameter for accessing current item data
Integrating Chip components with
```
ItemTemplate
```
Specific item customization using child content

📄 阅读： references/templates-and-customization.md

```
ItemTemplate
```
用于渲染自定义项UI
```
SeparatorTemplate
```
用于自定义项分隔符
模板
```
context
```
参数用于访问当前项数据
将Chip组件与
```
ItemTemplate
```
集成
使用子内容自定义特定项

Styling and Appearance

样式与外观

📄 Read: references/styling-and-appearance.md

CSS classes for customization (

.e-breadcrumb-item

.e-breadcrumb-text

.e-breadcrumb-icon

.e-breadcrumb-separator

)

Theme Studio integration for custom themes
Overriding default Breadcrumb styling with CSS
Customizing background, text color, icon color, and separator color

📄 阅读： references/styling-and-appearance.md

用于自定义的CSS类（

.e-breadcrumb-item

、

.e-breadcrumb-text

、

.e-breadcrumb-icon

、

.e-breadcrumb-separator

）

Theme Studio集成用于自定义主题
使用CSS覆盖默认面包屑样式
自定义背景、文本颜色、图标颜色和分隔符颜色

Quick Start Example

快速入门示例

Basic breadcrumb with explicit items:

cshtml

@using Syncfusion.Blazor.Navigations

<SfBreadcrumb>
    <BreadcrumbItems>
        <BreadcrumbItem IconCss="e-icons e-home" Url="https://example.com/home"></BreadcrumbItem>
        <BreadcrumbItem Text="Products" Url="https://example.com/products"></BreadcrumbItem>
        <BreadcrumbItem Text="Electronics" Url="https://example.com/products/electronics"></BreadcrumbItem>
        <BreadcrumbItem Text="Laptops"></BreadcrumbItem>
    </BreadcrumbItems>
</SfBreadcrumb>

Auto-generated breadcrumb from current URL:

cshtml

@using Syncfusion.Blazor.Navigations

<SfBreadcrumb></SfBreadcrumb>

带有明确项的基础面包屑：

cshtml

@using Syncfusion.Blazor.Navigations

<SfBreadcrumb>
    <BreadcrumbItems>
        <BreadcrumbItem IconCss="e-icons e-home" Url="https://example.com/home"></BreadcrumbItem>
        <BreadcrumbItem Text="Products" Url="https://example.com/products"></BreadcrumbItem>
        <BreadcrumbItem Text="Electronics" Url="https://example.com/products/electronics"></BreadcrumbItem>
        <BreadcrumbItem Text="Laptops"></BreadcrumbItem>
    </BreadcrumbItems>
</SfBreadcrumb>

从当前URL自动生成的面包屑：

cshtml

@using Syncfusion.Blazor.Navigations

<SfBreadcrumb></SfBreadcrumb>

Common Patterns

常见模式

Pattern 1: Icon + Text Items

模式1：图标+文本项

Combine icons with text for visual hierarchy and quick scanning:

cshtml

<SfBreadcrumb>
    <BreadcrumbItems>
        <BreadcrumbItem IconCss="e-icons e-home" Url="/"></BreadcrumbItem>
        <BreadcrumbItem IconCss="e-icons e-folder-open" Text="Documents" Url="/docs"></BreadcrumbItem>
        <BreadcrumbItem Text="Projects"></BreadcrumbItem>
    </BreadcrumbItems>
</SfBreadcrumb>

结合图标与文本，提升视觉层级和扫描效率：

cshtml

<SfBreadcrumb>
    <BreadcrumbItems>
        <BreadcrumbItem IconCss="e-icons e-home" Url="/"></BreadcrumbItem>
        <BreadcrumbItem IconCss="e-icons e-folder-open" Text="Documents" Url="/docs"></BreadcrumbItem>
        <BreadcrumbItem Text="Projects"></BreadcrumbItem>
    </BreadcrumbItems>
</SfBreadcrumb>

Pattern 2: Handling Long Breadcrumb Trails

模式2：处理长面包屑轨迹

Use

MaxItems

with

OverflowMode

to manage deep hierarchies:

cshtml

<SfBreadcrumb MaxItems="4" OverflowMode="BreadcrumbOverflowMode.Menu">
    <BreadcrumbItems>
        <BreadcrumbItem Text="Home" Url="/"></BreadcrumbItem>
        <BreadcrumbItem Text="Category 1" Url="/cat1"></BreadcrumbItem>
        <BreadcrumbItem Text="Category 2" Url="/cat1/cat2"></BreadcrumbItem>
        <BreadcrumbItem Text="Category 3" Url="/cat1/cat2/cat3"></BreadcrumbItem>
        <BreadcrumbItem Text="Current Page"></BreadcrumbItem>
    </BreadcrumbItems>
</SfBreadcrumb>

使用

MaxItems

和

OverflowMode

管理深层层级结构：

cshtml

<SfBreadcrumb MaxItems="4" OverflowMode="BreadcrumbOverflowMode.Menu">
    <BreadcrumbItems>
        <BreadcrumbItem Text="Home" Url="/"></BreadcrumbItem>
        <BreadcrumbItem Text="Category 1" Url="/cat1"></BreadcrumbItem>
        <BreadcrumbItem Text="Category 2" Url="/cat1/cat2"></BreadcrumbItem>
        <BreadcrumbItem Text="Category 3" Url="/cat1/cat2/cat3"></BreadcrumbItem>
        <BreadcrumbItem Text="Current Page"></BreadcrumbItem>
    </BreadcrumbItems>
</SfBreadcrumb>

Pattern 3: Dynamic Item Management

模式3：动态项管理

Add/remove items at runtime based on user actions:

csharp

@using Syncfusion.Blazor.Navigations

<SfBreadcrumb Items="@breadcrumbItems"></SfBreadcrumb>

<button @onclick="AddItem">Add Item</button>
<button @onclick="RemoveItem">Remove Item</button>

@code {
    List<BreadcrumbItem> breadcrumbItems = new List<BreadcrumbItem>
    {
        new BreadcrumbItem { IconCss = "e-icons e-home" },
        new BreadcrumbItem { Text = "Products" }
    };

    private void AddItem()
    {
        breadcrumbItems.Add(new BreadcrumbItem { Text = "New Item" });
    }

    private void RemoveItem()
    {
        if (breadcrumbItems.Count > 0)
            breadcrumbItems.RemoveAt(breadcrumbItems.Count - 1);
    }
}

根据用户操作在运行时添加/移除项：

csharp

@using Syncfusion.Blazor.Navigations

<SfBreadcrumb Items="@breadcrumbItems"></SfBreadcrumb>

<button @onclick="AddItem">Add Item</button>
<button @onclick="RemoveItem">Remove Item</button>

@code {
    List<BreadcrumbItem> breadcrumbItems = new List<BreadcrumbItem>
    {
        new BreadcrumbItem { IconCss = "e-icons e-home" },
        new BreadcrumbItem { Text = "Products" }
    };

    private void AddItem()
    {
        breadcrumbItems.Add(new BreadcrumbItem { Text = "New Item" });
    }

    private void RemoveItem()
    {
        if (breadcrumbItems.Count > 0)
            breadcrumbItems.RemoveAt(breadcrumbItems.Count - 1);
    }
}

Pattern 4: Custom Separator with Template

模式4：使用模板自定义分隔符

Use

SeparatorTemplate

for custom visual separators:

cshtml

<SfBreadcrumb>
    <BreadcrumbItems>
        <BreadcrumbItem Text="Home" Url="/"></BreadcrumbItem>
        <BreadcrumbItem Text="Products" Url="/products"></BreadcrumbItem>
        <BreadcrumbItem Text="Details"></BreadcrumbItem>
    </BreadcrumbItems>
    <BreadcrumbTemplates>
        <SeparatorTemplate>
            <span class="e-icons e-arrow"></span>
        </SeparatorTemplate>
    </BreadcrumbTemplates>
</SfBreadcrumb>

使用

SeparatorTemplate

实现自定义视觉分隔符：

cshtml

<SfBreadcrumb>
    <BreadcrumbItems>
        <BreadcrumbItem Text="Home" Url="/"></BreadcrumbItem>
        <BreadcrumbItem Text="Products" Url="/products"></BreadcrumbItem>
        <BreadcrumbItem Text="Details"></BreadcrumbItem>
    </BreadcrumbItems>
    <BreadcrumbTemplates>
        <SeparatorTemplate>
            <span class="e-icons e-arrow"></span>
        </SeparatorTemplate>
    </BreadcrumbTemplates>
</SfBreadcrumb>

Key Props

核心属性

Property	Type	Default	Purpose
`Items`	`List<BreadcrumbItem>`	null	Collection of breadcrumb items to display
`Url`	`string`	null	Generate items from a specific URL path
`MaxItems`	`int?`	null	Maximum items to display before overflow handling
`OverflowMode`	`BreadcrumbOverflowMode`	`Default`	How to handle items exceeding `MaxItems`
`EnableNavigation`	`bool`	`true`	Enable/disable URL navigation on item click
`EnableActiveItemNavigation`	`bool`	`false`	Enable navigation for the last (active) item
`ActiveItem`	`string`	null	Set the active (currently selected) item
`Class`	`string`	null	Custom CSS class for styling

属性	类型	默认值	用途
`Items`	`List<BreadcrumbItem>`	null	要显示的面包屑项集合
`Url`	`string`	null	从指定URL路径生成项
`MaxItems`	`int?`	null	触发溢出处理前的最大显示项数
`OverflowMode`	`BreadcrumbOverflowMode`	`Default`	处理超出 `MaxItems` 项的方式
`EnableNavigation`	`bool`	`true`	启用/禁用项点击时的URL导航
`EnableActiveItemNavigation`	`bool`	`false`	启用最后一个（活动）项的导航
`ActiveItem`	`string`	null	设置活动（当前选中）项
`Class`	`string`	null	用于样式自定义的CSS类

Common Use Cases

常见使用场景

E-commerce product breadcrumbs: Show navigation path through categories (Home > Electronics > Laptops > Gaming Laptops)
Admin dashboard navigation: Display user position in multi-level menu hierarchy
File explorer: Visualize folder navigation path with icons
Documentation sites: Show section hierarchy (Documentation > Guides > Getting Started)
Search result filters: Display active filter path (Search > Results > Filtered by Price)
Step-by-step workflows: Indicate current step in multi-step processes (Step 1 > Step 2 > Current)

Next Steps: Read the appropriate reference file based on your use case from the "Documentation and Navigation Guide" section above.

电商产品面包屑： 展示分类导航路径（首页 > 电子产品 > 笔记本电脑 > 游戏本）
管理后台导航： 显示用户在多级菜单层级中的位置
文件资源管理器： 用图标可视化文件夹导航路径
文档站点： 显示章节层级（文档 > 指南 > 快速入门）
搜索结果筛选： 显示活动筛选路径（搜索 > 结果 > 按价格筛选）
分步工作流： 指示多步骤流程中的当前步骤（步骤1 > 步骤2 > 当前步骤）

下一步： 根据你的使用场景，阅读上面“文档与导航指南”部分中的对应参考文件。