syncfusion-wpf-heatmap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing SfHeatMap (WPF)

实现SfHeatMap（WPF）

When to use this skill

何时使用本技能

Use this skill when you need an actionable, copy-pasteable guide to integrate and configure the Syncfusion

SfHeatMap

control in a WPF app. This is focused on implementation (what to configure and why), not exhaustive API reference.

当你需要一份可直接复制粘贴的指南，在WPF应用中集成和配置Syncfusion

SfHeatMap

控件时，可以使用本技能。本指南聚焦于实现（需要配置什么以及为什么），而非详尽的API参考。

Control overview

控件概述

Read: references/overview.md

Key points:

Visualizes tabular data as color gradients
Supports
```
TableMapping
```
and
```
CellMapping
```
data models
Useful for spotting patterns and value ranges quickly

阅读：references/overview.md

核心要点：

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

Quick start

快速入门

Read: references/getting-started.md

What to do first:

Add
```
SfHeatMap
```
to XAML
Provide an
```
ItemsSource
```
and an
```
ItemsMapping
```
(TableMapping or CellMapping)
Add
```
ColorMappingCollection
```
for value→color mapping
Optionally add
```
SfHeatMapLegend
```
to make ranges clear

阅读：references/getting-started.md

首要步骤：

在XAML中添加
```
SfHeatMap
```
提供
```
ItemsSource
```
和
```
ItemsMapping
```
（TableMapping或CellMapping）
添加
```
ColorMappingCollection
```
实现数值到颜色的映射
可选添加
```
SfHeatMapLegend
```
以明确数值范围

Color mapping guidance

颜色映射指南

Read: references/color-mapping.md

When to tune color mapping:

When you need semantic buckets (poor/average/good)
When precise range-to-color mapping is required for interpretation

阅读：references/color-mapping.md

何时调整颜色映射：

当你需要语义化分组（差/一般/优）时
当需要精确的范围到颜色映射以辅助数据解读时

Semantic buckets (red / yellow / green) — example

语义化分组（红/黄/绿）——示例

Copy-pasteable XAML + C# that maps explicit numeric ranges to semantic colors and shows a legend:

xaml

<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>
    <!-- Define semantic buckets: low=red, mid=yellow, high=green -->
    <syncfusion:ColorMappingCollection x:Key="semanticColorMapping">
      <!-- Value = numeric stop; Legend uses the Label text -->
      <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>

    <!-- CellMapping for row/column/value triplets -->
    <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>

    <!-- Legend explains the semantic buckets clearly -->
    <syncfusion:SfHeatMapLegend
        Grid.Row="0"
        LegendMode="List"
        Orientation="Horizontal"
        ColorMappingCollection="{StaticResource semanticColorMapping}" />

    <!-- The HeatMap uses the same ColorMappingCollection -->
    <syncfusion:SfHeatMap
        Grid.Row="1"
        ItemsSource="{Binding Cells}"
        ItemsMapping="{StaticResource cellMapping}"
        ColorMappingCollection="{StaticResource semanticColorMapping}" />
  </Grid>
</Window>

csharp

// 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;
    }
}

Notes:

The
```
ColorMappingCollection
```
defines stops; values between stops are interpolated unless you purposely treat them as buckets. Using the shown stops with
```
SfHeatMapLegend LegendMode="List"
```
produces labeled ranges in the legend.
Adjust exact
```
Value
```
thresholds to match your data distribution (e.g., 0/33/66 above). Ensure the
```
Value
```
range you define covers your data domain.

可直接复制粘贴的XAML + C#代码，将明确的数值范围映射为语义化颜色，并展示图例：

xaml

<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>
    <!-- Define semantic buckets: low=red, mid=yellow, high=green -->
    <syncfusion:ColorMappingCollection x:Key="semanticColorMapping">
      <!-- Value = numeric stop; Legend uses the Label text -->
      <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>

    <!-- CellMapping for row/column/value triplets -->
    <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>

    <!-- Legend explains the semantic buckets clearly -->
    <syncfusion:SfHeatMapLegend
        Grid.Row="0"
        LegendMode="List"
        Orientation="Horizontal"
        ColorMappingCollection="{StaticResource semanticColorMapping}" />

    <!-- The HeatMap uses the same ColorMappingCollection -->
    <syncfusion:SfHeatMap
        Grid.Row="1"
        ItemsSource="{Binding Cells}"
        ItemsMapping="{StaticResource cellMapping}"
        ColorMappingCollection="{StaticResource semanticColorMapping}" />
  </Grid>
</Window>

csharp

// 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
```
范围覆盖所有数据域。

Items mapping guidance

项映射指南

Read: references/items-mapping.md

When to use

TableMapping

CellMapping

Use
```
TableMapping
```
for wide objects with multiple numeric properties (years as columns)
Use
```
CellMapping
```
for row/column/value triplet datasets

阅读：references/items-mapping.md

何时使用

TableMapping

CellMapping

：

当处理包含多个数值属性的宽表对象（如年份作为列）时，使用
```
TableMapping
```
当处理行/列/数值三元组数据集时，使用
```
CellMapping
```

Legend & visualization

图例与可视化

Read: references/legend.md

Use a legend to make color ranges discoverable. Choose

Gradient

for continuous ranges and

List

for labeled buckets.

阅读：references/legend.md

使用图例让颜色范围更易理解。对于连续范围选择

Gradient

模式，对于带标签的分组选择

List

模式。

Common patterns

常见模式

Quick-start example: minimal XAML + items mapping + color mapping + legend
Responsive layouts: limit legend width and use
```
Orientation
```
to adapt
Accessibility: ensure labels and contrast are sufficient for screen readers

快速入门示例：极简XAML + 项映射 + 颜色映射 + 图例
响应式布局：限制图例宽度并使用
```
Orientation
```
适配布局
可访问性：确保标签和对比度足以支持屏幕阅读器

Troubleshooting

故障排除

If colors look unexpected, verify
```
ColorMappingCollection
```
values and ensure numeric ranges align with data
If items don't appear, confirm
```
ItemsMapping
```
matches the
```
ItemsSource
```
schema and keys

Generated by automation to provide a concise implementation router for the SfHeatMap control.

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

由自动化生成，为SfHeatMap控件提供简洁的实现指引。