syncfusion-winforms-treemap

Windows Forms TreeMap の実装

ネストされた色分けされた長方形を使って階層データを可視化する、Syncfusion® Windows Forms TreeMap コントロールの実装ガイドです。TreeMap は、長方形のサイズと色で定量値を表すことで、大規模なデータセットを効率よく表示できます。

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

次のような場合にこのスキルを使用します。

• ネストされた長方形を使って階層データを可視化する
• 省スペースなレイアウトで大規模なデータセットを表示する
• 長方形のサイズを通じて比例関係を示す
• 複数のマッピング方法でデータ値を色分けする
• TreeMap のレイアウト（Squarified、SliceAndDice の各種）を実装する
• ツールチップや凡例を使ったインタラクティブな可視化を作成する
• ヘッダー、ラベル、カスタム描画を使ってTreeMap の外観をカスタマイズする
• 株式ポートフォリオ、ディスク使用量、地域別売上などのカテゴリデータを分析する

TreeMap の概要

TreeMap は、定量変数に基づいてサイズと色が決まる長方形に空間を分割し、大量のデータを可視化するのに適しています。階層の各レベルは、ほかの長方形を含む長方形として可視化されます。

主な概念：

• 長方形はデータ項目を表します - サイズは重み値に基づきます
• 階層のネスト - 親の長方形に子の長方形が含まれます
• 色分け - 色はデータカテゴリまたは値の範囲を表します
• 省スペース - 可視化領域全体を活用します
• 複数のレベル - マルチレベル階層をサポートします

一般的な使用例

TreeMap は、さまざまなアプリケーションで大規模または複雑なデータセットを表すために使用されます。

1. 株式市場の分析 - 長方形のサイズは指数における株式の比重を表し、色は上昇・下落の範囲を示します
2. インターネット利用カテゴリ - 小売、ソーシャルネットワーク、検索などの利用状況を可視化します
3. ニュースの集約 - 色はセクション（ビジネス、政治など）を表し、サイズは記事の頻度を表します
4. 気象分析 - 不透明度は湿度を表し、サイズは地理的な面積を表します
5. ディスク容量の使用状況 - ストレージ内のファイルやフォルダーのサイズを可視化します
6. 地域別／製品別売上 - カテゴリごとの売上分布を示します
7. ポートフォリオ管理 - 資産配分とパフォーマンスを表示します

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

はじめに

📄 参照： references/getting-started.md

• アセンブリの配置とコントロールの依存関係
• NuGet パッケージのインストール
• TreeMap コントロールインスタンスの作成
• Windows Forms アプリケーションへのコントロールの追加
• 基本的な名前空間とアセンブリ参照
• 最初に動作する TreeMap の例

概要と可視化の概念

📄 参照： references/overview-and-use-cases.md

• TreeMap とは何か、その仕組み
• 階層情報の可視化
• クラスター化された長方形とデータ表現
• 実際の使用シナリオ
• ほかの可視化方法より TreeMap を選ぶ場面

基本設定 - 重みと色のパス

📄 参照： references/weight-and-color-paths.md

• 長方形のサイズを指定する WeightValuePath プロパティ
• 色のマッピングを指定する ColorValuePath プロパティ
• データバインディングのパス要件
• データモデルのフィールド指定
• 設定例

データバインディングとレベル

📄 参照： references/items-source-and-levels.md

• フラットなデータコレクションを使った ItemsSource の設定
• データビューモデルの作成
• TreeMapFlatLevel の設定
• 階層グループ化のための GroupPath
• 視覚的な分離のための GroupGap
• マルチレベル TreeMap 構造
• データバインディングの完全な例

レイアウトモード

📄 参照： references/layout-modes.md

• ItemsLayoutMode プロパティの概要
• Squarified レイアウトアルゴリズム
• SliceAndDiceAuto レイアウト
• SliceAndDiceHorizontal レイアウト
• SliceAndDiceVertical レイアウト
• データに適したレイアウトの選び方
• 視覚的な比較

カラーマッピング戦略

📄 参照： references/color-mapping.md

• 4 種類のカラーマッピングの概要
• 単一の色を適用する UniColorMapping
• 値の範囲に対応する RangeBrushColorMapping
• 不透明度に基づいて色を設定する DesaturationColorMapping
• 色のコレクションに対応する PaletteColorMapping
• LeafColorMapping の設定
• 各種類の完全なサンプル

ヘッダーとラベルのカスタマイズ

📄 参照： references/headers-and-labels.md

• ラベルのフォントと色のカスタマイズ
• LabelBrush と LabelBackgroundBrush
• ラベルの境界線プロパティ
• HeaderBrush の設定
• 表示を制御する ShowLabels プロパティ
• レベルヘッダーの HeaderHeight
• スタイル設定の完全なサンプル

凡例のサポート

📄 参照： references/legend-support.md

• 色の値を示す TreeMap の凡例
• LegendPosition の設定（Left、Right、Top、Bottom）
• アイコンの形状を指定する LegendType
• 間隔を指定する LegendGap
• RangeBrushColorMapping との連携
• RangeBrush 項目の LegendLabel

