syncfusion-wpf-navigation-drawer（syncfusion wpf 导航抽屉）

Implementing Syncfusion WPF Navigation Drawer

The WPF Navigation Drawer control is a sidebar navigation component used to create intuitive and efficient navigation menus within applications. It supports compact and expanded display modes, allowing users to switch between them dynamically based on the available screen size. Additionally, the control offers a default mode that enables developers to define a fully custom pane view, providing greater flexibility in designing navigation experiences

When to Use This Skill

Use this skill when user need to:

• Create sidebar navigation menus in WPF applications
• Implement collapsible drawer navigation with hamburger menu
• Build responsive navigation with compact and expanded modes
• Add hierarchical navigation menu items with icons
• Implement swipeable side panels
• Create custom navigation views with headers and footers
• Handle navigation events and selection
• Support keyboard navigation in drawer menus
• Build modern UI navigation patterns in WPF

Component Overview

The Syncfusion WPF Navigation Drawer (SfNavigationDrawer) is a sidebar navigation control that provides:

• Three Display Modes: Default (collapsible), Compact (icon-only), Expanded (full width)
• Flexible Positioning: Left, Right, Top, or Bottom placement
• Built-in Navigation Items: Tab, Button, Header, Separator types with hierarchical support
• Custom Views: Fully customizable header, content, and footer sections
• Data Binding: Support for ItemsSource with hierarchical data binding
• Rich Events: Opening, Opened, Closing, Closed, ItemClicked, ItemExpanded, ItemCollapsed
• Keyboard Support: Full keyboard navigation (Tab, Arrow keys, Enter, Space)
• Smooth Animations: SlideOnTop, Push, and Reveal transition effects
• Responsive Design: Auto-switching between display modes based on available width

Use Cases:

• Email client navigation (Inbox, Sent, Drafts with nested categories)
• E-commerce app menus (Products, Cart, Orders with subcategories)
• Banking app navigation (Accounts, Transfers, Payments)
• Admin dashboards with multi-level navigation
• Mobile-style navigation in desktop WPF apps

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md Use when: First-time implementation, setting up the control, understanding basic structure

• Installation and assembly deployment
• Creating basic NavigationDrawer in XAML and C#
• Adding content view and sidebar menu items
• Setting up navigation items with icons
• Minimal working example

Display Modes

📄 Read: references/display-modes.md Use when: Choosing between Default, Compact, or Expanded modes, implementing responsive navigation

• Default mode (collapsible drawer with custom views)
• Compact mode (narrow icon bar that expands on toggle)
• Expanded mode (full-width sidebar)
• Auto display mode switching based on window width
• CompactModeWidth and ExpandedModeWidth configuration
• ExpandedModeThresholdWidth for responsive behavior

Populating Data

📄 Read: references/populating-data.md Use when: Adding menu items, binding data sources, creating hierarchical navigation

• Built-in NavigationItem properties (Header, Icon, Items)
• ItemsSource data binding
• Hierarchical data binding with nested items
• IconTemplate and ItemTemplate customization
• Different item types: Tab, Button, Header, Separator
• DisplayMemberPath and IconMemberPath
• IndentationWidth for sub-items
• Popup support for sub-items

Custom Views and Customization

📄 Read: references/custom-views.md Use when: Creating custom drawer layouts, positioning drawer, adding animations

• DrawerHeaderView, DrawerContentView, DrawerFooterView
• DrawerWidth and DrawerHeight customization
• Position property (Left, Right, Top, Bottom)
• Swipe gestures and TouchThreshold
• Transition animations (SlideOnTop, Push, Reveal)
• AnimationDuration configuration
• DrawerBackground customization
• IsOpen property for programmatic control
• ToggleDrawer() method

Header and Footer Customization

📄 Read: references/header-and-footer.md Use when: Customizing toggle button, header, or footer sections

• ToggleButtonContentTemplate and ToggleButtonIconTemplate
• IsToggleButtonVisible property
• FooterItems collection
• HeaderHeight and FooterHeight properties
• Custom header and footer views in Default mode

Commands and Events

📄 Read: references/commands-and-events.md Use when: Handling drawer state changes, item clicks, navigation events

