syncfusion-aspnetcore-heatmap-chart

实现 Syncfusion HeatMap Chart

• 何时使用此技能
• 组件概述
  • 主要功能
• 文档与导航指南
  • 开始使用
  • 数据绑定与渲染模式
  • 气泡 HeatMap 可视化
  • 外观与样式
  • 轴配置
  • 图例与调色板系统
  • 工具提示与单元格选择
  • 高级场景与最佳实践
• 快速入门示例
  • Pages/Index.cshtml
  • Pages/Index.cshtml.cs
• 常见模式
  • 模式 1：带标签的类别轴
  • 模式 2：渐变颜色映射
  • 模式 3：固定调色板分类
  • 模式 4：响应式渲染
• 主要属性与配置
  • 必需配置
  • 单元格自定义
  • 外观
  • 图例配置
  • 调色板
• 常见用例

何时使用此技能

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

• 使用颜色编码的单元格可视化二维矩阵数据。
• 以网格布局显示业务、科学、运营或分析数据。
• 在 ASP.NET Core Razor Pages 中绑定来自 C# 集合的 HeatMap 数据。
• 将 HeatMap 标记保留在 Index.cshtml 中，并将数据准备和配置移至 Index.cshtml.cs。
• 配置类别、数值或日期时间轴。
• 添加标题、图例、工具提示、单元格标签和调色板自定义项。
• 对连续值或分类值使用渐变或固定颜色映射。
• 启用单元格选择并处理 HeatMap 事件。
• 为较大的数据集使用恰当的渲染模式，以提升性能。

组件概述

Syncfusion ASP.NET Core HeatMap Chart 是一种数据可视化组件，可通过颜色强度表示二维数据。每个单元格代表一个值，其颜色根据配置的调色板计算得出。

适用于：

• 销售业绩矩阵。
• 出勤与生产力报告。
• 相关性矩阵。
• 温度或密度可视化。
• 库存状态仪表板。
• 传感器读数网格。
• 随时间变化的使用情况或活动分析。

主要功能

• 支持数组和 JSON 风格的数据绑定。
• 支持类别、数值和日期时间轴。
• 支持渐变和固定调色板。
• 支持单元格标签、图例和工具提示。
• 支持 SVG、Canvas 和 Auto 渲染模式。
• 支持单选和多选单元格。
• 支持自定义事件，例如单元格渲染、工具提示渲染和单元格选中。
• 支持使用 Index.cshtml 和 Index.cshtml.cs 实现 Razor Pages。

文档与导航指南

开始使用

本节介绍：

• 安装所需的 Syncfusion ASP.NET Core 包。
• 注册 Syncfusion Tag Helpers。
• 添加 Syncfusion 样式和脚本。
• 创建第一个 HeatMap Chart。
• 在 Razor Pages 中渲染组件。

在 Pages/_ViewImports.cshtml 中进行必需的设置：

@using YourApplication
@namespace YourApplication.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, Syncfusion.EJ2

将 YourApplication 替换为实际的项目命名空间。例如，如果项目名称是 AspNetCoreWebApp，请使用：

@using AspNetCoreWebApp
@namespace AspNetCoreWebApp.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, Syncfusion.EJ2

在 Pages/Shared/_Layout.cshtml 的 head 标签内添加所需的主题和脚本引用。

<link rel="stylesheet" href="https://cdn.syncfusion.com/ej2/33.2.3/fluent.css" />
<script src="https://cdn.syncfusion.com/ej2/33.2.3/dist/ej2.min.js"></script>

在 Pages/Shared/_Layout.cshtml 的结束 body 标签之前添加 Syncfusion 脚本管理器。

<ejs-scripts></ejs-scripts>

数据绑定和渲染模式

HeatMap Chart 支持多种形式的数据绑定：

• 二维数组数据。
• JSON 表格数据。
• JSON 单元格数据。
• 远程数据。
• 强类型 C# 模型集合。

对于 Razor Pages，建议将数据和配置对象保存在 Index.cshtml.cs 中，并在 Index.cshtml 中通过 @Model 绑定。

渲染模式：

• SVG：适用于较小和中等规模的数据集。
• Canvas：适用于大型数据集。
• Auto：由组件选择合适的渲染模式。

