Back to Details

syncfusion-aspnetcore-breadcrumb

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Breadcrumb Navigation in ASP.NET Core

在ASP.NET Core中实现面包屑导航

The Breadcrumb component displays a hierarchical navigation path that helps users understand their location within your application. It enables navigation through parent pages and supports flexible data binding, templates, icons, and overflow handling.
Breadcrumb组件用于显示层级导航路径，帮助用户了解自己在应用中的位置。它支持导航至父页面，并提供灵活的数据绑定、模板、图标和溢出处理功能。

When to Use This Skill

何时使用此技能

Use this skill when you need to:
  • Display a hierarchical navigation breadcrumb in your ASP.NET Core application
  • Bind breadcrumb items from a collection or generate them from the current URL
  • Customize breadcrumb appearance using templates, icons, or CSS classes
  • Handle breadcrumb item clicks and render events
  • Implement overflow behavior for long breadcrumb trails
  • Support RTL rendering or disable specific items
当你需要以下功能时，可使用此技能：
  • 在ASP.NET Core应用中显示层级面包屑导航
  • 从集合绑定面包屑项，或根据当前URL生成面包屑项
  • 使用模板、图标或CSS类自定义面包屑外观
  • 处理面包屑项的点击和渲染事件
  • 为过长的面包屑路径实现溢出行为
  • 支持RTL（从右到左）渲染或禁用特定项

Component Overview

组件概述

The Breadcrumb component is a navigation UI element that:
  • Shows the current page position in a hierarchical structure
  • Allows users to navigate to parent-level pages
  • Renders items with optional icons, templates, and separators
  • Supports multiple overflow modes (Collapsed, Hidden, Menu, Wrap, Scroll, None)
  • Triggers events for item rendering and clicks
  • Works with ASP.NET Core TagHelper syntax
Key Properties:
  • items
    - Array of BreadcrumbItem objects to display
  • url
    - Automatically generate items from a URL path
  • activeItem
    - Mark a specific item as currently active
  • enableNavigation
    - Control whether items are navigable
  • overflowMode
    + 
    maxItems
    - Handle long breadcrumb trails
  • itemTemplate
    + 
    separatorTemplate
    - Customize rendering
Key Events:
  • beforeItemRender
    - Fires before each item renders (for customization)
  • itemClick
    - Fires when a breadcrumb item is clicked
  • created
    - Fires after the component is fully initialized
Breadcrumb组件是一种导航UI元素，具备以下特性：
  • 显示当前页面在层级结构中的位置
  • 允许用户导航至父级页面
  • 渲染带有可选图标、模板和分隔符的项
  • 支持多种溢出模式（Collapsed、Hidden、Menu、Wrap、Scroll、None）
  • 触发项渲染和点击事件
  • 支持ASP.NET Core TagHelper语法
关键属性：
  • items
    - 要显示的BreadcrumbItem对象数组
  • url
    - 根据URL路径自动生成项
  • activeItem
    - 将特定项标记为当前活动项
  • enableNavigation
    - 控制项是否可导航
  • overflowMode
    + 
    maxItems
    - 处理过长的面包屑路径
  • itemTemplate
    + 
    separatorTemplate
    - 自定义渲染
关键事件：
  • beforeItemRender
    - 每个项渲染前触发（用于自定义）
  • itemClick
    - 点击面包屑项时触发
  • created
    - 组件完全初始化后触发

Documentation and Navigation Guide

文档与导航指南

Choose the reference file that matches your implementation need:
选择符合你实现需求的参考文档：

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Setting up Syncfusion.EJ2.AspNet.Core package
  • Registering TagHelper and adding resources
  • Creating your first breadcrumb control
  • Binding items collection
  • Controlling item navigation
📄 阅读： references/getting-started.md
  • 设置Syncfusion.EJ2.AspNet.Core包
  • 注册TagHelper并添加资源
  • 创建你的第一个breadcrumb控件
  • 绑定项集合
  • 控制项导航

Data Binding and Items

数据绑定与项

