syncfusion-winforms-tree-navigator

ツリーナビゲーター（TreeNavigator）の実装

画面スペースを追加で消費せず、その場でツリーを展開できる、Windows Forms 用の独自のナビゲーションコントロールです。項目はインラインで展開・折りたたまれるため、項目をクリックして階層構造を掘り下げることができます。

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

次のような場合に、このスキルを使用してください。

• 省スペースなナビゲーション：コントロールのサイズを大きくせず、その場で展開される階層型ナビゲーションを表示する
• ドリルダウンインターフェイス：戻るボタンを使ったナビゲーションで、親項目から子項目へ移動できるようにする
• ファイルエクスプローラー風のナビゲーション：Windows Explorer のパンくずリストナビゲーションに似た、ファイル／フォルダーのナビゲーションを作成する
• メニュー階層：親子関係を持つ折りたたみ可能なメニューシステムを構築する
• パンくずリストナビゲーション：ナビゲーションパスを表示するヘッダーを積み重ねる拡張モードを実装する
• 設定ナビゲーション：階層構造で整理された、カテゴリーベースの設定インターフェイスを作成する
• ドキュメントブラウザー：ドキュメントの構造、セクション、サブセクションを移動する
• TreeView の代替：標準の TreeView を、よりコンパクトで使いやすいナビゲーションに置き換える

コンポーネントの概要

TreeNavigator コントロールは、階層型ナビゲーションのための独自のインターフェイスを提供します。

• 画面スペースを追加で使わず、その場でツリー構造を展開します
• 子項目に移動すると、項目が自動的に折りたたまれます
• 親項目をクリックして、サブ項目に移動できます
• 戻るボタンを使って親レベルに戻れます
• 2 種類のナビゲーションモード：デフォルト（戻るボタン 1 つ）と拡張（パンくずリスト形式のヘッダー）

主な機能：

• ナビゲーションスタイル（デフォルトまたは拡張）を選択する NavigationMode プロパティ
• TreeMenuItem オブジェクトを管理する Items コレクション
• ヘッダーの外観と動作をカスタマイズする Header 設定
• Office 2016/2019 のビジュアルテーマを適用する Style プロパティ
• プログラムから選択するための SelectedItem プロパティ
• ナビゲーションの追跡と制御に使用する選択イベント

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

参照する場面： 新しい実装を始めるとき、依存関係を設定するとき、初めて使用するとき、TreeNavigator の基本を作成するとき

説明するトピック：

• アセンブリの配置（Syncfusion.Tools.Windows、Syncfusion.Shared.Base）
• NuGet パッケージのインストール
• 名前空間の要件（Syncfusion.Windows.Forms.Tools）
• デザイナーを使った TreeNavigator の追加（ツールボックスからドラッグ＆ドロップ）
• コードからプログラムで TreeNavigator を追加する方法
• Items コレクションへの TreeMenuItem 項目の追加
• ヘッダーの設定（HeaderText プロパティ）
• デザイナーで項目を追加する方法（Smart Tag エディター）
• コードを含む完全なセットアップ例
• 子項目に関する .NET Core の回避策

---

ナビゲーションモード

📄 参照： references/navigation-modes.md

参照する場面： ナビゲーション動作を選択するとき、戻るボタンを使ったナビゲーションを実装するとき、パンくずリスト形式のインターフェイスを作成するとき

説明するトピック：

• NavigationMode プロパティの概要
• デフォルトモード（戻るボタン 1 つ、選択項目を最上部に表示）
• 拡張モード（パンくずリスト形式のヘッダーを積み重ね、任意の階層をクリック）
• モードによるナビゲーション動作の違い
• 各モードのユースケース（シンプルな階層と複雑な階層）
• ナビゲーションモードの設定例
• デフォルトモードと拡張モードの視覚的な比較

---

外観とスタイル設定

📄 参照： references/appearance-styling.md

読むタイミング： 外観のカスタマイズ、テーマの適用、ヘッダーのスタイル設定、境界線と色の構成

説明されているトピック：

• Style プロパティ（Office2016Colorful/White/Black/DarkGray、Office2019Colorful、Default）
• ビジュアルテーマの適用と比較
• ヘッダーのカスタマイズ（Height、HeaderBackColor、HeaderForeColor、HeaderText、TextBounds）
• ShowHeader プロパティ（ヘッダー領域の表示／非表示）
• 境界線のカスタマイズ（BorderColor、BorderThickness）
• 項目の間隔（項目間の間隔を設定する PadY プロパティ）
• TreeMenuItem の外観（ItemBackColor、ItemHoverColor、SelectedColor、SelectedItemForeColor）
• テキストの配置（TextAlign：Center、Left、Right）
• コードを使ったスタイル設定の完全な例

---

ツリーメニュー項目

📄 参照： references/tree-menu-items.md

読むタイミング： 項目の管理、TreeMenuItem の追加／削除、階層の構築、項目コレクションの操作

説明されているトピック：