气泡 HeatMap 可视化

当单元格需要通过气泡大小、颜色或两者来显示数值时，气泡 HeatMap 非常实用。

常见的气泡选项：

• 按大小显示气泡。
• 按颜色显示气泡。
• 按扇区显示气泡。
• 按大小和颜色显示气泡。

当每个单元格需要比普通矩形色块更丰富的视觉区分时，请使用气泡 HeatMap。

外观和样式

可以使用以下选项自定义 HeatMap 外观：

• titleSettings
• cellSettings
• paletteSettings
• legendSettings
• tooltipSettings
• backgroundColor
• margin
• height
• width

对于 ASP.NET Core Razor Pages，应在 Index.cshtml.cs 中声明强类型对象，并从 Index.cshtml 传递给 Tag Helper。

坐标轴配置

HeatMap Chart 支持以下坐标轴值类型：

• Category
• Numeric
• DateTime

当标签为月份、产品、地区或部门等名称时，请使用分类坐标轴。

当 X 和 Y 值基于索引或表示数值范围时，请使用数值坐标轴。

当值表示日期或时间间隔时，请使用日期时间坐标轴。

图例和调色板系统

使用图例说明颜色与数值之间的对应关系。

调色板类型：

• Gradient：适用于连续值。
• Fixed：适用于分类值或阈值。

图例位置：

• Right
• Left
• Top
• Bottom

工具提示和单元格选择

在 HeatMap 上使用 showTooltip="true" 可启用工具提示。

可以通过 tooltipSettings 自定义工具提示样式。

可以通过以下方式启用单元格选择：

allowSelection="true"
enableMultiSelect="true"

需要自定义交互逻辑时，请使用 cellSelected、cellClick 和 tooltipRender 等事件。

高级场景和最佳实践

推荐的最佳实践：

• 仅在 Index.cshtml 中保留 UI 标记。
• 在 Index.cshtml.cs 中保留数据、调色板、字体样式、标签和强类型模型。
• 对所有 Razor Page 绑定使用 @Model.PropertyName。
• 使用 renderingMode="Auto"，以获得响应式性能表现。
• 对于非常大的数据集，使用 showLabel="false"。
• 当数据会重复使用时，使用强类型类，而不是匿名对象。
• 需要 JSON 样式的单元格映射时，使用 dataSourceSettings。
• 确保 Index.cshtml.cs、Index.cshtml 和 _ViewImports.cshtml 中的命名空间一致。
• 在 .cshtml 文件中使用真实的 Razor/HTML 标签。不要将 <ejs-heatmap> 之类的编码标签粘贴到实际的 Razor 文件中。

快速入门示例

以下示例演示了一个完整的 ASP.NET Core Razor Pages HeatMap Chart 实现，同时使用 Index.cshtml 和 Index.cshtml.cs。

此版本保持 Razor 文件简洁，并将数据生成、调色板配置、标题样式、工具提示样式和标签移到 PageModel 中。

请将 YourApplication 替换为实际的项目命名空间。例如，如果项目名为 AspNetCoreWebApp，请使用 AspNetCoreWebApp.Pages。

Pages/Index.cshtml

@page
@model YourApplication.Pages.IndexModel

<ejs-heatmap
    id="heatmap"
    dataSource="@Model.DataSource"
    showTooltip="true"
    renderingMode="Auto"
    allowSelection="true"
    enableMultiSelect="true">

    <e-heatmap-titlesettings
        text="Sales Performance HeatMap"
        textStyle="@Model.TitleTextStyle">
    </e-heatmap-titlesettings>

    <e-heatmap-xaxis
        valueType="Category"
        labels="@Model.XAxisLabels">
    </e-heatmap-xaxis>

    <e-heatmap-yaxis
        valueType="Category"
        labels="@Model.YAxisLabels">
    </e-heatmap-yaxis>

    <e-heatmap-datasourcesettings
        isJsonData="true"
        adaptorType="Cell"
        xDataMapping="XValue"
        yDataMapping="YValue"
        valueMapping="Value">
    </e-heatmap-datasourcesettings>

    <e-heatmap-cellsettings
        showLabel="true"
        format="{value}"
        textStyle="@Model.CellTextStyle">
    </e-heatmap-cellsettings>

    <e-heatmap-palettesettings
        type="Gradient"
        palette="@Model.Palette">
    </e-heatmap-palettesettings>

    <e-heatmap-legendsettings
        visible="true"
        position="Right"
        showLabel="true"
        height="150">
    </e-heatmap-legendsettings>

    <e-heatmap-tooltipsettings
        textStyle="@Model.TooltipTextStyle">
    </e-heatmap-tooltipsettings>
