syncfusion-flutter-spark-charts

Syncfusion Flutter Spark 图表

此技能涵盖 Syncfusion Flutter Spark 图表（也称为微型图表）——这是一组轻量、紧凑的图表控件，旨在以简洁、紧凑的形式展示数据趋势，不带坐标轴或坐标。该软件包包含四种图表类型：SfSparkLineChart、SfSparkAreaChart、SfSparkBarChart 和 SfSparkWinLossChart。

何时使用此技能

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

• 展示紧凑的数据可视化图表，无需复杂的图表元素
• 以简洁、紧凑的形式展示趋势和模式
• 在表格、卡片或仪表板中添加内嵌图表
• 高效可视化 KPI 和绩效指标
• 创建轻量级可视化图表，适用于空间有限的场景
• 构建仪表板控件，快速洞察数据
• 为移动端或 Web 界面实现微型图表
• 展示数据摘要，避免过多细节
• 展示胜负场景或二元结果
• 在数据网格或列表项中添加迷你图

选择合适的图表类型

在以下情况下使用 SfSparkLineChart：

• 需要识别随时间变化的模式和趋势
• 展示连续的数据流或序列
• 展示季节性影响或一段时间内的变化
• 折线趋势是最合适的可视化方式
• 用于构建：股价趋势、温度变化、销售趋势、绩效指标

在以下情况下使用 SfSparkAreaChart：

• 想要强调变化幅度
• 需要突出显示累计值
• 变化的量级比单个数据点更重要
• 需要填充趋势线下方的区域
• 用于构建：数量指标、累计指标、填充式趋势图

在以下情况下使用 SfSparkBarChart：

• 离散值或单个数据点很重要
• 比较不同类别的值
• 柱形图/条形图的表示方式更直观
• 数据属于类别型或分段型
• 用于构建：月度比较、分类数据、离散测量值

在以下情况下使用 SfSparkWinLossChart：

• 展示二元结果（正/负、胜/负）
• 展示具有成功/失败状态的绩效指标
• 展示胜负记录或比赛结果
• 展示一段时间内的二元状态
• 用于构建：胜负记录、成功指标、二元绩效指标、平局场景

主要差异汇总：

特性	SfSparkLineChart	SfSparkAreaChart	SfSparkBarChart	SfSparkWinLossChart
主要用途	趋势线	强调幅度	离散值比较	二元结果
可视化形式	折线	填充区域	竖直条形	胜/负条形
标记支持	✅ 是	✅ 是	❌ 否	❌ 否
最适用于	连续趋势	累计数据	类别型数据	二元数据
数据标签	✅ 是	✅ 是	✅ 是	❌ 否
边框样式	仅折线	区域 + 边框	条形 + 边框	条形 + 边框
特殊数据点	最高、最低、首个、末尾、负值	最高、最低、首个、末尾、负值	最高、最低、首个、末尾、负值	最高、最低、首个、末尾、平局
虚线样式	✅ 是	❌ 否	❌ 否	❌ 否

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 所有图表类型的基本实现
• 添加依赖项和导入
• 绑定数据源
• 首个示例和快速入门

图表概览

📄 阅读： references/overview.md

• Spark 图表控件概览和功能
• 何时使用 Spark 图表与完整图表
• 四种图表类型介绍
• 主要功能和特性
• 轻量级可视化的优势

图表类型

📄 阅读： references/chart-types.md

• 折线图（SfSparkLineChart）
• 面积图（SfSparkAreaChart）
• 柱状图（SfSparkBarChart）
• 赢负图（SfSparkWinLossChart）
• 图表类型比较与选择
• 特定类型的属性与自定义
• 折线图支持虚线

坐标轴配置

📄 阅读： references/axis-types.md

• 数值坐标轴
• 日期时间坐标轴
• 类别坐标轴
• 自定义数据源绑定
• 坐标轴线自定义
• 坐标轴交叉位置
• 坐标轴样式（颜色、宽度、虚线数组）

数据绑定

📄 阅读： references/data-binding.md

• 使用 List 进行简单数据绑定
• 使用 xValueMapper 和 yValueMapper 配置自定义数据源
• 数值、日期时间和类别类型的 x 轴值
• 数据映射模式
• 使用 .custom() 构造函数

标记和数据标签

📄 阅读： references/markers-datalabels.md

