syncfusion-blazor-treemap

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing TreeMap

实现TreeMap

This skill collects all guidance for implementing the Syncfusion Blazor
TreeMap
component. Use the navigation guide below to open the specific reference topic you need; each reference file is self-contained and includes examples, edge cases, and troubleshooting.
本技能汇总了实现Syncfusion Blazor
TreeMap
组件的所有指南。使用下方的导航指南打开你需要的特定参考主题;每个参考文件都是独立的,包含示例、边缘情况和故障排查内容。

Official API Surface

官方API概览

  • Component:
    SfTreeMap<TValue>
  • Interface:
    ITreeMap
  • Core child settings:
    TreeMapLevels
    ,
    TreeMapLeafItemSettings
    ,
    TreeMapLegendSettings
    ,
    TreeMapTooltipSettings
    ,
    TreeMapSelectionSettings
    ,
    TreeMapHighlightSettings
    ,
    TreeMapEvents
  • Common enums:
    LayoutMode
    ,
    RenderingMode
    ,
    LabelPosition
    ,
    LabelPlacement
    ,
    LabelIntersectAction
    ,
    LegendMode
    ,
    LegendPosition
    ,
    LegendOrientation
    ,
    LegendShape
    ,
    SelectionMode
    ,
    HighLightMode
  • Common event args:
    LoadEventArgs
    ,
    LoadedEventArgs
    ,
    ItemRenderingEventArgs
    ,
    ItemClickEventArgs
    ,
    ItemSelectedEventArgs
    ,
    ItemMoveEventArgs
    ,
    LegendRenderingEventArgs
    ,
    LegendItemRenderingEventArgs
    ,
    TreeMapTooltipArgs
  • 组件:
    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

When to Use This Skill

何时使用本技能

  • When integrating a hierarchical, area-proportional visualization in a Blazor app.
  • When you need guidance on layouts, color-mapping, labels, legends, or drill-down.
  • When configuring data-binding for hierarchical or flat datasets.
  • When implementing accessibility, localization, print/export, or performance optimizations.
  • 在Blazor应用中集成层级化、面积比例可视化时。
  • 需要布局、颜色映射、标签、图例或钻取相关指南时。
  • 为层级或扁平数据集配置数据绑定时。
  • 实现无障碍、本地化、打印/导出或性能优化时。

⚠️ Security Warning

⚠️ 安全警告

DO NOT bind TreeMap to untrusted public APIs or third-party data sources without proper validation. Remote data can be manipulated to inject malicious code, corrupt visualizations, or cause denial-of-service attacks. Always:
  • ✅ Use only internal, authenticated APIs you own and control
  • ✅ Validate and sanitize ALL remote data before binding
  • ✅ Implement server-side authorization and rate limiting
  • ✅ Use HTTPS and verify SSL/TLS certificates
  • ✅ HTML-encode string properties to prevent XSS
For detailed security guidance, see: Security Considerations in data-binding.md
请勿在未进行适当验证的情况下,将TreeMap绑定到不受信任的公共API或第三方数据源。 远程数据可能被篡改以注入恶意代码、破坏可视化效果或导致拒绝服务攻击。请始终遵循以下原则:
  • ✅ 仅使用你拥有并控制的内部、经过身份验证的API
  • ✅ 在绑定前验证并清理所有远程数据
  • ✅ 实现服务器端授权和速率限制
  • ✅ 使用HTTPS并验证SSL/TLS证书
  • ✅ 对字符串属性进行HTML编码以防止XSS攻击
如需详细的安全指南,请参阅: 数据绑定中的安全注意事项.md

Documentation and Navigation Guide

文档与导航指南

API Reference

API参考

📄 Read: references/api-reference.md
  • Quick lookup for the main TreeMap component, child settings, events, methods, and enums.
📄 阅读: references/api-reference.md
  • 快速查阅主要TreeMap组件、子设置、事件、方法和枚举。

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installation, NuGet package, project setup, minimal example.
📄 阅读: references/getting-started.md
  • 安装、NuGet包、项目设置、最简示例。

