syncfusion-react-breadcrumb

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion React Breadcrumb Component Skill

Syncfusion React Breadcrumb 组件技能

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Create breadcrumb navigation showing the current location in a hierarchical structure
Enable navigation between different pages or sections in your application
Handle breadcrumb item overflow with different strategies (Menu, Scroll, Collapsed, etc.)
Customize breadcrumb appearance with icons, templates, or separators
Implement accessible breadcrumb navigation with keyboard support
Bind breadcrumb items dynamically from URLs or data
Integrate breadcrumbs with routing libraries for single-page applications
Disable entire breadcrumb or individual items conditionally
Handle breadcrumb events and perform custom logic
Apply RTL support for internationalization

当你需要完成以下需求时可使用本技能：

创建面包屑导航，展示用户在层级结构中的当前位置
支持应用内不同页面或板块之间的导航跳转
通过不同策略（菜单、滚动、折叠等）处理面包屑项溢出
通过图标、模板或分隔符自定义面包屑外观
实现支持键盘操作的无障碍面包屑导航
从URL或数据中动态绑定面包屑项
为单页应用将面包屑与路由库集成
按条件禁用整个面包屑组件或单个面包屑项
处理面包屑相关事件并执行自定义逻辑
适配国际化需求提供RTL（从右到左）支持

Component Overview

组件概述

The Syncfusion React Breadcrumb component provides a flexible way to display navigation paths and breadcrumb trails in your application. Key capabilities include:

Navigation Support: Enable or disable navigation with fine-grained control (component-level and item-level)
Component Control: Enable/disable entire component, set active item, apply custom CSS classes
Item-Level Control: Disable individual items, apply icons, set IDs for identification
Flexible Data Binding: Bind items declaratively or generate from URLs dynamically
Overflow Modes: Handle content overflow with 6 modes (Menu, Collapsed, Scroll, Wrap, Hidden, None)
Customization: Use item templates and separator templates for rich, custom layouts
Event Handling: 4 events (beforeItemRender, itemClick, created) with comprehensive arguments
Internationalization: Full RTL support for right-to-left languages
Accessibility: Full WCAG 2.2 compliance with keyboard navigation and screen reader support
Icon Integration: Support for font icons, images, and SVG graphics
State Management: Set active items programmatically, manage item enabled/disabled states

Syncfusion React Breadcrumb 组件提供了灵活的方式，用于在应用中展示导航路径和面包屑轨迹。核心能力包括：

导航支持：可细粒度地启用或禁用导航功能（组件级别和项级别）
组件控制：启用/禁用整个组件、设置激活项、应用自定义CSS类
项级别控制：禁用单个项、添加图标、设置ID用于标识
灵活数据绑定：声明式绑定项，或是从URL动态生成项
溢出模式：提供6种内容溢出处理模式（菜单、折叠、滚动、换行、隐藏、无）
自定义能力：支持项模板和分隔符模板，实现丰富的自定义布局
事件处理：提供4个事件（beforeItemRender、itemClick、created）及完整的参数
国际化：全面支持从右到左书写的语言的RTL展示
无障碍：完全符合WCAG 2.2标准，支持键盘导航和屏幕阅读器
图标集成：支持字体图标、图片和SVG图形
状态管理：可通过编程方式设置激活项，管理项的启用/禁用状态

Documentation and Navigation Guide

文档与导航指南

API Properties and Events Reference

API属性与事件参考

📄 Read: references/api-properties-and-events.md

Complete API reference with code examples:

All BreadcrumbComponent properties (activeItem, cssClass, disabled, enableNavigation, etc.)
All BreadcrumbItem properties (disabled, iconCss, id, text, url)
All component events (beforeItemRender, itemClick, created)
Event arguments and usage examples
All 6 overflow modes with examples
Property and event summary tables

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

包含代码示例的完整API参考：

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

Getting Started

入门指南

📄 Read: references/getting-started.md

Start here if you're new to Syncfusion Breadcrumb:

Installation and dependencies setup
Vite vs Create React App environment setup
Adding CSS stylesheets and themes
Creating your first basic breadcrumb component
Adding items to breadcrumb
TypeScript configuration and types

📄 阅读： references/getting-started.md

如果你是首次使用Syncfusion Breadcrumb，请从这里开始：

安装和依赖配置
Vite与Create React App环境配置
添加CSS样式表和主题
创建你的第一个基础面包屑组件
向面包屑中添加项
TypeScript配置和类型说明

Navigation and Routing

导航与路由

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

Use when you need to enable navigation:

Enable or disable item navigation (enableNavigation property)
Implement relative and absolute URLs
Enable active item (last breadcrumb) navigation (enableActiveItemNavigation)
Open URLs in new tabs using beforeItemRender
Handle itemClick events
Advanced routing integration with React Router

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

当你需要启用导航功能时使用：

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

Customization and Templates

自定义与模板

📄 Read: references/customization.md

Use when customizing the breadcrumb appearance:

Overflow modes (Menu, Collapsed, Scroll, Wrap, Hidden, None)
Item templates for rich content (itemTemplate property)
Separator templates with custom icons (separatorTemplate)
Managing maximum items display (maxItems property)
Item-level disabling (disabled property)
Styling and CSS classes (cssClass property)