</ejs-heatmap>

Pages/Index.cshtml.cs

using Microsoft.AspNetCore.Mvc.RazorPages;
using Syncfusion.EJ2.HeatMap;
using System.Collections.Generic;

namespace YourApplication.Pages
{
    public class IndexModel : PageModel
    {
        public List<HeatMapDataPoint> DataSource { get; set; } = new List<HeatMapDataPoint>();

        public string[] XAxisLabels { get; set; } =
        {
            "Jan", "Feb", "Mar", "Apr", "May"
        };

        public string[] YAxisLabels { get; set; } =
        {
            "Product A", "Product B", "Product C", "Product D", "Product E"
        };

        public HeatMapFont TitleTextStyle { get; set; } = new HeatMapFont
        {
            Size = "15px",
            FontWeight = "500",
            FontStyle = "Normal",
            FontFamily = "Segoe UI"
        };

        public HeatMapFont CellTextStyle { get; set; } = new HeatMapFont
        {
            FontFamily = "Segoe UI",
            Size = "12px",
            FontWeight = "400"
        };

        public HeatMapFont TooltipTextStyle { get; set; } = new HeatMapFont
        {
            Color = "#FFFFFF",
            FontFamily = "Segoe UI"
        };

        public List<HeatMapPalette> Palette { get; set; } = new List<HeatMapPalette>
        {
            new HeatMapPalette { Value = 0, Color = "#C2E7EC", Label = "Very Low" },
            new HeatMapPalette { Value = 25, Color = "#AED6DC", Label = "Low" },
            new HeatMapPalette { Value = 50, Color = "#87C1C9", Label = "Medium" },
            new HeatMapPalette { Value = 75, Color = "#4CA3AF", Label = "High" },
            new HeatMapPalette { Value = 100, Color = "#1B7280", Label = "Very High" }
        };

        public List<HeatMapPalette> FixedPalette { get; set; } = new List<HeatMapPalette>
        {
            new HeatMapPalette { Value = 0, Color = "#DFF6DD", Label = "Low" },
            new HeatMapPalette { Value = 50, Color = "#FFF4CE", Label = "Medium" },
            new HeatMapPalette { Value = 80, Color = "#FDE7E9", Label = "High" }
        };

        public void OnGet()
        {
            DataSource = new List<HeatMapDataPoint>
            {
                new HeatMapDataPoint { XValue = "Jan", YValue = "Product A", Value = 73 },
                new HeatMapDataPoint { XValue = "Feb", YValue = "Product A", Value = 39 },
                new HeatMapDataPoint { XValue = "Mar", YValue = "Product A", Value = 26 },
                new HeatMapDataPoint { XValue = "Apr", YValue = "Product A", Value = 39 },
                new HeatMapDataPoint { XValue = "May", YValue = "Product A", Value = 94 },

                new HeatMapDataPoint { XValue = "Jan", YValue = "Product B", Value = 93 },
                new HeatMapDataPoint { XValue = "Feb", YValue = "Product B", Value = 58 },
                new HeatMapDataPoint { XValue = "Mar", YValue = "Product B", Value = 53 },
                new HeatMapDataPoint { XValue = "Apr", YValue = "Product B", Value = 38 },
                new HeatMapDataPoint { XValue = "May", YValue = "Product B", Value = 26 },

                new HeatMapDataPoint { XValue = "Jan", YValue = "Product C", Value = 99 },
                new HeatMapDataPoint { XValue = "Feb", YValue = "Product C", Value = 28 },
                new HeatMapDataPoint { XValue = "Mar", YValue = "Product C", Value = 22 },
                new HeatMapDataPoint { XValue = "Apr", YValue = "Product C", Value = 4 },
                new HeatMapDataPoint { XValue = "May", YValue = "Product C", Value = 66 },

                new HeatMapDataPoint { XValue = "Jan", YValue = "Product D", Value = 14 },
                new HeatMapDataPoint { XValue = "Feb", YValue = "Product D", Value = 26 },
                new HeatMapDataPoint { XValue = "Mar", YValue = "Product D", Value = 97 },
                new HeatMapDataPoint { XValue = "Apr", YValue = "Product D", Value = 69 },
                new HeatMapDataPoint { XValue = "May", YValue = "Product D", Value = 69 },

                new HeatMapDataPoint { XValue = "Jan", YValue = "Product E", Value = 7 },
                new HeatMapDataPoint { XValue = "Feb", YValue = "Product E", Value = 46 },
                new HeatMapDataPoint { XValue = "Mar", YValue = "Product E", Value = 47 },
                new HeatMapDataPoint { XValue = "Apr", YValue = "Product E", Value = 47 },
                new HeatMapDataPoint { XValue = "May", YValue = "Product E", Value = 88 }
            };
        }
    }