• 标记配置（仅适用于折线图和面积图）
• 标记形状（圆形、菱形、正方形、三角形、倒三角形）
• 标记显示模式（全部、最高值、最低值、首个、末个、无）
• 标记自定义（颜色、边框、大小）
• 数据标签显示模式
• 数据标签样式

跟踪球

📄 阅读： references/trackball.md

• 启用跟踪球交互
• 跟踪球激活模式（tap、longPress、doubleTap）
• 跟踪球自定义（颜色、边框、背景）
• 跟踪球标签样式
• 触摸交互模式

绘图区间带

📄 阅读： references/plotband.md

• 突出显示特定的 Y 轴范围
• 绘图区间带的起始值和结束值
• 绘图区间带样式（颜色、边框）
• 绘图区间带的使用场景

自定义与样式

📄 阅读： references/customization.md

• 图表颜色自定义
• 特殊数据点颜色（最高值、最低值、首个、末个、负值、平局）
• 边框样式（宽度、颜色）
• 线条宽度自定义
• 图表反转
• 视觉外观模式

无障碍

📄 阅读： references/accessibility.md

• 确保图表具有足够的对比度
• 主题支持与自定义
• 大字体支持
• 使用 MediaQueryData 缩放文本
• 为无障碍功能自定义颜色

快速入门示例

基本折线图

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_charts/sparkcharts.dart';

class MySparkLineChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Spark Line Chart')),
      body: Center(
        child: Container(
          height: 100,
          padding: EdgeInsets.all(16),
          child: SfSparkLineChart(
            data: <double>[
              5, 6, 5, 7, 4, 3, 9, 5, 6, 5, 7, 8, 4, 5, 3, 4, 11, 10, 2, 12, 4, 7, 6, 8
            ],
          ),
        ),
      ),
    );
  }
}

带特殊数据点的柱状图

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_charts/sparkcharts.dart';

class SparkBarWithColors extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return SfSparkBarChart(
      data: <double>[
        10, 6, 8, -5, 11, 5, -2, 7, -3, 6, 8, 10
      ],
      highPointColor: Colors.red,
      lowPointColor: Colors.green,
      firstPointColor: Colors.orange,
      lastPointColor: Colors.orange,
      negativePointColor: Colors.purple,
    );
  }
}

赢负图

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_charts/sparkcharts.dart';

class SparkWinLossChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return SfSparkWinLossChart(
      data: <double>[
        12, 15, -10, 13, 15, 6, -12, 17, 13, 0, 8, -10
      ],
      color: Colors.blue,
      negativePointColor: Colors.red,
      tiePointColor: Colors.grey,
    );
  }
}

带跟踪球的图表

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_charts/sparkcharts.dart';

class SparkLineWithTrackball extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return SfSparkLineChart(
      axisLineWidth: 0,
      trackball: SparkChartTrackball(
        backgroundColor: Colors.blue.withOpacity(0.8),
        borderColor: Colors.blue.withOpacity(0.8),
        borderWidth: 2,
        color: Colors.blue,
        labelStyle: TextStyle(color: Colors.white),
        activationMode: SparkChartActivationMode.tap,
      ),
      marker: SparkChartMarker(
        displayMode: SparkChartMarkerDisplayMode.all,
      ),
      data: <double>[
        5, 6, 5, 7, 4, 3, 9, 5, 6, 5, 7, 8, 4, 5, 3, 4, 11, 10, 2, 12, 4, 7, 6, 8
      ],
    );
  }
}

常见模式

模式 1：仪表板 KPI 小组件

// Compact KPI card with sparkline
class KPICard extends StatelessWidget {
  final String title;
  final String value;
  final List<double> trendData;
  final Color trendColor;

  const KPICard({
    required this.title,
    required this.value,
    required this.trendData,
    this.trendColor = Colors.blue,
  });

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Padding(
        padding: EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(title, style: TextStyle(fontSize: 14, color: Colors.grey)),
            SizedBox(height: 8),
            Text(value, style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold)),
            SizedBox(height: 12),
            Container(
              height: 50,
              child: SfSparkLineChart(
                axisLineWidth: 0,
                data: trendData,
                color: trendColor,
                width: 2,
              ),
            ),
          ],
        ),
      ),
    );
  }
}

模式 2：带内嵌迷你图的数据表

