syncfusion-winforms-navigation-pane

在 Syncfusion WinForms 中实现导航窗格（GroupBar）

本技能将指导你实现 Syncfusion.Tools.WinForms（导航窗格）控件——一种 Outlook 风格的导航容器，可显示带有可折叠分区和子项集合的分层组。

何时使用此技能

在用户需要以下功能时使用此技能：

• 实现 Outlook 风格的导航窗格（类似 Microsoft Outlook 侧边栏）
• 创建带可折叠组的 分层侧边栏导航
• 构建 工具箱风格的界面（类似 Visual Studio .NET 工具箱）
• 添加带有 GroupBarItems 的 分类控件集合
• 实现 GroupView，在组内显示子项
• 启用 StackedMode，让导航窗格位于底部（Outlook 风格）
• 应用 Office 2007/2010/2016 主题和 Metro 样式
• 创建 嵌套 GroupBar（在 GroupBar 中嵌入 GroupBar）
• 为导航项添加 就地重命名功能
• 实现 序列化，以保存/还原导航布局
• 自定义 标题、边框、颜色和动画
• 使用主题化导航容器替换 标准面板

GroupBar 非常适合需要分类导航、工具箱风格界面或 Outlook 风格侧边栏布局的应用程序。

组件概述

GroupBar（导航窗格）是一种容器控件，可显示多个组（GroupBarItems），并且一次只显示一个所选组的内容。它与 GroupView 配合使用，用于显示子项。主要功能包括：

• GroupBarItem：类似选项卡的导航项（组/类别）
• GroupView：用于在组内显示子项的客户端控件
• GroupViewItem：GroupView 中的单个子项
• StackedMode：导航窗格模式（类似 Outlook），带有可折叠堆叠布局
• Office 主题：Office 2007/2010/2016、Metro、Office2016Colorful/White/DarkGray/Black
• 嵌套 GroupBar：在另一个 GroupBar 中嵌入 GroupBar
• 序列化：保存/还原布局状态和项位置
• 外观自定义：标题、边框、颜色、字体和动画
• 就地重命名：在运行时编辑 GroupBarItem 名称
• 本地化：多语言支持

与标准 Panel/TabControl 的主要区别： GroupBar 提供 Outlook 风格导航，并集成 GroupView，支持用于可折叠导航窗格的 StackedMode、Office 主题以及分层项显示功能。

其他资源

程序集： Syncfusion.Shared.Base.dll
命名空间： Syncfusion.Windows.Forms.Tools
NuGet 包： Syncfusion.Shared.Base 最低 .NET Framework 版本： 4.5

文档和导航指南

入门和基本设置

📄 阅读： references/getting-started.md

用户需要以下内容时，请阅读此参考资料：

• 程序集依赖项和 NuGet 包安装
• 命名空间：Syncfusion.Windows.Forms.Tools
• 通过设计器或代码创建 GroupBar
• 向控件添加 GroupBarItems
• GroupBar 基本配置
• 了解 GroupBar 结构
• 完整的最小可运行示例

GroupBar 项和结构

📄 阅读： references/groupbar-items-and-structure.md

用户需要以下内容时，请阅读此参考资料：

• 创建 GroupBarItem 实例
• 用于项标签的 Text 属性
• 用于项图标的 Image 属性
• Client 属性（关联 GroupView）
• 管理 GroupBarItems 集合
• 项选择和导航
• 处理 GroupBarItemSelected 事件
• 完整的组导航示例

GroupView 和子项

📄 阅读： references/groupview-and-child-items.md

当用户需要以下内容时，请阅读此参考：

• GroupView 概述（用于控制组的客户端）
• 创建 GroupView 实例
• 用于子项的 GroupViewItem
• 向 GroupViewItems 集合添加项
• 将 GroupView 链接到 GroupBarItem.Client
• 在 GroupView 中选择项
• GroupViewItem 点击事件
• 构建工具箱风格的界面

堆叠模式（导航窗格）

📄 阅读： references/stacked-mode.md

当用户需要以下内容时，请阅读此参考：

• StackedMode 属性（Outlook 风格导航）
• 底部导航窗格
• 折叠状态下的 HeaderHeight 属性
• 在堆叠项之间导航
• 展开/折叠状态管理
• 堆叠布局的序列化
• 完整的 Outlook 克隆示例

视觉样式和主题

