syncfusion-wpf-navigation-drawer

实现 Syncfusion WPF Navigation Drawer

WPF Navigation Drawer 控件是一种侧边栏导航组件，可在应用程序中创建直观且高效的导航菜单。它支持紧凑和展开显示模式，用户可根据可用屏幕尺寸动态切换。此外，该控件还提供默认模式，允许开发者定义完全自定义的窗格视图，从而为导航体验的设计提供更大的灵活性

何时使用此技能

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

• 在 WPF 应用程序中创建侧边栏导航菜单
• 实现带汉堡菜单的可折叠抽屉式导航
• 使用紧凑和展开模式构建响应式导航
• 添加带图标的分层导航菜单项
• 实现可滑动的侧边面板
• 创建带页眉和页脚的自定义导航视图
• 处理导航事件和选择操作
• 支持抽屉菜单中的键盘导航
• 在 WPF 中构建现代 UI 导航模式

组件概览

Syncfusion WPF Navigation Drawer (SfNavigationDrawer) 是一个侧边栏导航控件，提供：

• 三种显示模式： 默认（可折叠）、紧凑（仅图标）、展开（全宽）
• 灵活的定位方式： 可放置在左侧、右侧、顶部或底部
• 内置导航项： Tab、Button、Header、Separator 类型，支持分层结构
• 自定义视图： 页眉、内容和页脚区域均可完全自定义
• 数据绑定： 支持使用 ItemsSource 进行分层数据绑定
• 丰富的事件： Opening、Opened、Closing、Closed、ItemClicked、ItemExpanded、ItemCollapsed
• 键盘支持： 完整的键盘导航（Tab、方向键、Enter、Space）
• 流畅动画： SlideOnTop、Push 和 Reveal 转场效果
• 响应式设计： 根据可用宽度自动切换显示模式

使用场景：

• 电子邮件客户端导航（收件箱、已发送、草稿及嵌套类别）
• 电商应用菜单（商品、购物车、订单及子类别）
• 银行应用导航（账户、转账、付款）
• 具有多级导航的管理控制面板
• 在桌面 WPF 应用中实现移动端风格的导航

文档和导航指南

快速入门

📄 阅读： references/getting-started.md 适用场景： 首次实现、设置控件、了解基本结构

• 安装和程序集部署
• 在 XAML 和 C# 中创建基本的 NavigationDrawer
• 添加内容视图和侧边栏菜单项
• 设置带图标的导航项
• 最小可运行示例

显示模式

📄 阅读： references/display-modes.md 适用场景： 在 Default、Compact 或 Expanded 模式之间进行选择，实现响应式导航

• Default 模式（带自定义视图的可折叠抽屉）
• Compact 模式（切换后展开的窄图标栏）
• Expanded 模式（全宽侧边栏）
• 根据窗口宽度自动切换显示模式
• 配置 CompactModeWidth 和 ExpandedModeWidth
• 使用 ExpandedModeThresholdWidth 实现响应式行为

填充数据

📄 阅读： references/populating-data.md 适用场景： 添加菜单项、绑定数据源、创建分层导航

• 内置 NavigationItem 属性（Header、Icon、Items）
• ItemsSource 数据绑定
• 使用嵌套项进行分层数据绑定
• 自定义 IconTemplate 和 ItemTemplate
• 不同的项类型：Tab、Button、Header、Separator
• DisplayMemberPath 和 IconMemberPath
• 使用 IndentationWidth 设置子项缩进
• 子项的弹出支持

自定义视图和自定义项

📄 阅读： references/custom-views.md 适用场景： 创建自定义抽屉布局、调整抽屉位置、添加动画

• DrawerHeaderView、DrawerContentView、DrawerFooterView
• 自定义 DrawerWidth 和 DrawerHeight
• Position 属性（Left、Right、Top、Bottom）
• 滑动手势和 TouchThreshold
• 过渡动画（SlideOnTop、Push、Reveal）
• 配置 AnimationDuration
• 自定义 DrawerBackground
• 使用 IsOpen 属性进行编程控制
• ToggleDrawer() 方法

自定义页眉和页脚

📄 阅读： references/header-and-footer.md 适用场景： 自定义切换按钮、页眉或页脚部分

• ToggleButtonContentTemplate 和 ToggleButtonIconTemplate
• IsToggleButtonVisible 属性
• FooterItems 集合
• HeaderHeight 和 FooterHeight 属性
• Default 模式下的自定义页眉和页脚视图

命令和事件

📄 阅读： references/commands-and-events.md 适用场景： 处理抽屉状态变化、项目点击和导航事件

