syncfusion-flutter-spark-charts

Syncfusion Flutter Spark Charts

このスキルでは、Syncfusion Flutter Spark Charts（マイクロチャートとも呼ばれます）を扱います。これは、軸や座標を使わずにデータの傾向をシンプルかつコンパクトに表示するための、軽量で簡潔なチャートウィジェットです。このパッケージには、SfSparkLineChart、SfSparkAreaChart、SfSparkBarChart、SfSparkWinLossChart の4種類のチャートが含まれています。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• 複雑なチャート要素を使わずに、コンパクトなデータの視覚化を表示する
• 傾向やパターンを最小限の要素で簡潔に示す
• テーブル、カード、ダッシュボードにインラインチャートを追加する
• KPIやパフォーマンス指標を効率的に視覚化する
• 表示スペースが限られている場合に、軽量な視覚化を作成する
• データをすばやく把握できるダッシュボードウィジェットを構築する
• モバイルまたはウェブのインターフェースにマイクロチャートを実装する
• 詳細を過剰に表示せずに、データの概要を示す
• 勝敗のシナリオや二値の結果を示す
• データグリッドやリスト項目にスパークラインを追加する

適切なチャートの種類を選ぶ

次の場合は SfSparkLineChart を使用します。

• 時間の経過に伴うパターンや傾向を特定する必要がある
• 連続するデータの流れや系列を表示する
• 季節的な影響や、一定期間にわたる変化を表示する
• 線による傾向表示が最も適切な視覚化である
• 株価の推移、気温の変化、売上の傾向、パフォーマンス指標を作成する

次の場合は SfSparkAreaChart を使用します。

• 変化の大きさを強調したい
• 累積値を目立たせる必要がある
• 個々の点よりも、変化の量が重要である
• 傾向線の下の領域を塗りつぶす必要がある
• ボリューム指標、累積指標、塗りつぶし付きの傾向表示を作成する

次の場合は SfSparkBarChart を使用します。

• 個別の値やデータポイントが重要である
• カテゴリー間で値を比較する
• 縦棒／横棒による表示がより直感的である
• データがカテゴリ別または区分別である
• 月ごとの比較、カテゴリー別データ、個別の測定値を作成する

次の場合は SfSparkWinLossChart を使用します。

• 二値の結果（正／負、勝ち／負け）を表示する
• 成功／失敗の状態を示すパフォーマンス指標
• 勝敗記録や試合結果
• 期間ごとの二値のステータス
• 勝敗記録、成功指標、二値のパフォーマンス指標、引き分けのシナリオを作成する

主な違いのまとめ：

特徴	SfSparkLineChart	SfSparkAreaChart	SfSparkBarChart	SfSparkWinLossChart
主な用途	傾向線	大きさの強調	個別の比較	二値の結果
視覚化	線	塗りつぶし領域	縦棒	勝敗を示す棒
マーカーのサポート	✅ はい	✅ はい	❌ いいえ	❌ いいえ
最適な用途	連続的な傾向	累積データ	カテゴリデータ	二値データ
データラベル	✅ はい	✅ はい	✅ はい	❌ いいえ
境界線のスタイル	線のみ	領域＋境界線	棒＋境界線	棒＋境界線
特殊なポイント	最大、最小、最初、最後、負の値	最大、最小、最初、最後、負の値	最大、最小、最初、最後、負の値	最大、最小、最初、最後、引き分け
破線スタイル	✅ はい	❌ いいえ	❌ いいえ	❌ いいえ

ドキュメントとナビゲーションガイド

はじめに

📄 読む： references/getting-started.md

• インストールとパッケージのセットアップ
• すべてのチャートタイプの基本的な実装
• 依存関係とインポートの追加
• データソースのバインド
• 最初の例とクイックスタート

チャートの概要

📄 読む： references/overview.md

• Spark Charts ウィジェットの概要と機能
• Spark Charts と通常のチャートの使い分け
• 4種類のチャートの説明
• 主な機能と性能
• 軽量な視覚化のメリット

グラフの種類

📄 参照： 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 - テキストスタイルの設定

カスタムデータバインディング：

• dataCount、xValueMapper、yValueMapper を指定して .custom() コンストラクターを使用

📄 プロパティの詳細： references/customization.md を参照

一般的なユースケース

1. ダッシュボードの KPI - コンパクトなトレンド指標には SfSparkLineChart を使用します
2. データグリッドのトレンド - テーブルデータに任意の種類のチャートをインラインで使用します
3. パフォーマンス指標 - 特定のポイントに色を付ける場合は SfSparkLineChart を使用します
4. 勝敗記録 - 試合や競技の結果には SfSparkWinLossChart を使用します
5. 株価指標 - マーカー付きの SfSparkLineChart を使用します
6. 売上トレンド - ボリュームを強調する場合は SfSparkAreaChart を使用します
7. 月次比較 - 個別の期間には SfSparkBarChart を使用します
8. しきい値の監視 - プロットバンドを使用して重要な範囲を強調します
9. モバイルダッシュボード - スペースが限られた UI にはコンパクトなスパークラインを使用します
10. レポートの概要 - データをすばやく概観するにはスパークラインを使用します