syncfusion-wpf-navigation-pane

实现 WPF GroupBar（导航窗格）

GroupBar 控件实现了类似 Microsoft Outlook Bar 的导航窗格。它可在可展开/折叠的分区中承载分类项目集合和自定义控件。支持多种视觉模式、数据绑定、拖放重排、上下文菜单、工具栏和完整的主题支持。

程序集： Syncfusion.Tools.WPF + Syncfusion.Shared.WPF
命名空间： Syncfusion.Windows.Tools.Controls
XAML 架构： xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

控件层次结构

GroupBar                    ← Root navigation container
└── GroupBarItem            ← Category tab/header (e.g., "Mailbox", "Contacts")
    ├── GroupView           ← List container for link-style items
    │   └── GroupViewItem   ← Clickable item with text and icon
    └── Panel / any UIElement ← Or use any WPF panel as content

适用场景

• 用户想要 Outlook 风格的导航侧边栏或手风琴面板
• 用户需要包含内容的可展开/折叠分区
• 用户询问 GroupBar、GroupBarItem、GroupView、GroupViewItem
• 用户需要 StackMode（Outlook 栏）、MultipleExpansion（树视图）或 Default 模式
• 用户需要使用 MVVM 的数据绑定导航项目
• 用户询问导航项目的拖放重排
• 用户询问 Navigation Pane 弹出窗口、抓手或调整大小行为

快速入门

xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

<syncfusion:GroupBar Height="300" Width="230" VisualMode="StackMode" Name="groupBar">
    <syncfusion:GroupBarItem Header="Mailbox" HeaderImageSource="Images/mail.png">
        <syncfusion:GroupView>
            <syncfusion:GroupViewItem Text="Inbox"     ImageSource="Images/inbox.png"/>
            <syncfusion:GroupViewItem Text="Sent Items" ImageSource="Images/sent.png"/>
            <syncfusion:GroupViewItem Text="Deleted"   ImageSource="Images/trash.png"/>
        </syncfusion:GroupView>
    </syncfusion:GroupBarItem>
    <syncfusion:GroupBarItem Header="Contacts">
        <syncfusion:GroupView>
            <syncfusion:GroupViewItem Text="All Contacts"/>
            <syncfusion:GroupViewItem Text="Favorites"/>
        </syncfusion:GroupView>
    </syncfusion:GroupBarItem>
</syncfusion:GroupBar>

using Syncfusion.Windows.Tools.Controls;

GroupBar groupBar = new GroupBar();
groupBar.VisualMode = VisualMode.StackMode;

GroupBarItem item = new GroupBarItem { Header = "Mailbox" };
GroupView view = new GroupView();
view.Items.Add(new GroupViewItem { Text = "Inbox" });
item.Content = view;
groupBar.Items.Add(item);
this.Content = groupBar;

常见模式

目标	方法
Outlook 风格导航	VisualMode="StackMode"
树状多项展开	VisualMode="MultipleExpansion"
一次展开一项	VisualMode="Default"
可折叠栏	AllowCollapse="True" + VisualMode="StackMode"
数据绑定项目	ItemsSource + 带有 HeaderText/Content 设置器的 ItemContainerStyle
自定义项目内容	将任意 Panel 或 UIElement 放入 GroupBarItem.Content
列表视图风格项目	使用 IsListViewMode="True" 的 GroupView
拖动重排项目	DragItemVisibility="True"
调整导航弹出窗口大小	PopupResizeDirection="Both"
StackMode 的抓手	ShowGripper="True" + VisualMode="StackMode"
保存/恢复栏状态	SaveBarState() / LoadBarState() / ResetBarState()

关键属性

