syncfusion-wpf-tree-navigator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing SfTreeNavigator (WPF)

实现SfTreeNavigator（WPF）

When to Use This Skill

适用场景

Use this skill when the user needs to:

Build in-place hierarchical drill-down navigation in WPF (no popup, no separate panel)
Display a multi-level tree structure that expands within its own footprint
Show product/category/department hierarchy navigation
Choose between breadcrumb-style (Default) or stacked-header (Extended) navigation
Bind a nested business object collection to tree navigator items
Programmatically set or read the currently selected item

当用户需要以下功能时可使用该技能：

在WPF中构建嵌入式层级下钻导航（无弹窗、无独立面板）
显示可在自身区域内展开的多级树形结构
展示产品/分类/部门的层级导航
在面包屑样式（默认）或堆叠标题（扩展）导航模式间选择
将嵌套业务对象集合绑定到树形导航项
以编程方式设置或读取当前选中项

Component Overview

组件概述

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)

Assembly:

Syncfusion.SfTreeNavigator.WPF

Namespace:

Syncfusion.Windows.Controls.Navigation

XAML prefix:

navigation:

(typical alias)

SfTreeNavigator                        （根容器）
├── Header                             — 根标签文本（始终可见）
├── HeaderTemplate                     — 自定义根标题外观
└── SfTreeNavigatorItem  (×N)          （每个层级的项）
    ├── Header                         — 项显示文本
    └── SfTreeNavigatorItem  (×N)      （嵌套子项，深度无限制）

程序集：

Syncfusion.SfTreeNavigator.WPF

命名空间：

Syncfusion.Windows.Controls.Navigation

XAML前缀：

navigation:

（常用别名）

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly reference and namespace
Declarative XAML with SfTreeNavigatorItem
C# code-behind creation
Header on SfTreeNavigator
Themes with SfSkinManager

📄 阅读： references/getting-started.md

程序集引用和命名空间
使用SfTreeNavigatorItem的声明式XAML
C#代码后置创建方式
SfTreeNavigator的Header设置
使用SfSkinManager设置主题

Populating Items

填充项

📄 Read: references/populating-items.md

Declarative items via Items collection
Data binding via ItemsSource
Nested Model + ViewModel with ObservableCollection
ItemTemplate with HierarchicalDataTemplate
Connecting child levels via ItemsSource binding in template

📄 阅读： references/populating-items.md

通过Items集合声明式添加项
通过ItemsSource进行数据绑定
结合ObservableCollection的嵌套Model + ViewModel
搭配HierarchicalDataTemplate的ItemTemplate
在模板中通过ItemsSource绑定关联子层级

Navigation Mode

导航模式

📄 Read: references/navigation-mode.md

```
Default
```
— single header + back button at top
```
Extended
```
— stacked breadcrumb headers from root to current level
When to use each mode
TreeNavigatorHeaderItem styling in Extended mode
Decision guide

📄 阅读： references/navigation-mode.md

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

Header and Selection

标题与选择

📄 Read: references/header-and-selection.md

```
HeaderTemplate
```
— customize root header appearance
```
Header
```
— root title string
```
SelectedItem
```
— get/set the selected item
TwoWay MVVM binding for SelectedItem
Programmatic selection

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

```
HeaderTemplate
```
— 自定义根标题外观
```
Header
```
— 根标题字符串
```
SelectedItem
```
— 获取/设置选中项
SelectedItem的双向MVVM绑定
编程式选择

Quick Start

快速开始

xaml

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>

csharp

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

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>

csharp

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;

Common Patterns

常见模式

Scenario	Approach
Static hierarchy	Declarative `SfTreeNavigatorItem` nesting in XAML
Dynamic data-driven hierarchy	`ItemsSource` + `HierarchicalDataTemplate`
Show full breadcrumb path	`NavigationMode="Extended"`
Single back button at top	`NavigationMode="Default"`
Custom root title styling	`HeaderTemplate`
Pre-select an item on load	`SelectedItem` binding in ViewModel constructor
Respond to selection	`SelectedItem` TwoWay binding + ViewModel property

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

Key Properties

关键属性

Property	Description
`Header`	Root label text shown at top of navigator
`HeaderTemplate`	DataTemplate to customize root header appearance
`NavigationMode`	`Default` (back button) or `Extended` (stacked headers)
`ItemsSource`	Data collection for data-bound population
`ItemTemplate`	`HierarchicalDataTemplate` for data-bound items
`SelectedItem`	Gets or sets the currently selected item

SfTreeNavigatorItem properties:

Property	Description
`Header`	Display text for the item
`Items`	Child item collection

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

SfTreeNavigatorItem属性：

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