Data Binding and Sources

数据绑定与数据源

📄 Read: references/data-binding.md
  • Flat vs hierarchical data, local/remote sources, data adaptors.
  • Remote data binding: Only to internal, authenticated APIs you control — do NOT bind directly to untrusted third-party endpoints. See references/data-binding.md for the mandatory security checklist and safe patterns (server-side proxying, validation, sanitization, rate limits).
📄 阅读: references/data-binding.md
  • 扁平数据与层级数据、本地/远程数据源、数据适配器。
  • 远程数据绑定:仅绑定到你控制的内部、经过身份验证的API——请勿直接绑定到不受信任的第三方端点。请参阅references/data-binding.md获取强制安全检查清单和安全模式(服务器端代理、验证、清理、速率限制)。

Layout and Levels

布局与层级

📄 Read: references/layout-and-levels.md
  • Layout algorithms, level grouping, headers and gaps.
📄 阅读: references/layout-and-levels.md
  • 布局算法、层级分组、标题与间距。

Leaf Items

叶子项

📄 Read: references/leaf-items.md
  • Leaf node styling, templates and label positioning.
📄 阅读: references/leaf-items.md
  • 叶子节点样式、模板与标签定位。

Color Mapping

颜色映射

📄 Read: references/color-mapping.md
  • Range, equal, desaturation, palette mappings and strategies.
📄 阅读: references/color-mapping.md
  • 范围、均等、去饱和度、调色板映射及策略。

Labels

标签

📄 Read: references/labels.md
  • Data label templates, formatting and overflow handling.
📄 阅读: references/labels.md
  • 数据标签模板、格式化与溢出处理。

Legend

图例

📄 Read: references/legend.md
  • Legend modes, positioning and smart legend behaviors.
📄 阅读: references/legend.md
  • 图例模式、定位与智能图例行为。

Tooltips

工具提示

📄 Read: references/tooltip.md
  • Default and templated tooltips, styling and dynamic content.
📄 阅读: references/tooltip.md
  • 默认与模板化工具提示、样式与动态内容。

Drill-Down

钻取

📄 Read: references/drill-down.md
  • Enabling drill-down, breadcrumbs, and custom navigation.
📄 阅读: references/drill-down.md
  • 启用钻取、面包屑导航与自定义导航。

Selection & Highlight

选择与高亮

📄 Read: references/selection-and-highlight.md
  • Selection modes, highlight, and programmatic selection.
📄 阅读: references/selection-and-highlight.md
  • 选择模式、高亮与程序化选择。

Events & Methods

事件与方法

📄 Read: references/events-and-methods.md
  • Lifecycle events, render events, print/export methods.
📄 阅读: references/events-and-methods.md
  • 生命周期事件、渲染事件、打印/导出方法。

Advanced Features

高级功能

📄 Read: references/advanced-features.md
  • Accessibility, localization, performance, placing the TreeMap inside other components.
📄 阅读: references/advanced-features.md
  • 无障碍、本地化、性能优化、在其他组件中嵌入TreeMap。

Troubleshooting

故障排查

📄 Read: references/troubleshooting.md
  • Common issues, rendering and data-binding fixes.
📄 阅读: references/troubleshooting.md
  • 常见问题、渲染与数据绑定修复方案。

Quick Start (Minimal example)

快速入门(最简示例)

csharp
@using Syncfusion.Blazor.TreeMap

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

@code {
  public object[] Data = new[] { new { Category = "A", Value = 10 } };
}
csharp
@using Syncfusion.Blazor.TreeMap

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

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

Common Patterns

