syncfusion-wpf-treemap

实现 Syncfusion WPF TreeMap（SfTreeMap）

何时使用此技能

当用户需要以下功能时，请使用此技能：

• 可视化层次结构数据，以嵌套且大小各异的矩形表示数量
• 显示大型数据集，其中 TreeMap 的高空间利用率布局非常理想
• 实现数据可视化，用于股票市场分析、使用情况统计或分类数据
• 创建热力图，其中颜色表示数值，大小表示权重
• 构建 WPF 应用程序，需要使用 Syncfusion TreeMap 控件（SfTreeMap）
• 自定义 TreeMap 布局、颜色、层级或交互功能
• 配置数据绑定，以支持层次结构或扁平数据结构

此技能涵盖 Syncfusion WPF TreeMap 的完整实现，从基本设置到下钻、颜色映射和自定义模板等高级功能。

组件概述

Syncfusion WPF TreeMap（SfTreeMap） 是一种数据可视化控件，可将层次结构信息显示为一组聚集的矩形。每个矩形的大小表示定量值（权重），其颜色可以表示数据的另一个维度。

主要功能：

• 多种布局算法（Squarified、SliceAndDice 变体）
• 灵活的颜色映射策略（纯色、范围、去饱和度、调色板、按组映射）
• 可自定义标题的层次
• 交互功能（选择、工具提示、下钻）
• 全面的数据绑定支持
• 无障碍功能和键盘导航
• 主题支持

常见用例：

1. 股票市场分析 - 矩形大小 = 股票权重，颜色 = 涨跌
2. 互联网使用情况可视化 - 按类型对流量分类（零售、社交、搜索）
3. 新闻聚合 - 颜色 = 版块（商业/政治），大小 = 新闻数量
4. 天气分析 - 不透明度/颜色 = 湿度，大小 = 地理区域

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序包设置
• 程序集和命名空间参考（Syncfusion.SfTreeMap.WPF）
• 通过 Visual Studio、Expression Blend 或代码创建 TreeMap
• 在 XAML 和 C# 中配置基本 TreeMap
• 使用数据模型设置 ItemsSource
• 配置 DataContext
• 使用人口数据构建首个可运行示例
• 主题支持（SfSkinManager、ThemeStudio）

布局模式

📄 阅读： references/layout-modes.md

• 可用的布局算法
• Squarified 布局（默认，优化纵横比）
• SliceAndDiceAuto（按层级交替使用水平/垂直切分）
• SliceAndDiceHorizontal（仅水平切分）
• SliceAndDiceVertical（仅垂直切分）
• 为数据选择合适的布局
• 性能注意事项

数据绑定和配置

📄 阅读： references/data-binding.md

• WeightValuePath 属性（确定矩形大小）
• ColorValuePath 属性（驱动颜色映射）
• 将 ItemsSource 绑定到集合
• 数据模型的要求和结构
• 层次结构与扁平数据绑定
• 支持的集合类型（ObservableCollection、List 等）

颜色映射

📄 阅读： references/color-mapping.md

• 颜色映射概述和类型
• UniColorMapping（为所有叶节点设置纯色）
• RangeBrushColorMapping（根据数值范围设置颜色）
• DesaturationColorMapping（通过不透明度范围突出显示视觉重点）
• PaletteColorMapping（循环使用颜色集合）
• GroupColorMapping（为不同组设置不同颜色）
• LeafColorMapping 与 TreeMapLevel ColorMapping 的区别
• 为叶节点与标题应用颜色

TreeMap 层级与层次结构

📄 阅读： references/levels-and-hierarchy.md

• 使用 TreeMapFlatLevel 对扁平数据进行分组
• 使用 GroupPath 属性进行层次化组织
• 配置多个层级
• 使用 GroupGap 设置组间距
• 配置标头（HeaderHeight、ShowHeader）
• 标头模板和样式
• 使用 ShowLabels 属性显示叶节点标签
• 创建嵌套层次结构

叶节点自定义

📄 阅读： references/leaf-customization.md

• LeafItemSettings 概述
• 边框自定义（LeafBorderBrush、LeafBorderThickness）
• 使用 LeafLabelPath 显示叶节点文本
• 使用 LeafTemplate 自定义叶节点 UI
• 标签定位和格式设置
• 自定义单个叶节点的外观
• 复杂叶节点内容的模板示例

标头和标签

📄 阅读： references/headers-and-labels.md

• 标头模板（HeaderTemplate 属性）
• 标头样式和自定义
• 标签可见性和内容控制
• 使用数据绑定自定义标头内容
• 在层级内定位标头

交互功能

📄 阅读： references/interactive-features.md

• 支持选择（单选和多选）
• SelectionModes（Default、Multiple）
• SelectedItems 属性和选择事件
• 工具提示配置和显示
• 使用 TooltipTemplate 自定义工具提示
• 支持下钻导航
• 自定义 DrillDownHeaderTemplate
• EnableDrillDown 属性

图例

📄 阅读： references/legend.md