• TreeMenuItem クラスの概要とプロパティ
• 項目コレクションの管理（Add、Remove、Clear）
• プログラムによる項目の追加（C# および VB.NET）
• デザイナーを使った項目の追加（スマートタグのコレクションエディター）
• 親子項目の関係とネスト
• 項目のプロパティ（Text、ItemBackColor、ItemHoverColor、SelectedColor、SelectedItemForeColor）
• 複数レベルの階層の構築
• 実行時の項目の動的な操作
• ネストした項目を含む完全な例

---

選択とイベント

📄 参照： references/selection-events.md

読むタイミング： 選択の変更処理、ナビゲーションへの応答、プログラムによる項目の選択、選択の防止

説明されているトピック：

• SelectedItem プロパティ（現在選択されている項目の取得／設定）
• SelectionChanging イベント（選択の変更前に発生し、キャンセル可能）
• SelectionStateChangingEventArgs（NewValue、OldValue、Expanded、Cancel プロパティ）
• SelectionChanged イベント（選択の変更後に発生）
• SelectionStateChangedEventArgs（SelectedItem、Expanded プロパティ）
• コードを使ったイベント処理の例
• 選択変更のキャンセル（検証のシナリオ）
• タッチスクロールの動作（UseTouchScrollBehavior プロパティ）
• イベントワークフローの完全な例

---

クイックスタートの例

Office2016 テーマを使ったファイルエクスプローラー風のナビゲーション

using Syncfusion.Windows.Forms.Tools;

// Create TreeNavigator
TreeNavigator treeNavigator = new TreeNavigator();
treeNavigator.Size = new Size(250, 400);
treeNavigator.Header.HeaderText = "This PC";
treeNavigator.Style = TreeNavigatorStyle.Office2016Colorful;
treeNavigator.NavigationMode = NavigationMode.Extended;

// Add root items
TreeMenuItem desktop = new TreeMenuItem { Text = "Desktop" };
TreeMenuItem documents = new TreeMenuItem { Text = "Documents" };
TreeMenuItem downloads = new TreeMenuItem { Text = "Downloads" };

// Add items to TreeNavigator
treeNavigator.Items.Add(desktop);
treeNavigator.Items.Add(documents);
treeNavigator.Items.Add(downloads);

// Add child items to Documents
TreeMenuItem workFiles = new TreeMenuItem { Text = "Work Files" };
TreeMenuItem personalFiles = new TreeMenuItem { Text = "Personal Files" };
documents.Items.Add(workFiles);
documents.Items.Add(personalFiles);

this.Controls.Add(treeNavigator);

Imports Syncfusion.Windows.Forms.Tools

' Create TreeNavigator
Dim treeNavigator As New TreeNavigator()
treeNavigator.Size = New Size(250, 400)
treeNavigator.Header.HeaderText = "This PC"
treeNavigator.Style = TreeNavigatorStyle.Office2016Colorful
treeNavigator.NavigationMode = NavigationMode.Extended

' Add root items
Dim desktop As New TreeMenuItem With {.Text = "Desktop"}
Dim documents As New TreeMenuItem With {.Text = "Documents"}
Dim downloads As New TreeMenuItem With {.Text = "Downloads"}

' Add items to TreeNavigator
treeNavigator.Items.Add(desktop)
treeNavigator.Items.Add(documents)
treeNavigator.Items.Add(downloads)

' Add child items to Documents
Dim workFiles As New TreeMenuItem With {.Text = "Work Files"}
Dim personalFiles As New TreeMenuItem With {.Text = "Personal Files"}
documents.Items.Add(workFiles)
documents.Items.Add(personalFiles)

Me.Controls.Add(treeNavigator)

---

よく使われるパターン

パターン 1：カスタムカラーを使った設定ナビゲーション

// Create TreeNavigator for settings
TreeNavigator settingsNav = new TreeNavigator();
settingsNav.Header.HeaderText = "Settings";
settingsNav.Style = TreeNavigatorStyle.Office2016White;
settingsNav.NavigationMode = NavigationMode.Default;

// Customize appearance
settingsNav.Header.HeaderBackColor = Color.FromArgb(0, 120, 215);
settingsNav.Header.HeaderForeColor = Color.White;
settingsNav.ItemBackColor = Color.WhiteSmoke;

// Add settings categories
TreeMenuItem general = new TreeMenuItem { Text = "General" };
TreeMenuItem appearance = new TreeMenuItem { Text = "Appearance" };
TreeMenuItem advanced = new TreeMenuItem { Text = "Advanced" };

settingsNav.Items.Add(general);
settingsNav.Items.Add(appearance);
settingsNav.Items.Add(advanced);

// Add sub-settings
general.Items.Add(new TreeMenuItem { Text = "Language" });
general.Items.Add(new TreeMenuItem { Text = "Startup" });
appearance.Items.Add(new TreeMenuItem { Text = "Theme" });
appearance.Items.Add(new TreeMenuItem { Text = "Colors" });