常见模式

  • Quick selection + drill-down for hierarchical exploration.
  • Use
    RangeColorMapping
    for value-driven coloring and
    Palette
    when mapping explicit colors.
  • Prefer server-side paging/aggregation for very large datasets and use client-side rendering for moderate datasets.
  • 快速选择+钻取用于层级数据探索。
  • 使用
    RangeColorMapping
    实现基于值的颜色驱动,在映射明确颜色时使用
    Palette
  • 对于超大型数据集,优先选择服务器端分页/聚合;中等数据集使用客户端渲染。

References

参考资料

  • All reference files are in
    references/
    and are self-contained with TOCs.

  • 所有参考文件均位于
    references/
    目录下,且包含目录,独立完整。

Implementing Syncfusion Blazor TreeMap

实现Syncfusion Blazor TreeMap

A comprehensive guide for implementing hierarchical data visualization using Syncfusion Blazor TreeMap component. TreeMaps display hierarchical data as nested rectangles where the size and color of each rectangle represents different data dimensions.
一份使用Syncfusion Blazor TreeMap组件实现层级数据可视化的综合指南。树形图将层级数据显示为嵌套矩形,每个矩形的大小和颜色代表不同的数据维度。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Visualize hierarchical data structures - Display organizational charts, file systems, or nested data with parent-child relationships
  • Show proportional data - Represent data where rectangle size reflects quantitative values (sales, population, disk space)
  • Enable drill-down navigation - Allow users to interactively explore multi-level hierarchical data
  • Compare data distributions - Use color mapping to show additional dimensions (growth, performance, categories)
  • Display large datasets - Efficiently visualize hundreds or thousands of data points in limited space
  • Create interactive dashboards - Combine with selection, highlighting, tooltips, and legends for rich user experience
Common Use Cases:
  • Portfolio analysis and asset allocation
  • Market share and competitive analysis
  • Budget and resource distribution
  • File/folder size visualization
  • Organizational structure displays
  • Product category sales analysis
  • Website analytics (page hierarchy and traffic)
在以下场景中使用本技能:
  • 可视化层级数据结构 - 展示组织结构图、文件系统或具有父子关系的嵌套数据
  • 展示比例数据 - 用矩形大小反映定量值(销售额、人口、磁盘空间)
  • 启用钻取导航 - 允许用户交互式探索多层级数据
  • 比较数据分布 - 使用颜色映射展示额外维度(增长、性能、类别)
  • 展示大型数据集 - 在有限空间内高效可视化数百或数千个数据点
  • 创建交互式仪表盘 - 结合选择、高亮、工具提示和图例实现丰富的用户体验
常见用例:
  • 投资组合分析与资产配置
  • 市场份额与竞品分析
  • 预算与资源分配
  • 文件/文件夹大小可视化
  • 组织结构展示
  • 产品类别销售分析
  • 网站分析(页面层级与流量)

Component Overview

组件概述

The TreeMap component organizes data into nested rectangles using various layout algorithms (Squarified, SliceDiceAuto, Horizontal, Vertical). Each rectangle's size is proportional to a specified data value, and colors can represent additional dimensions through sophisticated color mapping strategies.
Key Capabilities:
  • Multiple layout algorithms for optimal space utilization
  • Hierarchical data binding (flat or nested structures)
  • Multi-level drill-down with breadcrumb navigation
  • Advanced color mapping (range, equal, desaturation, palette)
  • Interactive legends with filtering
  • Rich tooltips with templates
  • Selection and highlight modes
  • Print and export (PDF, PNG, JPEG, SVG)
  • Full accessibility support (ARIA, keyboard navigation)
