syncfusion-maui-toolkit-spark-charts

Syncfusion .NET MAUI Spark Charts の実装

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

.NET MAUI アプリケーションで SfSparkChart コントロールを実装するときに、このスキルを使用します。Spark Charts は軽量なマイクロビジュアライゼーションコントロールで、ダッシュボード、グリッド、レポートなどの限られたスペースでデータの傾向を表示するのに最適です。

主なシナリオ：

• UI のスペースを大きく使わずに、データの傾向をすばやく表示する
• 売上の傾向、株価の推移、時系列データを視覚化する
• 勝敗のシナリオで正の値／負の値を示す
• 複数のマイクロチャートを使ってダッシュボードのコンポーネントを作成する
• 特定のデータポイント（最初、最後、最大、最小、負の値）を強調表示する

---

コンポーネントの概要

SfSparkChart は、4 種類の組み込みチャートタイプを備えたコンパクトなチャートコントロールです。

チャートタイプ	用途	最適な用途
SparkLineChart	線による視覚化	傾向やパターンの把握
SparkAreaChart	塗りつぶし領域による視覚化	変化の大きさの強調
SparkColumnChart	縦棒による視覚化	異なるデータ値の比較
SparkWinLossChart	勝敗の表現	正の値／負の値のシナリオの表示

主な機能：

• ObservableCollection、List、または IEnumerable へのデータバインディング
• さまざまな視覚化ニーズに対応する 4 種類のチャート
• マーカーの表示とカスタマイズ（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 チャートでの負の値のスタイル設定
• ブラシと色のプロパティ
• パディングと間隔の設定
• サイズのカスタマイズとレイアウトの制御
• 高度なスタイル設定の例

データバインディング

📄 参照： references/data-binding.md

• 変更を反映する ObservableCollection へのバインディング
• 静的データ向けの List へのバインディング
• LINQ クエリ向けの IEnumerable へのバインディング
• 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	マーカーを表示します（Line／Area のみ）
ShowAxis	bool	false	軸の基準線を表示します
Padding	Thickness	0	チャートのコンテンツ周囲の余白
AxisOrigin	double	-	軸線の位置を示す Y 軸の値

スタイル設定プロパティ

プロパティ	型	デフォルト	用途
FirstPointFill	Brush	-	最初のデータポイントの色
LastPointFill	Brush	-	最後のデータポイントの色
HighPointFill	Brush	-	最も高いデータポイントの色
LowPointFill	Brush	-	最も低いデータポイントの色
NegativePointsFill	Brush	-	負の値の色（Column／WinLoss）

範囲帯のプロパティ

プロパティ	型	デフォルト	用途
RangeBandStart	double	-	範囲帯の Y 軸開始値
RangeBandEnd	double	-	範囲帯の Y 軸終了値
RangeBandFill	Brush	-	範囲帯領域の色

軸のプロパティ

プロパティ	型	デフォルト	用途
AxisType	SparkChartAxisType	Numeric	軸のスケールの種類（Numeric、Category、DateTime）
AxisLineStyle	SparkChartLineStyle	-	軸の外観（Stroke、StrokeWidth、StrokeDashArray）

マーカーのプロパティ（Line／Area のみ）

プロパティ	型	デフォルト	用途
MarkerSettings	SparkChartMarkerSettings	-	マーカーのカスタマイズ設定

---

よくある課題と解決策

問題：チャートが空に見える

原因： ItemsSource のバインドがない、YBindingPath が正しくない、データソースが null
解決策：

1. ItemsSource がデータの入ったコレクションに正しくバインドされていることを確認します
2. YBindingPath がデータのプロパティ名と完全に一致していることを確認します
3. データプロパティが public で、数値が含まれていることを確認します

問題：マーカーが表示されない

注： マーカーは Line チャートと Area チャートでのみ使用できます
解決策：

1. SfSparkLineChart または SfSparkAreaChart を使用していることを確認します
2. XAML またはコードで ShowMarkers="True" を設定します
3. MarkerSettings によってマーカーが非表示になっていないことを確認します（Height／Width > 0 であることを確認します）

問題：範囲帯が表示されない

解決策：

1. RangeBandStart < RangeBandEnd であることを確認します
2. 範囲の値がデータの Y 軸の範囲内にあることを確認します
3. RangeBandFill が透明でないことを確認します

問題：大規模なデータセットでパフォーマンスが低下する

解決策：

1. 直近のデータポイントのみを表示することを検討します
2. 生の値ではなく、集計したデータを使用します
3. 大規模なデータセットでは、マーカーの過度なスタイル設定を避けます
4. パフォーマンスが重要なシナリオでは ShowMarkers を無効にします

---

次のステップ

• 実装を始めますか？ → はじめにから始めます
• 特定の機能が必要ですか？ → チャートの種類、マーカー、またはスタイル設定をご覧ください
• 複雑なシナリオですか？ → データバインディングと軸の設定をご確認ください