syncfusion-aspnetcore-breadcrumb

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

Breadcrumb 组件会显示分层导航路径，帮助用户了解自己在应用中的位置。它支持通过父级页面导航，并提供灵活的数据绑定、模板、图标和溢出处理。

何时使用此技能

在以下情况下使用此技能：

• 在 ASP.NET Core 应用中显示分层面包屑导航
• 将面包屑项绑定到集合，或根据当前 URL 生成面包屑项
• 使用模板、图标或 CSS 类自定义面包屑外观
• 处理面包屑项点击和渲染事件
• 为较长的面包屑路径实现溢出行为
• 支持 RTL 渲染或禁用特定项

组件概览

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 - 组件完成初始化后触发

文档与导航指南

选择与实现需求相符的参考文件：

入门

📄 阅读： references/getting-started.md

• 设置 Syncfusion.EJ2.AspNet.Core 包
• 注册 TagHelper 并添加资源
• 创建第一个面包屑控件
• 绑定项集合
• 控制项导航

数据绑定与项

📄 阅读： references/data-binding.md

• 使用 e-breadcrumb-items 标签指令绑定项
• 根据当前页面 URL 生成项
• 根据静态 URL 生成项
• 使用 beforeItemRender 自定义生成的项
• 动态项绑定模式

导航与 URL

📄 阅读： references/navigation.md

• 定义相对 URL 和绝对 URL
• 为活动项（最后一项）启用导航
• 控制哪些项会触发导航
• 使用 beforeItemRender 修改 URL
• 使用 itemClick 处理导航事件

图标与视觉元素

📄 阅读： references/icons.md

• 使用 iconCss 属性添加字体图标
• 使用图像文件作为图标
• 显示 SVG 图标
• 设置图标位置（左侧或右侧）
• 将图标与项文本组合使用

模板与自定义

📄 阅读： references/templates.md

• 使用 itemTemplate 自定义项外观
• 使用 separatorTemplate 自定义分隔符
• 在模板中使用条件逻辑
• 在模板中集成其他组件（如 chips）
• 模板事件绑定模式

溢出与响应式显示

📄 阅读： references/overflow-modes.md

• 了解溢出模式和 maxItems
• Collapsed 模式（仅显示首项和末项）
• Hidden 模式（逐步显示）
• Menu 模式（通过子菜单显示溢出项）
• Wrap 模式（多行显示）
• Scroll 模式（HTML 滚动条）
• None 模式（单行显示，不截断）

高级自定义

📄 阅读： references/customization.md

• 为组件应用 CSS 类
• RTL（从右向左）渲染
• 禁用项目和组件
• 持久化面包屑状态
• 使用 beforeItemRender 进行高级自定义

完整 API 参考

📄 阅读： references/api-reference.md

• 所有属性、方法和事件
• 事件参数结构
• 溢出模式枚举
• 使用较少的 API 示例

快速入门示例

以下是一个最简面包屑实现：

@addTagHelper *, Syncfusion.EJ2


<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

常见模式

模式 1：基于 URL 生成

让 Breadcrumb 自动根据页面 URL 生成项目：

<ejs-breadcrumb url="https://example.com/products/electronics/laptops">
</ejs-breadcrumb>

适用场景： 希望根据 URL 结构自动生成面包屑时。

模式 2：控制导航

完全禁用导航，或仅对当前项目禁用导航：

<ejs-breadcrumb enableNavigation="false">
    
</ejs-breadcrumb>

<ejs-breadcrumb enableActiveItemNavigation="true">
    
</ejs-breadcrumb>

模式 3：处理溢出

使用溢出模式处理较长的面包屑路径：

<ejs-breadcrumb overflowMode="Collapsed" maxItems="3">
    
</ejs-breadcrumb>

模式 4：处理项目点击

使用 itemClick 事件响应项目点击：

<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# 处理程序中：

public void OnBreadcrumbItemClick(BreadcrumbClickEventArgs args)
{
    // Handle item click
    var clickedItem = args.Item;
}

主要属性摘要

属性	类型	用途
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	在页面重新加载后保留组件状态

常见用例

用例 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

---

后续步骤

1. 开始使用： 按照 入门指南 安装并完成基本设置
2. 绑定数据： 使用 数据绑定 连接面包屑项目
3. 自定义： 探索 模板 和 图标 进行个性化设置
4. 优化： 使用 溢出模式 处理较长的路径
5. 参考： 查看 API 参考 了解完整的 API 详情

有关详细的实现模式、事件处理和高级场景，请参阅相应的参考文件。