パターン 2：選択イベントを使ったパンくずリスト形式のナビゲーション

// Create breadcrumb-style navigator
TreeNavigator breadcrumbNav = new TreeNavigator();
breadcrumbNav.NavigationMode = NavigationMode.Extended;
breadcrumbNav.Style = TreeNavigatorStyle.Office2016Colorful;

// Handle selection changes
breadcrumbNav.SelectionChanged += (sender, e) => {
    TreeMenuItem selected = e.SelectedItem;
    bool isExpanded = e.Expanded;
    
    // Update content panel based on selection
    MessageBox.Show($"Navigated to: {selected.Text}\nExpanded: {isExpanded}");
};

// Build hierarchy
TreeMenuItem root = new TreeMenuItem { Text = "Home" };
breadcrumbNav.Items.Add(root);
TreeMenuItem level1 = new TreeMenuItem { Text = "Category" };
TreeMenuItem level2 = new TreeMenuItem { Text = "Subcategory" };
root.Items.Add(level1);
level1.Items.Add(level2);

パターン 3：項目のホバーカラーを使ったコンパクトなナビゲーションメニュー

// Create compact navigation
TreeNavigator compactNav = new TreeNavigator();
compactNav.ShowHeader = false; // Hide header for compact look
compactNav.Style = TreeNavigatorStyle.Office2016DarkGray;
compactNav.PadY = 5; // Reduce spacing between items

// Customize item colors
TreeMenuItem dashboard = new TreeMenuItem 
{ 
    Text = "Dashboard",
    ItemBackColor = Color.FromArgb(45, 45, 48),
    ItemHoverColor = Color.FromArgb(62, 62, 66),
    SelectedColor = Color.FromArgb(0, 122, 204)
};

TreeMenuItem reports = new TreeMenuItem 
{ 
    Text = "Reports",
    ItemBackColor = Color.FromArgb(45, 45, 48),
    ItemHoverColor = Color.FromArgb(62, 62, 66)
};

compactNav.Items.Add(dashboard);
compactNav.Items.Add(reports);

// Add report sub-items
reports.Items.Add(new TreeMenuItem { Text = "Sales" });
reports.Items.Add(new TreeMenuItem { Text = "Inventory" });
reports.Items.Add(new TreeMenuItem { Text = "Analytics" });

---

主なプロパティ

プロパティ	型	説明
Items	Collection	ナビゲーション階層を構成する TreeMenuItem オブジェクトのコレクション
NavigationMode	NavigationMode	ナビゲーションスタイル：Default（戻るボタン）または Extended（パンくずリスト）
Style	TreeNavigatorStyle	ビジュアルテーマ：Office2016Colorful/White/Black/DarkGray、Office2019Colorful、Default
SelectedItem	TreeMenuItem	現在の階層レベルで選択されている項目を取得または設定します
Header.HeaderText	string	ヘッダー領域に表示されるテキスト
Header.HeaderBackColor	Color	ヘッダーの背景色
Header.HeaderForeColor	Color	ヘッダーの前景色（テキスト色）
Header.Height	int	ヘッダー領域の高さ（ピクセル単位）
ShowHeader	bool	ヘッダー領域を表示または非表示にします（true = 表示、false = 非表示）
BorderColor	Color	コントロールの枠線の色
BorderThickness	int	コントロールの枠線の太さ（ピクセル単位）
PadY	int	TreeMenuItem 項目間の垂直方向の間隔
ItemBackColor	Color	すべての TreeMenuItem 項目の背景色（項目ごとに上書きできます）
TextAlign	TextAlignment	項目のテキスト配置：Center、Left、または Right
UseTouchScrollBehavior	bool	スクロールバーが自動的に非表示になる、タッチ操作に適したスクロールを有効にします

---

一般的な使用例

1. ファイル／フォルダーの参照：戻るボタンまたはパンくずリストによるナビゲーションで、Windows エクスプローラーのようにフォルダー階層を移動します
2. 設定インターフェイス：階層をたどるナビゲーションで、アプリケーションの設定をカテゴリやサブカテゴリに整理します
3. ドキュメントのアウトライン：ドキュメントのセクション、章、節を移動します
4. メニューのナビゲーション：スペースに制約のある複雑なアプリケーション向けに、階層型のメニューシステムを作成します
5. 製品カテゴリ：カテゴリ → サブカテゴリ → 製品のナビゲーションで製品カタログを閲覧します
6. ヘルプシステム：トピック間やカテゴリへの移動を簡単に行えるよう、ヘルプトピックをカテゴリに整理します
7. データダッシュボード：ダッシュボードのセクション、レポート、詳細ビュー間を移動します
8. ワークフローのステップ：階層的な構成で、複数ステップからなるワークフローをユーザーに案内します

---

追加リソース

• Syncfusion ヘルプの TreeNavigator コントロール
• Syncfusion.Windows.Forms.Tools 名前空間
• TreeNavigator API リファレンス
• TreeMenuItem API リファレンス