ツールチップと高度なカスタマイズ

📄 参照： references/tooltip-and-customization.md

• ツールチップの表示と設定
• グループのツールチップ用 HeaderToolTipInfo
• リーフのツールチップ用 ItemToolTipInfo
• カスタムツールチップのコンテンツパターン
• カスタム描画用 LeafItemDrawing イベント
• リーフノードの高度なカスタマイズ
• TreeMap でのカスタムグラフィックスと画像

クイックスタートのサンプル

ステップ 1：NuGet パッケージをインストールする

Install-Package Syncfusion.TreeMap.WinForms

ステップ 2：データモデルを作成する

using System.Collections.ObjectModel;

public class PopulationDetail
{
    public string Continent { get; set; }
    public string Country { get; set; }
    public double Growth { get; set; }
    public double Population { get; set; }
}

public class PopulationViewModel
{
    public ObservableCollection<PopulationDetail> PopulationDetails { get; set; }
    
    public PopulationViewModel()
    {
        PopulationDetails = new ObservableCollection<PopulationDetail>();
        
        PopulationDetails.Add(new PopulationDetail 
        { 
            Continent = "Asia", 
            Country = "Indonesia", 
            Growth = 3, 
            Population = 237641326 
        });
        
        PopulationDetails.Add(new PopulationDetail 
        { 
            Continent = "Asia", 
            Country = "Russia", 
            Growth = 2, 
            Population = 152518015 
        });
        
        PopulationDetails.Add(new PopulationDetail 
        { 
            Continent = "North America", 
            Country = "United States", 
            Growth = 4, 
            Population = 315645000 
        });
        
        // Add more data...
    }
}

ステップ 3：TreeMap を設定する

using Syncfusion.Windows.Forms.TreeMap;

public class MyForm : Form
{
    private TreeMap treeMap;
    
    public MyForm()
    {
        InitializeComponent();
        
        // Create TreeMap instance
        treeMap = new TreeMap();
        
        // Set data source
        PopulationViewModel data = new PopulationViewModel();
        treeMap.ItemsSource = data.PopulationDetails;
        
        // Configure paths
        treeMap.WeightValuePath = "Population";
        treeMap.ColorValuePath = "Growth";
        
        // Set layout mode
        treeMap.ItemsLayoutMode = ItemsLayoutModes.Squarified;
        
        // Add first level (Continent)
        TreeMapFlatLevel level1 = new TreeMapFlatLevel();
        level1.GroupPath = "Continent";
        level1.ShowLabels = true;
        treeMap.Levels.Add(level1);
        
        // Add second level (Country)
        TreeMapFlatLevel level2 = new TreeMapFlatLevel();
        level2.GroupPath = "Country";
        level2.ShowLabels = true;
        level2.HeaderHeight = 25;
        treeMap.Levels.Add(level2);
        
        // Add color mapping
        UniColorMapping colorMapping = new UniColorMapping();
        colorMapping.Color = Color.MediumSlateBlue;
        treeMap.LeafColorMapping = colorMapping;
        
        // Set size and add to form
        treeMap.Size = new Size(800, 600);
        treeMap.Location = new Point(10, 10);
        this.Controls.Add(treeMap);
    }
}

よく使われるパターン

複数レベルの階層パターン

// Create levels for nested grouping
TreeMapFlatLevel level1 = new TreeMapFlatLevel();
level1.GroupPath = "Category";
level1.ShowLabels = true;
treeMap.Levels.Add(level1);

TreeMapFlatLevel level2 = new TreeMapFlatLevel();
level2.GroupPath = "SubCategory";
level2.ShowLabels = true;
level2.HeaderHeight = 25;
treeMap.Levels.Add(level2);

TreeMapFlatLevel level3 = new TreeMapFlatLevel();
level3.GroupPath = "Item";
level3.ShowLabels = true;
level3.HeaderHeight = 20;
treeMap.Levels.Add(level3);

範囲ベースのカラーマッピングパターン

RangeBrushColorMapping rangeMapping = new RangeBrushColorMapping();

rangeMapping.Brushes.Add(new RangeBrush 
{ 
    Color = ColorTranslator.FromHtml("#77D8D8"), 
    From = 0, 
    To = 1, 
    LegendLabel = "Low" 
});

rangeMapping.Brushes.Add(new RangeBrush 
{ 
    Color = ColorTranslator.FromHtml("#FFAF51"), 
    From = 1, 
    To = 5, 
    LegendLabel = "Medium" 
});

rangeMapping.Brushes.Add(new RangeBrush 
{ 
    Color = ColorTranslator.FromHtml("#F3D240"), 
    From = 5, 
    To = 20, 
    LegendLabel = "High" 
});

treeMap.LeafColorMapping = rangeMapping;

インタラクティブなツールチップパターン

// Enable tooltips
treeMap.IsToolTipVisible = true;

// Configure header tooltip
ToolTipInfo headerToolTip = new ToolTipInfo();
headerToolTip.ToolTipHeaderPattern = "<b>{Label}</b>";
headerToolTip.ToolTipContentPattern = "Growth: {Growth}%";
treeMap.HeaderToolTipInfo = headerToolTip;