• 图例概述和用途
• ShowLegend 属性
• LegendType（Gradient、DockPosition）
• 配置 LegendHeight 和 LegendWidth
• 使用 LegendTemplate 自定义图例
• 图例位置选项

无障碍

📄 阅读： references/accessibility.md

• 支持键盘导航
• 使用 Tab 和 Shift+Tab 在项目之间导航
• SelectionModes 对键盘行为的影响
• WCAG 合规功能
• 屏幕阅读器支持

快速入门示例

下面是一个最简示例，用于创建显示人口数据的功能性 TreeMap：

<Window x:Class="TreeMapDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:syncfusion="clr-namespace:Syncfusion.UI.Xaml.TreeMap;assembly=Syncfusion.SfTreeMap.WPF"
        Title="TreeMap Demo" WindowState="Maximized">
    <Grid>
        <Grid.DataContext>
            <local:PopulationViewModel/>
        </Grid.DataContext>
        
        <syncfusion:SfTreeMap ItemsSource="{Binding PopulationDetails}" 
                              WeightValuePath="Population"
                              ColorValuePath="Growth"
                              ItemsLayoutMode="Squarified">
            
            
            <syncfusion:SfTreeMap.LeafColorMapping>
                <syncfusion:RangeBrushColorMapping>
                    <syncfusion:RangeBrushColorMapping.Brushes>
                        <syncfusion:RangeBrush From="0" To="1" Color="#A4C400"/>
                        <syncfusion:RangeBrush From="1" To="2" Color="#AA00FF"/>
                        <syncfusion:RangeBrush From="2" To="3" Color="#F0A30A"/>
                        <syncfusion:RangeBrush From="3" To="4" Color="#1BA1E2"/>
                    </syncfusion:RangeBrushColorMapping.Brushes>
                </syncfusion:RangeBrushColorMapping>
            </syncfusion:SfTreeMap.LeafColorMapping>
            
            
            <syncfusion:SfTreeMap.Levels>
                <syncfusion:TreeMapFlatLevel GroupPath="Continent" 
                                             GroupGap="10"
                                             HeaderHeight="30">
                    <syncfusion:TreeMapFlatLevel.HeaderTemplate>
                        <DataTemplate>
                            <TextBlock Text="{Binding Header}" 
                                      Foreground="#D6D6D6" 
                                      FontSize="18" 
                                      FontWeight="Light"/>
                        </DataTemplate>
                    </syncfusion:TreeMapFlatLevel.HeaderTemplate>
                </syncfusion:TreeMapFlatLevel>
            </syncfusion:SfTreeMap.Levels>
        </syncfusion:SfTreeMap>
    </Grid>
</Window>

// ViewModel with sample data
public class PopulationViewModel
{
    public ObservableCollection<PopulationDetail> PopulationDetails { get; set; }
    
    public PopulationViewModel()
    {
        PopulationDetails = new ObservableCollection<PopulationDetail>
        {
            new PopulationDetail { Continent = "Asia", Country = "Indonesia", Growth = 3, Population = 237641326 },
            new PopulationDetail { Continent = "Asia", Country = "Russia", Growth = 2, Population = 152518015 },
            new PopulationDetail { Continent = "North America", Country = "United States", Growth = 4, Population = 315645000 },
            new PopulationDetail { Continent = "Europe", Country = "Germany", Growth = 1, Population = 81993000 }
        };
    }
}

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

常见模式

模式 1：具有单个层级的基本 TreeMap

显示没有层次分组的扁平数据时：

<syncfusion:SfTreeMap ItemsSource="{Binding Items}" 
                      WeightValuePath="Value"
                      ItemsLayoutMode="Squarified">
    <syncfusion:SfTreeMap.LeafColorMapping>
        <syncfusion:UniColorMapping Color="Crimson"/>
    </syncfusion:SfTreeMap.LeafColorMapping>
</syncfusion:SfTreeMap>

模式 2：多层级层次结构

显示嵌套层次数据时（例如，大洲 → 国家）：

<syncfusion:SfTreeMap.Levels>
    <syncfusion:TreeMapFlatLevel GroupPath="Continent" GroupGap="10" HeaderHeight="30"/>
    <syncfusion:TreeMapFlatLevel GroupPath="Country" GroupGap="5" HeaderHeight="20" ShowLabels="True"/>
</syncfusion:SfTreeMap.Levels>

模式 3：基于范围的颜色映射

根据数值范围为矩形着色时：

<syncfusion:SfTreeMap.LeafColorMapping>
    <syncfusion:RangeBrushColorMapping>
        <syncfusion:RangeBrushColorMapping.Brushes>
            <syncfusion:RangeBrush From="0" To="25" Color="LightGreen"/>
            <syncfusion:RangeBrush From="25" To="50" Color="Yellow"/>
            <syncfusion:RangeBrush From="50" To="75" Color="Orange"/>
            <syncfusion:RangeBrush From="75" To="100" Color="Red"/>
        </syncfusion:RangeBrushColorMapping.Brushes>
    </syncfusion:RangeBrushColorMapping>
</syncfusion:SfTreeMap.LeafColorMapping>

