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

• 四种颜色映射类型概览
• 用于应用单一颜色的 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