📄 Read: references/data-binding.md
  • Binding items using e-breadcrumb-items tag directive
  • Generating items from the current page URL
  • Generating items from a static URL
  • Using beforeItemRender to customize generated items
  • Dynamic item binding patterns
📄 阅读： references/data-binding.md
  • 使用e-breadcrumb-items标签指令绑定项
  • 根据当前页面URL生成项
  • 根据静态URL生成项
  • 使用beforeItemRender自定义生成的项
  • 动态项绑定模式

Navigation and URLs

导航与URL

📄 Read: references/navigation.md
  • Defining relative and absolute URLs
  • Enabling navigation for the active (last) item
  • Controlling which items trigger navigation
  • Using beforeItemRender for URL manipulation
  • Handling navigation events with itemClick
📄 阅读： references/navigation.md
  • 定义相对和绝对URL
  • 启用活动（最后一个）项的导航
  • 控制哪些项触发导航
  • 使用beforeItemRender处理URL
  • 通过itemClick处理导航事件

Icons and Visual Elements

图标与视觉元素

📄 Read: references/icons.md
  • Adding font icons with iconCss property
  • Using image files as icons
  • Displaying SVG icons
  • Positioning icons (left vs. right)
  • Combining icons with item text
📄 阅读： references/icons.md
  • 使用iconCss属性添加字体图标
  • 使用图片文件作为图标
  • 显示SVG图标
  • 图标定位（左侧 vs 右侧）
  • 图标与项文本组合

Templates and Customization

模板与自定义

📄 Read: references/templates.md
  • Customizing item appearance with itemTemplate
  • Customizing separators with separatorTemplate
  • Using conditional logic in templates
  • Integrating other components (like chips) in templates
  • Template event binding patterns
📄 阅读： references/templates.md
  • 使用itemTemplate自定义项外观
  • 使用separatorTemplate自定义分隔符
  • 在模板中使用条件逻辑
  • 在模板中集成其他组件（如芯片）
  • 模板事件绑定模式

Overflow and Responsive Display

溢出与响应式显示

📄 Read: references/overflow-modes.md
  • Understanding overflow modes and maxItems
  • Collapsed mode (shows first/last only)
  • Hidden mode (progressive reveal)
  • Menu mode (submenu overflow)
  • Wrap mode (multiple lines)
  • Scroll mode (HTML scrollbar)
  • None mode (single line, no truncation)
📄 阅读： references/overflow-modes.md
  • 了解溢出模式和maxItems
  • Collapsed模式（仅显示首尾项）
  • Hidden模式（渐进式显示）
  • Menu模式（子菜单溢出）
  • Wrap模式（多行显示）
  • Scroll模式（HTML滚动条）
  • None模式（单行，无截断）

Advanced Customization

高级自定义

📄 Read: references/customization.md
  • Applying CSS classes to the component
  • RTL (right-to-left) rendering
  • Disabling items and the component
  • Persisting breadcrumb state
  • Using beforeItemRender for advanced customization
📄 阅读： references/customization.md
  • 为组件应用CSS类
  • RTL（从右到左）渲染
  • 禁用项和组件
  • 持久化面包屑状态
  • 使用beforeItemRender进行高级自定义

Complete API Reference

完整API参考

📄 Read: references/api-reference.md
  • All properties, methods, and events
  • Event argument structures
  • Overflow mode enumeration
  • Examples for less-covered APIs
📄 阅读： references/api-reference.md
  • 所有属性、方法和事件
  • 事件参数结构
  • 溢出模式枚举
  • 较少涉及的API示例

Quick Start Example

快速入门示例

Here's a minimal breadcrumb implementation:
cshtml
<!-- In _Layout.cshtml or _ViewImports.cshtml -->
@addTagHelper *, Syncfusion.EJ2

<!-- In your page (e.g., Index.cshtml) -->
<ejs-breadcrumb>
    <e-breadcrumb-items>
        <e-breadcrumb-item text="Home" url="~/"></e-breadcrumb-item>
        <e-breadcrumb-item text="Products" url="~/products"></e-breadcrumb-item>
        <e-breadcrumb-item text="Electronics" url="~/products/electronics"></e-breadcrumb-item>
        <e-breadcrumb-item text="Laptops"></e-breadcrumb-item>
    </e-breadcrumb-items>
