Back to Details

syncfusion-winforms-tree-navigator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Tree Navigators (TreeNavigator)

实现树形导航器（TreeNavigator）

A unique navigation control for Windows Forms that provides in-place tree expansion without consuming additional screen space. Items expand and collapse inline, allowing users to drill down through hierarchical structures by clicking items.
这是一款适用于Windows Forms的独特导航控件，支持原地展开树形结构，不会占用额外屏幕空间。菜单项会以内联方式展开和折叠，用户可通过点击项向下浏览层级结构。

When to Use This Skill

何时使用该技能

Use this skill when you need to:
  • Space-Efficient Navigation: Display hierarchical navigation that expands in-place without growing the control size
  • Drill-Down Interface: Allow users to navigate from parent to child items with back button navigation
  • File Explorer Style: Create file/folder navigation similar to Windows Explorer breadcrumb navigation
  • Menu Hierarchies: Build collapsible menu systems with parent-child relationships
  • Breadcrumb Navigation: Implement extended mode with stacked headers showing navigation path
  • Settings Navigation: Create category-based settings interfaces with hierarchical organization
  • Document Browser: Navigate through document structures, sections, and subsections
  • TreeView Alternative: Replace standard TreeView with a more compact, focused navigation experience
当你需要实现以下需求时可使用本技能：
  • 节省空间的导航：展示可原地展开的层级导航，不会增大控件尺寸
  • 下钻交互界面：支持用户通过返回按钮在父级和子级项之间来回导航
  • 文件资源管理器风格：打造类似Windows资源管理器面包屑的文件/文件夹导航功能
  • 菜单层级体系：构建带有父子关系的可折叠菜单系统
  • 面包屑导航：实现带堆叠头部展示导航路径的扩展模式
  • 设置页导航：创建按类别组织、层级清晰的设置界面
  • 文档浏览器：浏览文档结构、章节和子章节
  • TreeView替代方案：用更紧凑、聚焦的导航体验替换标准TreeView

Component Overview

组件概览

The TreeNavigator control provides a unique interface for hierarchical navigation:
  • Expands tree structures in-place without taking more screen space
  • Items collapse automatically when navigating to child items
  • Drill down to sub-items by clicking on parent items
  • Navigate back to parent levels using back button
  • Two navigation modes: Default (single back button) and Extended (breadcrumb-style headers)
Key Capabilities:
  • NavigationMode
    property for selecting navigation style (Default or Extended)
  • Items
    collection for managing TreeMenuItem objects
  • Header
    configuration for customizing header appearance and behavior
  • Style
    property for applying Office 2016/2019 visual themes
  • SelectedItem
    property for programmatic selection
  • Selection events for tracking and controlling navigation
TreeNavigator控件为层级导航提供了独特的交互界面：
  • 原地展开树结构，不会占用更多屏幕空间
  • 导航到子项时，父项会自动折叠
  • 点击父项即可向下钻取到子项
  • 使用返回按钮可回到父级层级
  • 两种导航模式：默认模式（单个返回按钮）和扩展模式（面包屑风格头部）
核心能力：
  • NavigationMode
    属性用于选择导航样式（默认/扩展）
  • Items
    集合用于管理TreeMenuItem对象
  • Header
    配置项可自定义头部的外观和行为
  • Style
    属性可应用Office 2016/2019视觉主题
  • SelectedItem
    属性用于编程控制选中项
  • 提供选择事件用于跟踪和控制导航行为

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
When to read: Starting new implementation, setting up dependencies, first-time usage, basic TreeNavigator creation
Topics covered:
  • Assembly deployment (Syncfusion.Tools.Windows, Syncfusion.Shared.Base)
  • NuGet package installation
  • Namespace requirements (Syncfusion.Windows.Forms.Tools)
  • Adding TreeNavigator via designer (drag-and-drop from toolbox)
  • Adding TreeNavigator programmatically in code
  • Adding TreeMenuItem items to Items collection
  • Header configuration (HeaderText property)
  • Adding items through designer (Smart Tag editor)
  • Complete setup example with code
  • .NET Core workaround for child items
