syncfusion-react-breadcrumb

Syncfusion React 面包屑组件技能

目录

1. 何时使用此技能
2. 组件概览
3. 文档和导航指南
4. 快速入门示例
5. 常见模式
6. 关键属性参考
7. 常见用例

何时使用此技能

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

• 创建面包屑导航，以显示分层结构中的当前位置
• 在应用中的不同页面或版块之间启用导航
• 使用不同策略（Menu、Scroll、Collapsed 等）处理面包屑项目溢出
• 使用图标、模板或分隔符自定义面包屑外观
• 实现支持键盘操作的无障碍面包屑导航
• 从 URL 或数据动态绑定面包屑项目
• 将面包屑与单页应用的路由库集成
• 有条件地禁用整个面包屑或单个项目
• 处理面包屑事件并执行自定义逻辑
• 为国际化应用提供 RTL 支持

组件概览

Syncfusion React 面包屑组件提供了一种灵活的方式，可在应用中显示导航路径和面包屑轨迹。主要功能包括：

• 导航支持：通过精细控制（组件级和项目级）启用或禁用导航
• 组件控制：启用/禁用整个组件、设置活动项目、应用自定义 CSS 类
• 项目级控制：禁用单个项目、应用图标、设置用于识别的 ID
• 灵活的数据绑定：声明式绑定项目，或根据 URL 动态生成项目
• 溢出模式：使用 6 种模式（Menu、Collapsed、Scroll、Wrap、Hidden、None）处理内容溢出
• 自定义：使用项目模板和分隔符模板创建丰富的自定义布局
• 事件处理：4 种事件（beforeItemRender、itemClick、created），提供全面的参数
• 国际化：为从右向左书写的语言提供完整的 RTL 支持
• 无障碍性：完全符合 WCAG 2.2 标准，支持键盘导航和屏幕阅读器
• 图标集成：支持字体图标、图像和 SVG 图形
• 状态管理：以编程方式设置活动项目，管理项目的启用/禁用状态

文档和导航指南

API 属性和事件参考

📄 阅读： references/api-properties-and-events.md

完整的 API 参考及代码示例：

• 所有 BreadcrumbComponent 属性（activeItem、cssClass、disabled、enableNavigation 等）
• 所有 BreadcrumbItem 属性（disabled、iconCss、id、text、url）
• 所有组件事件（beforeItemRender、itemClick、created）
• 事件参数和用法示例
• 全部 6 种溢出模式及示例
• 属性和事件汇总表

入门指南

📄 阅读： references/getting-started.md

如果你刚开始使用 Syncfusion Breadcrumb，请从这里开始：

• 安装和依赖项设置
• Vite 与 Create React App 环境设置
• 添加 CSS 样式表和主题
• 创建第一个基本面包屑组件
• 向面包屑添加项目
• TypeScript 配置和类型

导航和路由

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

在需要启用导航时使用：

• 启用或禁用项目导航（enableNavigation 属性）
• 实现相对 URL 和绝对 URL
• 启用活动项目（最后一个面包屑）的导航（enableActiveItemNavigation）
• 使用 beforeItemRender 在新标签页中打开 URL
• 处理 itemClick 事件
• 与 React Router 进行高级路由集成

自定义和模板

📄 阅读： references/customization.md

自定义面包屑外观时使用：

• 溢出模式（Menu、Collapsed、Scroll、Wrap、Hidden、None）
• 用于富内容的项目模板（itemTemplate 属性）
• 带自定义图标的分隔符模板（separatorTemplate）
• 管理显示的最大项目数（maxItems 属性）
• 禁用单个项目（disabled 属性）
• 样式和 CSS 类（cssClass 属性）

图标集成和数据绑定

📄 阅读： references/icon-integration-data-binding.md

使用图标或动态数据时使用：

• 字体图标实现（使用 iconCss 的 Syncfusion 图标）
• 添加图像和 SVG 图形作为图标
• 图标位置（左侧、右侧、仅图标）
• 从标签指令进行数据绑定
• 基于 URL 生成项目（组件上的 url 属性）
• 静态 URL 配置
• 使用 beforeItemRender 自定义生成的项目文本

无障碍访问

📄 阅读： references/accessibility.md

实现无障碍面包屑时使用：

• WCAG 2.2 合规指南
• ARIA 属性和角色
• 键盘导航支持（Tab、Shift+Tab、Enter）
• 屏幕阅读器优化
• 从右到左（RTL）支持（enableRtl 属性）
• 使用无障碍工具进行测试

快速入门示例

以下是一个可运行的最简示例，助您快速开始：

import { BreadcrumbComponent, BreadcrumbItemDirective, BreadcrumbItemsDirective } from '@syncfusion/ej2-react-navigations';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-navigations/styles/tailwind3.css';