TreeMap组件使用多种布局算法(Squarified、SliceDiceAuto、Horizontal、Vertical)将数据组织为嵌套矩形。每个矩形的大小与指定的数据值成比例,颜色可通过复杂的颜色映射策略表示额外维度。
核心功能:
  • 多种布局算法以优化空间利用率
  • 层级数据绑定(扁平或嵌套结构)
  • 带面包屑导航的多层级钻取
  • 高级颜色映射(范围、均等、去饱和度、调色板)
  • 带筛选功能的交互式图例
  • 支持模板的丰富工具提示
  • 选择与高亮模式
  • 打印与导出(PDF、PNG、JPEG、SVG)
  • 完整的无障碍支持(ARIA、键盘导航)

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
When to read: Setting up TreeMap for the first time, installation, basic implementation
What's covered:
  • Installation via Visual Studio, VS Code, or .NET CLI
  • NuGet package setup (Syncfusion.Blazor.TreeMap)
  • Service registration and namespace imports
  • CSS theme configuration
  • Basic TreeMap implementation with sample data
  • License registration for production
  • Blazor WebAssembly vs Web App differences
📄 阅读: references/getting-started.md
阅读时机: 首次设置TreeMap、安装、基础实现时
涵盖内容:
  • 通过Visual Studio、VS Code或.NET CLI进行安装
  • NuGet包设置(Syncfusion.Blazor.TreeMap)
  • 服务注册与命名空间导入
  • CSS主题配置
  • 带示例数据的基础TreeMap实现
  • 生产环境的许可证注册
  • Blazor WebAssembly与Web App的差异

Data Binding and Sources

数据绑定与数据源

📄 Read: references/data-binding.md
When to read: Connecting TreeMap to data sources, handling different data structures
What's covered:
  • Flat data structure vs hierarchical data structure
  • Local data binding (collections, JSON files)
  • Remote data binding with authentication and authorization
  • Security considerations - Only bind to trusted internal APIs with proper authentication
  • WeightValuePath and RangeColorValuePath configuration
  • Handling nested objects and complex data
  • Entity Framework integration
  • Data transformation techniques
  • Best practices for large datasets
📄 阅读: references/data-binding.md
阅读时机: 连接TreeMap到数据源、处理不同数据结构时
涵盖内容:
  • 扁平数据结构与层级数据结构
  • 本地数据绑定(集合、JSON文件)
  • 带身份验证与授权的远程数据绑定
  • 安全注意事项 - 仅绑定到受信任的内部API并进行适当身份验证
  • WeightValuePath与RangeColorValuePath配置
  • 处理嵌套对象与复杂数据
  • Entity Framework集成
  • 数据转换技巧
  • 大型数据集的最佳实践

Layout and Hierarchy

布局与层级

📄 Read: references/layout-and-levels.md
When to read: Configuring TreeMap appearance, multi-level structures
What's covered:
  • Layout algorithms (Squarified, SliceDiceAuto, Horizontal, Vertical)
  • When to use each layout type
  • Multi-level TreeMap configuration
  • Level-specific customization (headers, borders, colors)
  • GroupPath for hierarchical data organization
  • Gap and border configuration
  • Header templates and positioning
📄 阅读: references/layout-and-levels.md
阅读时机: 配置TreeMap外观、多层级结构时
涵盖内容:
  • 布局算法(Squarified、SliceDiceAuto、Horizontal、Vertical)
  • 每种布局类型的适用场景
  • 多层级TreeMap配置
  • 层级特定自定义(标题、边框、颜色)
  • 用于层级数据组织的GroupPath
  • 间距与边框配置
  • 标题模板与定位

Leaf Items

叶子项

📄 Read: references/leaf-items.md
When to read: Customizing individual TreeMap rectangles (leaf nodes)
What's covered:
  • Leaf item styling and appearance
  • Label formatting and positioning
  • Template-based customization
  • Gap, border, and color configuration
  • Show/hide labels
  • Overflow handling
  • Interactive leaf patterns
📄 阅读: references/leaf-items.md
阅读时机: 自定义单个TreeMap矩形(叶子节点)时
涵盖内容:
  • 叶子项样式与外观
  • 标签格式化与定位
  • 基于模板的自定义
  • 间距、边框与颜色配置
  • 显示/隐藏标签
  • 溢出处理
  • 交互式叶子项模式

Color Mapping

颜色映射

