syncfusion-maui-toolkit-spark-charts

实现 Syncfusion .NET MAUI Spark Charts

何时使用此技能

在 .NET MAUI 应用中实现 SfSparkChart 控件时使用此技能。Spark Charts 是轻量级的微型可视化控件，适合在仪表板、网格和报告等紧凑空间中显示数据趋势。

主要场景：

• 显示快速数据趋势，而不占用大量 UI 空间
• 可视化销售趋势、股票表现或时间序列数据
• 在盈亏场景中显示正值和负值
• 创建包含多个微型图表的仪表板组件
• 突出显示特定数据点（首个、末尾、最高、最低和负值）

---

组件概览

SfSparkChart 是一款紧凑型图表控件，内置四种图表类型：

图表类型	用例	最适合
SparkLineChart	基于线条的可视化	识别趋势和模式
SparkAreaChart	填充区域可视化	强调变化幅度
SparkColumnChart	垂直条形可视化	比较不同数据值
SparkWinLossChart	盈亏表示	显示正值和负值场景

核心功能：

• 绑定到 ObservableCollection、List 或 IEnumerable
• 为不同的可视化需求提供四种图表类型
• 标记显示和自定义（仅限 Line/Area 图表）
• 数据点样式设置（首个、末尾、最高、最低和负值）
• 轴显示和原点自定义
• 为数值区域添加范围带高亮
• 轻量且经过性能优化，适用于微型可视化

---

文档与导航指南

快速入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包配置
• 项目配置（MauiProgram.cs 处理程序注册）
• 基本 SparkLineChart 实现
• 命名空间导入和首次渲染
• 数据绑定设置
• 可直接复制粘贴的入门代码

图表类型

📄 阅读： references/chart-types.md

• 为数据选择合适的图表类型
• SparkLineChart：基于线条的趋势可视化
• SparkAreaChart：填充区域表示
• SparkColumnChart：垂直条形比较
• SparkWinLossChart：盈亏场景
• 各类型的适用场景及代码示例
• 常见的类型选择模式

标记和标签

📄 阅读： references/markers-and-labels.md

• 在 Line 和 Area 图表上启用标记
• 标记形状类型和自定义
• 标记样式属性（Fill、Stroke、StrokeWidth、Height、Width）
• 标记定位和可见性
• 常见标记模式（突出显示端点和数据点）
• 标记显示的性能注意事项

样式和外观

📄 阅读： references/styling-and-appearance.md

• 数据点样式和颜色自定义
• 突出显示首个、末尾、最高和最低数据点
• 为 Column 和 WinLoss 图表设置负值样式
• Brush 和颜色属性
• 内边距和间距配置
• 尺寸自定义和布局控制
• 高级样式示例

数据绑定

📄 阅读： references/data-binding.md

• 绑定到 ObservableCollection 以实现响应式更新
• 绑定到 List 以处理静态数据
• 绑定到 IEnumerable 以使用 LINQ 查询
• XBindingPath 和 YBindingPath 配置
• 动态数据源更新
• 常见绑定模式和最佳实践

轴和范围

📄 阅读： references/axis-and-ranges.md

• 启用轴显示（ShowAxis 属性）
• 配置轴原点以作为基线参考
• 轴类型（Numeric、Category、DateTime）
• 用于分类/时间轴的 XBindingPath 属性
• 范围带可视化（RangeBandStart、RangeBandEnd、RangeBandFill）
• 轴线样式和自定义
• 突出显示数值区域和阈值

---

快速开始示例

// Step 1: Configure handler in MauiProgram.cs
using Syncfusion.Maui.Toolkit.Hosting;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureSyncfusionToolkit()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });
        return builder.Build();
    }
}

// Step 2: Create basic SparkLineChart in XAML
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:sparkchart="clr-namespace:Syncfusion.Maui.Toolkit.SparkCharts;assembly=Syncfusion.Maui.Toolkit"
             x:Class="SparkChartDemo.MainPage">

    <sparkchart:SfSparkLineChart 
        ItemsSource="{Binding Data}" 
        YBindingPath="Value"
        ShowMarkers="True"
        HeightRequest="100"
        WidthRequest="150">
    </sparkchart:SfSparkLineChart>

</ContentPage>

// Step 3: Bind data from ViewModel
public class SparkDataViewModel
{
    public ObservableCollection<DataPoint> Data { get; set; }
    
    public SparkDataViewModel()
    {
        Data = new ObservableCollection<DataPoint>
        {
            new DataPoint { Value = 10 },
            new DataPoint { Value = 15 },
            new DataPoint { Value = 12 },
            new DataPoint { Value = 20 },
            new DataPoint { Value = 18 }
        };
    }
}

