syncfusion-winforms-navigation-view

Windows Forms でのナビゲーションビューの実装

このスキルを使用する場面

次のような場合は、NavigationView コントロールを使用してください。

• パンくずナビゲーション： 階層的な場所のパスを表示します（例：MyComputer > C: > Program Files > App）
• ファイルブラウザーのインターフェイス： Windows エクスプローラーのように、フォルダー階層を追跡して移動します
• 場所の追跡： 複数階層の構造内で現在の位置をユーザーが把握できるようにします
• クイックナビゲーション： 親の場所に戻ったり、ドロップダウンから移動したりできるようにします
• 設定／構成ウィザード： 入れ子になったカテゴリ内でのユーザーの進行状況を表示します
• ドキュメント管理： ドキュメントのフォルダー、カテゴリ、または組織構造内を移動します

主な機能： 従来のメニューやツリービューとは異なり、NavigationView は現在のパスを表示し、各階層で兄弟項目にアクセスできるドロップダウンを備えています。

コンポーネントの概要

NavigationView コントロールは、バー（ノード）を使用して階層パスを表示する、パンくず形式のナビゲーションインターフェイスを提供します。パス内の各バーには進む矢印が表示され、クリックするとその直下にある子バーのドロップダウンリストが開きます。

主な概念：

• バー： ナビゲーション階層内の単一ノード（例：「MyComputer」、「C:」、「Users」）
• 親バー： 子バーを含むバー（ルートレベルまたは中間レベル）
• 子バー： 親バー内にネストされたバー
• 選択されたバー： パスに表示されている現在アクティブなバー
• 履歴： クイックに戻って移動できるよう、以前に訪問したバーを記録します

視覚的な構造：

[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 をセットアップする
• 最小限の完全な動作例を確認する

主なトピック：

• アセンブリの配置（必須 DLL は 6 個）
• デザイナーでのドラッグアンドドロップによるコントロールの追加
• コードを使った手動でのコントロールの追加
• 最初の NavigationView インスタンスの作成
• 基本的なセットアップと初期化

---

バーの階層と構造

📄 参照： references/bar-hierarchy.md

次のことが必要な場合は、このリファレンスを参照してください。

• 親バーと子バーの関係を作成する
• 複数階層のナビゲーション構造を構築する
• NavigationView.Bars コレクションにバーを追加する
• 親バーの Bars コレクションに子バーを追加する
• 特定のパスを表示するよう選択されたバーを設定する
• バーのプロパティ（Text、ImageIndex）を確認する

主なトピック：

• バーインスタンスの作成
• 親子バーの関係
• NavigationView へのルートバーの追加
• 親バーへの子バーの追加
• SelectedBar プロパティの設定
• プログラムによるバー間の移動

---

ドロップダウンでの選択と履歴

📄 参照： references/dropdown-and-history.md

次のことが必要な場合は、このリファレンスを参照してください。

• 子バーへの移動でドロップダウン選択を実装する
• 履歴ボタンによる追跡を有効または無効にする
• 履歴ドロップダウンに以前訪問した場所を表示する
• NavigationView にカスタムボタンを追加する
• カスタムボタンの外観と画像を設定する
• ドロップダウンをカスタマイズするために BarPopup イベントを処理する
• ポップアップに表示する項目の最大数を制御する

主なトピック：

• 進む矢印によるドロップダウンの仕組み
• ShowHistoryButtons プロパティ
• 履歴の追跡とドロップダウン
• カスタムボタンコレクション
• カスタムボタンの追加（デザイナーとコード）
• BarPopup イベントの処理
• ポップアップ項目数のカスタマイズ

---

画像とビジュアルスタイル

📄 参照： references/images-and-styling.md

次の操作を行う場合は、このリファレンスをお読みください。

• ImageList を使って Bars にアイコンを追加する
• 親および子 Bars の ImageIndex を設定する
• ビジュアルスタイル（Office2007、Vista、Metro）を適用する
• VisualStyle プロパティを設定する
• コントロールの外観をカスタマイズする
• アプリケーションのテーマやスタイルに合わせる

主なトピック：

• ImageList の設定と割り当て
• Bar の ImageIndex プロパティの設定
• ビジュアルスタイルの概要
• Office2007 スタイルの適用
• Vista スタイルの適用
• Metro スタイルの適用
• 外観のカスタマイズ

---

高度な機能

📄 参照： references/advanced-features.md

次の操作を行う場合は、このリファレンスをお読みください。

• パスを直接入力できる編集モードを有効にする
• ユーザーがナビゲーションパスを入力できるようにする
• BarPopup イベントでポップアップの動作を制御する
• ポップアップに表示する項目数の上限を設定する
• 条件に応じてポップアップの表示をキャンセルする
• 高度なナビゲーションシナリオを実装する

主なトピック：

• 編集モードの有効化と使い方
• NavigationView へのパスの直接入力
• BarPopup イベントの高度な使い方
• MaximumItemsToDisplay プロパティ
• ポップアップのキャンセルロジック
• クイックナビゲーションの手法

---

クイックスタートの例

3 階層の階層構造を持つ 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	ルートレベルの Bars のコレクション
SelectedBar	Bar	パス内で現在表示されている Bar
ShowHistoryButtons	bool	履歴ドロップダウンボタンの表示／非表示
VisualStyle	VisualStyles	Office2007、Vista、または Metro のスタイルを適用
ImageList	ImageList	Bar アイコン用の画像コレクション

Bar のプロパティ

プロパティ	型	説明
Text	string	Bar に表示するテキスト
ImageIndex	int	NavigationView.ImageList 内のインデックス
Bars	BarCollection	この Bar の子 Bars
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 に Bar が表示されない

• 解決策： Bar を作成するだけでなく、navigationView1.Bars コレクションに追加してください
• 確認事項： Bar を表示するには、SelectedBar が設定されていることを確認してください

問題： 画像が表示されない

• 解決策： ImageList を NavigationView に割り当ててから、Bar の ImageIndex を設定してください
• 確認事項： ImageIndex の値が ImageList の範囲内であることを確認してください

問題： ドロップダウンに子 Bar が表示されない

• 解決策： 子 Bar を親の Bars コレクションに追加してください：parentBar.Bars.Add(childBar)
• 確認事項： 親 Bar に実際に子があることを確認してください

問題： 履歴ボタンが表示されない

• 解決策： navigationView1.ShowHistoryButtons = true を設定してください

問題： ビジュアルスタイルが適用されない

• 解決策： コントロールの初期化後に VisualStyle プロパティを設定してください
• 例： navigationView1.VisualStyle = VisualStyles.Office2007;

次のステップ

1. まずは使い始める： references/getting-started.md を読んで、コントロールをセットアップしてください
2. 階層を構築する： references/bar-hierarchy.md を読んで、Bar の構造を作成してください
3. 機能を追加する： 残りのリファレンスを読んで、ドロップダウン、履歴、画像、高度な機能を追加してください
4. 外観をカスタマイズする： ビジュアルスタイルを適用して、アプリケーションのテーマに合わせてください
5. イベントを処理する： BarSelected などのイベントを接続して、ユーザーのナビゲーションに応答してください

実装の詳細については、上記の順にリファレンスガイドを読み進めてください。