📄 阅读： references/visual-styles-and-themes.md

当用户需要以下内容时，请阅读此参考：

• VisualStyle 属性概述
• Office2007 主题（Blue、Silver、Black、Managed）
• Office2007Outlook 主题
• Office2010 主题（Blue、Silver、Black、Managed）
• Metro 主题
• Office2016 主题（Colorful、White、DarkGray、Black）
• 用于自定义品牌的 Managed 颜色
• 主题比较和选择
• 在运行时应用主题

外观自定义

📄 阅读： references/appearance-customization.md

当用户需要以下内容时，请阅读此参考：

• 标题自定义（颜色、字体、高度）
• 边框设置（样式、颜色）
• 文本对齐和设置
• 图像显示配置
• 工具提示设置
• 光标自定义
• 动画设置
• 自定义颜色和渐变

高级功能和配置

📄 阅读： references/advanced-features.md

当用户需要以下内容时，请阅读此参考：

• 嵌套 GroupBar 支持（GroupBar 中的 GroupBar）
• 就地重命名 GroupBarItems
• 布局状态的序列化
• 本地化支持
• 在 GroupView 中选择链接
• 自定义控件承载
• 事件处理（GroupBarItemSelected 等）
• 复杂导航场景

快速入门示例

以下是一个创建含有项和子内容的 GroupBar 的最简示例：

using Syncfusion.Windows.Forms.Tools;
using System;
using System.Drawing;
using System.Windows.Forms;

public class GroupBarExample : Form
{
    private GroupBar groupBar1;
    
    public GroupBarExample()
    {
        // Create GroupBar
        groupBar1 = new GroupBar();
        groupBar1.Dock = DockStyle.Left;
        groupBar1.Width = 200;
        
        // Create GroupBarItems
        GroupBarItem mailItem = new GroupBarItem();
        mailItem.Text = "Mail";
        
        GroupBarItem calendarItem = new GroupBarItem();
        calendarItem.Text = "Calendar";
        
        GroupBarItem contactsItem = new GroupBarItem();
        contactsItem.Text = "Contacts";
        
        // Add items to GroupBar
        groupBar1.GroupBarItems.AddRange(new GroupBarItem[] {
            mailItem,
            calendarItem,
            contactsItem
        });
        
        // Add GroupBar to form
        this.Controls.Add(groupBar1);
        
        this.Text = "GroupBar Example";
        this.Size = new Size(600, 400);
    }
}

结果： 一个停靠在左侧的导航窗格，包含 3 个组（Mail、Calendar、Contacts），类似于 Microsoft Outlook。

常见模式

Outlook 风格的 GroupView 导航

模式： 创建一个受 Outlook 启发、包含子项的导航窗格。

// Create GroupBar
GroupBar groupBar = new GroupBar();
groupBar.Dock = DockStyle.Left;
groupBar.Width = 220;
groupBar.VisualStyle = VisualStyle.Office2016Colorful;

// Create GroupBarItem
GroupBarItem mailItem = new GroupBarItem();
mailItem.Text = "Mail Folders";

// Create GroupView for child items
GroupView mailView = new GroupView();
mailView.Name = "MailView";
mailView.GroupViewItems.AddRange(new GroupViewItem[] {
    new GroupViewItem("Inbox", 0, true, null, "Inbox"),
    new GroupViewItem("Drafts", 1, true, null, "Drafts"),
    new GroupViewItem("Sent Items", 2, true, null, "Sent"),
    new GroupViewItem("Deleted Items", 3, true, null, "Deleted")
});

// Link GroupView to GroupBarItem
mailItem.Client = mailView;
groupBar.Controls.Add(mailView);
groupBar.GroupBarItems.Add(mailItem);

