syncfusion-wpf-heatmap

实现 SfHeatMap（WPF）

目录

• 何时使用此技能
• 控件概述 → references/overview.md
• 快速入门 → references/getting-started.md
• 颜色映射 → references/color-mapping.md
• 项映射 → references/items-mapping.md
• 图例与可视化 → references/legend.md
• 常见模式
• 故障排除

何时使用此技能

当你需要一份可直接操作和复制粘贴的指南，以便在 WPF 应用中集成和配置 Syncfusion SfHeatMap 控件时，请使用此技能。本文聚焦于实现（配置什么以及原因），并非详尽的 API 参考。

控件概述

阅读：references/overview.md

要点：

• 将表格数据可视化为颜色渐变
• 支持 TableMapping 和 CellMapping 数据模型
• 有助于快速发现模式和值范围

快速入门

阅读：references/getting-started.md

首先执行以下操作：

• 在 XAML 中添加 SfHeatMap
• 提供 ItemsSource 和 ItemsMapping（TableMapping 或 CellMapping）
• 添加 ColorMappingCollection 以建立值→颜色映射
• 可选：添加 SfHeatMapLegend，让范围一目了然

颜色映射指南

阅读：references/color-mapping.md

需要调整颜色映射的情况：

• 需要语义分档（差／一般／好）时
• 为便于解读，需要精确地将范围映射到颜色时

语义分档（红色／黄色／绿色）——示例

可复制粘贴的 XAML + C#，将明确的数值范围映射到语义颜色并显示图例：

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        x:Class="HeatMapSamples.MainWindow">
  <Window.Resources>
    
    <syncfusion:ColorMappingCollection x:Key="semanticColorMapping">
      
      <syncfusion:ColorMapping Value="0"   Color="#FF0000" Label="Low (0 - 33)" />
      <syncfusion:ColorMapping Value="33"  Color="#FFFF00" Label="Medium (34 - 66)" />
      <syncfusion:ColorMapping Value="66"  Color="#00B300" Label="High (67 - 100)" />
    </syncfusion:ColorMappingCollection>

    
    <syncfusion:CellMapping x:Key="cellMapping">
      <syncfusion:CellMapping.Column>
        <syncfusion:ColumnMapping PropertyName="Column" DisplayName="Column" />
      </syncfusion:CellMapping.Column>
      <syncfusion:CellMapping.Row>
        <syncfusion:ColumnMapping PropertyName="Row" DisplayName="Row" />
      </syncfusion:CellMapping.Row>
      <syncfusion:CellMapping.Value>
        <syncfusion:ColumnMapping PropertyName="Value" />
      </syncfusion:CellMapping.Value>
    </syncfusion:CellMapping>
  </Window.Resources>

  <Grid Margin="12">
    <Grid.RowDefinitions>
      <RowDefinition Height="Auto" />
      <RowDefinition Height="*" />
    </Grid.RowDefinitions>

    
    <syncfusion:SfHeatMapLegend
        Grid.Row="0"
        LegendMode="List"
        Orientation="Horizontal"
        ColorMappingCollection="{StaticResource semanticColorMapping}" />

    
    <syncfusion:SfHeatMap
        Grid.Row="1"
        ItemsSource="{Binding Cells}"
        ItemsMapping="{StaticResource cellMapping}"
        ColorMappingCollection="{StaticResource semanticColorMapping}" />
  </Grid>
</Window>

// Minimal code-behind (MainWindow.xaml.cs)
using System.Collections.ObjectModel;
using System.Windows;

public class CellData
{
    public string Row { get; set; }
    public string Column { get; set; }
    public double Value { get; set; }
}

public partial class MainWindow : Window
{
    public ObservableCollection<CellData> Cells { get; } = new ObservableCollection<CellData>();

    public MainWindow()
    {
        InitializeComponent();
        // sample values spanning 0..100
        Cells.Add(new CellData { Row = "R1", Column = "C1", Value = 10 });
        Cells.Add(new CellData { Row = "R1", Column = "C2", Value = 40 });
        Cells.Add(new CellData { Row = "R1", Column = "C3", Value = 80 });
        Cells.Add(new CellData { Row = "R2", Column = "C1", Value = 25 });
        Cells.Add(new CellData { Row = "R2", Column = "C2", Value = 55 });
        Cells.Add(new CellData { Row = "R2", Column = "C3", Value = 95 });

        DataContext = this;
    }
}

说明：

• ColorMappingCollection 定义色标；除非特意将其作为分档处理，否则色标之间的值会进行插值。使用所示色标并设置 SfHeatMapLegend LegendMode="List"，可在图例中显示带标签的范围。
• 根据数据分布调整精确的 Value 阈值（例如上文的 0/33/66）。确保定义的 Value 范围覆盖你的数据域。

项映射指南

阅读：references/items-mapping.md

何时使用 TableMapping 与 CellMapping：

• 对于具有多个数值属性的宽对象（以年份作为列），使用 TableMapping
• 对于由行／列／值三元组组成的数据集，使用 CellMapping

图例与可视化

阅读：references/legend.md

使用图例让颜色范围一目了然。连续范围选择 Gradient，带标签的分档选择 List。

常见模式

• 快速入门示例：最简 XAML + 项映射 + 颜色映射 + 图例
• 响应式布局：限制图例宽度，并使用 Orientation 进行适配
• 无障碍性：确保标签和对比度足以满足屏幕阅读器的需求

故障排除

• 如果颜色显示异常，请检查 ColorMappingCollection 的值，并确保数值范围与数据一致
• 如果项未显示，请确认 ItemsMapping 与 ItemsSource 的架构和键相匹配

---

由自动化工具生成，旨在为 SfHeatMap 控件提供简明的实现导航。