syncfusion-blazor-treemap

实现 TreeMap

NuGet： Syncfusion.Blazor.TreeMap + Syncfusion.Blazor.Themes
命名空间： Syncfusion.Blazor.TreeMap

本技能汇集了实现 Syncfusion Blazor TreeMap 组件所需的全部指南。使用下方导航指南打开所需的特定参考主题；每个参考文件都独立完整，并包含示例、边缘情况和故障排查内容。

官方 API 范围

• 组件：SfTreeMap<TValue>
• 接口：ITreeMap
• 核心子项设置：TreeMapLevels、TreeMapLeafItemSettings、TreeMapLegendSettings、TreeMapTooltipSettings、TreeMapSelectionSettings、TreeMapHighlightSettings、TreeMapEvents
• 常用枚举：LayoutMode、RenderingMode、LabelPosition、LabelPlacement、LabelIntersectAction、LegendMode、LegendPosition、LegendOrientation、LegendShape、SelectionMode、HighLightMode
• 常用事件参数：LoadEventArgs、LoadedEventArgs、ItemRenderingEventArgs、ItemClickEventArgs、ItemSelectedEventArgs、ItemMoveEventArgs、LegendRenderingEventArgs、LegendItemRenderingEventArgs、TreeMapTooltipArgs

何时使用此技能

• 在 Blazor 应用中集成按区域比例呈现的层次结构可视化时。
• 需要有关布局、颜色映射、标签、图例或下钻的指导时。
• 为层次结构或扁平数据集配置数据绑定时。
• 实现无障碍功能、本地化、打印/导出或性能优化时。

⚠️ 安全警告

请勿在未经适当验证的情况下，将 TreeMap 绑定到不受信任的公共 API 或第三方数据源。 远程数据可能被篡改，用于注入恶意代码、破坏可视化效果或发起拒绝服务攻击。请始终：

• ✅ 仅使用由你拥有和控制的内部、经过身份验证的 API
• ✅ 在绑定前验证并清理所有远程数据
• ✅ 实施服务器端授权和速率限制
• ✅ 使用 HTTPS 并验证 SSL/TLS 证书
• ✅ 对字符串属性进行 HTML 编码，以防止 XSS

详细的安全指南请参阅： 数据绑定中的安全注意事项

文档和导航指南

API 参考

📄 阅读： references/api-reference.md

• 快速查阅主要 TreeMap 组件、子项设置、事件、方法和枚举。

入门

📄 阅读： references/getting-started.md

• 安装、NuGet 包、项目设置和最简示例。

数据绑定和数据源

📄 阅读： references/data-binding.md

• 扁平数据与层次结构数据、本地/远程数据源、数据适配器。
• 远程数据绑定：仅绑定到你控制的内部、经过身份验证的 API——请勿直接绑定到不受信任的第三方端点。有关强制安全检查清单和安全模式（服务器端代理、验证、清理、速率限制），请参阅 references/data-binding.md。

布局和层级

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

• 布局算法、层级分组、标题和间距。

叶项

📄 阅读： references/leaf-items.md

• 叶节点样式、模板和标签位置。

颜色映射

📄 阅读： references/color-mapping.md

• 范围、相等、去饱和、调色板映射和策略。

标签

📄 阅读： references/labels.md

• 数据标签模板、格式设置和溢出处理。

图例

📄 阅读： references/legend.md

• 图例模式、位置和智能图例行为。

工具提示

📄 阅读： references/tooltip.md

• 默认工具提示和模板化工具提示、样式及动态内容。

下钻

📄 阅读： references/drill-down.md

• 启用下钻、面包屑导航和自定义导航。

选择与高亮

📄 阅读：references/selection-and-highlight.md

• 选择模式、高亮和编程式选择。

事件与方法

📄 阅读：references/events-and-methods.md

• 生命周期事件、渲染事件、打印/导出方法。

高级功能

📄 阅读：references/advanced-features.md

• 无障碍、本地化、性能，以及在其他组件中放置 TreeMap。

故障排除

📄 阅读：references/troubleshooting.md

• 常见问题、渲染和数据绑定修复方法。

快速入门（最小示例）

@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@Data"> 
  <TreeMapLevels>
    <TreeMapLevel GroupPath="Category" />
  </TreeMapLevels>
</SfTreeMap>

@code {
  public object[] Data = new[] { new { Category = "A", Value = 10 } };
}

常见模式

• 快速选择并逐层深入，以探索层级结构。
• 使用 RangeColorMapping 根据值着色；映射指定颜色时使用 Palette。
• 对于超大型数据集，优先采用服务器端分页/聚合；对于中等规模的数据集，使用客户端渲染。