// Handle item click
mailView.GroupViewItemSelected += (s, e) => {
    string folderName = ((sender as GroupView)?.SelectedItem >= 0 ? (sender as GroupView).GroupViewItems[(sender as GroupView).SelectedItem].Text : null)`;
    LoadMailFolder(folderName);
};

this.Controls.Add(groupBar);

适用场景： 用户需要带有文件夹层级结构的 Outlook 风格邮件导航。

Visual Studio 工具箱克隆

模式： 创建一个按类别组织控件的工具箱风格界面。

// Create GroupBar for toolbox
GroupBar toolbox = new GroupBar();
toolbox.Dock = DockStyle.Left;
toolbox.Width = 200;
toolbox.VisualStyle = VisualStyle.Office2010;

// Create "Windows Forms" category
GroupBarItem winFormsItem = new GroupBarItem();
winFormsItem.Text = "Windows Forms";

GroupView winFormsView = new GroupView();
winFormsView.GroupViewItems.AddRange(new GroupViewItem[] {
    new GroupViewItem("Button", 0, true, null, "Button"),
    new GroupViewItem("TextBox", 1, true, null, "TextBox"),
    new GroupViewItem("Label", 2, true, null, "Label"),
    new GroupViewItem("ComboBox", 3, true, null, "ComboBox")
});

// Create "Data" category
GroupBarItem dataItem = new GroupBarItem();
dataItem.Text = "Data";

GroupView dataView = new GroupView();
dataView.GroupViewItems.AddRange(new GroupViewItem[] {
    new GroupViewItem("DataSet", 0, true, null, "DataSet"),
    new GroupViewItem("DataTable", 1, true, null, "DataTable"),
    new GroupViewItem("BindingSource", 2, true, null, "BindingSource")
});

// Link and add
winFormsItem.Client = winFormsView;
dataItem.Client = dataView;

toolbox.Controls.Add(winFormsView);
toolbox.Controls.Add(dataView);

toolbox.GroupBarItems.Add(winFormsItem);
toolbox.GroupBarItems.Add(dataItem);

this.Controls.Add(toolbox);

适用场景： 用户需要一个带有可折叠分区、类似 Visual Studio 的分类工具箱。

堆叠导航窗格（Outlook 模式）

模式： 启用 Outlook 风格的堆叠导航，并在底部显示窗格。

// Create GroupBar in stacked mode
GroupBar navPane = new GroupBar();
navPane.Dock = DockStyle.Left;
navPane.Width = 220;
navPane.StackedMode = true; // Enable Outlook-style navigation
navPane.VisualStyle = VisualStyle.Office2016White;

// Create multiple GroupBarItems
GroupBarItem mailItem = new GroupBarItem();
mailItem.Text = "Mail";

GroupBarItem calendarItem = new GroupBarItem();
calendarItem.Text = "Calendar";

GroupBarItem contactsItem = new GroupBarItem();
contactsItem.Text = "Contacts";

GroupBarItem tasksItem = new GroupBarItem();
tasksItem.Text = "Tasks";

// Add all items
navPane.GroupBarItems.AddRange(new GroupBarItem[] {
    mailItem,
    calendarItem,
    contactsItem,
    tasksItem
});

// Handle item selection
navPane.GroupBarItemSelected += (s, e) => {
    string selectedSection = ((sender as GroupView)?.SelectedItem >= 0 ? (sender as GroupView).GroupViewItems[(sender as GroupView).SelectedItem].Text : null)`;
    LoadSection(selectedSection);
};

this.Controls.Add(navPane);

适用场景： 用户需要带堆叠项和底部导航窗格的 Outlook 风格导航。

关键属性

核心属性

属性	类型	说明	使用场景
GroupBarItems	Collection	GroupBarItem 实例的集合	添加导航组
SelectedItem	GroupBarItem	当前选中的项	获取/设置活动组
StackedMode	bool	启用 Outlook 风格的堆叠导航	Outlook 风格布局
VisualStyle	VisualStyle	视觉主题	应用 Office 主题
HeaderHeight	int	GroupBar 标题的高度	自定义标题大小

GroupBarItem 属性

属性	类型	描述	使用场景
Text	string	项目的显示文本	设置组标签
Image	Image	项目的图标图像	添加视觉标识
Client	Control	客户端控件（通常为 GroupView）	将内容关联到项目
Selected	bool	项目是否处于选中状态	检查／设置选中状态

GroupView 属性

属性	类型	描述	使用场景
GroupViewItems	Collection	视图中的子项目	添加子项目
SelectedItem	GroupViewItem	当前选中的子项目	获取／设置选中的子项目
Name	string	视图的标识符	引用该视图

样式属性

属性	类型	描述	使用场景
VisualStyle	VisualStyle	主题（Office2007/2010/2016/Metro）	应用主题
Office2007Theme	Office2007Theme	Office2007 配色方案	蓝色／银色／黑色／托管
Office2010Theme	Office2010Theme	Office2010 配色方案	蓝色／银色／黑色／托管
BorderStyle	BorderStyle	边框外观	自定义边框
BackColor	Color	背景颜色	自定义背景