属性	类型	说明
VisualMode	VisualMode	Default / MultipleExpansion / StackMode
AllowCollapse	bool	允许折叠（StackMode）
ShowGripper	bool	显示调整大小抓手（StackMode）
ItemsSource	IEnumerable	数据绑定项目
ItemContainerStyle	Style	应用于每个 GroupBarItem 的样式
DragItemVisibility	bool	启用拖放重排
DragMarkerBrush	Brush	拖放插入标记的颜色
PopupResizeDirection	PopupResizeDirection	调整导航窗格弹出窗口大小的方向（Both/H/V/None）
ItemContentLength	double	所选项目内容区域的高度/宽度
GroupBarHeaderStyle	Style	GroupBar 标题边框的样式
GroupBarItem.Header	string	项目标题的显示文本
GroupBarItem.HeaderImageSource	ImageSource	项目标题中的图标
GroupBarItem.IsSelected	bool	初始展开此项目
GroupBarItem.GroupBarItemCornerRadius	CornerRadius	项目标题的圆角
GroupView.IsListViewMode	bool	列表视图风格（而非图标风格）
GroupViewItem.Text	string	视图项目的文本标签
GroupViewItem.ImageSource	ImageSource	视图项目的图标
SaveOriginalState	bool	加载时自动保存状态

---

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 程序集引用（Tools.WPF + Shared.WPF）
• 通过设计器、XAML 或 C# 添加
• 使用 GroupView 内容声明 GroupBarItems
• 向 GroupBarItem 添加面板内容
• VisualMode 基本概览
• 使用 SfSkinManager 设置主题

GroupBar 项

📄 阅读： references/groupbar-items.md

• GroupBarItem 属性（Header、HeaderText、HeaderImageSource）
• IsSelected、ShowInGroupBar、GroupBarItemCornerRadius
• GroupBarItemCursorType（Default/Hand）
• ItemContentLength（内容区域的高度/宽度）
• DraggingItemInProgress、HiddenItemsCount
• GroupBarItemAdded / GroupBarItemRemoved 事件

GroupView 和内容

📄 阅读： references/groupview-and-content.md

• GroupView 作为包含 GroupViewItem 元素的项容器
• GroupViewItem（Text、ImageSource、工具提示）
• IsListViewMode（列表或图标显示）
• GroupViewItem 的默认图像
• 添加面板和自定义 UIElements 作为内容
• 旋转项内容

视觉模式

📄 阅读： references/visual-modes.md

• 默认模式（一次展开一项）
• MultipleExpansion 模式（树视图样式）
• StackMode（Outlook 栏样式，底部弹出菜单）
• AllowCollapse、ShowGripper
• StackMode 下 ThemeStudio 与经典主题的布局差异

数据绑定

📄 阅读： references/data-binding.md

• ItemsSource + ItemContainerStyle，以及 HeaderText/Content 设置器
• 使用 ObservableCollection 的 Model + ViewModel
• DataContext 绑定模式
• 使用 XML 进行数据绑定（XmlDataProvider）
• 自定义 HeaderTemplate 和 ContentTemplate
• 用于条件样式的 ItemContainerStyleSelector

方向和布局

📄 阅读： references/orientation-and-layout.md

• GroupBar 方向（Horizontal/Vertical）
• GroupView 和 GroupViewItem 方向
• 调整 GroupBar 宽度、更改标题高度
• 旋转 GroupBar
• 用于支持 RTL 的 FlowDirection
• 导航窗格：PopupResizeDirection、ShowGripper

行为和功能

📄 阅读： references/behavior-and-features.md

• 拖放重新排序（DragItemVisibility、DragMarkerBrush）
• 内置上下文菜单（排序、添加、重命名、移动）
• GroupBar 内的工具栏
• GroupViewItems 的工具提示
• 展开/折叠动画
• 在 StackMode 下折叠和关闭
• 状态持久化（SaveBarState/LoadBarState/ResetBarState）
• 本地化

外观

📄 阅读： references/appearance.md

• GroupBarHeaderStyle（背景、圆角半径、高度）
• CollapseButtonTemplate 和 CollapseButtonBackground
• ItemContainerStyle（HeaderTemplate + ContentTemplate）
• ItemContainerStyleSelector
• DragMarkerBrush
• SfSkinManager 主题表
• ThemeStudio 自定义主题