syncfusion-winforms-tree-navigator

实现树形导航器（TreeNavigator）

一种独特的 Windows Forms 导航控件，可在不占用额外屏幕空间的情况下就地展开树结构。项目可内联展开和折叠，用户只需点击项目即可逐层浏览层次结构。

何时使用此技能

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

• 节省空间的导航：显示可就地展开且不会增大控件尺寸的层次导航
• 逐层深入界面：允许用户从父项目导航到子项目，并通过返回按钮返回
• 文件资源管理器风格：创建类似 Windows 资源管理器面包屑导航的文件／文件夹导航
• 菜单层级：构建具有父子关系的可折叠菜单系统
• 面包屑导航：实现扩展模式，通过堆叠标题显示导航路径
• 设置导航：创建按类别组织的层次化设置界面
• 文档浏览器：浏览文档结构、章节和子章节
• TreeView 替代方案：用更紧凑、更专注的导航体验替代标准 TreeView

组件概述

TreeNavigator 控件为层次导航提供了独特的界面：

• 就地展开树结构，无需占用更多屏幕空间
• 导航到子项目时，项目会自动折叠
• 点击父项目即可深入浏览子项目
• 使用返回按钮返回父级
• 支持两种导航模式：默认模式（单个返回按钮）和扩展模式（面包屑样式标题）

主要功能：

• NavigationMode 属性，用于选择导航样式（Default 或 Extended）
• Items 集合，用于管理 TreeMenuItem 对象
• Header 配置，用于自定义标题的外观和行为
• Style 属性，用于应用 Office 2016/2019 视觉主题
• SelectedItem 属性，用于以编程方式选择项目
• 选择事件，用于跟踪和控制导航

文档和导航指南

入门

📄 阅读： references/getting-started.md

何时阅读： 开始新的实现、设置依赖项、首次使用、创建基本的 TreeNavigator

涵盖主题：

• 程序集部署（Syncfusion.Tools.Windows、Syncfusion.Shared.Base）
• NuGet 包安装
• 命名空间要求（Syncfusion.Windows.Forms.Tools）
• 通过设计器添加 TreeNavigator（从工具箱拖放）
• 在代码中以编程方式添加 TreeNavigator
• 将 TreeMenuItem 项添加到 Items 集合
• 标题配置（HeaderText 属性）
• 通过设计器添加项目（Smart Tag 编辑器）
• 完整的代码设置示例
• .NET Core 中子项目的解决方法

---

导航模式

📄 阅读： references/navigation-modes.md

何时阅读： 选择导航行为、实现返回按钮导航、构建面包屑样式界面

涵盖主题：

• NavigationMode 属性概述
• 默认模式（单个返回按钮，所选项目位于顶部）
• 扩展模式（堆叠式面包屑标题，可点击任意层级）
• 不同模式下的导航行为差异
• 各模式的适用场景（简单或复杂层次结构）
• 设置导航模式的代码示例
• 默认模式与扩展模式的视觉对比

---

外观和样式

📄 阅读： references/appearance-styling.md

阅读时机： 自定义视觉外观、应用主题、设置标题样式、配置边框和颜色

涵盖主题：

• Style 属性（Office2016Colorful/White/Black/DarkGray、Office2019Colorful、Default）
• 视觉主题的应用与比较
• 标题自定义（Height、HeaderBackColor、HeaderForeColor、HeaderText、TextBounds）
• ShowHeader 属性（隐藏/显示标题区域）
• 边框自定义（BorderColor、BorderThickness）
• 项间距（用于设置项目间距的 PadY 属性）
• TreeMenuItem 外观（ItemBackColor、ItemHoverColor、SelectedColor、SelectedItemForeColor）
• 文本对齐（TextAlign：Center、Left、Right）
• 包含代码的完整样式示例

---

树形菜单项

📄 阅读： references/tree-menu-items.md

阅读时机： 管理项目、添加/移除 TreeMenuItem、构建层级结构、操作项目集合

涵盖主题：

• TreeMenuItem 类概述及属性
• Items 集合管理（Add、Remove、Clear）
• 通过代码添加项目（C# 和 VB.NET）
• 通过设计器添加项目（Smart Tag 集合编辑器）
• 父子项目关系和嵌套
• 项目属性（Text、ItemBackColor、ItemHoverColor、SelectedColor、SelectedItemForeColor）
• 构建多级层级结构
• 在运行时动态操作项目
• 包含嵌套项目的完整示例

---

选择和事件

📄 阅读： references/selection-events.md

阅读时机： 处理选择变更、响应导航、以编程方式选择项目、防止选择

涵盖主题：

• SelectedItem 属性（获取/设置当前所选项目）
• SelectionChanging 事件（在选择变更前触发，可取消）
• SelectionStateChangingEventArgs（NewValue、OldValue、Expanded、Cancel 属性）
• SelectionChanged 事件（在选择变更后触发）
• SelectionStateChangedEventArgs（SelectedItem、Expanded 属性）
• 包含代码的事件处理示例
• 取消选择变更（验证场景）
• 触控滚动行为（UseTouchScrollBehavior 属性）
• 完整的事件工作流示例

---

快速入门示例

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

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);

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)

---

常见模式

模式 1：使用自定义颜色的设置导航

// 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" });

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

// 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);

模式 3：使用项目悬停颜色的紧凑导航菜单

// 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" });

---

关键属性

属性	类型	描述
Items	Collection	构成导航层级的 TreeMenuItem 对象集合
NavigationMode	NavigationMode	导航样式：Default（返回按钮）或 Extended（面包屑导航）
Style	TreeNavigatorStyle	视觉主题：Office2016Colorful/White/Black/DarkGray、Office2019Colorful、Default
SelectedItem	TreeMenuItem	获取或设置当前层级中选中的项
Header.HeaderText	string	标题区域中显示的文本
Header.HeaderBackColor	Color	标题的背景色
Header.HeaderForeColor	Color	标题的前景色（文本颜色）
Header.Height	int	标题区域的高度，单位为像素
ShowHeader	bool	显示或隐藏标题区域（true = 显示，false = 隐藏）
BorderColor	Color	控件边框的颜色
BorderThickness	int	控件边框的粗细，单位为像素
PadY	int	TreeMenuItem 项之间的垂直间距
ItemBackColor	Color	所有 TreeMenuItem 项的背景色（可按项覆盖）
TextAlign	TextAlignment	项的文本对齐方式：Center、Left 或 Right
UseTouchScrollBehavior	bool	启用适合触控的滚动行为，并自动隐藏滚动条

---

常见用例

1. 文件/文件夹浏览器：像 Windows 资源管理器一样浏览文件夹层级，支持返回按钮或面包屑导航
2. 设置界面：将应用设置整理到类别和子类别中，支持逐层深入导航
3. 文档大纲：浏览文档的各个章节、章和小节
4. 菜单导航：为复杂应用创建层级菜单系统，以适应空间限制
5. 产品类别：浏览产品目录，按类别 → 子类别 → 产品导航
6. 帮助系统：将帮助主题整理到各类别中，便于在主题之间导航并返回类别
7. 数据仪表板：在仪表板各个区域、报告和详细视图之间导航
8. 工作流步骤：通过层级组织，引导用户完成多步骤工作流

---

其他资源

• Syncfusion 帮助中的 TreeNavigator 控件
• Syncfusion.Windows.Forms.Tools 命名空间
• TreeNavigator API 参考
• TreeMenuItem API 参考