syncfusion-blazor-heatmap-chart

实现 Syncfusion Blazor HeatMap Chart

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

本指南全面介绍如何实现 Syncfusion Blazor HeatMap Chart 组件，使用矩阵布局中的颜色编码单元格来可视化多维数据。

何时使用此技能

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

• 可视化矩阵数据，使用颜色渐变表示数值
• 显示相关矩阵或跨两个维度的比较数据
• 创建热度或密度可视化，展示数据强度
• 显示表格数据，其中单元格颜色表示大小或类别
• 实现气泡 HeatMap，结合大小和颜色来表示多个数据维度
• 构建数据仪表板，需要直观的网格可视化
• 显示时间序列数据，使用类别轴或日期时间轴
• 通过交互式工具提示和图例可视化大型数据集
• 创建无障碍数据可视化，具备符合 WCAG 的功能

组件概述

Syncfusion Blazor HeatMap Chart 组件（SfHeatMap）是一款强大的数据可视化工具，可将多维数据显示为单元格矩阵，其中每个单元格的颜色代表其值。它支持：

• 多种数据绑定模式：数组（2D）、JSON/表格和单元格
• 灵活的轴类型：类别、数值和日期时间，并支持多级标签
• 两种可视化模式：矩形单元格和气泡 HeatMap
• 丰富的自定义选项：调色板（渐变/固定）、图例、工具提示、标题和标签
• 交互功能：单元格选择、事件和动态渲染
• 无障碍支持：符合 WCAG 标准、键盘导航和屏幕阅读器支持
• 高级功能：支持内容安全策略、自适应尺寸和性能优化

文档和导航指南

入门和安装

📄 阅读： references/getting-started.md

• 先决条件和系统要求
• 创建 Blazor WebAssembly 应用（Visual Studio、VS Code、.NET CLI）
• 安装 Syncfusion.Blazor.HeatMap NuGet 包
• 注册 Syncfusion Blazor 服务
• 添加样式表和脚本资源
• 导入命名空间
• 首次实现 HeatMap 组件
• 基本数据源配置
• 运行和测试应用程序

数据绑定和数据处理

📄 阅读： references/working-with-data.md

• 数据源类型概述（数组、JSON/表格、单元格）
• 使用 2D 和多维数组进行数组数据绑定
• 配置适配器进行 JSON/表格数据绑定
• 使用单元格数据绑定自定义单个单元格
• x 轴和 y 轴的字段映射
• 数据转换模式
• 处理空单元格和 null 值
• 大型数据集的性能注意事项

轴配置

📄 阅读： references/axis.md

• 轴类型：类别、数值和日期时间
• 使用自定义标签的类别轴
• 设置范围（最小值、最大值、间隔）的数值轴
• 支持格式设置和间隔类型的日期时间轴
• 自定义轴标签（旋转、对齐、样式）
• 轴标签模板
• 用于层次数据的多级标签
• 轴反转和对侧定位
• 轴标题配置

外观和自定义

📄 阅读： references/appearance.md

• 单元格自定义（边框、高亮、平铺类型）
• 间距的边距配置
• 标题设置（文本、对齐、文本样式）
• 数据标签配置（可见性、格式、模板）
• 边框配置（宽度、圆角、颜色）
• 背景和容器样式
• 文本样式自定义（大小、颜色、字体系列、字重）
• 数据标签的模板支持
• 响应式设计注意事项

颜色调色板

📄 阅读： references/palette.md

• 调色板类型：固定和渐变
• 固定调色板及其颜色映射和值范围
• 渐变调色板及其颜色渐变
• 自定义配色方案
• 空单元格和 null 单元格的颜色
• 内置调色板预设
• 颜色无障碍注意事项
• 颜色渐变模式（表格、行、列）

图例配置

📄 阅读： references/legend.md

• 图例可见性和位置
• 图例类型（渐变、列表）
• 图例自定义（宽度、高度、对齐方式）
• 支持切换单元格可见性的智能图例
• 在图例中显示百分比
• 图例文本样式自定义
• 图例标题配置
• 分段配置
• 支持图例项模板

工具提示

📄 阅读： references/tooltip.md

• 启用和配置工具提示
• 工具提示内容自定义
• 数组数据的工具提示模板
• JSON 数据的工具提示模板
• 工具提示文本样式自定义
• 边框和填充自定义
• 动画设置
• 条件式显示工具提示

事件和交互

📄 阅读： references/events.md

• 组件生命周期事件（Load、Loaded）
• 带有事件参数的 CellClick 事件
• CellDoubleClick 事件
• 用于自定义单元格渲染的 CellRender 事件
• 用于动态工具提示内容的 TooltipRender 事件
• 用于自定义图例的 LegendRender 事件
• 用于自定义轴标签的 AxisLabelRender 事件
• 事件处理模式和最佳实践
• 事件相关的性能注意事项

气泡 HeatMap 变体

📄 阅读： references/bubble-heatmap.md