模式 4：选择和交互

启用用户交互时：

<syncfusion:SfTreeMap SelectionModes="Multiple">
    
</syncfusion:SfTreeMap>

模式 5：自定义工具提示

悬停时显示详细信息：

<syncfusion:SfTreeMap>
    <syncfusion:SfTreeMap.TooltipTemplate>
        <DataTemplate>
            <StackPanel Background="White" Margin="5">
                <TextBlock Text="{Binding Country}" FontWeight="Bold"/>
                <TextBlock Text="{Binding Population, StringFormat='Population: {0:N0}'}"/>
            </StackPanel>
        </DataTemplate>
    </syncfusion:SfTreeMap.TooltipTemplate>
</syncfusion:SfTreeMap>

关键属性

基本属性

• ItemsSource - 要可视化的数据对象集合
• WeightValuePath - 决定矩形大小的属性名称
• ColorValuePath - 决定颜色映射值的属性名称
• ItemsLayoutMode - 布局算法（Squarified、SliceAndDiceAuto 等）

颜色映射属性

• LeafColorMapping - 叶节点的颜色映射策略
• RangeBrushColorMapping.Brushes - 用于基于数值着色的颜色范围
• DesaturationColorMapping - 基于不透明度的颜色映射
• PaletteColorMapping.Colors - 用于循环使用的颜色集合

层级配置

• Levels - TreeMapFlatLevel 对象集合
• GroupPath - 用于在每个层级对数据分组的属性名称
• GroupGap - 组间距（以像素为单位）
• HeaderHeight - 组标头高度
• HeaderTemplate - 标头的自定义模板
• ShowHeader - 显示/隐藏某个层级的标头
• ShowLabels - 显示/隐藏叶节点上的标签

叶节点自定义

• LeafItemSettings - 叶节点外观设置
• LeafBorderBrush - 叶节点边框颜色
• LeafBorderThickness - 叶节点边框粗细
• LeafLabelPath - 叶节点标签的属性名称
• LeafTemplate - 叶节点内容的自定义模板

交互功能

• SelectionModes - 选择行为（Default、Multiple）
• SelectedItems - 当前选中项的集合
• TooltipTemplate - 工具提示的自定义模板
• EnableDrillDown - 启用下钻导航
• DrillDownHeaderTemplate - 下钻标题模板

图例属性

• ShowLegend - 显示/隐藏图例
• LegendType - 图例显示类型
• LegendHeight/LegendWidth - 图例尺寸
• LegendTemplate - 图例的自定义模板

常见用例

用例 1：股票投资组合可视化

展示股票持仓，其中矩形大小 = 投资金额，颜色 = 表现：

指导： 使用 RangeBrushColorMapping 设置从负值（红色）到正值（绿色）的范围。将 WeightValuePath 设置为投资金额，将 ColorValuePath 设置为涨跌百分比。

参考： color-mapping.md、data-binding.md

用例 2：磁盘空间使用情况分析

展示文件系统层级中的文件夹大小：

指导： 使用多层 TreeMapFlatLevel 和 GroupPath 表示文件夹层级。将 WeightValuePath 设置为文件大小。可考虑使用 SliceAndDiceAuto 布局以提高可读性。

参考： levels-and-hierarchy.md、layout-modes.md

用例 3：销售业绩仪表板

按区域和销售人员展示销售额：

指导： 创建两个层级（区域 → 销售人员），使用 DesaturationColorMapping 以更鲜明的颜色突出表现最佳者。启用工具提示以显示详细指标。

参考： interactive-features.md、levels-and-hierarchy.md

用例 4：网站流量分析

按类别和页面可视化页面浏览量：

指导： 使用 PaletteColorMapping 为不同类别设置不同颜色。添加自定义 LeafTemplate 以显示页面名称和指标。启用下钻导航。

参考： color-mapping.md、leaf-customization.md、interactive-features.md

用例 5：天气数据可视化

按地理区域展示温度或降水数据：

指导： 使用 DesaturationColorMapping，以不透明度表示湿度/降水量。设置 GroupColorMapping，为不同区域指定基色。

参考： color-mapping.md

程序集和命名空间

程序集： Syncfusion.SfTreeMap.WPF
命名空间： Syncfusion.UI.Xaml.TreeMap

将此命名空间添加到 XAML 中：

xmlns:syncfusion="clr-namespace:Syncfusion.UI.Xaml.TreeMap;assembly=Syncfusion.SfTreeMap.WPF"

其他资源

主题支持：

• 使用 SfSkinManager 应用主题
• 使用 ThemeStudio 创建自定义主题
• 参见：references/getting-started.md

无障碍功能：

• 键盘导航（Tab/Shift+Tab）
• 符合 WCAG 标准
• 参见：references/accessibility.md

---

后续步骤：

1. 查看 getting-started.md，了解安装和设置
2. 从 layout-modes.md 中选择合适的布局
3. 使用 data-binding.md 配置数据绑定
4. 应用 color-mapping.md 中的颜色映射策略
5. 根据需要，从 levels-and-hierarchy.md 添加层级和层次结构