</ejs-breadcrumb>
What this does:
  • Renders 4 breadcrumb items
  • First 3 items are navigable (have URLs)
  • Last item (Laptops) is the current page, not navigable
  • Breadcrumb displays: Home > Products > Electronics > Laptops
以下是一个最简面包屑实现：
cshtml
<!-- In _Layout.cshtml or _ViewImports.cshtml -->
@addTagHelper *, Syncfusion.EJ2

<!-- In your page (e.g., Index.cshtml) -->
<ejs-breadcrumb>
    <e-breadcrumb-items>
        <e-breadcrumb-item text="Home" url="~/"></e-breadcrumb-item>
        <e-breadcrumb-item text="Products" url="~/products"></e-breadcrumb-item>
        <e-breadcrumb-item text="Electronics" url="~/products/electronics"></e-breadcrumb-item>
        <e-breadcrumb-item text="Laptops"></e-breadcrumb-item>
    </e-breadcrumb-items>
</ejs-breadcrumb>
功能说明：
  • 渲染4个面包屑项
  • 前3个项可导航（带有URL）
  • 最后一个项（Laptops）为当前页面，不可导航
  • 面包屑显示：Home > Products > Electronics > Laptops

Common Patterns

常见模式

Pattern 1: URL-Based Generation

模式1：基于URL的生成

Let the Breadcrumb automatically generate items from the page URL:
cshtml
<ejs-breadcrumb url="https://example.com/products/electronics/laptops">
</ejs-breadcrumb>
When to use: When you want automatic breadcrumbs that follow the URL structure.
让Breadcrumb根据页面URL自动生成项：
cshtml
<ejs-breadcrumb url="https://example.com/products/electronics/laptops">
</ejs-breadcrumb>
适用场景： 当你希望面包屑自动遵循URL结构时。

Pattern 2: Controlling Navigation

模式2：控制导航

Disable navigation entirely or only for the active item:
cshtml
<ejs-breadcrumb enableNavigation="false">
    <!-- Items won't be clickable -->
</ejs-breadcrumb>

<ejs-breadcrumb enableActiveItemNavigation="true">
    <!-- Last item becomes clickable when URL is set -->
</ejs-breadcrumb>
完全禁用导航，或仅禁用活动项的导航：
cshtml
<ejs-breadcrumb enableNavigation="false">
    <!-- Items won't be clickable -->
</ejs-breadcrumb>

<ejs-breadcrumb enableActiveItemNavigation="true">
    <!-- Last item becomes clickable when URL is set -->
</ejs-breadcrumb>

Pattern 3: Handling Overflow

模式3：处理溢出

Use overflow modes for long breadcrumb trails:
cshtml
<ejs-breadcrumb overflowMode="Collapsed" maxItems="3">
    <!-- Only first/last shown, others hidden in icon -->
</ejs-breadcrumb>
为过长的面包屑路径使用溢出模式：
cshtml
<ejs-breadcrumb overflowMode="Collapsed" maxItems="3">
    <!-- Only first/last shown, others hidden in icon -->
</ejs-breadcrumb>

Pattern 4: Item Click Handling

模式4：项点击处理

Respond to item clicks with the itemClick event:
cshtml
<ejs-breadcrumb itemClick="OnBreadcrumbItemClick">
    <e-breadcrumb-items>
        <e-breadcrumb-item text="Home" url="~/"></e-breadcrumb-item>
        <e-breadcrumb-item text="Dashboard" url="~/dashboard"></e-breadcrumb-item>
    </e-breadcrumb-items>
