syncfusion-javascript-breadcrumb

实现 Breadcrumb

Breadcrumb 组件是一种图形用户界面元素，可帮助识别和突出显示网站层级结构中的当前位置。它能让用户了解自己当前在网站链接层级中的位置，从而改善导航体验并减轻认知负担。

何时使用此技能

在需要执行以下操作时，请立即使用此技能：

• 显示分层导航路径
• 显示多级结构中的当前位置
• 在单页应用中实现面包屑导航
• 使用不同的显示模式处理溢出项
• 自定义面包屑的外观和行为
• 响应用户对面包屑项的交互
• 为面包屑项应用动态样式和模板

控件概览

Breadcrumb 组件提供：

• 分层导航显示 - 显示从根位置到当前位置的导航路径
• 多种溢出模式 - Menu、Collapsed、Hidden、Scroll、Wrap、None
• 项自定义 - 模板、图标、禁用状态
• 事件处理 - 点击事件和渲染回调
• RTL 支持 - 从右到左方向渲染
• 状态持久化 - 可选的组件状态保留
• 基于 URL 的生成 - 根据 URL 自动创建面包屑

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 初始化基本的面包屑组件
• 创建并填充 items 数组
• 将组件添加到 DOM
• 附带代码的最小可用示例
• CSS 导入和主题配置

组件属性概览

📄 阅读： references/component-properties.md

• 核心属性参考（activeItem、cssClass、disabled、enableNavigation）
• 导航配置（enableActiveItemNavigation、enableNavigation）
• 状态管理（enablePersistence、enableRtl）
• 基于 URL 的面包屑生成
• 属性说明及默认值
• 配置模式和最佳实践

项配置

📄 阅读： references/items-configuration.md

• BreadcrumbItemModel 接口和属性
• 项属性（id、text、url、disabled、iconCss）
• 创建和配置面包屑项
• 管理项状态（启用/禁用）
• 为导航项添加图标
• 动态更新和操作项
• 项的无障碍注意事项

模板与自定义

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

• 用于自定义项渲染的 itemTemplate 属性
• 用于自定义分隔符的 separatorTemplate
• 模板函数模式和示例
• 自定义渲染实现
• 自定义分隔符（默认值为“/”以及其他选项）
• CSS 类自定义策略

溢出模式与行为

📄 阅读： references/overflow-modes.md

• 包含全部 6 种模式的 BreadcrumbOverflowMode 枚举
• Menu 模式 - 为溢出项显示子菜单
• Collapsed 模式 - 显示折叠图标并隐藏部分项
• Hidden 模式 - 采用最大可见项数量的方式
• Scroll 模式 - 使用 HTML 滚动条解决方案
• Wrap 模式 - 换行显示
• None 模式 - 单行显示
• 各模式下的 maxItems 配置

事件与事件处理

📄 阅读： references/events-handling.md

• itemClick 事件（BreadcrumbClickEventArgs）
• beforeItemRender 事件（BreadcrumbBeforeItemRenderEventArgs）
• 用于组件初始化的 created 事件
• 事件处理程序模式和设置
• 访问事件参数及属性
• 使用 cancel 属性取消事件
• 常见事件用例和模式

方法与生命周期

📄 阅读： references/methods-and-lifecycle.md

• 组件生命周期方法
• appendTo() - 附加 DOM 元素
• destroy() - 清理组件
• dataBind() - 立即进行数据绑定
• refresh() - 重新渲染组件
• getRootElement() - 访问根元素
• addEventListener/removeEventListener - 动态管理事件
• Inject() - 注入模块
• 方法最佳实践和调用时机

快速入门示例

// Create breadcrumb component
const breadcrumbObj = new Breadcrumb({
  items: [
    { text: 'Home', url: '/' },
    { text: 'Category', url: '/category' },
    { text: 'Product', url: '/product' }
  ],
  enableNavigation: true
});

// Append to DOM
breadcrumbObj.appendTo('#breadcrumb');

// Handle item click
breadcrumbObj.itemClick = (args) => {
  console.log('Clicked item:', args.item.text);
};

常见模式

模式 1：使用图标的基本导航

const breadcrumb = new Breadcrumb({
  items: [
    { text: 'Dashboard', url: '/', iconCss: 'e-icons e-home' },
    { text: 'Products', url: '/products', iconCss: 'e-icons e-package' },
    { text: 'Electronics', url: '/products/electronics' }
  ]
});

模式 2：使用菜单模式处理溢出

const breadcrumb = new Breadcrumb({
  items: [...manyItems],
  maxItems: 4,
  overflowMode: 'Menu'
});

模式 3：导航事件处理

const breadcrumb = new Breadcrumb({
  items: [...items],
  itemClick: (args) => {
    // Prevent default navigation
    args.cancel = false;
    // Navigate to item URL
    window.location.href = args.item.url;
  }
});

模式 4：动态更新项

breadcrumb.items = newItemsList;
breadcrumb.dataBind();

关键属性

属性	类型	默认值	用途
items	BreadcrumbItemModel[]	[]	要显示的面包屑项列表
activeItem	string	''	当前活动面包屑项的 URL
overflowMode	string	'Menu'	处理超出 maxItems 的项的方式
maxItems	number	-1	触发溢出行为前的最大项数
enableNavigation	boolean	true	允许项导航
disabled	boolean	false	禁用整个面包屑
cssClass	string	''	用于设置样式的自定义 CSS 类
enableRtl	boolean	false	从右向左渲染

常见使用场景

使用场景 1：网站导航面包屑

• 显示当前页面在网站层级结构中的位置
• 允许导航至父页面
• 突出显示活动项

使用场景 2：电子商务类别导航

• 显示产品类别路径
• 通过溢出处理深层嵌套类别
• 支持快速导航至父类别

使用场景 3：应用工作区导航

• 显示当前模块/功能路径
• 显示导航历史面包屑
• 实现动态路径更新

使用场景 4：文件系统浏览器

• 显示当前目录路径
• 在文件夹层级结构中导航
• 通过溢出处理大型文件夹结构

---

后续步骤： 选择上方的参考资料，深入了解具体实现细节；或运行测试用例，验证面包屑实现。