• 气泡 HeatMap 概述和使用场景
• 启用气泡类型（TileType.Bubble）
• 根据值配置气泡大小
• 气泡大小类型（绝对值、百分比）
• 气泡颜色映射
• 结合气泡大小和颜色展示多维数据
• 气泡 HeatMap 的数据要求
• 气泡可视化最佳实践

高级功能

📄 阅读： references/advanced-features.md

• 尺寸和大小（宽度、高度、自适应大小）
• 单元格选择模式（单元格、列、行）
• 选择自定义
• 内容安全策略（CSP）合规性
• 无障碍功能（WCAG、WAI-ARIA、键盘导航）
• 屏幕阅读器支持
• 大型数据集的性能优化
• 虚拟化策略
• 服务端渲染注意事项

API 参考

📄 阅读： references/api-reference.md

• SfHeatMap 主组件
• 核心设置类（Cell、Title、Palette、Legend、Tooltip）
• 轴类（HeatMapXAxis、HeatMapYAxis）
• 多级标签配置
• 气泡配置类
• 样式类（边框、文本样式、边距）
• 事件参数类
• 枚举（CellType、PaletteType、AdaptorType 等）
• 完整的属性和方法参考

快速入门示例

以下是一个用于开始使用 HeatMap Chart 组件的最简示例：

@page "/heatmap"
@using Syncfusion.Blazor.HeatMap

<SfHeatMap DataSource="@HeatMapData">
    <HeatMapTitleSettings Text="Sales Revenue per Employee (in 1000 US$)"></HeatMapTitleSettings>
    <HeatMapCellSettings ShowLabel="true" TileType="CellType.Rect"></HeatMapCellSettings>
</SfHeatMap>

@code {
    int[,] GetDefaultData()
    {
        int[,] dataSource = new int[,]
        {
            {52, 65, 67, 45, 37, 52},
            {68, 52, 63, 51, 30, 51},
            {7, 16, 47, 47, 88, 6},
            {66, 64, 46, 40, 47, 41},
            {14, 46, 97, 69, 69, 3},
            {54, 46, 61, 46, 40, 39}
        };
        return dataSource;
    }
    
    public object HeatMapData { get; set; }
    
    protected override void OnInitialized()
    {
        HeatMapData = GetDefaultData();
    }
}

先决条件：

1. 安装 Syncfusion.Blazor.HeatMap NuGet 包
2. 注册 Syncfusion 服务：builder.Services.AddSyncfusionBlazor();
3. 在 index.html 中添加主题样式表和脚本引用
4. 添加命名空间：@using Syncfusion.Blazor.HeatMap

常见模式

模式 1：使用自定义轴的 JSON 数据

@using Syncfusion.Blazor.HeatMap

<SfHeatMap DataSource="@JsonData">
    <HeatMapDataSourceSettings IsJsonData="true" 
                               AdaptorType="AdaptorType.Table" 
                               XDataMapping="ProductName"
                               YDataMapping="Year" 
                               ValueMapping="Value">
    </HeatMapDataSourceSettings>
    <HeatMapXAxis Labels="@XAxisLabels"></HeatMapXAxis>
    <HeatMapYAxis Labels="@YAxisLabels"></HeatMapYAxis>
</SfHeatMap>

@code {
    private object[] JsonData = new object[]
    {
        new { ProductName = "Laptop", Year = "2022", Value = 150 },
        new { ProductName = "Desktop", Year = "2022", Value = 80 },
        // ... more data
    };
    
    private string[] XAxisLabels = new string[] { "Laptop", "Desktop", "Tablet", "Phone" };
    private string[] YAxisLabels = new string[] { "2022", "2023", "2024" };
}

模式 2：使用自定义颜色的渐变调色板

@using Syncfusion.Blazor.HeatMap

<SfHeatMap DataSource="@HeatMapData">
    <HeatMapPaletteSettings Type="PaletteType.Gradient">
        <HeatMapPalettes>
            <HeatMapPalette Color="#C2E7EC" Value="0"></HeatMapPalette>
            <HeatMapPalette Color="#AEDFE6" Value="25"></HeatMapPalette>
            <HeatMapPalette Color="#7FCDC4" Value="50"></HeatMapPalette>
            <HeatMapPalette Color="#6EB5D0" Value="75"></HeatMapPalette>
            <HeatMapPalette Color="#2D6CA2" Value="100"></HeatMapPalette>
        </HeatMapPalettes>
    </HeatMapPaletteSettings>
</SfHeatMap>

模式 3：具有大小和颜色的气泡 HeatMap

@using Syncfusion.Blazor.HeatMap

<SfHeatMap DataSource="@BubbleData">
    <HeatMapCellSettings TileType="CellType.Bubble" 
                         BubbleType="BubbleType.SizeAndColor">
        <HeatMapBubbleSize Minimum="10" Maximum="30"></HeatMapBubbleSize>
    </HeatMapCellSettings>
    <HeatMapDataSourceSettings IsJsonData="true" 
                               AdaptorType="AdaptorType.Cell"
                               XDataMapping="XAxis"
                               YDataMapping="YAxis"
                               ValueMapping="Value">
        <HeatMapBubbleDataMapping Size="Size" Color="Value"></HeatMapBubbleDataMapping>
    </HeatMapDataSourceSettings>
