syncfusion-winforms-navigation-view

在 Windows Forms 中实现导航视图

何时使用此技能

在以下情况下使用 NavigationView 控件：

• 面包屑导航： 显示分层位置路径（例如，MyComputer > C: > Program Files > App）
• 文件浏览器界面： 跟踪并浏览文件夹层级结构，例如 Windows 资源管理器
• 位置跟踪： 让用户了解自己在多层结构中的当前位置
• 快速导航： 允许用户返回上级位置，或通过下拉菜单进行导航
• 设置/配置向导： 显示用户在嵌套类别中的进度
• 文档管理： 浏览文档文件夹、类别或组织结构

主要功能： 与传统菜单或树形视图不同，NavigationView 会显示当前路径，并可通过下拉菜单访问每个层级的同级项。

组件概述

NavigationView 控件提供面包屑样式的导航界面，使用 Bar（节点）显示分层路径。路径中的每个 Bar 都会显示一个向前箭头，单击后会展开其正下方子 Bar 的下拉列表。

核心概念：

• Bar： 导航层级中的单个节点（例如，“MyComputer”、“C:”、“Users”）
• 父 Bar： 包含子 Bar 的 Bar（根级或中间级）
• 子 Bar： 嵌套在父 Bar 中的 Bar
• 选定的 Bar： 当前处于活动状态并显示在路径中的 Bar
• 历史记录： 跟踪之前访问过的 Bar，以便快速返回导航

视觉结构：

[Icon] MyComputer > C: > Program Files > App   [History ▼]
       └─────┬─────┘
              └─ Click arrow to see child Bars dropdown

文档与导航指南

入门

📄 阅读： references/getting-started.md

在以下情况下，请阅读此参考文档：

• 为 NavigationView 安装程序集或 NuGet 包
• 通过设计器或代码向窗体添加控件
• 了解所需的命名空间（Syncfusion.Windows.Forms.Tools）
• 使用最少配置设置基本的 NavigationView
• 查看完整的最简可运行示例

主要主题：

• 程序集部署（需要 6 个 DLL）
• 通过设计器拖放添加控件
• 使用代码手动添加控件
• 创建第一个 NavigationView 实例
• 基本设置和初始化

---

Bar 层级结构

📄 阅读： references/bar-hierarchy.md

在以下情况下，请阅读此参考文档：

• 创建父 Bar 与子 Bar 之间的关系
• 构建多层导航层级
• 向 NavigationView.Bars 集合添加 Bar
• 向父 Bar 的 Bars 集合添加子 Bar
• 设置选定的 Bar 以显示特定路径
• 了解 Bar 属性（Text、ImageIndex）

主要主题：

• 创建 Bar 实例
• 父 Bar 与子 Bar 的关系
• 向 NavigationView 添加根 Bar
• 向父 Bar 添加子 Bar
• 设置 SelectedBar 属性
• 以编程方式在 Bar 之间导航

---

下拉选择与历史记录

📄 阅读： references/dropdown-and-history.md

在以下情况下，请阅读此参考文档：

• 实现子 Bar 导航的下拉选择
• 启用/禁用历史记录按钮跟踪
• 在历史记录下拉菜单中显示之前访问过的位置
• 向 NavigationView 添加自定义按钮
• 配置自定义按钮的外观和图像
• 处理 BarPopup 事件以自定义下拉菜单
• 控制弹出菜单中显示的最大项目数

主要主题：

• 向前箭头下拉机制
• ShowHistoryButtons 属性
• 历史记录跟踪与下拉菜单
• 自定义按钮集合
• 添加自定义按钮（设计器和代码）
• 处理 BarPopup 事件
• 可自定义的弹出菜单项目数

---

图像和视觉样式

📄 阅读： references/images-and-styling.md

在以下情况下，请阅读此参考文档：

• 使用 ImageList 为 Bar 添加图标
• 设置父级和子级 Bar 的 ImageIndex
• 应用视觉样式（Office2007、Vista、Metro）
• 配置 VisualStyle 属性
• 自定义控件外观
• 匹配应用程序主题或样式

主要主题：

