syncfusion-winforms-folder-browser

用途

Syncfusion FolderBrowser 控件用于在 Windows Forms 应用中显示文件夹选择对话框。它是对 Win32 Shell Folder Browser API 的封装，以 .NET 风格的属性、事件和方法对外提供文件夹选择能力。当你需要让用户浏览并选择目录路径、展示文件夹选择对话框、实现目录浏览，或配置浏览起始位置时，可以使用该组件。

主要能力

组件为对话框型控件，展示原生 Windows 文件夹选择对话框，并抽象了复杂的 Win32 Shell API 交互。其能力包括：

位置设置：配置浏览的起始位置，如 MyComputer、CustomStartLocation 等。
样式选项：控制对话框行为，如 RestrictToFilesystem、BrowseForComputer、ShowTextBox、NewDialogStyle、Validate 等标志。
路径选择：自动滚动并高亮指定文件夹路径（SelectLocation）。
回调事件：在浏览过程中通过 FolderBrowserCallback 事件实时校验文件夹选择。
文字自定义：设置对话框描述和状态消息（Description、StatusText）。
自动完成：支持带文件夹路径建议的文本框（ShowTextBox 与自动完成功能）。

关键属性

StartLocation（FolderBrowserFolder）：设置浏览的根文件夹。
CustomStartLocation（string）：当 StartLocation 为 CustomStartLocation 时使用的自定义路径。
SelectLocation（string）：浏览时自动高亮的路径。
DirectoryPath（string）：获取已选择的文件夹路径。
Style（FolderBrowserStyles）：控制对话框外观和行为的标志组合。
Description（string）：设置对话框中的描述文字。

使用方式

快速开始

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

程序集要求

使用 FolderBrowser 前需添加程序集引用：

Syncfusion.Shared.Base.dll

或通过 NuGet 安装：

Install-Package Syncfusion.Shared.Base

文档导航

Getting Started（references/getting-started.md）：程序集引用与 NuGet 部署、通过设计器添加控件、通过代码添加控件、基本对话框初始化与显示、完整可运行示例。
Location Settings（references/location-settings.md）：StartLocation 属性与预定义位置、CustomStartLocation 自定义浏览路径、SelectLocation 自动路径高亮、DirectoryPath 获取已选路径及代码示例。
Style Options（references/style-options.md）：Style 属性概览与全部可用标志、RestrictToFilesystem 与域限制、BrowseForComputer 与 BrowseForEverything、ShowTextBox 与自动完成功能、NewDialogStyle 可调整大小对话框、组合多个样式标志。
Text Customization（references/text-customization.md）：Description 属性设置对话框标题、设置自定义对话框文字、回调中 StatusText 的使用、用户友好消息的最佳实践。
Callback Events（references/callback-events.md）：FolderBrowserCallback 事件处理、FolderBrowserCallbackEventArgs 成员、Dismiss 属性控制对话框、BrowseCallbackText 与状态更新、FolderBrowserMessage 类型及含义、实时校验模式。
Common Patterns（references/common-patterns.md）：完整文件夹选择工作流、错误处理与路径校验、针对特定场景组合样式、与文件系统操作集成、性能注意事项。

适用场景

需要向用户展示文件夹选择对话框。
需要允许用户浏览并选择目录路径。
需要自定义对话框行为（如限制到文件系统、显示计算机等）。
需要在文件夹选择时通过回调进行校验。
需要配置浏览的起始位置。
需要添加文件路径自动完成功能。

限制

提供的资料未说明该组件的授权方式、收费与价格、支持的具体平台版本、性能指标或与其他控件的兼容性限制，这些信息暂未提供。