参考资料

• 所有参考文件都位于 references/ 中，并且自包含目录。

---

实现 Syncfusion Blazor TreeMap

使用 Syncfusion Blazor TreeMap 组件实现层级数据可视化的综合指南。TreeMap 将层级数据显示为嵌套矩形，每个矩形的大小和颜色代表不同的数据维度。

何时使用此技能

在以下情况下使用此技能：

• 可视化层级数据结构——显示组织结构图、文件系统，或具有父子关系的嵌套数据
• 展示比例数据——表示矩形大小反映定量值的数据（销售额、人口、磁盘空间）
• 启用逐层深入导航——允许用户交互式探索多层级层次数据
• 比较数据分布——使用颜色映射展示其他维度（增长、绩效、类别）
• 显示大型数据集——在有限空间内高效可视化数百或数千个数据点
• 创建交互式仪表板——结合选择、高亮、工具提示和图例，提供丰富的用户体验

常见用例：

• 投资组合分析与资产配置
• 市场份额与竞争分析
• 预算与资源分配
• 文件/文件夹大小可视化
• 组织结构展示
• 产品类别销售分析
• 网站分析（页面层级与流量）

组件概述

TreeMap 使用多种布局算法（Squarified、SliceDiceAuto、Horizontal、Vertical）将数据组织为嵌套矩形。每个矩形的大小与指定的数据值成正比，颜色则可通过复杂的颜色映射策略表示其他维度。

主要功能：

• 多种布局算法，实现最佳空间利用率
• 层级数据绑定（扁平或嵌套结构）
• 支持面包屑导航的多级逐层深入
• 高级颜色映射（范围、相等、去饱和度、调色板）
• 支持筛选的交互式图例
• 支持模板的丰富工具提示
• 选择和高亮模式
• 打印与导出（PDF、PNG、JPEG、SVG）
• 全面的无障碍支持（ARIA、键盘导航）

文档与导航指南

入门

📄 阅读：references/getting-started.md

**何时阅读：**首次设置 TreeMap、安装或进行基础实现时

涵盖内容：

• 通过 Visual Studio、VS Code 或 .NET CLI 安装
• NuGet 包设置（Syncfusion.Blazor.TreeMap）
• 服务注册和命名空间导入
• CSS 主题配置
• 使用示例数据进行基本 TreeMap 实现
• 生产环境的许可证注册
• Blazor WebAssembly 与 Web App 的区别

数据绑定和数据源

📄 **阅读：references/data-binding.md

何时阅读： 将 TreeMap 连接到数据源、处理不同的数据结构

涵盖内容：

• 扁平数据结构与层次数据结构
• 本地数据绑定（集合、JSON 文件）
• 带身份验证和授权的远程数据绑定
• 安全注意事项——仅绑定到经过适当身份验证的可信内部 API
• WeightValuePath 和 RangeColorValuePath 配置
• 处理嵌套对象和复杂数据
• Entity Framework 集成
• 数据转换技巧
• 大型数据集的最佳实践

布局和层级

📄 **阅读：references/layout-and-levels.md

何时阅读： 配置 TreeMap 外观、多层结构

涵盖内容：

• 布局算法（Squarified、SliceDiceAuto、Horizontal、Vertical）
• 各种布局类型的适用场景
• 多层 TreeMap 配置
• 针对特定层级的自定义（标题、边框、颜色）
• 使用 GroupPath 组织层次数据
• 间隙和边框配置
• 标题模板和位置

叶节点

📄 **阅读：references/leaf-items.md

何时阅读： 自定义单个 TreeMap 矩形（叶节点）

涵盖内容：

• 叶节点的样式和外观
• 标签格式和位置
• 基于模板的自定义
• 间隙、边框和颜色配置
• 显示/隐藏标签
• 溢出处理
• 交互式叶节点模式

颜色映射

📄 **阅读：references/color-mapping.md

何时阅读： 使用颜色表示数据维度、创建热力图

涵盖内容：

• 范围颜色映射（基于值范围的渐变）
• 等值颜色映射（每个类别使用不同颜色）
• 去饱和度颜色映射（强度变化）
• 多色去饱和度映射
• 调色板颜色映射
• 直接从数据源绑定颜色
• 处理被排除在颜色映射之外的项
• 自定义颜色策略

标签

📄 **阅读：references/labels.md

何时阅读： 为 TreeMap 项添加文本标签

涵盖内容：

• 数据标签配置和格式
• 标签位置选项（Center、TopLeft、TopCenter 等）
• 字体自定义
• 包含自定义内容的标签模板
• 智能标签位置（截断、隐藏、换行）
• 格式字符串和数据绑定
• 响应式标签行为