    public class HeatMapDataPoint
    {
        public string XValue { get; set; } = string.Empty;

        public string YValue { get; set; } = string.Empty;

        public double Value { get; set; }
    }
}

常见模式

模式 1：带标签的分类坐标轴

显示月份、产品、团队、地区或部门等命名的行标题和列标题时，请使用分类坐标轴。

推荐用法：

• 为所需坐标轴设置 valueType="Category"。
• 在 Index.cshtml.cs 中以 string[] 提供标签。
• 在 Index.cshtml 中使用 @Model.XAxisLabels 和 @Model.YAxisLabels 绑定标签。

Index.cshtml 中的配置示例：

<e-heatmap-xaxis
    valueType="Category"
    labels="@Model.XAxisLabels">
</e-heatmap-xaxis>

<e-heatmap-yaxis
    valueType="Category"
    labels="@Model.YAxisLabels">
</e-heatmap-yaxis>

Index.cshtml.cs 中的配置示例：

public string[] XAxisLabels { get; set; } =
{
    "Jan", "Feb", "Mar", "Apr", "May"
};

public string[] YAxisLabels { get; set; } =
{
    "Product A", "Product B", "Product C", "Product D", "Product E"
};

模式 2：渐变颜色映射

当值是连续的，且需要在多个颜色节点之间进行插值时，请使用渐变颜色映射。

建议用法：

• 在 paletteSettings 中设置 type="Gradient"。
• 在 Index.cshtml.cs 中将调色板定义为 List<HeatMapPalette>。
• 用于分数、密度、温度、流量强度、利用率或性能值。

Index.cshtml 中的配置示例：

<e-heatmap-palettesettings
    type="Gradient"
    palette="@Model.Palette">
</e-heatmap-palettesettings>

Index.cshtml.cs 中的配置示例：

public List<HeatMapPalette> Palette { get; set; } = new List<HeatMapPalette>
{
    new HeatMapPalette { Value = 0, Color = "#C2E7EC", Label = "Very Low" },
    new HeatMapPalette { Value = 25, Color = "#AED6DC", Label = "Low" },
    new HeatMapPalette { Value = 50, Color = "#87C1C9", Label = "Medium" },
    new HeatMapPalette { Value = 75, Color = "#4CA3AF", Label = "High" },
    new HeatMapPalette { Value = 100, Color = "#1B7280", Label = "Very High" }
};

模式 3：固定调色板分类

当值表示离散范围、状态或分类级别时，请使用固定调色板映射。

建议用法：

• 在 paletteSettings 中设置 type="Fixed"。
• 在 Index.cshtml.cs 中将调色板定义为 List<HeatMapPalette>。
• 确保 Razor 文件中使用的属性名称存在于 PageModel 中。
• 用于风险级别、可用性状态、SLA 状态或基于类别的热图。

以下代码片段只有在 Index.cshtml.cs 中存在 FixedPalette，并且将代码片段作为真实标签粘贴到 .cshtml 文件中时才有效。

在 Index.cshtml 中的正确用法：

<e-heatmap-palettesettings
    type="Fixed"
    palette="@Model.FixedPalette">
</e-heatmap-palettesettings>

请勿将下面的编码版本粘贴到实际的 .cshtml 文件中：

