syncfusion-winforms-folder-browser

Windows Forms での FolderBrowser の実装

Syncfusion FolderBrowser コントロールは、Win32 Shell Folder Browser 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

---

次のステップ： 特定のニーズに合わせて上記のリファレンスドキュメントを選択するか、このコンポーネントを初めて使用する場合は「はじめに」から始めてください。