• Opening 和 Opened 事件（支持取消）
• Closing 和 Closed 事件（支持取消）
• ItemClicked 事件（仅限 Compact/Expanded 模式）
• ItemExpanded 和 ItemCollapsed 事件
• 使用 Command 和 CommandParameter 绑定命令
• DelegateCommand 实现示例

选择处理

📄 阅读： references/handling-selection.md 适用场景： 管理选中项、跟踪导航状态

• SelectedItem 属性用法
• 使用 NavigationItem 进行选择
• 使用自定义数据对象进行选择
• 自定义 SelectionBackground

键盘支持

📄 阅读： references/keyboard-support.md 适用场景： 实现键盘导航，确保无障碍访问

• 使用 Tab 键在元素间导航
• 使用向上/向下箭头键导航项目
• 使用 Enter 和 Space 选择项目
• 焦点管理

快速入门示例

包含项目的基本导航抽屉

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <syncfusion:SfNavigationDrawer x:Name="navigationDrawer" 
                                   DisplayMode="Expanded">
        
        <syncfusion:NavigationItem Header="Inbox" IsSelected="True">
            <syncfusion:NavigationItem.Icon>
                <Path Data="M32.032381,16.445429 L25.410999..." Fill="White"/>
            </syncfusion:NavigationItem.Icon>
        </syncfusion:NavigationItem>
        
        <syncfusion:NavigationItem Header="Sent mail">
            <syncfusion:NavigationItem.Icon>
                <Path Data="M42.128046,6.7269681..." Fill="White"/>
            </syncfusion:NavigationItem.Icon>
        </syncfusion:NavigationItem>
        
        <syncfusion:NavigationItem Header="Drafts">
            <syncfusion:NavigationItem.Icon>
                <Path Data="M6.9999996,48.353..." Fill="White"/>
            </syncfusion:NavigationItem.Icon>
        </syncfusion:NavigationItem>
        
        
        <syncfusion:SfNavigationDrawer.ContentView>
            <Grid>
                <Label Content="Content View" 
                       HorizontalAlignment="Center"
                       VerticalAlignment="Center"/>
            </Grid>
        </syncfusion:SfNavigationDrawer.ContentView>
    </syncfusion:SfNavigationDrawer>
</Window>

代码隐藏文件（C#）

using Syncfusion.UI.Xaml.NavigationDrawer;

// Create navigation drawer
SfNavigationDrawer navigationDrawer = new SfNavigationDrawer();
navigationDrawer.DisplayMode = DisplayMode.Expanded;

// Add items
navigationDrawer.Items.Add(new NavigationItem()
{
    Header = "Inbox",
    Icon = new Path() { Data = Geometry.Parse("M32.032381...") },
    IsSelected = true
});

navigationDrawer.Items.Add(new NavigationItem()
{
    Header = "Sent mail",
    Icon = new Path() { Data = Geometry.Parse("M42.128046...") }
});

// Set content
Label label = new Label { Content = "Content View" };
navigationDrawer.ContentView = label;

常见模式

模式 1：响应式导航（自动切换模式）

<syncfusion:SfNavigationDrawer DisplayMode="Expanded"
                               AutoChangeDisplayMode="True"
                               ExpandedModeThresholdWidth="700">
    
</syncfusion:SfNavigationDrawer>

适用场景： 需要适应窗口大小变化的桌面应用

模式 2：带子项目的分层导航

<syncfusion:NavigationItem Header="Inbox" IsExpanded="True">
    <syncfusion:NavigationItem.Icon>
        <Path Data="..." Fill="White"/>
    </syncfusion:NavigationItem.Icon>
    
    <syncfusion:NavigationItem Header="Primary">
        <syncfusion:NavigationItem.Icon>
            <Path Data="..." Fill="White"/>
        </syncfusion:NavigationItem.Icon>
    </syncfusion:NavigationItem>
    <syncfusion:NavigationItem Header="Social">
        <syncfusion:NavigationItem.Icon>
            <Path Data="..." Fill="White"/>
        </syncfusion:NavigationItem.Icon>
    </syncfusion:NavigationItem>
</syncfusion:NavigationItem>

适用场景： 多级导航菜单（例如，电子邮件类别、产品类别）

模式 3：带页眉和页脚的自定义抽屉

<syncfusion:SfNavigationDrawer DisplayMode="Default" DrawerWidth="300">
    <syncfusion:SfNavigationDrawer.DrawerHeaderView>
        <Grid Background="#31ade9">
            <Label Content="User Profile" />
        </Grid>
    </syncfusion:SfNavigationDrawer.DrawerHeaderView>
    
    <syncfusion:SfNavigationDrawer.DrawerContentView>
        <ListBox ItemsSource="{Binding MenuItems}"/>
    </syncfusion:SfNavigationDrawer.DrawerContentView>
    
    <syncfusion:SfNavigationDrawer.DrawerFooterView>
        <Button Content="Logout" />
    </syncfusion:SfNavigationDrawer.DrawerFooterView>
    
    <syncfusion:SfNavigationDrawer.ContentView>
        <Grid></Grid>
    </syncfusion:SfNavigationDrawer.ContentView>