📄 阅读： references/getting-started.md
适用场景： 开始新的实现、配置依赖、首次使用、基础TreeNavigator创建
覆盖内容：
  • 程序集部署（Syncfusion.Tools.Windows、Syncfusion.Shared.Base）
  • NuGet包安装
  • 命名空间要求（Syncfusion.Windows.Forms.Tools）
  • 通过设计器添加TreeNavigator（从工具箱拖拽）
  • 通过代码编程添加TreeNavigator
  • 向Items集合添加TreeMenuItem项
  • 头部配置（HeaderText属性）
  • 通过设计器添加项（智能标签编辑器）
  • 完整的代码配置示例
  • .NET Core下子项适配方案

Navigation Modes

导航模式

📄 Read: references/navigation-modes.md
When to read: Choosing navigation behavior, implementing back button navigation, breadcrumb-style interfaces
Topics covered:
  • NavigationMode property overview
  • Default Mode (single back button, selected item at top)
  • Extended Mode (stacked breadcrumb headers, click any level)
  • Navigation behavior differences between modes
  • Use cases for each mode (simple vs complex hierarchies)
  • Code examples for setting navigation mode
  • Visual comparison of Default vs Extended modes
📄 阅读： references/navigation-modes.md
适用场景： 选择导航行为、实现返回按钮导航、面包屑风格界面
覆盖内容：
  • NavigationMode属性概览
  • 默认模式（单个返回按钮，选中项展示在顶部）
  • 扩展模式（堆叠面包屑头部，可点击任意层级）
  • 不同模式下的导航行为差异
  • 各模式适用场景（简单/复杂层级）
  • 设置导航模式的代码示例
  • 默认模式与扩展模式的视觉对比

Appearance and Styling

外观与样式

📄 Read: references/appearance-styling.md
When to read: Customizing visual appearance, applying themes, styling headers, configuring borders and colors
Topics covered:
  • Style property (Office2016Colorful/White/Black/DarkGray, Office2019Colorful, Default)
  • Visual theme application and comparison
  • Header customization (Height, HeaderBackColor, HeaderForeColor, HeaderText, TextBounds)
  • ShowHeader property (hide/show header area)
  • Border customization (BorderColor, BorderThickness)
  • Item spacing (PadY property for gap between items)
  • TreeMenuItem appearance (ItemBackColor, ItemHoverColor, SelectedColor, SelectedItemForeColor)
  • Text alignment (TextAlign: Center, Left, Right)
  • Complete styling examples with code
📄 阅读： references/appearance-styling.md
适用场景： 自定义视觉外观、应用主题、设置头部样式、配置边框和颜色
覆盖内容：
  • Style属性（Office2016Colorful/White/Black/DarkGray、Office2019Colorful、默认）
  • 视觉主题应用与对比
  • 头部自定义（高度、HeaderBackColor、HeaderForeColor、HeaderText、TextBounds）
  • ShowHeader属性（隐藏/展示头部区域）
  • 边框自定义（BorderColor、BorderThickness）
  • 项间距（控制项之间间距的PadY属性）
  • TreeMenuItem外观（ItemBackColor、ItemHoverColor、SelectedColor、SelectedItemForeColor）
  • 文本对齐（TextAlign：居中、左对齐、右对齐）
  • 完整的样式代码示例

Tree Menu Items

树形菜单项