export default function App() {
  return (
    <BreadcrumbComponent enableNavigation={false}>
      <BreadcrumbItemsDirective>
        <BreadcrumbItemDirective iconCss="e-icons e-home" url="/" />
        <BreadcrumbItemDirective text="Components" url="/components" />
        <BreadcrumbItemDirective text="Breadcrumb" url="/breadcrumb" />
      </BreadcrumbItemsDirective>
    </BreadcrumbComponent>
  );
}

常见模式

模式 1：启用导航的面包屑

通过设置 enableNavigation={true} 并提供 URL，启用用户导航：

<BreadcrumbComponent enableNavigation={true}>
  <BreadcrumbItemsDirective>
    <BreadcrumbItemDirective text="Home" url="../" />
    <BreadcrumbItemDirective text="Products" url="../products" />
    <BreadcrumbItemDirective text="Category" url="../products/category" />
  </BreadcrumbItemsDirective>
</BreadcrumbComponent>

模式 2：带图标的面包屑

使用基于图标的面包屑添加视觉提示：

<BreadcrumbComponent enableNavigation={false}>
  <BreadcrumbItemsDirective>
    <BreadcrumbItemDirective iconCss="e-icons e-home" />
    <BreadcrumbItemDirective iconCss="e-bicons e-folder" text="Folder" />
    <BreadcrumbItemDirective iconCss="e-bicons e-file" text="Document" />
  </BreadcrumbItemsDirective>
</BreadcrumbComponent>

模式 3：处理溢出

使用溢出模式处理自适应面包屑路径：

<BreadcrumbComponent maxItems={3} overflowMode="Menu" enableNavigation={false}>
  <BreadcrumbItemsDirective>
    <BreadcrumbItemDirective text="Home" />
    <BreadcrumbItemDirective text="Folder 1" />
    <BreadcrumbItemDirective text="Folder 2" />
    <BreadcrumbItemDirective text="Folder 3" />
    <BreadcrumbItemDirective text="File" />
  </BreadcrumbItemsDirective>
</BreadcrumbComponent>

模式 4：组件级控制

禁用整个组件，或通过编程方式设置活动项目：

import { useState } from 'react';

export default function App() {
  const [isDisabled, setIsDisabled] = useState(false);
  const [activeUrl, setActiveUrl] = useState('/products');

  return (
    <div>
      <BreadcrumbComponent 
        disabled={isDisabled}
        activeItem={activeUrl}
        enableNavigation={true}
      >
        <BreadcrumbItemsDirective>
          <BreadcrumbItemDirective text="Home" url="/" />
          <BreadcrumbItemDirective text="Products" url="/products" />
          <BreadcrumbItemDirective text="Electronics" url="/products/electronics" />
        </BreadcrumbItemsDirective>
      </BreadcrumbComponent>
    </div>
  );
}

模式 5：禁用单个项目

根据条件禁用特定项目：

<BreadcrumbComponent enableNavigation={true}>
  <BreadcrumbItemsDirective>
    <BreadcrumbItemDirective text="Home" url="/" disabled={false} />
    <BreadcrumbItemDirective text="Products" url="/products" disabled={false} />
    <BreadcrumbItemDirective text="Admin Only" url="/admin" disabled={!isAdmin} />
  </BreadcrumbItemsDirective>
</BreadcrumbComponent>

关键属性参考

组件级属性

属性	类型	默认值	用途
enableNavigation	boolean	true	启用/禁用项目导航
enableActiveItemNavigation	boolean	false	使最后一个项目可点击
disabled	boolean	false	禁用整个组件
activeItem	string	N/A	活动面包屑项目的 URL
cssClass	string	N/A	容器的 CSS 类
enableRtl	boolean	false	从右到左渲染
maxItems	number	N/A	溢出前可见项目的最大数量
overflowMode	string	'Menu'	溢出行为：Menu、Collapsed、Scroll、Wrap、Hidden、None
items	BreadcrumbItemModel[]	N/A	面包屑项目数组
itemTemplate	Function|string	N/A	项目的自定义模板
separatorTemplate	Function|string	N/A	分隔符的自定义模板
url	string	N/A	根据 URL 路径生成项目

项目级属性

属性	类型	默认值	用途
text	string	''	显示文本
url	string	''	导航 URL
iconCss	string	null	图标 CSS 类
disabled	boolean	false	禁用单个项目
id	string	''	唯一项目标识符

事件

事件	触发时机	参数
beforeItemRender	每个项目渲染前	cancel、element、item、name
itemClick	点击项目时	cancel、element、event、item、name
created	组件渲染完成时	Event

常见用例

1. 文件系统导航：显示当前文件夹路径，并配有文件夹／文件图标
2. 电子商务产品路径：展示类别 → 子类别 → 产品层级
3. 文档导航：浏览文档各章节和页面
4. 多步骤表单：显示表单步骤和进度
5. 网站导航：显示当前页面在网站层级中的位置

---

后续步骤：

• 根据需要阅读相应的参考文件
• 复制代码示例，并根据用例进行调整
• 查阅 API 文档，了解高级属性
• 使用不同主题（Tailwind、Bootstrap、Fluent、Material）进行测试