</syncfusion:SfNavigationDrawer>

适用场景： 需要超越内置项目实现自定义抽屉布局的应用

模式 4：使用 ItemsSource 进行数据绑定

<syncfusion:SfNavigationDrawer DisplayMode="Compact"
                               ItemsSource="{Binding NavigationItems}"
                               DisplayMemberPath="Title"
                               IconMemberPath="Icon">
</syncfusion:SfNavigationDrawer>

适用场景： 从数据库或 API 动态生成导航菜单

关键属性

基本属性

属性	类型	描述
DisplayMode	DisplayMode	Default、Compact 或 Expanded
Items	NavigationItemsCollection	NavigationItem 对象集合
ContentView	object	主内容区域
IsOpen	bool	获取/设置抽屉的打开状态
SelectedItem	object	当前选中的导航项目
Position	Position	Left、Right、Top、Bottom（Default 模式）

显示模式属性

属性	类型	默认值	描述
AutoChangeDisplayMode	bool	false	根据宽度自动切换模式
ExpandedModeThresholdWidth	double	1007	自动切换模式的宽度阈值
CompactModeWidth	double	48	Compact 模式下的宽度
ExpandedModeWidth	double	320	Expanded 模式下的宽度

自定义属性

属性	类型	说明
DrawerWidth	double	抽屉宽度（Default 模式，Left/Right）
DrawerHeight	double	抽屉高度（Default 模式，Top/Bottom）
DrawerBackground	Brush	抽屉背景色
HeaderHeight	double	标题区域高度
FooterHeight	double	页脚区域高度
IndentationWidth	double	子项的水平间距

动画属性

属性	类型	选项
Transition	Transition	SlideOnTop、Push、Reveal
AnimationDuration	TimeSpan	打开/关闭动画的时长
EnableSwipeGesture	bool	启用滑动以打开/关闭
TouchThreshold	double	滑动灵敏度（像素）

模板属性

属性	类型	说明
ToggleButtonContentTemplate	DataTemplate	自定义切换按钮内容
ToggleButtonIconTemplate	DataTemplate	自定义切换按钮图标
ItemTemplate	DataTemplate	导航项模板
ItemTemplateSelector	DataTemplateSelector	动态选择模板

常见用例

用例 1：电子邮件客户端导航

场景： 包含“主要”“社交”“促销”的多级收件箱
解决方案： 使用带有 IsExpanded 的层级 NavigationItem，以及 Compact/Expanded 模式
参考： references/populating-data.md

用例 2：管理后台

场景： 带有子分区的顶级菜单（仪表板、用户、设置）
解决方案： 使用 ItemsSource 进行数据绑定，并采用层级数据结构
参考： references/populating-data.md

用例 3：移动风格应用

场景： 滑动覆盖内容的汉堡菜单
解决方案： 使用 Default 模式和 DrawerHeaderView，并启用滑动手势
参考： references/custom-views.md

用例 4：响应式桌面应用

场景： 在窄窗口中自动折叠为紧凑模式
解决方案： 使用 Expanded 模式，并设置 AutoChangeDisplayMode=true
参考： references/display-modes.md

用例 5：银行应用

场景： 账户、转账、支付及事件处理
解决方案： 使用 ItemClicked 事件和 Command 绑定进行导航
参考： references/commands-and-events.md

实现技巧

1. 选择合适的显示模式：

   • 使用 Default 实现带自定义视图的移动风格叠加层
   • 使用 Compact 实现仅含图标、可展开至全宽的侧边栏
   • 使用 Expanded 实现始终可见的完整侧边栏

2. 使用内置项还是自定义视图：

   • 使用 NavigationItem（Compact/Expanded）创建标准导航菜单
   • 使用 Custom Views（Default 模式）实现独特布局

3. 优化性能：

   • 对大型数据集使用 ItemsSource 进行数据绑定
   • 为异构项实现 ItemTemplateSelector
   • 保持层级较浅（最多 2-3 层）

4. 妥善处理状态：

   • 使用 Opening/Closing 事件取消状态更改
   • 存储 SelectedItem，以便恢复导航状态
   • 处理 ItemClicked 事件以进行页面导航

5. 确保无障碍访问：

   • 实现键盘导航（已内置）
   • 为屏幕阅读器提供有意义的 Header 文本
   • 为 SelectionBackground 使用足够的颜色对比度