</ejs-breadcrumb>
In your C# handler:
csharp
public void OnBreadcrumbItemClick(BreadcrumbClickEventArgs args)
{
    // Handle item click
    var clickedItem = args.Item;
}
通过itemClick事件响应项点击：
cshtml
<ejs-breadcrumb itemClick="OnBreadcrumbItemClick">
    <e-breadcrumb-items>
        <e-breadcrumb-item text="Home" url="~/"></e-breadcrumb-item>
        <e-breadcrumb-item text="Dashboard" url="~/dashboard"></e-breadcrumb-item>
    </e-breadcrumb-items>
</ejs-breadcrumb>
在你的C#处理程序中：
csharp
public void OnBreadcrumbItemClick(BreadcrumbClickEventArgs args)
{
    // Handle item click
    var clickedItem = args.Item;
}

Key Properties Summary

关键属性汇总

PropertyTypePurpose
items
BreadcrumbItemModel[]Collection of breadcrumb items to display
url
stringAuto-generate items from a URL path
activeItem
stringURL/identifier of the currently active item
enableNavigation
booleanAllow/prevent item navigation (default: true)
enableActiveItemNavigation
booleanMake the last item navigable (default: false)
maxItems
numberThreshold for triggering overflow behavior
overflowMode
stringHow to display items beyond maxItems (Collapsed, Hidden, Menu, Wrap, Scroll, None)
itemTemplate
string | FunctionCustom template for item rendering
separatorTemplate
string | FunctionCustom template for separators
enableRtl
booleanRender right-to-left (default: false)
disabled
booleanDisable the entire component (default: false)
cssClass
stringApply CSS classes to the component
enablePersistence
booleanPersist component state between page reloads
属性类型用途
items
BreadcrumbItemModel[]要显示的面包屑项集合
url
string根据URL路径自动生成项
activeItem
string当前活动项的URL/标识符
enableNavigation
boolean允许/阻止项导航（默认：true）
enableActiveItemNavigation
boolean使最后一个项可导航（默认：false）
maxItems
number触发溢出行为的阈值
overflowMode
string超出maxItems时的项显示方式（Collapsed、Hidden、Menu、Wrap、Scroll、None）
itemTemplate
string | Function项渲染的自定义模板
separatorTemplate
string | Function分隔符的自定义模板
enableRtl
boolean从右到左渲染（默认：false）
disabled
boolean禁用整个组件（默认：false）
cssClass
string为组件应用CSS类
enablePersistence
boolean在页面重载之间持久化组件状态

Common Use Cases

常见使用场景

Use Case 1: E-Commerce Breadcrumb Navigate through product categories: Home > Electronics > Laptops > Gaming Laptops
Use Case 2: File Browser Show file path: Root > Documents > Projects > MyProject
Use Case 3: Multi-Step Form Indicate form progress: Step 1 > Step 2 > Step 3 (Current)
Use Case 4: Documentation Site Navigate documentation hierarchy: Docs > API > Components > Breadcrumb
Use Case 5: Admin Dashboard Show user path: Dashboard > Users > Admin > Edit Profile
场景1：电商面包屑 导航产品分类：Home > Electronics > Laptops > Gaming Laptops
场景2：文件浏览器 显示文件路径：Root > Documents > Projects > MyProject
场景3：多步骤表单 指示表单进度：Step 1 > Step 2 > Step 3 (Current)
场景4：文档站点 导航文档层级：Docs > API > Components > Breadcrumb
场景5：管理后台 显示用户路径：Dashboard > Users > Admin > Edit Profile

Next Steps

下一步

  1. Get Started: Follow Getting Started for installation and basic setup
  2. Bind Data: Use Data Binding to connect breadcrumb items
  3. Customize: Explore Templates and Icons for personalization
  4. Optimize: Handle long trails with Overflow Modes
  5. Reference: Check API Reference for complete API details
For detailed implementation patterns, event handling, and advanced scenarios, see the corresponding reference files.
  1. 快速入门： 遵循快速入门完成安装和基础设置
  2. 绑定数据： 使用数据绑定连接面包屑项
  3. 自定义： 探索模板和图标进行个性化设置
  4. 优化： 使用溢出模式处理过长路径
  5. 参考： 查看API参考获取完整API详情
如需详细的实现模式、事件处理和高级场景，请查看对应的参考文档。