图例

📄 **阅读：references/legend.md

何时阅读： 添加图例以帮助解读颜色映射

涵盖内容：

• 图例模式（Default、Interactive、Smart）
• 图例位置和对齐方式
• 图例自定义（颜色、形状、文本）
• 带切换功能的智能图例
• 用于自定义渲染的图例模板
• 可见性控制
• 图例与颜色映射的集成

工具提示

📄 **阅读：references/tooltip.md

何时阅读： 为 TreeMap 项添加悬停信息

涵盖内容：

• 默认工具提示配置
• 使用自定义 HTML/Blazor 组件的工具提示模板
• 样式和格式
• 基于数据的动态工具提示内容
• 工具提示位置和动画
• 值的格式字符串
• 适用于不同数据结构的工具提示

下钻导航

📄 **阅读：references/drill-down.md

何时阅读： 启用交互式层次导航

涵盖内容：

• 启用项点击下钻
• 面包屑导航配置
• 下钻标题自定义
• 以编程方式控制下钻
• 下钻事件（ItemClick、DrillStart、DrillEnd）
• 重置为初始视图
• 多层导航模式

选择和高亮

📄 阅读： references/selection-and-highlight.md

阅读时机： 添加用于选择或高亮项的用户交互

涵盖内容：

• 选择模式（Item、Child、Parent、All）
• 单选与多选
• 配置悬停时高亮
• 自定义选择外观（颜色、边框、不透明度）
• 以编程方式选择
• 选择事件（ItemSelected）
• 将选择与下钻结合使用

事件和方法

📄 阅读： references/events-and-methods.md

阅读时机： 处理用户交互、生命周期事件或调用组件方法

涵盖内容：

• 组件生命周期事件（Loaded、BeforeRender）
• 用户交互事件（ItemClick、ItemSelected、ItemHighlight）
• 渲染事件（ItemRendering、TooltipRender、LegendRender）
• 下钻事件（DrillStart、DrillEnd）
• Print() 和 Export() 方法（PDF、PNG、JPEG、SVG）
• Refresh() 和其他实用方法
• 事件处理模式和最佳实践

高级功能

📄 阅读： references/advanced-features.md

阅读时机： 实现打印/导出、本地化、无障碍功能或性能优化

涵盖内容：

• 打印和导出功能（PDF、PNG、JPEG、SVG）
• 国际化和本地化
• RTL（从右到左）支持
• 无障碍功能（ARIA、键盘导航、屏幕阅读器）
• 性能优化技巧
• 响应式设计模式
• 在其他组件中嵌入 TreeMap
• CSP（内容安全策略）合规性

快速入门示例

以下是一个用于快速上手的最小可运行示例：

@page "/treemap-demo"
@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@GrowthReports"
            WeightValuePath="GDP"
            TValue="Country">
    <TreeMapLeafItemSettings LabelPath="Name">
    </TreeMapLeafItemSettings>
</SfTreeMap>

@code {
    public class Country
    {
        public string Name { get; set; }
        public double GDP { get; set; }
    }

    private List<Country> GrowthReports = new List<Country>
    {
        new Country { Name = "United States", GDP = 17946 },
        new Country { Name = "China", GDP = 10866 },
        new Country { Name = "Japan", GDP = 4123 },
        new Country { Name = "Germany", GDP = 3355 },
        new Country { Name = "United Kingdom", GDP = 2848 }
    };
}

先决条件：

• 安装 Syncfusion.Blazor.TreeMap NuGet 包
• 在 Program.cs 中注册服务：builder.Services.AddSyncfusionBlazor();
• 在布局文件中添加主题 CSS 引用
• 在生产环境中注册 Syncfusion 许可证

常见模式

模式 1：通过颜色映射显示分层数据

@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@SalesData"
            WeightValuePath="Sales"
            RangeColorValuePath="Growth"
            TValue="Region">
    <TreeMapLeafItemSettings LabelPath="Name">
        <TreeMapLeafLabelStyle Color="#FFFFFF"></TreeMapLeafLabelStyle>
    </TreeMapLeafItemSettings>
    <TreeMapLegendSettings Visible="true" Position="@using Syncfusion.Blazor.TreeMap.LegendPosition.Top">
    </TreeMapLegendSettings>
    <TreeMapLevels>
        <TreeMapLevel GroupPath="Continent" HeaderFormat="${Continent} - ${Sales}">
            <TreeMapLevelBorder Color="#FFFFFF" Width="1"></TreeMapLevelBorder>
        </TreeMapLevel>
    </TreeMapLevels>
    <TreeMapRangeColorMappings>
        <TreeMapRangeColorMapping From="0" To="5" Color="@("#70AD47")" />
        <TreeMapRangeColorMapping From="5" To="10" Color="@("#FFC000")" />
        <TreeMapRangeColorMapping From="10" To="20" Color="@("#FF5722")" />
    </TreeMapRangeColorMappings>
