syncfusion-winforms-navigation-drawer

Windows Forms 导航抽屉

Syncfusion Windows Forms Navigation Drawer 是一种滑动面板菜单，可从窗口边缘滑出，让内容显示在隐藏面板中。你可以从屏幕的任意一条边缘滑动来显示它，也可以根据需要以编程方式打开。

何时使用此技能

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

• 实现从屏幕边缘滑出的面板菜单（左侧、右侧、顶部或底部）
• 创建汉堡菜单导航，并使用可折叠的侧边栏面板
• 构建隐藏面板，使其通过流畅的动画滑入
• 为 Windows Forms 应用程序添加基于抽屉的导航
• 配置过渡效果（SlideOnTop、Push、Reveal）
• 使用内置的 Office 2016 主题自定义抽屉外观
• 处理抽屉事件（Opening、Closing、Opened、Closed）
• 通过编程或用户交互切换抽屉的可见性
• 将导航面板放置在不同的屏幕边缘，并配置动画

组件概述

主要功能：

• 四种位置选项： Left、Right、Top、Bottom
• 三种过渡类型： SlideOnTop、Push、Reveal
• 内置主题： Default、Office2016Colorful、Office2016White、Office2016DarkGray、Office2016Black
• 抽屉事件： Opening、Closing、Opened、Closed
• 可配置动画时长
• 用于编程控制的抽屉切换方法
• 支持图像的标题和菜单项

文档和导航指南

入门

📄 阅读： references/getting-started.md

在需要以下操作时阅读此参考文档：

• 通过 NuGet 或设计器安装 NavigationDrawer 控件
• 将控件添加到 Windows Forms 项目
• 以编程方式创建 NavigationDrawer 实例
• 添加标题（DrawerHeader）和菜单项（DrawerMenuItem）
• 设置基本抽屉尺寸（DrawerWidth、DrawerHeight）
• 为菜单项添加图像
• 配置文本和图像的位置（TextAlign、TextImageRelation）
• 了解侧边栏的基本放置方式

抽屉功能和配置

📄 阅读： references/drawer-features.md

在需要以下操作时阅读此参考文档：

• 配置 ContentView（主视图内容）
• 了解 DrawerView 结构
• 实现过渡类型（SlideOnTop、Push、Reveal）
• 设置抽屉位置（Left、Right、Top、Bottom）
• 配置抽屉尺寸和动画时长
• 使用 ToggleDrawer 方法进行编程控制
• 了解不同过渡效果之间的区别

自定义和样式设置

📄 阅读： references/customization.md

在需要以下操作时阅读此参考文档：

• 应用内置主题（Default、Office2016Colorful、Office2016White、Office2016DarkGray、Office2016Black）
• 自定义抽屉项颜色（DefaultColor、BackColor、HoverColor）
• 使用自定义颜色设置菜单项样式
• 在整个应用程序中应用一致的视觉主题

事件

📄 阅读： references/events.md

在需要以下操作时阅读此参考文档：

• 处理 Opening 事件（展开过渡开始时）
• 处理 Closing 事件（折叠过渡开始时）
• 处理 Opened 事件（展开过渡结束时）
• 处理 Closed 事件（折叠过渡结束时）
• 响应抽屉状态变化
• 取消抽屉操作
• 在过渡期间实现自定义逻辑

高级用法

📄 阅读： references/advanced-usage.md

在需要以下操作时阅读此参考文档：

• 使用复杂控件配置 ContentViewContainer
• 在 ContentView 中集成 RichTextBox 或其他控件
• 管理动态添加或移除项
• 实现复杂的项层级结构
• 优化大型菜单的性能
• 遵循抽屉实现的最佳实践

快速入门

基本导航抽屉

using Syncfusion.Windows.Forms.Tools;

// Create NavigationDrawer instance
NavigationDrawer navigationDrawer1 = new NavigationDrawer();
this.Controls.Add(navigationDrawer1);

// Set drawer dimensions
navigationDrawer1.DrawerWidth = this.Width / 4;
navigationDrawer1.DrawerHeight = this.Height;

// Set position and transition
navigationDrawer1.Position = SlidePosition.Left;
navigationDrawer1.Transition = Transition.SlideOnTop;

// Add header
DrawerHeader drawerHeader1 = new DrawerHeader();
drawerHeader1.Text = "Menu";
navigationDrawer1.Items.Add(drawerHeader1);