• ImageList 的设置和分配
• 设置 Bar 的 ImageIndex 属性
• 视觉样式概述
• 应用 Office2007 样式
• 应用 Vista 样式
• 应用 Metro 样式
• 外观自定义

---

高级功能

📄 阅读： references/advanced-features.md

在以下情况下，请阅读此参考文档：

• 启用编辑模式以直接输入路径
• 允许用户输入导航路径
• 使用 BarPopup 事件控制弹出行为
• 设置弹出窗口中显示的最大项目数
• 有条件地取消弹出窗口显示
• 实现高级导航场景

主要主题：

• 启用和使用编辑模式
• 直接在 NavigationView 中输入路径
• BarPopup 事件的高级用法
• MaximumItemsToDisplay 属性
• 弹出窗口取消逻辑
• 快速导航技巧

---

快速入门示例

以下是创建包含三级层级结构的 NavigationView 的最简示例：

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);

结果： 面包屑导航显示“MyComputer”，并可通过下拉菜单访问“C:”和“D:”。

常见模式

文件系统导航模式

模拟 Windows 资源管理器的文件夹导航：

// 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;

根据数据动态创建 Bar

从数据源填充 NavigationView：

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);

带历史记录的导航

允许用户跟踪并返回之前的位置：

// 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);
}

自定义导航按钮

向 NavigationView 添加搜索或刷新按钮：

// 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);

关键属性和事件

基本属性

属性	类型	说明
Bars	BarCollection	根级 Bar 的集合
SelectedBar	Bar	路径中当前显示的 Bar
ShowHistoryButtons	bool	显示/隐藏历史记录下拉按钮
VisualStyle	VisualStyles	应用 Office2007、Vista 或 Metro 样式
ImageList	ImageList	Bar 图标的图像集合

Bar 属性

属性	类型	说明
Text	string	Bar 的显示文本
ImageIndex	int	NavigationView.ImageList 中的索引
Bars	BarCollection	此 Bar 的子级 Bar
Tag	object	存储自定义数据（例如完整路径）

重要事件

事件	说明	常见用途
BarSelected	用户选择 Bar 时触发	加载所选位置的内容
BarPopup	下拉菜单显示前触发	自定义弹出菜单项、设置最大项目数
Click	用户单击控件时触发	处理常规交互

常见用例

用例 1：带编辑模式的文件资源管理器

允许用户通过可视方式浏览文件夹或直接输入路径：

// 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);
    }
};

用例 2：设置导航

引导用户浏览嵌套的设置类别：

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;

用例 3：文档管理系统

使用自定义图标浏览文档类别：

// 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);

用例 4：限制大型层级结构中的弹出项目数

控制包含许多子文件夹的文件夹的下拉菜单大小：

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;
    }
};

故障排除提示

问题： NavigationView 中未显示栏

• 解决方案： 确保将栏添加到 navigationView1.Bars 集合中，而不只是创建栏
• 检查： 验证是否设置了 SelectedBar，以显示栏

问题： 图片未显示

• 解决方案： 将 ImageList 分配给 NavigationView，然后在栏上设置 ImageIndex
• 检查： 确保 ImageIndex 值在 ImageList 范围内

问题： 下拉菜单中未显示子栏

• 解决方案： 将子栏添加到父栏的 Bars 集合中：parentBar.Bars.Add(childBar)
• 检查： 验证父栏是否确实包含子栏

问题： 历史记录按钮不可见

• 解决方案： 设置 navigationView1.ShowHistoryButtons = true

问题： 未应用视觉样式

• 解决方案： 在控件初始化后设置 VisualStyle 属性
• 示例： navigationView1.VisualStyle = VisualStyles.Office2007;

后续步骤

1. 从入门指南开始： 阅读 references/getting-started.md，设置控件
2. 构建层级结构： 阅读 references/bar-hierarchy.md，创建栏结构
3. 添加功能： 阅读其余参考文档，添加下拉菜单、历史记录、图片和高级功能
4. 自定义外观： 应用视觉样式，使其与应用程序主题相匹配
5. 处理事件： 连接 BarSelected 和其他事件，以响应用户导航

如需了解完整的实现细节，请按上述顺序阅读参考指南。