高级属性

属性	类型	描述	使用场景
AllowCollapse	bool	允许折叠组	启用折叠行为
AllowInPlaceEditing	bool	启用项目重命名	运行时编辑
AnimateCollapse	bool	为折叠／展开添加动画	实现平滑过渡
ShowToolTips	bool	显示工具提示	显示项目说明

常见使用场景

邮件客户端导航

Outlook 风格的邮件文件夹导航：

• 邮件文件夹（收件箱、草稿、已发送、已删除）
• 包含约会的日历视图
• 按类别整理的联系人列表
• 按优先级划分的任务区域

IDE 工具箱界面

Visual Studio 风格的工具箱：

• 按类别整理的控件集合
• 组件类别（数据、布局、控件）
• 可折叠区域
• 拖放式工具选择

文档管理系统

分层文档导航：

• 文档类别和文件夹
• 项目层级结构
• 文件类型分组
• 归档区域

设置和配置面板

按类别组织的设置导航：

• 常规设置区域
• 账户偏好设置
• 高级选项
• 主题自定义

实现检查清单

实现 GroupBar（导航窗格）时，请确保：

• ✅ 引用了必需程序集（Syncfusion.Shared.Base.dll）
• ✅ 包含了命名空间（Syncfusion.Windows.Forms.Tools）
• ✅ 创建并配置了 GroupBar 实例
• ✅ 将 GroupBarItems 添加到 GroupBarItems 集合
• ✅ 如需显示子项目，已创建 GroupView
• ✅ 已设置 Client 属性，将 GroupView 关联到 GroupBarItem
• ✅ 已应用视觉样式（VisualStyle 属性）
• ✅ 已设置 Dock 属性以实现正确布局（通常为 DockStyle.Left）
• ✅ 已为项目选择添加事件处理程序
• ✅ 已对多个项目和导航进行测试

故障排除快速参考

问题： GroupBar 不可见

• 检查是否已将 GroupBar 添加到窗体的 Controls 中
• 设置 Dock 属性（推荐使用 DockStyle.Left）
• 确认 Width 属性足够大（通常为 200-250 像素）
• 确保窗体有足够空间容纳停靠控件

问题： GroupBarItems 未显示

• 确认已将项目添加到 GroupBarItems 集合
• 检查每个项目是否已设置 Text 属性
• 确保 GroupBar.Visible = true
• 确认项目未折叠或隐藏

问题： 子项目（GroupViewItems）未显示

• 创建 GroupView 实例
• 将 GroupViewItems 添加到 GroupView.GroupViewItems 集合
• 设置 GroupBarItem.Client = groupView
• 将 GroupView 添加到 GroupBar.Controls 集合

问题： StackedMode 不起作用

• 设置 StackedMode = true
• 确保存在多个 GroupBarItems（堆叠至少需要 2 个）
• 检查 HeaderHeight 属性（设为 0 会隐藏标题）
• 确认视觉样式支持堆叠模式

问题： 主题未应用

• 将 VisualStyle 属性设置为所需主题
• 对于 Office2007/2010，设置对应的主题属性（Office2007Theme、Office2010Theme）
• 对于托管颜色，调用 ApplyManagedColors 方法
• 确保已引用 Syncfusion.Shared.Base 程序集

问题： GroupView 选择不起作用

• 处理 GroupViewItemSelected 事件
• 检查 GroupView.SelectedItem 属性
• 确保 GroupViewItems 具有唯一标识符
• 确认点击事件已正确连接

总结

GroupBar（导航窗格）提供类似 Outlook 的导航功能，包括：

• 分层导航：包含 GroupView 子项目的 GroupBarItem 分组
• 堆叠模式：带可折叠分区的 Outlook 风格导航窗格
• Office 主题：Office 2007/2010/2016、Metro 和自定义主题
• 嵌套支持：支持在 GroupBar 中嵌套 GroupBar
• 序列化：保存/恢复布局状态
• 可自定义外观：标题、边框、颜色、动画

在创建专业且井然有序的 WinForms 应用程序时，如果需要 Outlook 风格导航、工具箱界面、分类层级结构或带主题的导航容器，请使用 GroupBar。