// Configure item tooltip
ToolTipInfo itemToolTip = new ToolTipInfo();
itemToolTip.ToolTipHeaderPattern = "<b>{Country}</b>";
itemToolTip.ToolTipContentPattern = "Growth: {Growth}%\nPopulation: {Population}";
treeMap.ItemToolTipInfo = itemToolTip;

主要プロパティのリファレンス

基本プロパティ

プロパティ	型	説明
ItemsSource	object	可視化するデータコレクション
WeightValuePath	string	長方形のサイズを決定するフィールドへのパス
ColorValuePath	string	カラーマッピングに使用するフィールドへのパス
ItemsLayoutMode	ItemsLayoutModes	レイアウトアルゴリズムの選択
Levels	TreeMapLevelCollection	階層レベルのコレクション
LeafColorMapping	TreeMapColorMapping	カラーマッピング戦略

カスタマイズ用プロパティ

プロパティ	型	説明
LabelFont	Font	リーフノードのラベルに使用するフォント
LabelBrush	Brush	ラベルのテキスト色
LabelBackgroundBrush	Brush	ラベルの背景色
LabelBorderBrush	Brush	ラベルの境界線の色
LabelBorderThickness	int	ラベルの境界線の幅
HeaderBrush	Brush	ヘッダーの背景色

凡例のプロパティ

プロパティ	型	説明
LegendPosition	LegendPositions	凡例の配置（Top/Bottom/Left/Right）
LegendType	LegendTypes	凡例アイコンの形状
LegendGap	int	凡例項目間の間隔

ツールチップのプロパティ

プロパティ	型	説明
IsToolTipVisible	bool	ツールチップの有効化／無効化
HeaderToolTipInfo	ToolTipInfo	ヘッダー用のツールチップ設定
ItemToolTipInfo	ToolTipInfo	リーフ項目用のツールチップ設定

選択ガイド

各レイアウトモードの使用場面

Squarified：

• アスペクト比のバランスを取りやすい
• 長方形の視認性が高い
• 汎用的な可視化に適しています
• 使用する場面： データの比率に大きな差がある場合

SliceAndDiceAuto：

• レベルごとに水平分割と垂直分割を交互に適用
• 階層を明確に示すのに適しています
• 使用する場面： レベルの分離を明確に示す場合

SliceAndDiceHorizontal：

• すべての長方形を水平方向に分割
• 使用する場面： 横幅の広い表示領域を利用できる場合

SliceAndDiceVertical：

• すべての長方形を垂直方向に分割
• 使用する場面： 縦長の表示領域を利用できる場合

色のマッピングを選択する

UniColorMapping:

• すべての項目に単一の色を使用します
• 使用する場面: 色がデータを表すのではなく、グループ化のみを表す場合

RangeBrushColorMapping:

• 値の範囲ごとに異なる色を使用します
• 使用する場面: データを離散的な範囲（低・中・高）に分類する場合

DesaturationColorMapping:

• 単一のベースカラーを使用し、不透明度を変化させます
• 使用する場面: 値の連続的なグラデーションを表示する場合

PaletteColorMapping:

• 色のコレクションを順番に使用します
• 使用する場面: 値の意味を持たせずにカテゴリを区別する場合

エッジケースとトラブルシューティング

可視化にデータが表示されない

• 原因: データモデルにWeightValuePathまたはColorValuePathフィールドがありません
• 解決策: すべてのデータオブジェクトに必要なプロパティがあることを確認してください

ラベルが表示されない

• 原因: TreeMapFlatLevelでShowLabelsプロパティが設定されていません
• 解決策: 各レベルに対してlevel.ShowLabels = trueを設定してください

色が適用されない

• 原因: LeafColorMappingが設定されていません
• 解決策: 色のマッピングを作成し、TreeMap.LeafColorMappingに割り当ててください

アセンブリ参照エラー

• 原因: Syncfusion.TreeMap.Windowsアセンブリがありません
• 解決策: Syncfusion.TreeMap.WinForms NuGetパッケージをインストールしてください

レベルが正しくグループ化されない

• 原因: GroupPathがデータプロパティ名と一致していません
• 解決策: GroupPathの文字列がプロパティ名と完全に一致していることを確認してください（大文字と小文字は区別されます）

ベストプラクティス

1. 変更される可能性のある動的データにはObservableCollectionを使用します
2. 複数レベルのTreeMapには適切なHeaderHeightを設定します（20～30ピクセル）
3. データの意味に基づいて色のマッピングを選択します（範囲またはグラデーション）
4. データを対話的に探索できるようにツールチップを有効にします
5. レベルを視覚的に分けるにはGroupGapを使用します（5～10ピクセル）
6. レイアウトが適切に機能することを確認するため、実際のデータ量に近いデータでテストします
7. RangeBrushColorMappingを使用する場合は、凡例を用意します
8. 表示寸法に基づいてレイアウトモードを検討します

---

アセンブリ: Syncfusion.TreeMap.Windows
名前空間: Syncfusion.Windows.Forms.TreeMap
NuGetパッケージ: Syncfusion.TreeMap.WinForms