📄 阅读： references/customization.md

当你需要自定义面包屑外观时使用：

溢出模式（菜单、折叠、滚动、换行、隐藏、无）
用于展示丰富内容的项模板（itemTemplate属性）
支持自定义图标的分隔符模板（separatorTemplate）
管理最大展示项数（maxItems属性）
项级别禁用（disabled属性）
样式和CSS类配置（cssClass属性）

Icon Integration and Data Binding

图标集成与数据绑定

📄 Read: references/icon-integration-data-binding.md

Use when working with icons or dynamic data:

Font icon implementation (Syncfusion icons with iconCss)
Adding images and SVG graphics as icons
Icon positioning (left, right, icon-only)
Data binding from tag directives
URL-based item generation (url property on component)
Static URL configuration
Customizing generated item text with beforeItemRender

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

当你需要使用图标或动态数据时使用：

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

Accessibility

无障碍

📄 Read: references/accessibility.md

Use when implementing accessible breadcrumbs:

WCAG 2.2 compliance guidelines
ARIA attributes and roles
Keyboard navigation support (Tab, Shift+Tab, Enter)
Screen reader optimization
Right-to-left (RTL) support (enableRtl property)
Testing with accessibility tools

📄 阅读： references/accessibility.md

当你需要实现无障碍面包屑时使用：

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

Quick Start Example

快速入门示例

Here's a minimal working example to get started:

tsx

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

以下是可直接运行的最小示例：

tsx

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

Common Patterns

常用模式

Pattern 1: Navigation Enabled Breadcrumb

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

Enable user navigation by setting

enableNavigation={true}

and providing URLs:

tsx

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

通过设置

enableNavigation={true}

并提供URL来启用用户导航：

tsx

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

Pattern 2: Breadcrumb with Icons

模式2：带图标的面包屑

Add visual context with icon-based breadcrumbs:

tsx

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

通过基于图标的面包屑添加视觉上下文：

tsx

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

Pattern 3: Handling Overflow

模式3：溢出处理

Use overflow modes for responsive breadcrumb trails:

tsx

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

使用溢出模式实现响应式面包屑轨迹：

tsx

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

Pattern 4: Component-Level Control

模式4：组件级别控制

Disable entire component or set active item programmatically:

tsx

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

禁用整个组件或是通过编程方式设置激活项：

tsx

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

Pattern 5: Item-Level Disabling

模式5：项级别禁用

Disable specific items based on conditions:

tsx

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

根据条件禁用特定项：

tsx

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

Key Props Reference

核心属性参考

Component-Level Properties

组件级别属性

Property	Type	Default	Purpose
`enableNavigation`	boolean	true	Enable/disable item navigation
`enableActiveItemNavigation`	boolean	false	Make last item clickable
`disabled`	boolean	false	Disable entire component
`activeItem`	string	N/A	URL of active breadcrumb item
`cssClass`	string	N/A	CSS classes for container
`enableRtl`	boolean	false	Right-to-left rendering
`maxItems`	number	N/A	Maximum visible items before overflow
`overflowMode`	string	'Menu'	Overflow behavior: Menu, Collapsed, Scroll, Wrap, Hidden, None
`items`	BreadcrumbItemModel[]	N/A	Breadcrumb items array
`itemTemplate`	Function\|string	N/A	Custom template for items
`separatorTemplate`	Function\|string	N/A	Custom template for separators
`url`	string	N/A	Generate items from URL path

属性	类型	默认值	作用
`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路径生成项

Item-Level Properties

项级别属性

Property	Type	Default	Purpose
`text`	string	''	Display text
`url`	string	''	Navigation URL
`iconCss`	string	null	Icon CSS classes
`disabled`	boolean	false	Disable individual item
`id`	string	''	Unique item identifier

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

Events

事件

Event	Fires When	Arguments
`beforeItemRender`	Before rendering each item	cancel, element, item, name
`itemClick`	When item clicked	cancel, element, event, item, name
`created`	Component rendering completes	Event

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

Common Use Cases

常见使用场景

File System Navigation: Display current folder path with folder/file icons
E-commerce Product Path: Show category → subcategory → product hierarchy
Documentation Navigation: Navigate through documentation sections and pages
Multi-step Forms: Display form steps and progress
Website Navigation: Show current page location within site hierarchy

Next Steps:

Read the appropriate reference file based on your needs
Copy code examples and adapt to your use case
Refer to API documentation for advanced properties
Test with different themes (Tailwind, Bootstrap, Fluent, Material)

文件系统导航：展示当前文件夹路径，搭配文件夹/文件图标
电商产品路径：展示分类→子分类→产品的层级结构
文档导航：在文档板块和页面之间跳转
多步骤表单：展示表单步骤和进度
网站导航：展示当前页面在站点层级中的位置

后续步骤：

根据你的需求阅读对应的参考文档
复制代码示例并适配你的使用场景
参考API文档了解高级属性
测试不同主题（Tailwind、Bootstrap、Fluent、Material）