syncfusion-winforms-folder-browser

在 Windows Forms 中实现 FolderBrowser

Syncfusion FolderBrowser 控件为 Win32 Shell 文件夹浏览器 API 提供了封装，使开发者能够使用以 .NET 为中心的属性、事件和方法显示文件夹选择对话框。

何时使用此技能

在以下情况下使用此技能：

• 向用户显示文件夹选择对话框
• 允许用户浏览并选择目录路径
• 自定义对话框行为（限制为文件系统、显示计算机等）
• 通过回调验证处理文件夹选择
• 配置浏览起始位置
• 添加文件路径自动完成功能

组件概述

FolderBrowser 是一个基于对话框的组件，可以：

• 显示原生 Windows 文件夹选择对话框
• 封装复杂的 Win32 Shell API 交互
• 支持各种浏览样式和限制
• 提供用于验证的回调事件
• 支持自定义起始位置和路径选择
• 同时支持通过设计器和代码实现

主要功能

功能	用途
位置设置	配置浏览的起始位置（MyComputer、CustomStartLocation 等）
样式选项	控制对话框行为（RestrictToFilesystem、BrowseForComputer、ShowTextBox 等）
路径选择	自动滚动到并突出显示指定的文件夹路径
回调事件	在浏览过程中实时验证文件夹选择
文本自定义	设置对话框说明和状态消息
自动完成	启用带文件夹路径建议的文本框

快速入门示例

// Create and display a basic folder browser dialog
FolderBrowser folderBrowser = new FolderBrowser();

// Set starting location to My Computer
folderBrowser.StartLocation = Syncfusion.Windows.Forms.FolderBrowserFolder.MyComputer;

// Configure dialog styles
folderBrowser.Style = Syncfusion.Windows.Forms.FolderBrowserStyles.RestrictToFilesystem | 
                      Syncfusion.Windows.Forms.FolderBrowserStyles.NewDialogStyle;

// Show dialog and get selected path
if (folderBrowser.ShowDialog() == DialogResult.OK)
{
    string selectedFolder = folderBrowser.DirectoryPath;
    MessageBox.Show($"Selected: {selectedFolder}");
}

常见模式

模式 1：基本文件夹选择

显示一个简单的对话框，允许用户浏览并选择文件系统中的任意文件夹。

var folderBrowser = new FolderBrowser();
folderBrowser.Style = FolderBrowserStyles.RestrictToFilesystem;
folderBrowser.ShowDialog();

模式 2：自定义起始位置

从指定路径开始浏览，并预先突出显示所选位置。

folderBrowser.StartLocation = FolderBrowserFolder.CustomStartLocation;
folderBrowser.CustomStartLocation = "C:\\Program Files";
folderBrowser.SelectLocation = "C:\\Program Files\\Syncfusion";
folderBrowser.ShowDialog();

模式 3：多个样式标志

组合多个样式，以启用文本输入和验证。

folderBrowser.Style = FolderBrowserStyles.ShowTextBox | 
                      FolderBrowserStyles.Validate | 
                      FolderBrowserStyles.NewDialogStyle;

模式 4：使用回调验证

通过回调事件处理文件夹选择验证。

folderBrowser.FolderBrowserCallback += FolderBrowser_Callback;
folderBrowser.ShowDialog();

private void FolderBrowser_Callback(object sender, FolderBrowserCallbackEventArgs e)
{
    // Validate path or update status
    if (IsValidFolder(e.Path))
        e.BrowseCallbackText = $"Selected: {e.Path}";
    else
        e.Dismiss = true;
}

文档导航

入门

📄 阅读： references/getting-started.md

• 程序集引用和 NuGet 部署
• 通过设计器添加控件
• 通过代码添加控件
• 基本对话框初始化和显示
• 完整的可运行示例

位置设置

📄 阅读： references/location-settings.md

• 使用 StartLocation 属性设置预定义位置
• 使用 CustomStartLocation 设置自定义浏览路径
• 使用 SelectLocation 自动突出显示路径
• 使用 DirectoryPath 属性获取所选路径
• 实用代码示例

样式选项

📄 阅读： references/style-options.md

• Style 属性概述及所有可用标志
• RestrictToFilesystem 和域限制
• BrowseForComputer 和 BrowseForEverything
• ShowTextBox 和自动完成功能
• 用于可调整大小对话框的 NewDialogStyle
• 组合多个样式标志

文本自定义

📄 阅读： references/text-customization.md

• 使用 Description 属性设置对话框标题
• 设置自定义对话框文本
• 在回调中使用 StatusText
• 用户友好消息的最佳实践

回调事件

📄 阅读： references/callback-events.md

• 处理 FolderBrowserCallback 事件
• FolderBrowserCallbackEventArgs 成员
• 使用 Dismiss 属性控制对话框
• BrowseCallbackText 和状态更新
• FolderBrowserMessage 类型及其含义
• 实时验证模式

常见模式

📄 阅读： references/common-patterns.md

• 完整的文件夹选择工作流
• 错误处理和路径验证
• 为特定场景组合样式
• 与文件系统操作集成
• 性能注意事项

关键属性

属性	类型	用途
StartLocation	FolderBrowserFolder	设置浏览的根文件夹
CustomStartLocation	string	当 StartLocation 为 CustomStartLocation 时使用的自定义路径
SelectLocation	string	浏览时自动高亮显示的路径
DirectoryPath	string	获取所选文件夹路径
Style	FolderBrowserStyles	控制对话框外观和行为的标志
Description	string	设置对话框中的说明文本

程序集要求

使用 FolderBrowser 前，请添加以下程序集引用：

• Syncfusion.Shared.Base.dll

或通过 NuGet 安装：

Install-Package Syncfusion.Shared.Base

---

后续步骤： 根据具体需求选择上方的参考文档；如果你是首次使用此组件，请从入门指南开始。