// Table row with sparkline trend
class DataRowWithSparkline extends StatelessWidget {
  final String label;
  final List<double> data;

  const DataRowWithSparkline({
    required this.label,
    required this.data,
  });

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        Expanded(
          flex: 2,
          child: Text(label),
        ),
        Expanded(
          flex: 3,
          child: Container(
            height: 30,
            child: SfSparkLineChart(
              axisLineWidth: 0,
              data: data,
              highPointColor: Colors.green,
              lowPointColor: Colors.red,
            ),
          ),
        ),
      ],
    );
  }
}

模式 3：赢负记录显示

// Display win-loss record with chart
class WinLossRecord extends StatelessWidget {
  final List<double> results; // 1 for win, -1 for loss, 0 for tie

  const WinLossRecord({required this.results});

  @override
  Widget build(BuildContext context) {
    int wins = results.where((r) => r > 0).length;
    int losses = results.where((r) => r < 0).length;
    int ties = results.where((r) => r == 0).length;

    return Column(
      children: [
        Row(
          mainAxisAlignment: MainAxisAlignment.spaceAround,
          children: [
            Text('W: $wins', style: TextStyle(color: Colors.green)),
            Text('L: $losses', style: TextStyle(color: Colors.red)),
            Text('T: $ties', style: TextStyle(color: Colors.grey)),
          ],
        ),
        SizedBox(height: 8),
        Container(
          height: 40,
          child: SfSparkWinLossChart(
            data: results,
            color: Colors.green,
            negativePointColor: Colors.red,
            tiePointColor: Colors.grey,
          ),
        ),
      ],
    );
  }
}

模式 4：带绘图区间带阈值的图表

// Highlight threshold zones with plot band
class ThresholdSparkLine extends StatelessWidget {
  final List<double> data;
  final double thresholdMin;
  final double thresholdMax;

  const ThresholdSparkLine({
    required this.data,
    this.thresholdMin = 5.0,
    this.thresholdMax = 10.0,
  });

  @override
  Widget build(BuildContext context) {
    return SfSparkLineChart(
      axisLineWidth: 1,
      axisLineColor: Colors.grey[300],
      data: data,
      color: Colors.blue,
      plotBand: SparkChartPlotBand(
        start: thresholdMin,
        end: thresholdMax,
        color: Colors.green.withOpacity(0.2),
        borderColor: Colors.green,
        borderWidth: 1,
      ),
    );
  }
}

关键属性

基本属性（所有图表类型）

数据与显示：

• data - 数据值列表（List）
• color - 图表的主色
• axisLineWidth - 坐标轴线宽度（设为 0 可隐藏）
• isInversed - 垂直反转图表

特殊数据点颜色：

• highPointColor、lowPointColor、firstPointColor、lastPointColor
• negativePointColor - 用于负值
• tiePointColor - 用于零值（仅适用于赢负图）

交互功能：

• marker - 标记配置（仅适用于折线图和面积图）
• trackball - 交互式工具提示配置
• plotBand - 突出显示 Y 轴范围

折线图专用：

• width - 线条粗细
• dashArray - 虚线模式 [5, 3]

面积图／柱状图／赢负图专用：

• borderColor、borderWidth - 图表边框

数据标签：

• labelDisplayMode - 显示模式（全部、最高值、最低值、首个、末个、无）
• labelStyle - 文本样式配置

自定义数据绑定：

• 使用 .custom() 构造函数，并设置 dataCount、xValueMapper、yValueMapper

📄 详细属性： 请参阅 references/customization.md

常见用例

1. 仪表板 KPI - 使用 SfSparkLineChart 显示紧凑的趋势指标
2. 数据网格趋势 - 在表格数据中内嵌任意图表类型
3. 性能指标 - 使用带特殊数据点颜色的 SfSparkLineChart
4. 胜负记录 - 使用 SfSparkWinLossChart 显示比赛结果
5. 股票价格指标 - 使用带标记的 SfSparkLineChart
6. 销售趋势 - 使用 SfSparkAreaChart 突出显示销量
7. 月度对比 - 使用 SfSparkBarChart 展示不同时间段的数据
8. 阈值监控 - 使用绘图区带突出显示关键范围
9. 移动仪表板 - 在空间有限的 UI 中使用紧凑的迷你图
10. 报告摘要 - 使用迷你图快速概览数据