syncfusion-blazor-breadcrumb

Syncfusion Blazor Breadcrumb 组件

何时使用此技能

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

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

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

---

组件概述

Blazor Breadcrumb 组件是一种导航控件，用于显示应用中访问过的页面或区域层级。

主要功能：

• 根据当前 URL 路径自动生成项目
• 使用 BreadcrumbItem 标记指令手动声明项目
• 多种溢出模式（Collapsed、Menu、Wrap、Scroll、Hidden、None）
• 通过 IconCss 属性支持图标和图像
• 基于模板进行自定义，适用于项目和分隔符
• 动态管理项目（在运行时添加/移除）
• URL 导航（相对或绝对）
• 通过 CSS 自定义实现响应式设计

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

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

项目配置

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

• BreadcrumbItem 属性（Text、Url、IconCss）
• 使用 <BreadcrumbItem> 标记指令声明项目
• 根据当前页面 URL 自动生成项目
• 使用 Url 属性从绝对 URL 生成项目
• 使用 Items 属性在运行时动态添加和移除项目

图标和视觉元素

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

• 使用 e-icons CSS 类添加字体图标
• 通过 IconCss 属性和自定义 CSS 类设置图像
• 支持面包屑项目使用 SVG 图像
• 仅显示图标的面包屑项目（无文本）
• 选择性显示图标（例如，仅显示第一个项目）

导航和路由

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

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

溢出模式

📄 阅读： references/overflow-modes.md

• 使用 MaxItems 属性限制显示的项目数
• Collapsed 模式：隐藏中间项目，通过展开按钮显示首尾项目
• Menu 模式：将其余项目放入下拉子菜单
• Wrap 模式：项目换行显示为多行
• Scroll 模式：溢出时显示水平滚动条
• Hidden 模式：点击父级时显示隐藏的项目
• None 模式：所有项目显示在同一行

模板与自定义

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

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

样式与外观

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

• 用于自定义的 CSS 类（.e-breadcrumb-item、.e-breadcrumb-text、.e-breadcrumb-icon、.e-breadcrumb-separator）
• 与 Theme Studio 集成以创建自定义主题
• 使用 CSS 覆盖 Breadcrumb 的默认样式
• 自定义背景、文本颜色、图标颜色和分隔符颜色

---

快速入门示例

使用显式项的基本面包屑：

@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 自动生成面包屑：

@using Syncfusion.Blazor.Navigations

<SfBreadcrumb></SfBreadcrumb>

---

常见模式

模式 1：图标 + 文本项

将图标与文本结合，构建视觉层级并便于快速浏览：

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

模式 2：处理较长的面包屑路径

使用 MaxItems 和 OverflowMode 管理较深的层级：

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

模式 3：动态管理项

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

@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);
    }
}

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

使用 SeparatorTemplate 设置自定义视觉分隔符：

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

---

关键属性

属性	类型	默认值	用途
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 类

---

常见使用场景

1. 电商产品面包屑： 显示穿过各类别的导航路径（首页 > 电子产品 > 笔记本电脑 > 游戏笔记本电脑）
2. 管理后台导航： 显示用户在多级菜单层级中的位置
3. 文件浏览器： 使用图标直观展示文件夹导航路径
4. 文档网站： 显示章节层级（文档 > 指南 > 入门）
5. 搜索结果筛选器： 显示当前筛选路径（搜索 > 结果 > 按价格筛选）
6. 分步工作流： 指示多步流程中的当前步骤（步骤 1 > 步骤 2 > 当前步骤）

---

后续步骤： 根据上述“文档与导航指南”部分中的使用场景，阅读相应的参考文件。