syncfusion-winforms-folder-browser

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing FolderBrowser in Windows Forms

在Windows Forms中实现FolderBrowser

The Syncfusion FolderBrowser control provides a wrapper around the Win32 Shell Folder Browser API, enabling developers to display a folder selection dialog with .NET-centric properties, events, and methods.

Syncfusion FolderBrowser控件对Win32 Shell Folder Browser API进行了封装，让开发者可以使用面向.NET的属性、事件和方法来展示文件夹选择对话框。

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Display a folder selection dialog to users
Allow users to browse and select directory paths
Customize dialog behavior (restrict to filesystem, show computers, etc.)
Handle folder selection with callback validation
Configure starting locations for browsing
Add auto-complete file path functionality

当你需要完成以下操作时可使用本技能：

向用户展示文件夹选择对话框
允许用户浏览并选择目录路径
自定义对话框行为（限制仅访问文件系统、展示计算机列表等）
通过回调验证处理文件夹选择逻辑
配置浏览的起始位置
添加文件路径自动补全功能

Component Overview

组件概述

FolderBrowser is a dialog-based component that:

Shows a native Windows folder selection dialog
Abstracts complex Win32 Shell API interactions
Supports various browsing styles and restrictions
Provides callback events for validation
Enables custom starting locations and path selection
Works with both designer and code-based implementations

FolderBrowser 是一个基于对话框的组件，具备以下特性：

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

Key Capabilities

核心能力

Feature	Purpose
Location Settings	Configure where browsing starts (MyComputer, CustomStartLocation, etc.)
Style Options	Control dialog behavior (RestrictToFilesystem, BrowseForComputer, ShowTextBox, etc.)
Path Selection	Automatically scroll and highlight specific folder paths
Callback Events	Validate folder selection in real-time during browsing
Text Customization	Set dialog descriptions and status messages
Auto-Complete	Enable textbox with folder path suggestions

功能	用途
位置设置	配置浏览的起始位置（我的电脑、自定义起始位置等）
样式选项	控制对话框行为（限制仅访问文件系统、浏览计算机、展示文本框等）
路径选择	自动滚动并高亮指定的文件夹路径
回调事件	在浏览过程中实时验证文件夹选择
文本自定义	设置对话框描述和状态消息
自动补全	为文本框启用文件夹路径建议功能

Quick Start Example

快速入门示例

csharp

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

csharp

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

Common Patterns

常见模式

Pattern 1: Basic Folder Selection

模式1：基础文件夹选择

Show a simple dialog allowing users to browse and select any folder in the filesystem.

csharp

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

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

csharp

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

Pattern 2: Custom Starting Location

模式2：自定义起始位置

Start browsing from a specific path with pre-highlighted selection.

csharp

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

从指定路径开始浏览，并预先高亮选中对应位置。

csharp

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

Pattern 3: Multiple Style Flags

模式3：多样式标识组合

Combine multiple styles to enable text input and validation.

csharp

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

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

csharp

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

Pattern 4: With Callback Validation

模式4：带回调验证

Handle folder selection validation through callback events.

csharp

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

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

csharp

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

Documentation Navigation

文档导航

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly references and NuGet deployment
Adding control via designer
Adding control via code
Basic dialog initialization and display
Complete working example

📄 阅读： references/getting-started.md

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

Location Settings

位置设置

📄 Read: references/location-settings.md

StartLocation property with predefined locations
CustomStartLocation for custom browsing paths
SelectLocation for automatic path highlighting
DirectoryPath property for retrieving selected path
Practical code examples

📄 阅读： references/location-settings.md

预定义位置的StartLocation属性
用于自定义浏览路径的CustomStartLocation
用于自动高亮路径的SelectLocation
用于获取选中路径的DirectoryPath属性
实用代码示例

Style Options

样式选项

📄 Read: references/style-options.md

Style property overview and all available flags
RestrictToFilesystem and domain restrictions
BrowseForComputer and BrowseForEverything
ShowTextBox and auto-complete functionality
NewDialogStyle for resizable dialogs
Combining multiple style flags

📄 阅读： references/style-options.md

Style属性概述及所有可用标识
RestrictToFilesystem和域限制
BrowseForComputer和BrowseForEverything
ShowTextBox和自动补全功能
支持调整大小的对话框样式NewDialogStyle
多样式标识组合方法

Text Customization

文本自定义

📄 Read: references/text-customization.md

Description property for dialog titles
Setting custom dialog text
StatusText usage in callbacks
Best practices for user-friendly messaging

📄 阅读： references/text-customization.md

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

Callback Events

回调事件

📄 Read: references/callback-events.md

FolderBrowserCallback event handling
FolderBrowserCallbackEventArgs members
Dismiss property for dialog control
BrowseCallbackText and status updates
FolderBrowserMessage types and meanings
Real-time validation patterns

📄 阅读： references/callback-events.md

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

Common Patterns

常见模式

📄 Read: references/common-patterns.md

Complete folder selection workflow
Error handling and path validation
Combining styles for specific scenarios
Integration with file system operations
Performance considerations

📄 阅读： references/common-patterns.md

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

Key Properties

核心属性

Property	Type	Purpose
`StartLocation`	FolderBrowserFolder	Sets the root folder for browsing
`CustomStartLocation`	string	Custom path when StartLocation is CustomStartLocation
`SelectLocation`	string	Path to auto-highlight during browsing
`DirectoryPath`	string	Gets the selected folder path
`Style`	FolderBrowserStyles	Flags controlling dialog appearance and behavior
`Description`	string	Sets the description text in the dialog

属性	类型	用途
`StartLocation`	FolderBrowserFolder	设置浏览的根文件夹
`CustomStartLocation`	string	当StartLocation设为CustomStartLocation时的自定义路径
`SelectLocation`	string	浏览过程中自动高亮的路径
`DirectoryPath`	string	获取选中的文件夹路径
`Style`	FolderBrowserStyles	控制对话框外观和行为的标识
`Description`	string	设置对话框中的描述文本

Assembly Requirements

程序集要求

Before using FolderBrowser, add the following assembly reference:

Syncfusion.Shared.Base.dll

Or install via NuGet:

Install-Package Syncfusion.Shared.Base

Next Steps: Choose a reference document above based on your specific need, or start with Getting Started if you're new to this component.

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

Syncfusion.Shared.Base.dll

或者通过NuGet安装：

Install-Package Syncfusion.Shared.Base

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