</SfHeatMap>

模式 4：带事件的交互式 HeatMap

@using Syncfusion.Blazor.HeatMap

<SfHeatMap DataSource="@HeatMapData">
    <HeatMapEvents CellClicked="@OnCellClick"
                   TooltipRendering="@OnTooltipRender">
    </HeatMapEvents>
    <HeatMapTooltipSettings>
        <Template>
            @{
                var data = context as TooltipEventArgs;
                <div>@data.XLabel - @data.YLabel: @data.Value</div>
            }
        </Template>
    </HeatMapTooltipSettings>
</SfHeatMap>

@code {
    private void OnCellClick(Syncfusion.Blazor.HeatMap.CellClickEventArgs args)
    {
        Console.WriteLine($"Cell clicked: {args.XLabel}, {args.YLabel}, Value: {args.Value}");
    }
    
    private void OnTooltipRender(Syncfusion.Blazor.HeatMap.TooltipEventArgs args)
    {
        // Customize tooltip content dynamically
    }
}

关键属性参考

属性	类型	用途
DataSource	object	设置 HeatMap 的数据（数组、JSON 或单元格数据）
Width	string	设置 HeatMap 的宽度（例如，“100%”、“600px”）
Height	string	设置 HeatMap 的高度（例如，“400px”）
HeatMapCellSettings.ShowLabel	bool	显示或隐藏单元格标签
HeatMapCellSettings.TileType	CellType	设置单元格类型（Rect 或 Bubble）
HeatMapDataSourceSettings.IsJsonData	bool	指示数据源是否为 JSON 格式
HeatMapDataSourceSettings.AdaptorType	AdaptorType	设置适配器类型（Table、Cell、None）
HeatMapPaletteSettings.Type	PaletteType	设置调色板类型（Fixed 或 Gradient）
HeatMapLegendSettings.Visible	bool	显示或隐藏图例
HeatMapTooltipSettings	object	配置工具提示的外观和内容
HeatMapXAxis.ValueType	ValueType	设置 x 轴类型（Category、Numeric、DateTime）
HeatMapYAxis.ValueType	ValueType	设置 y 轴类型（Category、Numeric、DateTime）

常见用例

用例 1：销售业绩仪表板

使用渐变色的 HeatMap 可视化不同产品和时间段的销售业绩，突出表现出色和欠佳的项目。

适用场景： 月度／季度销售跟踪、产品比较、区域业绩分析。

用例 2：相关性矩阵

以矩阵形式展示多个变量之间的相关系数，并使用发散色彩方案。

适用场景： 统计分析、数据科学项目、特征相关性分析。

用例 3：服务器资源监控

监控多台服务器在不同时间段的 CPU、内存或网络使用情况。

适用场景： DevOps 仪表板、基础设施监控、容量规划。

用例 4：日历 HeatMap

以日历样式布局展示不同日期和月份的活动级别或事件频率。

适用场景： GitHub 风格的贡献图、出勤跟踪、活动日志。

用例 5：多维数据气泡 HeatMap

使用气泡大小表示一项指标（例如，销售量），并使用颜色表示另一项指标（例如，利润率）。

适用场景： 同时比较两个相关指标、投资组合分析、竞争定位。

相关技能

• 有关 TreeMap 可视化，请参阅 Syncfusion Blazor TreeMap
• 要了解其他数据可视化组件，请浏览“数据可视化”类别

最佳实践

1. 选择合适的调色板类型：连续数据使用渐变调色板，分类数据使用固定调色板
2. 启用工具提示：始终提供工具提示，以便更好地解读数据
3. 使用有意义的轴标签：确保轴标签清楚地描述数据维度
4. 优化大型数据集：对于包含数千个单元格的数据集，可考虑使用数据采样或虚拟化
5. 测试无障碍功能：验证键盘导航和屏幕阅读器兼容性
6. 响应式尺寸：使用百分比宽度实现响应式布局
7. 颜色无障碍性：确保颜色对比度充足，避免仅依靠颜色传达信息
8. 性能：尽量减少复杂的事件处理程序和模板渲染，以提升性能

故障排查快速指南

问题	解决方案
HeatMap 未显示	确认已安装 NuGet 包并完成服务注册
数据未显示	检查 DataSource 绑定，并确认数据格式与适配器类型匹配
颜色未显示	使用适当的调色板类型配置 HeatMapPaletteSettings
工具提示无法使用	确保已使用有效内容配置 HeatMapTooltipSettings
轴标签缺失	在 HeatMapXAxis/HeatMapYAxis 上设置 Labels 属性
性能问题	减少单元格数量、禁用动画或实现虚拟化

如需详细的故障排查信息，请参阅各功能领域对应的参考文件。