// Add menu items
DrawerMenuItem menuItem1 = new DrawerMenuItem();
menuItem1.Text = "Home";
menuItem1.Image = Image.FromFile(@"home.png");

DrawerMenuItem menuItem2 = new DrawerMenuItem();
menuItem2.Text = "Settings";
menuItem2.Image = Image.FromFile(@"settings.png");

navigationDrawer1.Items.Add(menuItem1);
navigationDrawer1.Items.Add(menuItem2);

// Add content to ContentView
RichTextBox richTextBox = new RichTextBox();
richTextBox.Text = "Main content area";
navigationDrawer1.ContentViewContainer.Controls.Add(richTextBox);

常见模式

模式 1：使用 Push 过渡效果的左侧滑动面板

// Create drawer that pushes content when opened
NavigationDrawer drawer = new NavigationDrawer();
drawer.Position = SlidePosition.Left;
drawer.Transition = Transition.Push;
drawer.DrawerWidth = 250;
drawer.DrawerHeight = this.Height;
drawer.AnimationDuration = 150; // milliseconds

this.Controls.Add(drawer);

模式 2：通过按钮单击切换抽屉

// Toggle drawer visibility on button click
private void hamburgerButton_Click(object sender, EventArgs e)
{
    navigationDrawer1.ToggleDrawer();
}

模式 3：带自定义颜色的主题抽屉

// Apply Office 2016 theme with custom item colors
navigationDrawer1.Style = NavigationDrawerStyle.Office2016Colorful;

// Customize menu item colors
drawerMenuItem1.DefaultColor = System.Drawing.Color.LightBlue;
drawerMenuItem1.HoverColor = System.Drawing.Color.SkyBlue;
drawerMenuItem1.BackColor = System.Drawing.Color.LightBlue;

模式 4：处理抽屉事件

// Subscribe to drawer events
navigationDrawer1.Opening += NavigationDrawer1_Opening;
navigationDrawer1.Opened += NavigationDrawer1_Opened;
navigationDrawer1.Closing += NavigationDrawer1_Closing;
navigationDrawer1.Closed += NavigationDrawer1_Closed;

private void NavigationDrawer1_Opening(object sender, OpeningEventArgs e)
{
    // Logic when drawer starts opening
    Console.WriteLine("Drawer is opening...");
}

private void NavigationDrawer1_Opened(object sender, EventArgs e)
{
    // Logic when drawer is fully open
    Console.WriteLine("Drawer opened");
}

private void NavigationDrawer1_Closing(object sender, CancelEventArgs e)
{
    // Can cancel closing if needed
    // e.Cancel = true;
    Console.WriteLine("Drawer is closing...");
}

private void NavigationDrawer1_Closed(object sender, EventArgs e)
{
    // Logic when drawer is fully closed
    Console.WriteLine("Drawer closed");
}

模式 5：带 Reveal 过渡效果的右侧抽屉

// Create drawer that reveals from behind content
NavigationDrawer drawer = new NavigationDrawer();
drawer.Position = SlidePosition.Right;
drawer.Transition = Transition.Reveal;
drawer.DrawerWidth = 300;
drawer.AnimationDuration = 200;

// Add items
DrawerHeader header = new DrawerHeader { Text = "Options" };
drawer.Items.Add(header);

string[] menuItems = { "Profile", "Settings", "Notifications", "Help" };
foreach (string item in menuItems)
{
    DrawerMenuItem menuItem = new DrawerMenuItem { Text = item };
    drawer.Items.Add(menuItem);
}

this.Controls.Add(drawer);

主要属性

属性	类型	说明
Position	SlidePosition	抽屉滑出位置：Left、Right、Top、Bottom
Transition	Transition	动画类型：SlideOnTop、Push、Reveal
DrawerWidth	int	抽屉面板的宽度
DrawerHeight	int	抽屉面板的高度
AnimationDuration	int	抽屉动画的持续时间，单位为毫秒
Style	NavigationDrawerStyle	视觉主题：Default、Office2016Colorful 等
Items	Collection	DrawerHeader 和 DrawerMenuItem 对象的集合
ContentViewContainer	Control	主内容区域控件的容器

主要方法

方法	说明
ToggleDrawer()	切换抽屉的显示状态（打开 ↔ 关闭）

主要事件

事件	说明
Opening	展开过渡开始时触发
Opened	展开过渡结束时触发
Closing	折叠过渡开始时触发（可取消）
Closed	折叠过渡结束时触发