<e-heatmap-palettesettings
    type="Fixed"
    palette="@Model.FixedPalette">
</e-heatmap-palettesettings>

Index.cshtml.cs 中所需的属性：

public List<HeatMapPalette> FixedPalette { get; set; } = new List<HeatMapPalette>
{
    new HeatMapPalette { Value = 0, Color = "#DFF6DD", Label = "Low" },
    new HeatMapPalette { Value = 50, Color = "#FFF4CE", Label = "Medium" },
    new HeatMapPalette { Value = 80, Color = "#FDE7E9", Label = "High" }
};

如果要在主快速入门示例中使用固定调色板，请将此代码块：

<e-heatmap-palettesettings
    type="Gradient"
    palette="@Model.Palette">
</e-heatmap-palettesettings>

替换为此代码块：

<e-heatmap-palettesettings
    type="Fixed"
    palette="@Model.FixedPalette">
</e-heatmap-palettesettings>

模式 4：响应式渲染

处理中型或大型数据集时，请采用响应式渲染实践。

建议用法：

• 数据集较小时使用 renderingMode="SVG"。
• 数据集较大时使用 renderingMode="Canvas"。
• 当组件应自行确定合适的渲染模式时，使用 renderingMode="Auto"。
• 对高密度数据禁用标签。
• 避免为数千个单元格使用复杂的标签模板。

Index.cshtml 中的配置示例：

<ejs-heatmap
    id="heatmap"
    dataSource="@Model.DataSource"
    renderingMode="Auto">

    <e-heatmap-cellsettings
        showLabel="false">
    </e-heatmap-cellsettings>
</ejs-heatmap>

关键属性和配置

必需配置

• dataSource：将数据集合分配给 HeatMap。
• xAxis.valueType：定义 X 轴值类型。常用值包括 Category、Numeric 和 DateTime。
• yAxis.valueType：定义 Y 轴值类型。常用值包括 Category、Numeric 和 DateTime。
• dataSourceSettings：使用 JSON 样式的对象映射时必需。
• dataSourceSettings.isJsonData：绑定对象集合时，将此项设为 true。
• dataSourceSettings.adaptorType：对于基于单元格的记录，请使用 Cell。
• dataSourceSettings.xDataMapping：映射 X 值字段。
• dataSourceSettings.yDataMapping：映射 Y 值字段。
• dataSourceSettings.valueMapping：映射单元格值字段。

单元格自定义

• cellSettings.showLabel：在单元格内显示值。
• cellSettings.format：设置显示的单元格值的格式。
• cellSettings.textStyle：自定义标签字体样式。
• cellSettings.tileType：定义平铺类型，例如矩形单元格或气泡单元格。

外观

• backgroundColor：定义 HeatMap 背景颜色。
• margin：定义 HeatMap 周围的间距。
• titleSettings.text：定义 HeatMap 标题。
• titleSettings.textStyle：定义标题字体样式。
• height：定义组件高度。
• width：定义组件宽度。

图例配置

• legendSettings.visible：显示或隐藏图例。
• legendSettings.position：定义图例位置。
• legendSettings.type：定义图例类型。
• legendSettings.showLabel：显示或隐藏图例标签。
• legendSettings.height：定义图例高度。
• legendSettings.width：定义图例宽度。
• legendSettings.toggleVisibility：在适用时启用基于图例的可见性切换。

调色板

• paletteSettings.type：定义调色板行为。常见值为 Gradient 和 Fixed。
• paletteSettings.palette：分配强类型 List<HeatMapPalette>。
• HeatMapPalette.Value：定义数值阈值。
• HeatMapPalette.Color：定义阈值对应的颜色。
• HeatMapPalette.Label：定义调色板项的标签。

常见用例

1. 按月份和部门展示员工绩效矩阵。
2. 按地区和时间段比较产品销售情况。
3. 可视化网站流量或使用强度。
4. 用于分析仪表板的相关性矩阵。
5. 展示不同地点和时段的温度分布。
6. 按仓库和产品展示库存状态。
7. 分析用户在不同日期和时段的活动情况。
8. 展示多个设备的传感器读数。
9. 按类别可视化风险等级。
10. 分析 SLA 或工单数量。