syncfusion-wpf-tree-navigator

实现 SfTreeNavigator（WPF）

何时使用此技能

当用户需要以下功能时，请使用此技能：

• 在 WPF 中构建就地分层下钻导航（无弹出窗口，也不使用独立面板）
• 显示在自身占用区域内展开的多级树结构
• 展示产品／类别／部门层级导航
• 在面包屑样式（Default）和堆叠标题（Extended）导航之间进行选择
• 将嵌套的业务对象集合绑定到树导航器项目
• 以编程方式设置或读取当前选中的项目

---

组件概览

SfTreeNavigator                        (root container)
├── Header                             — root label text (always visible)
├── HeaderTemplate                     — customize root header appearance
└── SfTreeNavigatorItem  (×N)          (each level item)
    ├── Header                         — item display text
    └── SfTreeNavigatorItem  (×N)      (nested child items, unlimited depth)

程序集： Syncfusion.SfTreeNavigator.WPF
命名空间： Syncfusion.Windows.Controls.Navigation
XAML 前缀： navigation:（常用别名）

---

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 程序集引用和命名空间
• 使用 SfTreeNavigatorItem 编写声明式 XAML
• 创建 C# 代码隐藏
• 在 SfTreeNavigator 上设置标题
• 使用 SfSkinManager 设置主题

填充项目

📄 阅读： references/populating-items.md

• 通过 Items 集合声明项目
• 通过 ItemsSource 进行数据绑定
• 使用 ObservableCollection 构建嵌套的 Model 和 ViewModel
• 使用 HierarchicalDataTemplate 设置 ItemTemplate
• 在模板中通过 ItemsSource 绑定连接子级

导航模式

📄 阅读： references/navigation-mode.md

• Default — 顶部显示单个标题和返回按钮
• Extended — 从根级到当前级显示堆叠的面包屑标题
• 各模式的适用场景
• Extended 模式下的 TreeNavigatorHeaderItem 样式设置
• 选择指南

标题和选择

📄 阅读： references/header-and-selection.md

• HeaderTemplate — 自定义根级标题的外观
• Header — 根级标题字符串
• SelectedItem — 获取／设置选中项
• 对 SelectedItem 进行 TwoWay MVVM 绑定
• 以编程方式选择项目

---

快速入门

xmlns:navigation="clr-namespace:Syncfusion.Windows.Controls.Navigation;assembly=Syncfusion.SfTreeNavigator.WPF"

<navigation:SfTreeNavigator Header="Enterprise Toolkit"
                             Width="300" Height="400">
    <navigation:SfTreeNavigatorItem Header="WinRT (XAML)">
        <navigation:SfTreeNavigatorItem Header="Chart"/>
        <navigation:SfTreeNavigatorItem Header="Tools"/>
    </navigation:SfTreeNavigatorItem>
    <navigation:SfTreeNavigatorItem Header="Metro Studio"/>
</navigation:SfTreeNavigator>

using Syncfusion.Windows.Controls.Navigation;

SfTreeNavigator navigator = new SfTreeNavigator { Header = "Enterprise Toolkit" };

SfTreeNavigatorItem winrt  = new SfTreeNavigatorItem { Header = "WinRT (XAML)" };
SfTreeNavigatorItem chart  = new SfTreeNavigatorItem { Header = "Chart" };
SfTreeNavigatorItem tools  = new SfTreeNavigatorItem { Header = "Tools" };
SfTreeNavigatorItem metro  = new SfTreeNavigatorItem { Header = "Metro Studio" };

winrt.Items.Add(chart);
winrt.Items.Add(tools);
navigator.Items.Add(winrt);
navigator.Items.Add(metro);
this.Content = navigator;

---

常见模式

场景	方法
静态层级结构	在 XAML 中声明嵌套的 SfTreeNavigatorItem
动态数据驱动的层级结构	ItemsSource + HierarchicalDataTemplate
显示完整的面包屑路径	NavigationMode="Extended"
在顶部显示单个返回按钮	NavigationMode="Default"
自定义根级标题样式	HeaderTemplate
加载时预选项目	在 ViewModel 构造函数中绑定 SelectedItem
响应选择操作	使用 SelectedItem TwoWay 绑定 + ViewModel 属性

---

关键属性

属性	说明
Header	显示在导航器顶部的根级标签文本
HeaderTemplate	用于自定义根级标题外观的 DataTemplate
NavigationMode	Default（返回按钮）或 Extended（堆叠标题）
ItemsSource	用于数据绑定填充的数据集合
ItemTemplate	用于数据绑定项目的 HierarchicalDataTemplate
SelectedItem	获取或设置当前选中的项目

SfTreeNavigatorItem 属性：

属性	说明
Header	项目的显示文本
Items	子项目集合