📄 Read: references/color-mapping.md
When to read: Applying colors to represent data dimensions, creating heat maps
What's covered:
  • Range color mapping (gradients based on value ranges)
  • Equal color mapping (distinct colors per category)
  • Desaturation color mapping (intensity variations)
  • Desaturation with multiple colors
  • Palette color mapping
  • Binding colors directly from data source
  • Handling items excluded from color mapping
  • Custom color strategies
📄 阅读: references/color-mapping.md
阅读时机: 应用颜色表示数据维度、创建热力图时
涵盖内容:
  • 范围颜色映射(基于值范围的渐变)
  • 均等颜色映射(每个类别使用不同颜色)
  • 去饱和度颜色映射(强度变化)
  • 多颜色去饱和度
  • 调色板颜色映射
  • 直接从数据源绑定颜色
  • 处理未纳入颜色映射的项
  • 自定义颜色策略

Labels

标签

📄 Read: references/labels.md
When to read: Adding text labels to TreeMap items
What's covered:
  • Data label configuration and formatting
  • Label positioning options (Center, TopLeft, TopCenter, etc.)
  • Font customization
  • Label templates with custom content
  • Smart label positioning (trim, hide, wrap)
  • Format strings and data binding
  • Responsive label behavior
📄 阅读: references/labels.md
阅读时机: 为TreeMap项添加文本标签时
涵盖内容:
  • 数据标签配置与格式化
  • 标签定位选项(Center、TopLeft、TopCenter等)
  • 字体自定义
  • 带自定义内容的标签模板
  • 智能标签定位(截断、隐藏、换行)
  • 格式字符串与数据绑定
  • 响应式标签行为

Legend

图例

📄 Read: references/legend.md
When to read: Adding legends for color mapping interpretation
What's covered:
  • Legend modes (Default, Interactive, Smart)
  • Legend positioning and alignment
  • Legend customization (colors, shapes, text)
  • Smart legend with toggle functionality
  • Legend templates for custom rendering
  • Visibility control
  • Legend integration with color mappings
📄 阅读: references/legend.md
阅读时机: 添加图例以解释颜色映射时
涵盖内容:
  • 图例模式(Default、Interactive、Smart)
  • 图例定位与对齐
  • 图例自定义(颜色、形状、文本)
  • 带切换功能的智能图例
  • 用于自定义渲染的图例模板
  • 可见性控制
  • 图例与颜色映射的集成

Tooltips

工具提示

📄 Read: references/tooltip.md
When to read: Adding hover information to TreeMap items
What's covered:
  • Default tooltip configuration
  • Tooltip templates with custom HTML/Blazor components
  • Styling and formatting
  • Dynamic tooltip content based on data
  • Tooltip positioning and animation
  • Format strings for values
  • Tooltips for different data structures
📄 阅读: references/tooltip.md
阅读时机: 为TreeMap项添加悬停信息时
涵盖内容:
  • 默认工具提示配置
  • 带自定义HTML/Blazor组件的工具提示模板
  • 样式与格式化
  • 基于数据的动态工具提示内容
  • 工具提示定位与动画
  • 值的格式字符串
  • 不同数据结构的工具提示

Drill-Down Navigation

钻取导航

📄 Read: references/drill-down.md
When to read: Enabling interactive hierarchical navigation
What's covered:
  • Enabling drill-down on item click
  • Breadcrumb navigation configuration
  • Header customization for drill-down
  • Programmatic drill-down control
  • Drill-down events (ItemClick, DrillStart, DrillEnd)
  • Resetting to initial view
  • Multi-level navigation patterns
📄 阅读: references/drill-down.md
阅读时机: 启用交互式层级导航时
涵盖内容:
  • 点击项时启用钻取
  • 面包屑导航配置
  • 钻取的标题自定义
  • 程序化钻取控制
  • 钻取事件(ItemClick、DrillStart、DrillEnd)
  • 重置至初始视图
  • 多层级导航模式

Selection and Highlight

选择与高亮

