syncfusion-wpf-breadcrumb

实现 WPF HierarchyNavigator（面包屑导航）

Syncfusion® WPF HierarchyNavigator 控件实现指南——这是一种类似于 Windows 资源管理器地址栏的面包屑导航／地址栏组件，支持通过数据绑定、编辑模式、历史记录和进度条进行层次路径导航。

何时使用此技能

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

• 在 WPF 中创建面包屑导航／地址栏导航 UI
• 使用声明式项目（HierarchyNavigatorItem）或数据绑定集合填充 HierarchyNavigator
• 使用 HierarchicalDataTemplate 显示多层业务对象、XML 数据或 WCF 来源的数据
• 启用编辑模式，以便用户输入并自动补全导航路径
• 通过后退箭头下拉菜单显示导航历史记录
• 添加刷新按钮并处理 HierarchyNavigatorRefreshButtonClick
• 在导航操作期间显示／取消进度条
• 通过命令绑定（MVVM 模式）响应项目选择
• 应用工具提示、键盘导航和内置主题

组件概览

HierarchyNavigator 会呈现一个面包屑栏，其中的每个片段都是可点击的 HierarchyNavigatorItem。单击某个片段会打开弹出窗口，列出其子项以供逐级导航。

所需程序集：

• Syncfusion.Tools.WPF
• Syncfusion.Shared.WPF

XAML 命名空间：

xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

C# 命名空间：

using Syncfusion.Windows.Tools.Controls;

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集引用和 NuGet 设置
• 通过设计器、XAML 和 C# 添加控件
• 使用 HierarchyNavigatorItem 以声明方式添加项目
• 基本的 ItemsSource + HierarchicalDataTemplate 绑定
• 应用内置主题

填充数据

📄 阅读： references/populating-data.md

• 绑定到 ObservableCollection 业务对象
• 用于多层层次结构的 HierarchicalDataTemplate
• 通过解析 XDocument 绑定 XML 数据
• 通过 WCF 服务绑定
• 按需／延迟加载项目

编辑模式与自动补全

📄 阅读： references/edit-mode-and-autocomplete.md

• 使用 IsEnableEditMode 属性允许输入路径
• 自动补全筛选下拉列表显示匹配路径
• 键盘操作：按 Enter 确认，按 Esc 取消
• 输入无效路径时的行为

导航功能

📄 阅读： references/navigation-features.md

• ShowToolTip 和单个项目的工具提示
• 导航历史记录（后退箭头下拉菜单）
• 刷新按钮和 HierarchyNavigatorRefreshButtonClick 事件
• ShowProgressBar() / CancelProgressBar()，支持可选的 TimeSpan
• 键盘导航参考表
• 限制可选择的层级

命令绑定（MVVM）

📄 阅读： references/command-binding.md

• 将 Command 属性绑定到 ICommand / DelegateCommand
• 在 ViewModel 中使用 SelectedItemCommand 模式
• 响应所选项目的更改
• 将 HierarchyNavigatorItem 作为 CommandParameter 传递

外观与主题

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

• 使用 HierarchicalDataTemplate 配置 ItemTemplate，自定义项目显示
• 使用 Microsoft Expression Blend 进行自定义
• 通过 SfSkinManager 应用内置主题
• 使用 ThemeStudio 创建自定义主题

快速入门

声明式项目（XAML）

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf"
        x:Class="MyApp.MainWindow"
        Title="MainWindow" Height="350" Width="525">
  <Grid>
    <syncfusion:HierarchyNavigator x:Name="navigator"
                                   VerticalAlignment="Top"
                                   Height="30"
                                   Width="600">
      <syncfusion:HierarchyNavigator.Items>
        <syncfusion:HierarchyNavigatorItem Content="Syncfusion">
          <syncfusion:HierarchyNavigatorItem.Items>
            <syncfusion:HierarchyNavigatorItem Content="User Interface">
              <syncfusion:HierarchyNavigatorItem.Items>
                <syncfusion:HierarchyNavigatorItem Content="WPF"/>
                <syncfusion:HierarchyNavigatorItem Content="Silverlight"/>
              </syncfusion:HierarchyNavigatorItem.Items>
            </syncfusion:HierarchyNavigatorItem>
          </syncfusion:HierarchyNavigatorItem.Items>
        </syncfusion:HierarchyNavigatorItem>
      </syncfusion:HierarchyNavigator.Items>
    </syncfusion:HierarchyNavigator>
  </Grid>
</Window>

数据绑定（XAML + MVVM）

<syncfusion:HierarchyNavigator ItemsSource="{Binding HierarchyItems}"
                               Height="30" Width="600">
  <syncfusion:HierarchyNavigator.ItemTemplate>
    <HierarchicalDataTemplate ItemsSource="{Binding Children}">
      <TextBlock Text="{Binding Name}" Margin="2,0"/>
    </HierarchicalDataTemplate>
  </syncfusion:HierarchyNavigator.ItemTemplate>
</syncfusion:HierarchyNavigator>

C# 代码隐藏

using Syncfusion.Windows.Tools.Controls;

HierarchyNavigator navigator = new HierarchyNavigator { Height = 30 };
HierarchyNavigatorItem root = new HierarchyNavigatorItem { Content = "Syncfusion" };
HierarchyNavigatorItem child = new HierarchyNavigatorItem { Content = "WPF" };
root.Items.Add(child);
navigator.Items.Add(root);
this.Content = navigator;

常见模式

选择合适的数据填充方式

• 静态／已知层次结构 → 在 XAML 中使用声明式 HierarchyNavigatorItem
• 业务对象集合 → 使用 ItemsSource + HierarchicalDataTemplate
• XML 或 WCF 数据 → 解析为 ObservableCollection，然后绑定到 ItemsSource
• 大型／延迟加载的层次结构 → 通过项目展开事件按需加载子项

使用自动完成启用编辑模式

<syncfusion:HierarchyNavigator IsEnableEditMode="True" .../>

用户点击控件以输入路径；筛选后的下拉列表会显示匹配的节点。按 Enter 确认，按 Esc 取消。

导航期间显示进度条

// Show for default 500ms
navigator.ShowProgressBar();

// Show for custom duration
navigator.ShowProgressBar(new TimeSpan(0, 0, 0, 0, 1000));

// Cancel immediately
navigator.CancelProgressBar();

MVVM 命令绑定

<syncfusion:HierarchyNavigator Command="{Binding SelectedItemCommand}"
                               ItemsSource="{Binding Items}" .../>

选中的面包屑项更改时会触发该命令，并将 HierarchyNavigatorItem 作为参数传递。

关键属性和方法

属性 / 方法	描述
Items	声明式的 HierarchyNavigatorItem 子项
ItemsSource	绑定的数据集合
ItemTemplate	用于显示项的 HierarchicalDataTemplate
IsEnableEditMode	启用路径编辑和自动完成
ShowToolTip	为所有项启用工具提示
Command	选中项更改时触发的 ICommand
ShowProgressBar()	显示进度条（默认 500ms）
ShowProgressBar(TimeSpan)	在指定时长内显示进度条
CancelProgressBar()	取消显示中的进度条
CancelProgressBar(TimeSpan)	在指定延迟后取消进度条
HierarchyNavigatorRefreshButtonClick	点击“刷新”按钮时触发的事件