📄 Read: references/tree-menu-items.md
When to read: Managing items, adding/removing TreeMenuItems, building hierarchies, manipulating item collections
Topics covered:
  • TreeMenuItem class overview and properties
  • Items collection management (Add, Remove, Clear)
  • Adding items programmatically (C# and VB.NET)
  • Adding items via designer (Smart Tag collection editor)
  • Parent-child item relationships and nesting
  • Item properties (Text, ItemBackColor, ItemHoverColor, SelectedColor, SelectedItemForeColor)
  • Building multi-level hierarchies
  • Dynamic item manipulation at runtime
  • Complete examples with nested items
📄 阅读： references/tree-menu-items.md
适用场景： 管理菜单项、添加/删除TreeMenuItem、构建层级结构、操作项集合
覆盖内容：
  • TreeMenuItem类概览与属性
  • Items集合管理（添加、移除、清空）
  • 编程添加项（C#和VB.NET）
  • 通过设计器添加项（智能标签集合编辑器）
  • 父子项关系与嵌套
  • 项属性（Text、ItemBackColor、ItemHoverColor、SelectedColor、SelectedItemForeColor）
  • 构建多层级结构
  • 运行时动态操作项
  • 嵌套项的完整示例

Selection and Events

选择与事件

📄 Read: references/selection-events.md
When to read: Handling selection changes, responding to navigation, programmatically selecting items, preventing selection
Topics covered:
  • SelectedItem property (get/set currently selected item)
  • SelectionChanging event (fires before selection changes, cancellable)
  • SelectionStateChangingEventArgs (NewValue, OldValue, Expanded, Cancel properties)
  • SelectionChanged event (fires after selection changes)
  • SelectionStateChangedEventArgs (SelectedItem, Expanded properties)
  • Event handling examples with code
  • Cancelling selection changes (validation scenarios)
  • Touch scroll behavior (UseTouchScrollBehavior property)
  • Complete event workflow examples
📄 阅读： references/selection-events.md
适用场景： 处理选择变更、响应导航、编程选中项、阻止选择行为
覆盖内容：
  • SelectedItem属性（获取/设置当前选中项）
  • SelectionChanging事件（选择变更前触发，可取消）
  • SelectionStateChangingEventArgs（NewValue、OldValue、Expanded、Cancel属性）
  • SelectionChanged事件（选择变更后触发）
  • SelectionStateChangedEventArgs（SelectedItem、Expanded属性）
  • 事件处理代码示例
  • 取消选择变更（验证场景）
  • 触摸滚动行为（UseTouchScrollBehavior属性）
  • 完整的事件流程示例

Quick Start Example

快速入门示例

File Explorer-Style Navigation with Office2016 Theme

带Office2016主题的文件资源管理器风格导航

csharp
using Syncfusion.Windows.Forms.Tools;

// Create TreeNavigator
TreeNavigator treeNavigator = new TreeNavigator();
treeNavigator.Size = new Size(250, 400);
treeNavigator.Header.HeaderText = "This PC";
treeNavigator.Style = TreeNavigatorStyle.Office2016Colorful;
treeNavigator.NavigationMode = NavigationMode.Extended;

// Add root items
TreeMenuItem desktop = new TreeMenuItem { Text = "Desktop" };
TreeMenuItem documents = new TreeMenuItem { Text = "Documents" };
TreeMenuItem downloads = new TreeMenuItem { Text = "Downloads" };

// Add items to TreeNavigator
treeNavigator.Items.Add(desktop);
treeNavigator.Items.Add(documents);
treeNavigator.Items.Add(downloads);

// Add child items to Documents
TreeMenuItem workFiles = new TreeMenuItem { Text = "Work Files" };
TreeMenuItem personalFiles = new TreeMenuItem { Text = "Personal Files" };
documents.Items.Add(workFiles);
documents.Items.Add(personalFiles);

this.Controls.Add(treeNavigator);
vbnet
Imports Syncfusion.Windows.Forms.Tools

' Create TreeNavigator
Dim treeNavigator As New TreeNavigator()
treeNavigator.Size = New Size(250, 400)
treeNavigator.Header.HeaderText = "This PC"
treeNavigator.Style = TreeNavigatorStyle.Office2016Colorful
treeNavigator.NavigationMode = NavigationMode.Extended

' Add root items
Dim desktop As New TreeMenuItem With {.Text = "Desktop"}
Dim documents As New TreeMenuItem With {.Text = "Documents"}
Dim downloads As New TreeMenuItem With {.Text = "Downloads"}

' Add items to TreeNavigator
treeNavigator.Items.Add(desktop)
treeNavigator.Items.Add(documents)
treeNavigator.Items.Add(downloads)

' Add child items to Documents
Dim workFiles As New TreeMenuItem With {.Text = "Work Files"}
Dim personalFiles As New TreeMenuItem With {.Text = "Personal Files"}
documents.Items.Add(workFiles)
documents.Items.Add(personalFiles)

Me.Controls.Add(treeNavigator)
csharp
using Syncfusion.Windows.Forms.Tools;

// Create TreeNavigator
TreeNavigator treeNavigator = new TreeNavigator();
treeNavigator.Size = new Size(250, 400);
treeNavigator.Header.HeaderText = "This PC";
treeNavigator.Style = TreeNavigatorStyle.Office2016Colorful;
treeNavigator.NavigationMode = NavigationMode.Extended;

// Add root items
TreeMenuItem desktop = new TreeMenuItem { Text = "Desktop" };
TreeMenuItem documents = new TreeMenuItem { Text = "Documents" };
TreeMenuItem downloads = new TreeMenuItem { Text = "Downloads" };

// Add items to TreeNavigator
treeNavigator.Items.Add(desktop);
treeNavigator.Items.Add(documents);
treeNavigator.Items.Add(downloads);

// Add child items to Documents
TreeMenuItem workFiles = new TreeMenuItem { Text = "Work Files" };
TreeMenuItem personalFiles = new TreeMenuItem { Text = "Personal Files" };
documents.Items.Add(workFiles);
documents.Items.Add(personalFiles);

this.Controls.Add(treeNavigator);
vbnet
Imports Syncfusion.Windows.Forms.Tools

' Create TreeNavigator
Dim treeNavigator As New TreeNavigator()
treeNavigator.Size = New Size(250, 400)
treeNavigator.Header.HeaderText = "This PC"
treeNavigator.Style = TreeNavigatorStyle.Office2016Colorful
treeNavigator.NavigationMode = NavigationMode.Extended

' Add root items
Dim desktop As New TreeMenuItem With {.Text = "Desktop"}
Dim documents As New TreeMenuItem With {.Text = "Documents"}
Dim downloads As New TreeMenuItem With {.Text = "Downloads"}

' Add items to TreeNavigator
treeNavigator.Items.Add(desktop)
treeNavigator.Items.Add(documents)
treeNavigator.Items.Add(downloads)

' Add child items to Documents
Dim workFiles As New TreeMenuItem With {.Text = "Work Files"}
Dim personalFiles As New TreeMenuItem With {.Text = "Personal Files"}
documents.Items.Add(workFiles)
documents.Items.Add(personalFiles)

Me.Controls.Add(treeNavigator)

Common Patterns

常用模式

Pattern 1: Settings Navigation with Custom Colors

模式1：带自定义颜色的设置页导航

csharp
// Create TreeNavigator for settings
TreeNavigator settingsNav = new TreeNavigator();
settingsNav.Header.HeaderText = "Settings";
settingsNav.Style = TreeNavigatorStyle.Office2016White;
settingsNav.NavigationMode = NavigationMode.Default;

// Customize appearance
settingsNav.Header.HeaderBackColor = Color.FromArgb(0, 120, 215);
settingsNav.Header.HeaderForeColor = Color.White;
settingsNav.ItemBackColor = Color.WhiteSmoke;

// Add settings categories
TreeMenuItem general = new TreeMenuItem { Text = "General" };
TreeMenuItem appearance = new TreeMenuItem { Text = "Appearance" };
TreeMenuItem advanced = new TreeMenuItem { Text = "Advanced" };

settingsNav.Items.Add(general);
settingsNav.Items.Add(appearance);
settingsNav.Items.Add(advanced);

// Add sub-settings
general.Items.Add(new TreeMenuItem { Text = "Language" });
general.Items.Add(new TreeMenuItem { Text = "Startup" });
appearance.Items.Add(new TreeMenuItem { Text = "Theme" });
appearance.Items.Add(new TreeMenuItem { Text = "Colors" });
csharp
// Create TreeNavigator for settings
TreeNavigator settingsNav = new TreeNavigator();
settingsNav.Header.HeaderText = "Settings";
settingsNav.Style = TreeNavigatorStyle.Office2016White;
settingsNav.NavigationMode = NavigationMode.Default;

// Customize appearance
settingsNav.Header.HeaderBackColor = Color.FromArgb(0, 120, 215);
settingsNav.Header.HeaderForeColor = Color.White;
settingsNav.ItemBackColor = Color.WhiteSmoke;

// Add settings categories
TreeMenuItem general = new TreeMenuItem { Text = "General" };
TreeMenuItem appearance = new TreeMenuItem { Text = "Appearance" };
TreeMenuItem advanced = new TreeMenuItem { Text = "Advanced" };

settingsNav.Items.Add(general);
settingsNav.Items.Add(appearance);
settingsNav.Items.Add(advanced);

// Add sub-settings
general.Items.Add(new TreeMenuItem { Text = "Language" });
general.Items.Add(new TreeMenuItem { Text = "Startup" });
appearance.Items.Add(new TreeMenuItem { Text = "Theme" });
appearance.Items.Add(new TreeMenuItem { Text = "Colors" });

Pattern 2: Breadcrumb Navigation with Selection Event

模式2：带选择事件的面包屑导航

csharp
// Create breadcrumb-style navigator
TreeNavigator breadcrumbNav = new TreeNavigator();
breadcrumbNav.NavigationMode = NavigationMode.Extended;
breadcrumbNav.Style = TreeNavigatorStyle.Office2016Colorful;

// Handle selection changes
breadcrumbNav.SelectionChanged += (sender, e) => {
    TreeMenuItem selected = e.SelectedItem;
    bool isExpanded = e.Expanded;
    
    // Update content panel based on selection
    MessageBox.Show($"Navigated to: {selected.Text}\nExpanded: {isExpanded}");
};

// Build hierarchy
TreeMenuItem root = new TreeMenuItem { Text = "Home" };
breadcrumbNav.Items.Add(root);
TreeMenuItem level1 = new TreeMenuItem { Text = "Category" };
TreeMenuItem level2 = new TreeMenuItem { Text = "Subcategory" };
root.Items.Add(level1);
level1.Items.Add(level2);
csharp
// Create breadcrumb-style navigator
TreeNavigator breadcrumbNav = new TreeNavigator();
breadcrumbNav.NavigationMode = NavigationMode.Extended;
breadcrumbNav.Style = TreeNavigatorStyle.Office2016Colorful;

// Handle selection changes
breadcrumbNav.SelectionChanged += (sender, e) => {
    TreeMenuItem selected = e.SelectedItem;
    bool isExpanded = e.Expanded;
    
    // Update content panel based on selection
    MessageBox.Show($"Navigated to: {selected.Text}\nExpanded: {isExpanded}");
};

// Build hierarchy
TreeMenuItem root = new TreeMenuItem { Text = "Home" };
breadcrumbNav.Items.Add(root);
TreeMenuItem level1 = new TreeMenuItem { Text = "Category" };
TreeMenuItem level2 = new TreeMenuItem { Text = "Subcategory" };
root.Items.Add(level1);
level1.Items.Add(level2);

Pattern 3: Compact Navigation Menu with Item Hover Colors

模式3：带项悬浮色的紧凑型导航菜单

csharp
// Create compact navigation
TreeNavigator compactNav = new TreeNavigator();
compactNav.ShowHeader = false; // Hide header for compact look
compactNav.Style = TreeNavigatorStyle.Office2016DarkGray;
compactNav.PadY = 5; // Reduce spacing between items

// Customize item colors
TreeMenuItem dashboard = new TreeMenuItem 
{ 
    Text = "Dashboard",
    ItemBackColor = Color.FromArgb(45, 45, 48),
    ItemHoverColor = Color.FromArgb(62, 62, 66),
    SelectedColor = Color.FromArgb(0, 122, 204)
};

TreeMenuItem reports = new TreeMenuItem 
{ 
    Text = "Reports",
    ItemBackColor = Color.FromArgb(45, 45, 48),
    ItemHoverColor = Color.FromArgb(62, 62, 66)
};

compactNav.Items.Add(dashboard);
compactNav.Items.Add(reports);

// Add report sub-items
reports.Items.Add(new TreeMenuItem { Text = "Sales" });
reports.Items.Add(new TreeMenuItem { Text = "Inventory" });
reports.Items.Add(new TreeMenuItem { Text = "Analytics" });
csharp
// Create compact navigation
TreeNavigator compactNav = new TreeNavigator();
compactNav.ShowHeader = false; // Hide header for compact look
compactNav.Style = TreeNavigatorStyle.Office2016DarkGray;
compactNav.PadY = 5; // Reduce spacing between items

// Customize item colors
TreeMenuItem dashboard = new TreeMenuItem 
{ 
    Text = "Dashboard",
    ItemBackColor = Color.FromArgb(45, 45, 48),
    ItemHoverColor = Color.FromArgb(62, 62, 66),
    SelectedColor = Color.FromArgb(0, 122, 204)
};

TreeMenuItem reports = new TreeMenuItem 
{ 
    Text = "Reports",
    ItemBackColor = Color.FromArgb(45, 45, 48),
    ItemHoverColor = Color.FromArgb(62, 62, 66)
};

compactNav.Items.Add(dashboard);
compactNav.Items.Add(reports);

// Add report sub-items
reports.Items.Add(new TreeMenuItem { Text = "Sales" });
reports.Items.Add(new TreeMenuItem { Text = "Inventory" });
reports.Items.Add(new TreeMenuItem { Text = "Analytics" });

Key Properties

核心属性

PropertyTypeDescription
ItemsCollectionCollection of TreeMenuItem objects that form the navigation hierarchy
NavigationModeNavigationModeNavigation style: Default (back button) or Extended (breadcrumb)
StyleTreeNavigatorStyleVisual theme: Office2016Colorful/White/Black/DarkGray, Office2019Colorful, Default
SelectedItemTreeMenuItemGets or sets the currently selected item in the current hierarchy level
Header.HeaderTextstringText displayed in the header area
Header.HeaderBackColorColorBackground color of the header
Header.HeaderForeColorColorForeground (text) color of the header
Header.HeightintHeight of the header area in pixels
ShowHeaderboolShows or hides the header area (true = visible, false = hidden)
BorderColorColorColor of the control border
BorderThicknessintThickness of the control border in pixels
PadYintVertical spacing (gap) between TreeMenuItem items
ItemBackColorColorBackground color for all TreeMenuItem items (can be overridden per item)
TextAlignTextAlignmentText alignment for items: Center, Left, or Right
UseTouchScrollBehaviorboolEnables touch-friendly scrolling with auto-hide scrollbar
属性类型描述
ItemsCollection构成导航层级的TreeMenuItem对象集合
NavigationModeNavigationMode导航样式：默认（返回按钮）或扩展（面包屑）
StyleTreeNavigatorStyle视觉主题：Office2016Colorful/White/Black/DarkGray、Office2019Colorful、默认
SelectedItemTreeMenuItem获取或设置当前层级中选中的项
Header.HeaderTextstring头部区域展示的文本
Header.HeaderBackColorColor头部背景色
Header.HeaderForeColorColor头部前景（文本）色
Header.Heightint头部区域高度，单位为像素
ShowHeaderbool展示或隐藏头部区域（true=可见，false=隐藏）
BorderColorColor控件边框颜色
BorderThicknessint控件边框厚度，单位为像素
PadYintTreeMenuItem之间的垂直间距
ItemBackColorColor所有TreeMenuItem的背景色（可按项单独覆盖）
TextAlignTextAlignment项文本对齐方式：居中、左对齐、右对齐
UseTouchScrollBehaviorbool启用触摸友好的滚动，自带自动隐藏滚动条

Common Use Cases

常见使用场景

  1. File/Folder Browser: Navigate through folder hierarchies like Windows Explorer with back button or breadcrumb navigation
  2. Settings Interface: Organize application settings into categories and subcategories with drill-down navigation
  3. Document Outline: Navigate through document sections, chapters, and subsections
  4. Menu Navigation: Create hierarchical menu systems for complex applications with space constraints
  5. Product Categories: Browse product catalogs with category → subcategory → product navigation
  6. Help System: Organize help topics into categories with easy navigation between topics and back to categories
  7. Data Dashboard: Navigate between dashboard sections, reports, and detailed views
  8. Workflow Steps: Guide users through multi-step workflows with hierarchical organization
  1. 文件/文件夹浏览器：类似Windows资源管理器的文件夹层级导航，支持返回按钮或面包屑导航
  2. 设置界面：将应用设置组织为分类和子分类，支持下钻导航
  3. 文档大纲：浏览文档的章节、篇章和子章节
  4. 菜单导航：为有空间限制的复杂应用构建层级菜单系统
  5. 产品分类：浏览产品目录，支持分类→子分类→产品的导航路径
  6. 帮助系统：将帮助主题按分类组织，支持在主题间轻松导航和返回分类页
  7. 数据看板：在看板板块、报表和详情视图之间导航
  8. 工作流步骤：引导用户完成按层级组织的多步工作流

Additional Resources

额外资源