syncfusion-winforms-navigation-view
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Navigation Views in Windows Forms
在Windows Forms中实现导航视图
When to Use This Skill
何时使用该技能
Use the NavigationView control when you need:
- Breadcrumb Navigation: Display hierarchical location paths (e.g., )
MyComputer > C: > Program Files > App - File Browser Interfaces: Track and navigate folder hierarchies like Windows Explorer
- Location Tracking: Keep users aware of their current position in multi-level structures
- Quick Navigation: Allow users to jump back to parent locations or navigate via dropdown
- Settings/Configuration Wizards: Show user's progress through nested categories
- Document Management: Navigate document folders, categories, or organizational structures
Key Feature: Unlike traditional menus or tree views, NavigationView shows the current path with dropdown access to siblings at each level.
当你需要满足以下需求时可以使用NavigationView控件:
- 面包屑导航: 展示层级位置路径(例如 )
我的电脑 > C盘 > 程序文件 > 应用 - 文件浏览器界面: 跟踪并导航文件夹层级,就像Windows资源管理器一样
- 位置跟踪: 让用户清楚自己在多层级结构中的当前位置
- 快速导航: 允许用户一键跳转回父级位置,或者通过下拉菜单导航
- 设置/配置向导: 展示用户在嵌套类别中的完成进度
- 文档管理: 导航文档文件夹、分类或者组织结构
核心特性: 和传统菜单或者树视图不同,NavigationView会展示当前路径,并且每个层级都支持下拉访问同级节点。
Component Overview
组件概述
The control provides a breadcrumb-style navigation interface that displays a hierarchical path using Bars (nodes). Each Bar in the path shows a forward arrow that, when clicked, reveals a dropdown list of child Bars directly below it.
NavigationViewCore Concepts:
- Bar: A single node in the navigation hierarchy (e.g., "MyComputer", "C:", "Users")
- Parent Bar: A Bar that contains child Bars (root level or intermediate)
- Child Bar: A Bar nested within a parent Bar
- Selected Bar: The currently active Bar displayed in the path
- History: Tracks previously visited Bars for quick return navigation
Visual Structure:
[Icon] MyComputer > C: > Program Files > App [History ▼]
└─────┬─────┘
└─ Click arrow to see child Bars dropdownNavigationView核心概念:
- Bar: 导航层级中的单个节点(例如 "我的电脑"、"C:"、"用户")
- 父Bar: 包含子Bar的Bar(根层级或者中间层级)
- 子Bar: 嵌套在父Bar中的Bar
- 选中Bar: 路径中当前激活的Bar
- 历史记录: 跟踪之前访问过的Bar,支持快速返回导航
视觉结构:
[图标] 我的电脑 > C: > 程序文件 > 应用 [历史记录 ▼]
└─────┬─────┘
└─ 点击箭头查看子Bar下拉列表Documentation and Navigation Guide
文档和导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
Read this reference when you need to:
- Install assemblies or NuGet packages for NavigationView
- Add the control to a form via designer or code
- Understand required namespaces ()
Syncfusion.Windows.Forms.Tools - Set up a basic NavigationView with minimal configuration
- See a complete minimal working example
Key Topics:
- Assembly deployment (6 required DLLs)
- Adding control via designer drag-and-drop
- Adding control manually using code
- Creating the first NavigationView instance
- Basic setup and initialization
📄 阅读: references/getting-started.md
当你需要完成以下操作时阅读该参考文档:
- 安装NavigationView所需的程序集或者NuGet包
- 通过设计器或者代码将控件添加到窗体中
- 了解所需的命名空间()
Syncfusion.Windows.Forms.Tools - 用最少的配置搭建基础的NavigationView
- 查看完整的最小可运行示例
核心主题:
- 程序集部署(6个必需的DLL)
- 通过设计器拖放添加控件
- 通过代码手动添加控件
- 创建第一个NavigationView实例
- 基础设置和初始化
Bar Hierarchy and Structure
Bar层级和结构
📄 Read: references/bar-hierarchy.md
Read this reference when you need to:
- Create parent and child Bar relationships
- Build multi-level navigation hierarchies
- Add Bars to the NavigationView.Bars collection
- Add child Bars to a parent Bar's Bars collection
- Set the selected Bar to display a specific path
- Understand Bar properties (Text, ImageIndex)
Key Topics:
- Creating Bar instances
- Parent-child Bar relationships
- Adding root Bars to NavigationView
- Adding child Bars to parent Bars
- Setting SelectedBar property
- Navigating between Bars programmatically
📄 阅读: references/bar-hierarchy.md
当你需要完成以下操作时阅读该参考文档:
- 创建父子Bar关系
- 构建多层级导航结构
- 向NavigationView.Bars集合添加Bar
- 向父Bar的Bars集合添加子Bar
- 设置选中Bar以展示特定路径
- 了解Bar的属性(Text、ImageIndex)
核心主题:
- 创建Bar实例
- 父子Bar关系
- 向NavigationView添加根Bar
- 向父Bar添加子Bar
- 设置SelectedBar属性
- 通过代码在Bar之间导航
Dropdown Selection and History
下拉选择和历史记录
📄 Read: references/dropdown-and-history.md
Read this reference when you need to:
- Implement dropdown selection for child Bar navigation
- Enable/disable history button tracking
- Show previously visited locations in history dropdown
- Add custom buttons to the NavigationView
- Configure custom button appearance and images
- Handle BarPopup event for dropdown customization
- Control maximum items displayed in popups
Key Topics:
- Forward arrow dropdown mechanism
- ShowHistoryButtons property
- History tracking and dropdown
- Custom button collection
- Adding custom buttons (designer and code)
- BarPopup event handling
- Customizable popup item count
📄 阅读: references/dropdown-and-history.md
当你需要完成以下操作时阅读该参考文档:
- 实现子Bar导航的下拉选择功能
- 启用/禁用历史记录按钮跟踪
- 在历史记录下拉列表中展示之前访问过的位置
- 向NavigationView添加自定义按钮
- 配置自定义按钮的外观和图标
- 处理BarPopup事件实现下拉自定义
- 控制弹窗中显示的最大条目数
核心主题:
- 前进箭头下拉机制
- ShowHistoryButtons属性
- 历史记录跟踪和下拉列表
- 自定义按钮集合
- 添加自定义按钮(设计器和代码)
- BarPopup事件处理
- 可自定义的弹窗条目数量
Images and Visual Styling
图标和视觉样式
📄 Read: references/images-and-styling.md
Read this reference when you need to:
- Add icons to Bars using ImageList
- Set ImageIndex for parent and child Bars
- Apply visual styles (Office2007, Vista, Metro)
- Configure VisualStyle property
- Customize control appearance
- Match application theme or style
Key Topics:
- ImageList setup and assignment
- Setting Bar ImageIndex properties
- Visual styles overview
- Applying Office2007 style
- Applying Vista style
- Applying Metro style
- Appearance customization
📄 阅读: references/images-and-styling.md
当你需要完成以下操作时阅读该参考文档:
- 使用ImageList为Bar添加图标
- 为父子Bar设置ImageIndex
- 应用视觉样式(Office2007、Vista、Metro)
- 配置VisualStyle属性
- 自定义控件外观
- 匹配应用主题或者样式
核心主题:
- ImageList设置和赋值
- 设置Bar的ImageIndex属性
- 视觉样式概述
- 应用Office2007样式
- 应用Vista样式
- 应用Metro样式
- 外观自定义
Advanced Features
高级特性
📄 Read: references/advanced-features.md
Read this reference when you need to:
- Enable edit mode for direct path typing
- Allow users to type navigation paths
- Control popup behavior with BarPopup event
- Set maximum items to display in popups
- Cancel popup display conditionally
- Implement advanced navigation scenarios
Key Topics:
- Edit mode enabling and usage
- Typing paths directly into NavigationView
- BarPopup event advanced usage
- MaximumItemsToDisplay property
- Popup cancellation logic
- Quick navigation techniques
📄 阅读: references/advanced-features.md
当你需要完成以下操作时阅读该参考文档:
- 启用编辑模式支持直接输入路径
- 允许用户输入导航路径
- 通过BarPopup事件控制弹窗行为
- 设置弹窗中显示的最大条目数
- 有条件地取消弹窗展示
- 实现高级导航场景
核心主题:
- 编辑模式启用和使用
- 直接在NavigationView中输入路径
- BarPopup事件高级用法
- MaximumItemsToDisplay属性
- 弹窗取消逻辑
- 快速导航技巧
Quick Start Example
快速入门示例
Here's a minimal example of creating a NavigationView with a three-level hierarchy:
csharp
using Syncfusion.Windows.Forms.Tools;
using Syncfusion.Windows.Forms.Tools.Navigation;
// Create NavigationView
NavigationView navigationView1 = new NavigationView();
navigationView1.Width = 400;
navigationView1.Height = 25;
navigationView1.Location = new System.Drawing.Point(20, 20);
// Create root Bar
Bar rootBar = new Bar();
rootBar.Text = "MyComputer";
// Create child Bars
Bar driveC = new Bar();
driveC.Text = "Local Disk (C:)";
Bar driveD = new Bar();
driveD.Text = "Local Disk (D:)";
Bar programFiles = new Bar();
programFiles.Text = "Program Files";
// Build hierarchy
rootBar.Bars.AddRange(new Bar[] { driveC, driveD });
driveC.Bars.Add(programFiles);
// Add root to NavigationView
navigationView1.Bars.Add(rootBar);
// Set initial selection
navigationView1.SelectedBar = rootBar;
// Add to form
this.Controls.Add(navigationView1);Result: A breadcrumb navigation showing "MyComputer" with dropdown access to "C:" and "D:".
以下是创建三级层级NavigationView的最小示例:
csharp
using Syncfusion.Windows.Forms.Tools;
using Syncfusion.Windows.Forms.Tools.Navigation;
// 创建NavigationView
NavigationView navigationView1 = new NavigationView();
navigationView1.Width = 400;
navigationView1.Height = 25;
navigationView1.Location = new System.Drawing.Point(20, 20);
// 创建根Bar
Bar rootBar = new Bar();
rootBar.Text = "MyComputer";
// 创建子Bar
Bar driveC = new Bar();
driveC.Text = "Local Disk (C:)";
Bar driveD = new Bar();
driveD.Text = "Local Disk (D:)";
Bar programFiles = new Bar();
programFiles.Text = "Program Files";
// 构建层级
rootBar.Bars.AddRange(new Bar[] { driveC, driveD });
driveC.Bars.Add(programFiles);
// 向NavigationView添加根节点
navigationView1.Bars.Add(rootBar);
// 设置初始选中项
navigationView1.SelectedBar = rootBar;
// 添加到窗体
this.Controls.Add(navigationView1);效果: 展示"MyComputer"的面包屑导航,支持下拉访问"C:"和"D:"。
Common Patterns
常见模式
File System Navigation Pattern
文件系统导航模式
Mimic Windows Explorer folder navigation:
csharp
// Root = Computer
Bar computer = new Bar { Text = "This PC" };
// Drives
Bar cDrive = new Bar { Text = "Local Disk (C:)" };
Bar dDrive = new Bar { Text = "Local Disk (D:)" };
// Common folders
Bar users = new Bar { Text = "Users" };
Bar documents = new Bar { Text = "Documents" };
Bar downloads = new Bar { Text = "Downloads" };
// Build hierarchy
computer.Bars.AddRange(new Bar[] { cDrive, dDrive });
cDrive.Bars.Add(users);
users.Bars.AddRange(new Bar[] { documents, downloads });
navigationView1.Bars.Add(computer);
navigationView1.SelectedBar = computer;模拟Windows资源管理器文件夹导航:
csharp
// 根节点 = 计算机
Bar computer = new Bar { Text = "This PC" };
// 磁盘
Bar cDrive = new Bar { Text = "Local Disk (C:)" };
Bar dDrive = new Bar { Text = "Local Disk (D:)" };
// 常用文件夹
Bar users = new Bar { Text = "Users" };
Bar documents = new Bar { Text = "Documents" };
Bar downloads = new Bar { Text = "Downloads" };
// 构建层级
computer.Bars.AddRange(new Bar[] { cDrive, dDrive });
cDrive.Bars.Add(users);
users.Bars.AddRange(new Bar[] { documents, downloads });
navigationView1.Bars.Add(computer);
navigationView1.SelectedBar = computer;Dynamic Bar Creation Based on Data
基于数据动态创建Bar
Populate NavigationView from data source:
csharp
public void LoadFoldersFromPath(string rootPath, Bar parentBar)
{
try
{
var directories = Directory.GetDirectories(rootPath);
foreach (var dir in directories)
{
Bar childBar = new Bar();
childBar.Text = Path.GetFileName(dir);
childBar.Tag = dir; // Store full path
parentBar.Bars.Add(childBar);
// Optionally load sub-folders
// LoadFoldersFromPath(dir, childBar);
}
}
catch (UnauthorizedAccessException)
{
// Handle permission errors
}
}
// Usage
Bar rootBar = new Bar { Text = "C:", Tag = @"C:\" };
LoadFoldersFromPath(@"C:\", rootBar);
navigationView1.Bars.Add(rootBar);从数据源填充NavigationView:
csharp
public void LoadFoldersFromPath(string rootPath, Bar parentBar)
{
try
{
var directories = Directory.GetDirectories(rootPath);
foreach (var dir in directories)
{
Bar childBar = new Bar();
childBar.Text = Path.GetFileName(dir);
childBar.Tag = dir; // 存储完整路径
parentBar.Bars.Add(childBar);
// 可选:加载子文件夹
// LoadFoldersFromPath(dir, childBar);
}
}
catch (UnauthorizedAccessException)
{
// 处理权限错误
}
}
// 使用示例
Bar rootBar = new Bar { Text = "C:", Tag = @"C:\" };
LoadFoldersFromPath(@"C:\", rootBar);
navigationView1.Bars.Add(rootBar);Navigation with History Tracking
带历史记录跟踪的导航
Enable users to track and return to previous locations:
csharp
// Enable history button
navigationView1.ShowHistoryButtons = true;
// Handle BarSelected event to track navigation
navigationView1.BarSelected += (sender, e) =>
{
string currentPath = GetFullPath(navigationView1.SelectedBar);
Console.WriteLine($"Navigated to: {currentPath}");
// Update UI based on selection
LoadContent(currentPath);
};
// Helper to build full path
private string GetFullPath(Bar bar)
{
List<string> path = new List<string>();
Bar current = bar;
while (current != null)
{
path.Insert(0, current.Text);
current = current.Parent as Bar;
}
return string.Join(" > ", path);
}支持用户跟踪并返回之前的位置:
csharp
// 启用历史记录按钮
navigationView1.ShowHistoryButtons = true;
// 处理BarSelected事件跟踪导航
navigationView1.BarSelected += (sender, e) =>
{
string currentPath = GetFullPath(navigationView1.SelectedBar);
Console.WriteLine($"Navigated to: {currentPath}");
// 根据选中项更新UI
LoadContent(currentPath);
};
// 构建完整路径的辅助方法
private string GetFullPath(Bar bar)
{
List<string> path = new List<string>();
Bar current = bar;
while (current != null)
{
path.Insert(0, current.Text);
current = current.Parent as Bar;
}
return string.Join(" > ", path);
}Custom Navigation Buttons
自定义导航按钮
Add search or refresh buttons to NavigationView:
csharp
// Create custom search button
CustomButton searchButton = new CustomButton();
searchButton.Name = "searchButton";
searchButton.Image = Properties.Resources.SearchIcon; // Your icon
searchButton.Appearance = ButtonAppearance.Office2007;
// Handle click
searchButton.Click += (sender, e) =>
{
// Show search dialog or panel
ShowSearchPanel();
};
// Add to NavigationView
navigationView1.Controls.Add(searchButton);向NavigationView添加搜索或者刷新按钮:
csharp
// 创建自定义搜索按钮
CustomButton searchButton = new CustomButton();
searchButton.Name = "searchButton";
searchButton.Image = Properties.Resources.SearchIcon; // 你的图标
searchButton.Appearance = ButtonAppearance.Office2007;
// 处理点击事件
searchButton.Click += (sender, e) =>
{
// 展示搜索对话框或者面板
ShowSearchPanel();
};
// 添加到NavigationView
navigationView1.Controls.Add(searchButton);Key Properties and Events
核心属性和事件
Essential Properties
基础属性
| Property | Type | Description |
|---|---|---|
| | Collection of root-level Bars |
| | Currently displayed Bar in the path |
| | Show/hide history dropdown button |
| | Apply Office2007, Vista, or Metro styling |
| | Image collection for Bar icons |
| 属性 | 类型 | 描述 |
|---|---|---|
| | 根层级Bar的集合 |
| | 路径中当前展示的Bar |
| | 展示/隐藏历史记录下拉按钮 |
| | 应用Office2007、Vista或者Metro样式 |
| | Bar图标的图片集合 |
Bar Properties
Bar属性
| Property | Type | Description |
|---|---|---|
| | Display text for the Bar |
| | Index in NavigationView.ImageList |
| | Child Bars of this Bar |
| | Store custom data (e.g., full path) |
| 属性 | 类型 | 描述 |
|---|---|---|
| | Bar的展示文本 |
| | 在NavigationView.ImageList中的索引 |
| | 当前Bar的子Bar集合 |
| | 存储自定义数据(例如完整路径) |
Important Events
重要事件
| Event | Description | Common Use |
|---|---|---|
| Fires when user selects a Bar | Load content for selected location |
| Fires before dropdown shows | Customize popup items, set max items |
| User clicks the control | Handle general interaction |
| 事件 | 描述 | 常见用途 |
|---|---|---|
| 用户选择Bar时触发 | 加载选中位置对应的内容 |
| 下拉列表展示前触发 | 自定义下拉条目、设置最大条目数 |
| 用户点击控件时触发 | 处理通用交互 |
Common Use Cases
常见使用场景
Use Case 1: File Explorer with Edit Mode
场景1:带编辑模式的文件资源管理器
Allow users to navigate folders visually or type paths directly:
csharp
// Enable edit mode
navigationView1.AllowEdit = true; // If property exists
// Handle path changes
navigationView1.BarSelected += (sender, e) =>
{
if (navigationView1.SelectedBar.Tag is string path)
{
LoadDirectoryContents(path);
}
};允许用户通过可视化方式导航文件夹,或者直接输入路径:
csharp
// 启用编辑模式
navigationView1.AllowEdit = true; // 如该属性存在
// 处理路径变更
navigationView1.BarSelected += (sender, e) =>
{
if (navigationView1.SelectedBar.Tag is string path)
{
LoadDirectoryContents(path);
}
};Use Case 2: Settings Navigation
场景2:设置导航
Guide users through nested settings categories:
csharp
Bar settings = new Bar { Text = "Settings" };
Bar appearance = new Bar { Text = "Appearance" };
Bar colors = new Bar { Text = "Colors" };
Bar fonts = new Bar { Text = "Fonts" };
settings.Bars.Add(appearance);
appearance.Bars.AddRange(new Bar[] { colors, fonts });
navigationView1.Bars.Add(settings);
navigationView1.SelectedBar = settings;引导用户浏览嵌套的设置分类:
csharp
Bar settings = new Bar { Text = "Settings" };
Bar appearance = new Bar { Text = "Appearance" };
Bar colors = new Bar { Text = "Colors" };
Bar fonts = new Bar { Text = "Fonts" };
settings.Bars.Add(appearance);
appearance.Bars.AddRange(new Bar[] { colors, fonts });
navigationView1.Bars.Add(settings);
navigationView1.SelectedBar = settings;Use Case 3: Document Management System
场景3:文档管理系统
Navigate document categories with custom icons:
csharp
// Setup ImageList
ImageList imgList = new ImageList();
imgList.Images.Add("folder", Properties.Resources.FolderIcon);
imgList.Images.Add("doc", Properties.Resources.DocumentIcon);
navigationView1.ImageList = imgList;
// Create hierarchy with images
Bar root = new Bar { Text = "Documents", ImageIndex = 0 };
Bar contracts = new Bar { Text = "Contracts", ImageIndex = 0 };
Bar invoices = new Bar { Text = "Invoices", ImageIndex = 0 };
root.Bars.AddRange(new Bar[] { contracts, invoices });
navigationView1.Bars.Add(root);使用自定义图标导航文档分类:
csharp
// 设置ImageList
ImageList imgList = new ImageList();
imgList.Images.Add("folder", Properties.Resources.FolderIcon);
imgList.Images.Add("doc", Properties.Resources.DocumentIcon);
navigationView1.ImageList = imgList;
// 构建带图标的层级
Bar root = new Bar { Text = "Documents", ImageIndex = 0 };
Bar contracts = new Bar { Text = "Contracts", ImageIndex = 0 };
Bar invoices = new Bar { Text = "Invoices", ImageIndex = 0 };
root.Bars.AddRange(new Bar[] { contracts, invoices });
navigationView1.Bars.Add(root);Use Case 4: Limited Popup Items for Large Hierarchies
场景4:为大型层级限制弹窗条目
Control dropdown size for folders with many subfolders:
csharp
navigationView1.BarPopup += (sender, e) =>
{
// Limit items to 10 for better UX
e.MaximumItemsToDisplay = 10;
// Cancel popup for specific Bars
if (e.CurrentBar.Text == "EmptyFolder")
{
e.Cancel = true;
}
};为包含大量子文件夹的文件夹控制下拉大小:
csharp
navigationView1.BarPopup += (sender, e) =>
{
// 限制最多展示10条,提升用户体验
e.MaximumItemsToDisplay = 10;
// 为特定Bar取消弹窗
if (e.CurrentBar.Text == "EmptyFolder")
{
e.Cancel = true;
}
};Troubleshooting Tips
故障排查技巧
Issue: Bars not appearing in NavigationView
- Solution: Ensure Bars are added to collection, not just created
navigationView1.Bars - Check: Verify is set to make a Bar visible
SelectedBar
Issue: Images not displaying
- Solution: Assign to NavigationView, then set
ImageListon BarsImageIndex - Check: Ensure ImageIndex values are within ImageList bounds
Issue: Dropdown not showing child Bars
- Solution: Add child Bars to parent's collection:
BarsparentBar.Bars.Add(childBar) - Check: Verify parent Bar actually has children
Issue: History button not visible
- Solution: Set
navigationView1.ShowHistoryButtons = true
Issue: Visual style not applied
- Solution: Set property after control initialization
VisualStyle - Example:
navigationView1.VisualStyle = VisualStyles.Office2007;
问题: NavigationView中没有展示Bar
- 解决方案: 确保Bar已经添加到集合,而不仅仅是创建了实例
navigationView1.Bars - 检查: 确认已经设置让Bar可见
SelectedBar
问题: 图片没有展示
- 解决方案: 先为NavigationView赋值,再为Bar设置
ImageListImageIndex - 检查: 确认ImageIndex值在ImageList的有效范围内
问题: 下拉列表没有展示子Bar
- 解决方案: 将子Bar添加到父级的集合:
BarsparentBar.Bars.Add(childBar) - 检查: 确认父Bar确实包含子节点
问题: 历史记录按钮不可见
- 解决方案: 设置
navigationView1.ShowHistoryButtons = true
问题: 视觉样式没有生效
- 解决方案: 在控件初始化完成后设置属性
VisualStyle - 示例:
navigationView1.VisualStyle = VisualStyles.Office2007;
Next Steps
后续步骤
- Start with Getting Started: Read references/getting-started.md to set up the control
- Build Hierarchy: Read references/bar-hierarchy.md to create your Bar structure
- Add Features: Read remaining references to add dropdown, history, images, and advanced capabilities
- Customize Appearance: Apply visual styles to match your application theme
- Handle Events: Wire up and other events to respond to user navigation
BarSelected
For complete implementation details, proceed through the reference guides in the order listed above.
- 从入门指南开始: 阅读references/getting-started.md完成控件设置
- 构建层级结构: 阅读references/bar-hierarchy.md创建你的Bar结构
- 添加功能: 阅读剩余的参考文档,添加下拉、历史记录、图标和高级能力
- 自定义外观: 应用视觉样式匹配你的应用主题
- 处理事件: 绑定和其他事件响应用户导航操作
BarSelected
如需完整的实现细节,请按照上述列出的顺序依次阅读参考指南。