• Opening and Opened events (with Cancel support)
• Closing and Closed events (with Cancel support)
• ItemClicked event (Compact/Expanded modes only)
• ItemExpanded and ItemCollapsed events
• Command binding with Command and CommandParameter
• DelegateCommand implementation example

Selection Handling

📄 Read: references/handling-selection.md Use when: Managing selected items, tracking navigation state

• SelectedItem property usage
• Selection with NavigationItem
• Selection with custom data objects
• SelectionBackground customization

Keyboard Support

📄 Read: references/keyboard-support.md Use when: Implementing keyboard navigation, ensuring accessibility

• Tab key navigation between elements
• Up/Down arrow keys for item navigation
• Enter and Space for item selection
• Focus management

Quick Start Example

Basic Navigation Drawer with Items

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <syncfusion:SfNavigationDrawer x:Name="navigationDrawer"
                                   DisplayMode="Expanded">
        <!-- Navigation Items -->
        <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>

        <!-- Main Content -->
        <syncfusion:SfNavigationDrawer.ContentView>
            <Grid>
                <Label Content="Content View"
                       HorizontalAlignment="Center"
                       VerticalAlignment="Center"/>
            </Grid>
        </syncfusion:SfNavigationDrawer.ContentView>
    </syncfusion:SfNavigationDrawer>
</Window>

Code-behind (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;

Common Patterns

Pattern 1: Responsive Navigation (Auto Mode Switching)

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

When to use: Desktop apps that need to adapt to window resizing

Pattern 2: Hierarchical Navigation with Sub-items

<syncfusion:NavigationItem Header="Inbox" IsExpanded="True">
    <syncfusion:NavigationItem.Icon>
        <Path Data="..." Fill="White"/>
    </syncfusion:NavigationItem.Icon>
    <!-- Sub-items -->
    <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>

When to use: Multi-level navigation menus (e.g., email categories, product categories)

Pattern 3: Custom Drawer with Header and Footer

<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><!-- Main content --></Grid>
    </syncfusion:SfNavigationDrawer.ContentView>
</syncfusion:SfNavigationDrawer>

When to use: Apps needing custom drawer layouts beyond built-in items

Pattern 4: Data Binding with ItemsSource

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

When to use: Dynamic navigation menus from database or API

Key Properties

Essential Properties

Display Mode Properties

Customization Properties

Animation Properties

Template Properties

Common Use Cases

Use Case 1: Email Client Navigation

Scenario: Multi-level inbox with Primary, Social, Promotions Solution: Use hierarchical NavigationItem with IsExpanded, Compact/Expanded modes Reference: references/populating-data.md

Use Case 2: Admin Dashboard

Scenario: Top-level menu (Dashboard, Users, Settings) with sub-sections Solution: Data binding with ItemsSource, hierarchical data structure Reference: references/populating-data.md

Use Case 3: Mobile-Style App

Scenario: Hamburger menu that slides over content Solution: Default mode with DrawerHeaderView, swipe gestures enabled Reference: references/custom-views.md

Use Case 4: Responsive Desktop App

Scenario: Auto-collapse to compact mode on narrow windows Solution: Expanded mode with AutoChangeDisplayMode=true Reference: references/display-modes.md

Use Case 5: Banking App

Scenario: Accounts, Transfers, Payments with event handling Solution: ItemClicked event, Command binding for navigation Reference: references/commands-and-events.md

Implementation Tips

1. Choose the Right Display Mode:

- Use Default for mobile-style overlays with custom views - Use Compact for icon-only sidebar that expands to full width - Use Expanded for always-visible full sidebar

1. Use Built-in Items vs Custom Views:

- Use NavigationItem (Compact/Expanded) for standard navigation menus - Use Custom Views (Default mode) for unique layouts

1. Optimize Performance:

- Use data binding with ItemsSource for large datasets - Implement ItemTemplateSelector for heterogeneous items - Keep hierarchies shallow (2-3 levels max)

1. Handle State Properly:

- Use Opening/Closing events to cancel state changes - Store SelectedItem for navigation state restoration - Handle ItemClicked for page navigation

1. Ensure Accessibility:

- Implement keyboard navigation (already built-in) - Provide meaningful Header text for screen readers - Use sufficient color contrast for SelectionBackground