📄 Read: references/selection-and-highlight.md
When to read: Adding user interaction for selecting/highlighting items
What's covered:
  • Selection modes (Item, Child, Parent, All)
  • Single vs multiple selection
  • Highlight on hover configuration
  • Customizing selection appearance (colors, borders, opacity)
  • Programmatic selection
  • Selection events (ItemSelected)
  • Combining selection with drill-down
📄 阅读: references/selection-and-highlight.md
阅读时机: 添加选择/高亮项的用户交互时
涵盖内容:
  • 选择模式(Item、Child、Parent、All)
  • 单选与多选
  • 悬停高亮配置
  • 自定义选择外观(颜色、边框、透明度)
  • 程序化选择
  • 选择事件(ItemSelected)
  • 选择与钻取的结合

Events and Methods

事件与方法

📄 Read: references/events-and-methods.md
When to read: Handling user interactions, lifecycle events, or invoking component methods
What's covered:
  • Component lifecycle events (Loaded, BeforeRender)
  • User interaction events (ItemClick, ItemSelected, ItemHighlight)
  • Rendering events (ItemRendering, TooltipRender, LegendRender)
  • Drill-down events (DrillStart, DrillEnd)
  • Print() and Export() methods (PDF, PNG, JPEG, SVG)
  • Refresh() and other utility methods
  • Event handling patterns and best practices
📄 阅读: references/events-and-methods.md
阅读时机: 处理用户交互、生命周期事件或调用组件方法时
涵盖内容:
  • 组件生命周期事件(Loaded、BeforeRender)
  • 用户交互事件(ItemClick、ItemSelected、ItemHighlight)
  • 渲染事件(ItemRendering、TooltipRender、LegendRender)
  • 钻取事件(DrillStart、DrillEnd)
  • Print()与Export()方法(PDF、PNG、JPEG、SVG)
  • Refresh()及其他实用方法
  • 事件处理模式与最佳实践

Advanced Features

高级功能

📄 Read: references/advanced-features.md
When to read: Implementing print/export, localization, accessibility, or performance optimization
What's covered:
  • Print and export functionality (PDF, PNG, JPEG, SVG)
  • Internationalization and localization
  • RTL (right-to-left) support
  • Accessibility features (ARIA, keyboard navigation, screen readers)
  • Performance optimization techniques
  • Responsive design patterns
  • Embedding TreeMap in other components
  • CSP (Content Security Policy) compliance
📄 阅读: references/advanced-features.md
阅读时机: 实现打印/导出、本地化、无障碍或性能优化时
涵盖内容:
  • 打印与导出功能(PDF、PNG、JPEG、SVG)
  • 国际化与本地化
  • RTL(从右到左)支持
  • 无障碍功能(ARIA、键盘导航、屏幕阅读器)
  • 性能优化技巧
  • 响应式设计模式
  • 在其他组件中嵌入TreeMap
  • CSP(内容安全策略)合规

Quick Start Example

快速入门示例

Here's a minimal working example to get started:
razor
@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 }
    };
}
Prerequisites:
  • Install
    Syncfusion.Blazor.TreeMap
    NuGet package
  • Register services in
    Program.cs
    :
    builder.Services.AddSyncfusionBlazor();
  • Add theme CSS reference in layout file
  • Register Syncfusion license for production use
以下是一个可运行的最简入门示例:
razor
@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许可证

Common Patterns

常见模式

Pattern 1: Hierarchical Data with Color Mapping

模式1:带颜色映射的层级数据

razor
@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>
Use when: Displaying hierarchical business data with performance indicators
razor
@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>
适用场景: 展示带绩效指标的层级业务数据

Pattern 2: Drill-Down with Breadcrumb Navigation

模式2:带面包屑导航的钻取

razor
@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>
Use when: Users need to navigate through multi-level organizational or hierarchical data
razor
@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>
适用场景: 用户需要浏览多层级组织或层级数据时

Pattern 3: Interactive TreeMap with Selection and Tooltips