</SfTreeMap>

适用场景： 显示包含性能指标的分层业务数据

模式 2：通过面包屑导航实现下钻

@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@OrganizationData"
            WeightValuePath="EmployeeCount"
            EnableDrillDown="true"
            TValue="Department">
    <TreeMapLeafItemSettings LabelPath="Name">
    </TreeMapLeafItemSettings>
    <TreeMapBreadcrumbSettings Visible="true">
    </TreeMapBreadcrumbSettings>
    <TreeMapLevels>
        <TreeMapLevel GroupPath="Division" HeaderFormat="${Division}">
        </TreeMapLevel>
        <TreeMapLevel GroupPath="Team" HeaderFormat="${Team}">
        </TreeMapLevel>
    </TreeMapLevels>
</SfTreeMap>

适用场景： 用户需要浏览多层级的组织数据或分层数据

模式 3：带选择和工具提示的交互式 TreeMap

@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@PortfolioData"
            WeightValuePath="Value"
            TValue="Investment">
    <TreeMapLeafItemSettings LabelPath="Name">
    </TreeMapLeafItemSettings>
    <TreeMapTooltipSettings Visible="true">
        <Template>
            @{
                var data = context as Investment;
                <div style="padding:5px;background:#fff;border:1px solid #ccc">
                    <b>@data.Name</b><br/>
                    Value: [email protected]("N0")<br/>
                    Return: @data.Return%
                </div>
            }
        </Template>
    </TreeMapTooltipSettings>
    <TreeMapSelectionSettings Enable="true" Fill="#58a0d3" Opacity="0.8">
    </TreeMapSelectionSettings>
    <TreeMapHighlightSettings Enable="true" Fill="#e5e5e5" Opacity="0.6">
    </TreeMapHighlightSettings>
</SfTreeMap>

适用场景： 构建需要用户参与的交互式仪表板

模式 4：搭配自定义调色板的矩形树图布局

@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@Categories"
            WeightValuePath="Sales"
            LayoutType="LayoutMode.Squarified"
            Palette="@(new string[] {"#9999ff", "#CBCBCB", "#E8DAFF", "#E4E4E4"})"
            TValue="Category">
    <TreeMapLeafItemSettings LabelPath="Name" Fill="#8ebfe2">
        <TreeMapLeafBorder Color="#FFFFFF" Width="2"></TreeMapLeafBorder>
    </TreeMapLeafItemSettings>
    <TreeMapTitleSettings Text="Product Category Sales">
    </TreeMapTitleSettings>
</SfTreeMap>

适用场景： 创建视觉效果鲜明的类别对比图

主要属性和配置

基本属性：

属性	类型	用途
DataSource	IEnumerable	要绑定的数据集合
WeightValuePath	string	决定矩形大小的属性
RangeColorValuePath	string	用于颜色映射的值的属性
TValue	Type	数据项的泛型类型
LayoutType	LayoutMode	布局算法（Squarified、SliceDiceAuto 等）
EnableDrillDown	bool	启用分层导航
Palette	string[]	项目的调色板

子组件：

• TreeMapLeafItemSettings - 叶节点配置
• TreeMapLevels - 多层级结构
• TreeMapRangeColorMappings / TreeMapEqualColorMappings - 颜色策略
• TreeMapLegendSettings - 图例配置
• TreeMapTooltipSettings - 工具提示配置
• TreeMapSelectionSettings - 选择行为
• TreeMapHighlightSettings - 悬停效果

相关技能

• 热力图 - 用于基于矩阵的热力图可视化
• 若要了解其他数据可视化组件，请浏览“数据可视化”类别

故障排除快速提示

• **TreeMap 未渲染：**确保已安装 NuGet 包、已注册服务，并引用了 CSS 主题
• **未显示数据：**验证 WeightValuePath 与数据模型中的数值属性匹配
• **颜色未生效：**检查是否已设置 RangeColorValuePath，并正确配置颜色映射
• **下钻功能未生效：**设置 EnableDrillDown="true"，并使用 GroupPath 配置 TreeMapLevels
• **性能问题：**对于大型数据集（>1000 个项目），可考虑分页或使用下钻进行分层加载

如需了解任何主题的详细信息，请参阅上方导航指南中列出的相应参考文件。