public class DataPoint
{
    public double Value { get; set; }
}

---

常见模式

模式 1：仪表板摘要卡片

// Show quick sales trend in a card
<sparkchart:SfSparkLineChart 
    ItemsSource="{Binding MonthlySales}" 
    YBindingPath="Amount"
    ShowMarkers="False"
    FirstPointFill="Blue"
    LastPointFill="Red">
</sparkchart:SfSparkLineChart>

模式 2：带阈值的性能指标

// Highlight data within acceptable range using RangeBand
<sparkchart:SfSparkLineChart 
    ItemsSource="{Binding PerformanceMetrics}" 
    YBindingPath="Value"
    ShowAxis="True"
    RangeBandStart="50"
    RangeBandEnd="100"
    RangeBandFill="LightGreen">
</sparkchart:SfSparkLineChart>

模式 3：胜负可视化

// Show positive and negative outcomes
<sparkchart:SfSparkWinLossChart 
    ItemsSource="{Binding GameResults}" 
    YBindingPath="Result"
    NegativePointsFill="Red">
</sparkchart:SfSparkWinLossChart>

模式 4：设置样式的数据点

// Emphasize critical data points
<sparkchart:SfSparkColumnChart 
    ItemsSource="{Binding MonthlyRevenue}" 
    YBindingPath="Revenue"
    FirstPointFill="Green"
    LastPointFill="Blue"
    HighPointFill="Gold"
    LowPointFill="Red"
    NegativePointsFill="DarkRed">
</sparkchart:SfSparkColumnChart>

---

关键属性参考

核心属性

属性	类型	默认值	用途
ItemsSource	IEnumerable	-	图表的数据源
YBindingPath	string	-	Y 轴数值的属性名称
XBindingPath	string	-	X 轴数值的属性名称
Height	double	-	图表高度（像素）
Width	double	-	图表宽度（像素）

显示属性

属性	类型	默认值	用途
ShowMarkers	bool	false	显示标记（仅适用于折线图/面积图）
ShowAxis	bool	false	显示坐标轴基线
Padding	Thickness	0	图表内容周围的间距
AxisOrigin	double	-	坐标轴线位置对应的 Y 轴数值

样式属性

属性	类型	默认值	用途
FirstPointFill	Brush	-	第一个数据点的颜色
LastPointFill	Brush	-	最后一个数据点的颜色
HighPointFill	Brush	-	最高数据点的颜色
LowPointFill	Brush	-	最低数据点的颜色
NegativePointsFill	Brush	-	负值的颜色（柱状图/胜负图）

范围带属性

属性	类型	默认值	用途
RangeBandStart	double	-	范围带的 Y 轴起始值
RangeBandEnd	double	-	范围带的 Y 轴结束值
RangeBandFill	Brush	-	范围带区域的颜色

坐标轴属性

属性	类型	默认值	用途
AxisType	SparkChartAxisType	Numeric	坐标轴刻度类型（Numeric、Category、DateTime）
AxisLineStyle	SparkChartLineStyle	-	坐标轴外观（Stroke、StrokeWidth、StrokeDashArray）

标记属性（仅适用于折线图/面积图）

属性	类型	默认值	用途
MarkerSettings	SparkChartMarkerSettings	-	标记自定义配置

---

常见问题与解决方案

问题：图表显示为空

原因： 缺少 ItemsSource 绑定、YBindingPath 不正确，或数据源为 null
解决方案：

1. 确认 ItemsSource 已正确绑定到包含数据的集合
2. 确认 YBindingPath 与数据属性名称完全一致
3. 检查数据属性是否为 public 且包含数值

问题：标记未显示

注意： 标记仅适用于折线图和面积图
解决方案：

1. 确认使用的是 SfSparkLineChart 或 SfSparkAreaChart
2. 在 XAML 或代码中设置 ShowMarkers="True"
3. 检查 MarkerSettings 是否隐藏了标记（确认 Height/Width > 0）

问题：范围带不可见

解决方案：

1. 确认 RangeBandStart < RangeBandEnd
2. 确保范围值处于数据的 Y 轴范围内
3. 检查 RangeBandFill 是否为透明色

问题：大型数据集性能不佳

解决方案：

1. 考虑仅显示最近的数据点
2. 使用聚合数据代替原始值
3. 避免在大型数据集中使用过多标记样式
4. 在对性能要求较高的场景中禁用 ShowMarkers

---

后续步骤

• 准备好开始实现了吗？ → 从 入门指南 开始
• 需要特定功能？ → 浏览 图表类型、标记或样式
• 复杂场景？ → 查看数据绑定和坐标轴配置