模式3:带选择与工具提示的交互式TreeMap

razor
@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: $@data.Value.ToString("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>
Use when: Building interactive dashboards requiring user engagement
razor
@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: $@data.Value.ToString("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>
适用场景: 构建需要用户参与的交互式仪表盘时

Pattern 4: Squarified Layout with Custom Palette

模式4:带自定义调色板的Squarified布局

razor
@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>
Use when: Creating visually distinct category comparisons
razor
@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>
适用场景: 创建视觉区分明显的类别对比时

Key Props and Configuration

核心属性与配置

Essential Properties:
PropertyTypePurpose
DataSource
IEnumerable<TValue>Data collection to bind
WeightValuePath
stringProperty determining rectangle size
RangeColorValuePath
stringProperty for color mapping values
TValue
TypeGeneric type of data items
LayoutType
LayoutModeLayout algorithm (Squarified, SliceDiceAuto, etc.)
EnableDrillDown
boolEnable hierarchical navigation
Palette
string[]Color palette for items
Child Components:
  • TreeMapLeafItemSettings
    - Leaf node configuration
  • TreeMapLevels
    - Multi-level hierarchy
  • TreeMapRangeColorMappings
    /
    TreeMapEqualColorMappings
    - Color strategies
  • TreeMapLegendSettings
    - Legend configuration
  • TreeMapTooltipSettings
    - Tooltip configuration
  • TreeMapSelectionSettings
    - Selection behavior
  • TreeMapHighlightSettings
    - Hover effects
关键属性:
属性类型用途
DataSource
IEnumerable<TValue>要绑定的数据集合
WeightValuePath
string决定矩形大小的属性
RangeColorValuePath
string用于颜色映射的值属性
TValue
Type数据项的泛型类型
LayoutType
LayoutMode布局算法(Squarified、SliceDiceAuto等)
EnableDrillDown
bool启用层级导航
Palette
string[]项的颜色调色板
子组件:
  • TreeMapLeafItemSettings
    - 叶子节点配置
  • TreeMapLevels
    - 多层级结构
  • TreeMapRangeColorMappings
    /
    TreeMapEqualColorMappings
    - 颜色策略
  • TreeMapLegendSettings
    - 图例配置
  • TreeMapTooltipSettings
    - 工具提示配置
  • TreeMapSelectionSettings
    - 选择行为
  • TreeMapHighlightSettings
    - 悬停效果

Related Skills

相关技能

  • HeatMap Chart - For matrix-based heat map visualization
  • For other data visualization components, explore the Data Visualization category
  • 热力图图表 - 用于基于矩阵的热力图可视化
  • 如需其他数据可视化组件,请探索数据可视化类别

Troubleshooting Quick Tips

故障排查快速提示

  • TreeMap not rendering: Ensure NuGet package is installed, services are registered, and CSS theme is referenced
  • Data not displaying: Verify
    WeightValuePath
    matches a numeric property in your data model
  • Colors not applying: Check that
    RangeColorValuePath
    is set and color mappings are properly configured
  • Drill-down not working: Set
    EnableDrillDown="true"
    and configure
    TreeMapLevels
    with
    GroupPath
  • Performance issues: For large datasets (>1000 items), consider pagination or hierarchical loading with drill-down
For comprehensive details on any topic, refer to the appropriate reference file listed in the navigation guide above.
  • TreeMap未渲染: 确保已安装NuGet包、注册服务并引用CSS主题
  • 数据未显示: 验证
    WeightValuePath
    与数据模型中的数值属性匹配
  • 颜色未应用: 检查是否设置了
    RangeColorValuePath
    且颜色映射配置正确
  • 钻取不工作: 设置
    EnableDrillDown="true"
    并为
    TreeMapLevels
    配置
    GroupPath
  • 性能问题: 对于大型数据集(>1000项),考虑分页或结合钻取的层级加载
如需任何主题的详细信息,请参阅上方导航指南中列出的对应参考文件。