syncfusion-blazor-charts

Syncfusion Blazor Charts の実装

NuGet: Syncfusion.Blazor.Charts + Syncfusion.Blazor.Themes
名前空間: Syncfusion.Blazor.Charts

Blazor アプリケーションでインタラクティブかつ多機能なデータ可視化を作成するために、Syncfusion Blazor Chart コンポーネントを実装する包括的なガイドです。Chart コンポーネントは、33 種類以上のチャートタイプ、複数の軸、高度なインタラクティブ機能、幅広いカスタマイズオプションをサポートしています。

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

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

• Blazor アプリケーションでデータ可視化を作成する（折れ線、縦棒、横棒、面など）
• 金融チャートを実装する（株式分析用のローソク足、HILO、HILOOC）
• 統計データを可視化する（ヒストグラム、箱ひげ図、パレート図、ウォーターフォール）
• 積み上げチャートやグループ化チャートで比較データを表示する
• 範囲エリア／範囲縦棒チャートで範囲ベースのデータを表示する
• 円形データ表現用の極座標チャートやレーダーチャートを作成する
• ツールチップ、ズーム、十字カーソル、選択などのインタラクティブ機能を追加する
• テーマ、グラデーション、注釈を使用してチャートの外観をカスタマイズする
• ライブ更新やデータ編集によって動的データを処理する
• ARIA サポートや国際化に対応したアクセシブルなチャートを実装する

コンポーネントの概要

Syncfusion Blazor Chart コンポーネントは、次の機能を備えた強力なデータ可視化ツールです。

• 33 種類以上のチャートタイプ： 折れ線、縦棒、横棒、面、スプライン、散布図、バブル、ローソク足、HILO、極座標、レーダーなど
• 複数の軸： カテゴリ、数値、日時、対数軸に対応
• 豊富なインタラクティブ機能： ズーム、パン、十字カーソル、トラックボール、ツールチップ、選択
• データバインディング： List、DataManager、動的更新、ライブデータに対応
• 視覚要素： マーカー、データラベル、注釈、凡例、グラデーション
• 高度な機能： テクニカルインジケーター、トレンドライン、帯状線、複数ペイン
• アクセシビリティ： ARIA、キーボードナビゲーション、ローカライズ、RTL に完全対応
• カスタマイズ： テーマ、レスポンシブデザイン、印刷対応、適応型レイアウト

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

完全な API リファレンス

📄 参照： references/api-reference.md

重要：API に関する質問では、まずこのリファレンスを参照してください

次の用途には、この信頼できる API リファレンスを使用してください。

• 正しい列挙値を確認する（ChartSeriesType、ValueType、SelectionMode など）
• パブリックメソッドのシグネチャを確認する（RefreshAsync、ExportAsync、ShowTooltip など）
• プロパティ名と型を確認する
• コードサンプルを作成する
• API 関連の問題をトラブルシューティングする

掲載トピック：

• SfChart のパブリックメソッドとシグネチャの完全な一覧
• 正しい値を含むすべてのチャート列挙型
• 主なコンポーネントクラスとそのプロパティ
• メソッドの使用例
• 一般的なパターンとベストプラクティス

重要なポイント：

• 列挙値はすべて正確な値です。別の表記は使用しないでください
• メソッド名は C# の規則に従います（例：Refresh ではなく RefreshAsync）
• メソッド呼び出しでチャートインスタンスにアクセスするには、必ず @ref を使用してください
• 名前空間：Syncfusion.Blazor.Charts

---

はじめに

📄 参照： references/getting-started.md

次の用途には、このドキュメントを使用してください。

• 新しい Blazor Chart プロジェクトをセットアップする
• NuGet パッケージをインストールしてサービスを設定する
• 最初のチャートコンポーネントを作成する
• チャートの基本構造とデータバインディングを理解する
• Visual Studio、VS Code、または .NET CLI を使用する

掲載トピック：

• インストールと前提条件
• パッケージのセットアップ（Syncfusion.Blazor.Charts）
• 名前空間のインポートとサービスの登録
• スクリプト参照
• 基本的なチャートの実装
• シンプルなデータバインディングの例

---

チャートタイプ

一般的なチャートの種類

📄 参照： references/chart-types-common.md

よく使用されるチャートの種類については、こちらを参照してください。

• トレンドの可視化に使う折れ線チャート
• 時間経過に伴う大きさの表示に使うエリアチャート
• カテゴリの比較に使う縦棒チャート
• 水平方向の比較に使う横棒チャート
• 滑らかな曲線を描くスプラインチャート
• 段階的なデータの推移を示すステップチャート

対象トピック：

• 折れ線、エリア、縦棒、横棒チャートの実装
• スプラインおよびスプラインエリアのバリエーション
• ステップ折れ線とステップエリアのパターン
• 各チャートの種類を使う場面
• 設定とカスタマイズ
• 複数系列の例

特殊なチャートの種類

📄 参照： references/chart-types-specialized.md

特殊な可視化のニーズについては、こちらを参照してください。

• 金融チャート（ローソク足、HILO、HILOOC）
• 統計チャート（箱ひげ図、ヒストグラム、エラーバー、パレート図、ウォーターフォール図）
• 積み上げチャート（積み上げエリア／横棒／縦棒／折れ線）
• 範囲チャート（範囲エリア／縦棒／ステップエリア）
• 極座標チャートとレーダーチャート
• 散布図とバブルチャート
• 垂直方向のチャート表示

対象トピック：

• 金融チャートのパターンと設定
• 統計分析用のチャートの種類
• 積み上げモード（通常と 100％）
• 範囲の可視化手法
• 円形チャートのレイアウト
• XY 散布図の関係性
• チャートの向きのオプション

---

軸とデータの設定

📄 参照： references/axes-and-scales.md

次のような場合に参照してください。

• 軸の種類（カテゴリ、数値、日時、対数）を設定する
• 軸の外観と動作をカスタマイズする
• 軸ラベルと値の書式を設定する
• 複数の軸を使用する
• 軸の範囲と間隔を設定する

対象トピック：

• 離散データ用のカテゴリ軸
• 連続値用の数値軸
• 時系列データ用の日時軸
• 指数データ用の対数軸
• 軸のカスタマイズ（タイトル、範囲、間隔）
• ラベルの書式設定、回転、配置
• 複数軸の設定
• 逆軸と反対側の軸

📄 参照： references/data-handling.md

次のような場合に参照してください。

• データソースをチャートにバインドする
• データを動的に追加、削除、更新する
• データ編集を有効にする
• チャートデータを並べ替える
• ライブデータやストリーミングデータを扱う

対象トピック：

• データソースのバインド（List、DataManager）
• 動的なデータ操作
• データ編集機能
• チャートの並べ替えオプション
• リアルタイムのデータ更新
• データのシリアル化パターン

---

視覚要素

📄 参照： references/visual-elements.md

次のような場合に参照してください。

• チャートのデータポイントにデータマーカーを追加する
• 系列にデータラベルを表示する
• カスタムラベルテンプレートを作成する
• 注釈（テキスト、図形、画像）を追加する
• グラデーションの塗りつぶしを適用する

対象トピック：

• データマーカーの種類とカスタマイズ
• データラベルの表示と書式設定
• ラベルの配置方法
• データラベルテンプレート
• 系列を識別するための系列ラベルの表示
• 最後のデータラベルの強調表示
• チャートの注釈（テキスト、図形、画像）
• グラデーションの塗りつぶし

📄 参照： references/legend.md

次のような場合に参照してください。

• チャートの凡例を有効化して設定する
• 凡例の位置（上、下、左、右）を指定する
• 凡例の外観をカスタマイズする
• 凡例のクリック動作を実装する
• カスタム凡例テンプレートを作成する

対象トピック：

• 凡例の表示と配置
• 凡例の図形とテキストのカスタマイズ
• インタラクティブな凡例（系列の切り替え）
• 凡例のページ分割
• カスタム凡例テンプレート
• 凡例の配置オプション

---

インタラクティブ機能

📄 参照： references/interactive-features.md

次のような場合に使用します：

• カスタム書式のツールチップを有効にする
• データ追跡用のクロスヘアやトラックボールを追加する
• ポイント、系列、クラスターの選択を実装する
• ズームとパンを有効にする
• インタラクティブなユーザー体験を作成する

対象トピック：

• ツールチップの設定とテンプレート
• クロスヘアとトラックボール機能
• 選択モードとパターン
• ズームの種類（選択、ピンチ、マウスホイール）
• ズームツールバーの設定
• パン機能
• ユーザー操作イベント

---

カスタマイズと外観

📄 参照： references/appearance-styling.md

次のような場合に使用します：

• チャートの外観とテーマをカスタマイズする
• チャートの寸法とサイズを設定する
• レスポンシブ／アダプティブレイアウトを設定する
• 印刷機能を有効にする
• 背景、枠線、余白をスタイリングする

対象トピック：

• チャートの外観のカスタマイズ
• テーマの設定
• チャートの寸法とサイズ
• レスポンシブデザインのパターン
• モバイル向けアダプティブレイアウト
• 印刷サポート
• 背景と枠線のスタイリング
• グラデーションのカスタマイズ

📄 参照： references/advanced-features.md

次のような場合に使用します：

• テクニカル指標（EMA、SMA、RSI など）を追加する
• トレンドライン（線形、指数、多項式）を実装する
• ストリップライン（水平／垂直の帯）を作成する
• 複数のペイン（サブチャート）を使用する
• 空のポイントを処理する

対象トピック：

• 金融チャート向けテクニカル指標
• トレンドラインの種類と設定
• ストリップラインのパターン
• 複数ペインのレイアウト
• 空のポイントの処理方法
• 行と列の定義

---

アクセシビリティと国際化

📄 参照： references/accessibility-internationalization.md

次のような場合に使用します：

• アクセシブルなチャート（ARIA、キーボード操作）を実装する
• 高度なアクセシビリティ機能を設定する
• 国際化（i18n）を有効にする
• ローカライズ（l10n）を設定する
• RTL レイアウトに対応する

対象トピック：

• アクセシビリティ機能と ARIA サポート
• キーボード操作のパターン
• 高度なアクセシビリティ設定
• 国際化の設定
• ローカライズリソース
• RTL サポート
• スクリーンリーダーとの互換性

---

イベント

📄 参照： references/events.md

次のような場合に使用します：

• チャートのライフサイクルイベントを処理する
• ユーザー操作（クリック、マウスイベント）に応答する
• 軸、系列、ポイントのイベントをリッスンする
• カスタムイベントハンドラーを実装する
• ズーム、パン、選択時にアクションを実行する

対象トピック：

• チャートの読み込みイベントと描画イベント
• ポイントと系列のイベント
• マウスイベント（クリック、移動、離脱）
• 軸ラベルの描画イベント
• 凡例のイベント
• ズームとパンのイベント
• 選択イベント
• イベントハンドラーのパターン

---

実用例とハウツーガイド

📄 参照： references/practical-examples.md

次のような一般的な実装シナリオに使用します：

• 系列を動的に追加／削除する
• 軸をプログラムで非表示にする
• ミリ秒を日時に変換する
• ポイントを動的に更新する
• 遅延読み込みを実装する
• ライブ／リアルタイムチャートを作成する
• 選択したデータを取得する
• 複数のチャートを同期する
• しきい値ラインを追加する
• カスタムツールチップテーブルを作成する

対象トピック：

• 系列の動的な管理
• 軸の表示制御
• 日付変換の手法
• ポイントの動的な更新
• 遅延読み込みのパターン
• ライブチャートの実装
• 選択データの取得
• チャートの同期
• しきい値ラインの実装
• カスタムツールチップテーブル

---

パブリックメソッドのリファレンス

SfChart コンポーネントには、プログラムから制御するための複数のパブリックメソッドが用意されています。これらのメソッドにアクセスするには、必ず @ref を使用してください。

必須メソッド

<SfChart @ref="ChartRef">
    
</SfChart>

@code {
    SfChart ChartRef;
    
    // Refresh the chart
    async Task RefreshChart() => await ChartRef.RefreshAsync();
    
    // Export the chart
    async Task ExportChart() => await ChartRef.ExportAsync(ExportType.PNG, "chart.png");
    
    // Print the chart
    async Task PrintChart() => await ChartRef.PrintAsync();
    
    // Show/Hide tooltip
    void ShowChartTooltip() => ChartRef.ShowTooltip("January", 35);
    void HideChartTooltip() => ChartRef.HideTooltip();
    
    // Show/Hide crosshair
    void ShowChartCrosshair() => ChartRef.ShowCrosshair(100, 50);
    void HideChartCrosshair() => ChartRef.HideCrosshair();
    
    // Selection control
    void ClearSelections() => ChartRef.ClearSelection();
    
    // Sorting
    void SortData() => ChartRef.Sort("YValue", ListSortDirection.Descending);
    void ClearChartSort() => ChartRef.ClearSort();
}

メソッドの詳細については、references/api-reference.md を参照してください。

---

⚠️ 重要：API 使用ガイドライン

1. 列挙型名 — 完全修飾名を必ず使用する

Syncfusion Blazor Charts では、列挙型名を完全修飾名で指定する必要があります。

<ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category" />
<ChartSeries Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column" />


<ChartPrimaryXAxis ValueType="ValueType.Category" />
<ChartSeries Type="ChartSeriesType.Column" />

以下には、必ず Syncfusion.Blazor.Charts. のプレフィックスを付けてください。

• ValueType（Category、Double、DateTime など）
• ChartSeriesType（Column、Line、Area など）
• LegendPosition、SelectionMode、ZoomMode、ChartShape など

2. コンポーネントのプロパティ制限

⚠️ よくあるプロパティのエラーに注意してください。

ChartCrosshairLine — 使用できるプロパティは限定されています

<ChartCrosshairSettings Enable="true">
    <ChartCrosshairLine Width="1" Color="#666"></ChartCrosshairLine>
</ChartCrosshairSettings>


<ChartCrosshairLine Width="1" Color="#666" DashArray="5,5"></ChartCrosshairLine>

ChartCrosshairLine でサポートされているプロパティ：

• Width — 線の幅（数値）
• Color — 線の色（文字列）

サポートされていないプロパティ：

• ❌ DashArray — 実行時エラーが発生します
• ❌ Opacity — このコンポーネントでは使用できません

ストリップライン — 複数形を使用する

<ChartPrimaryYAxis>
    <ChartStriplines>
        <ChartStripline Start="50" End="60" Color="red" />
    </ChartStriplines>
</ChartPrimaryYAxis>


<ChartAxisStripLineSettings>
    <ChartAxisStripLine Start="50" End="60" />
</ChartAxisStripLineSettings>

3. 検証チェックリスト

デプロイする前に、以下を確認してください。

• ✅ すべての列挙型に Syncfusion.Blazor.Charts. のプレフィックスが付いている
• ✅ ChartCrosshairLine では Width と Color のみを使用している
• ✅ ストリップラインで <ChartStriplines> と <ChartStripline> を使用している
• ✅ メソッドにアクセスするコンポーネント参照で @ref を使用している
• ✅ プロパティ名が公式 API と完全に一致している（大文字と小文字を区別）

---

クイックスタートの例

データを使って縦棒グラフを作成する最小限の例を紹介します。

@page "/chart-demo"
@using Syncfusion.Blazor.Charts

<SfChart Title="Sales Analysis">
    <ChartPrimaryXAxis Title="Month" ValueType="Syncfusion.Blazor.Charts.ValueType.Category">
    </ChartPrimaryXAxis>
    
    <ChartPrimaryYAxis Title="Sales in Dollar">
    </ChartPrimaryYAxis>
    
    <ChartTooltipSettings Enable="true"></ChartTooltipSettings>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@SalesData" 
                     Name="Sales" 
                     XName="Month" 
                     YName="SalesValue" 
                     Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
            <ChartMarker>
                <ChartDataLabel Visible="true"></ChartDataLabel>
            </ChartMarker>
        </ChartSeries>
    </ChartSeriesCollection>
</SfChart>

@code {
    public class SalesInfo
    {
        public string Month { get; set; }
        public double SalesValue { get; set; }
    }

    public List<SalesInfo> SalesData = new List<SalesInfo>
    {
        new SalesInfo { Month = "Jan", SalesValue = 35 },
        new SalesInfo { Month = "Feb", SalesValue = 28 },
        new SalesInfo { Month = "Mar", SalesValue = 34 },
        new SalesInfo { Month = "Apr", SalesValue = 32 },
        new SalesInfo { Month = "May", SalesValue = 40 },
        new SalesInfo { Month = "Jun", SalesValue = 32 }
    };
}

前提条件：

1. Syncfusion.Blazor.Charts NuGet パッケージをインストールする
2. _Imports.razor に @using Syncfusion.Blazor.Charts を追加する
3. Program.cs でサービスを登録する：builder.Services.AddSyncfusionBlazor();
4. App.razor にスクリプト参照を追加する

---

よく使われるパターン

複数系列の比較グラフ

<SfChart Title="Product Sales Comparison">
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category"></ChartPrimaryXAxis>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@Product1Sales" XName="Month" YName="Sales" 
                     Name="Product 1" Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
        </ChartSeries>
        <ChartSeries DataSource="@Product2Sales" XName="Month" YName="Sales" 
                     Name="Product 2" Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
        </ChartSeries>
    </ChartSeriesCollection>
    
    <ChartLegendSettings Visible="true"></ChartLegendSettings>
</SfChart>

ズーム機能付き時系列折れ線グラフ

<SfChart>
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.DateTime" 
                        Title="Date">
    </ChartPrimaryXAxis>
    
    <ChartZoomSettings EnableSelectionZooming="true" 
                       EnablePan="true" 
                       EnableMouseWheelZooming="true">
    </ChartZoomSettings>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@TimeSeriesData" 
                     XName="Date" 
                     YName="Value" 
                     Type="Syncfusion.Blazor.Charts.ChartSeriesType.Line">
        </ChartSeries>
    </ChartSeriesCollection>
</SfChart>

凡例付き積み上げ面グラフ

<SfChart Title="Resource Allocation">
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category"></ChartPrimaryXAxis>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@ResourceData1" XName="Period" YName="Hours" 
                     Name="Development" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
        <ChartSeries DataSource="@ResourceData2" XName="Period" YName="Hours" 
                     Name="Testing" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
        <ChartSeries DataSource="@ResourceData3" XName="Period" YName="Hours" 
                     Name="Documentation" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
    </ChartSeriesCollection>
    
    <ChartLegendSettings Visible="true" Position="Syncfusion.Blazor.Charts.LegendPosition.Bottom">
    </ChartLegendSettings>
</SfChart>

---

主な構成プロパティ

グラフコンポーネント（SfChart）

• Title — グラフのタイトルテキスト
• Width / Height — グラフの寸法（px または % を指定。デフォルト：「100%」）
• Theme — ビジュアルテーマ（API リファレンスの Theme 列挙型を参照）
• Background — グラフの背景色
• EnableAnimation — アニメーションの有効／無効（デフォルト：true）
• SelectionMode — 選択モード（None、Series、Point、Cluster、DragXY、DragX、DragY、Lasso）
• HighlightMode — ハイライトモード（None、Series、Point、Cluster）

主軸（ChartPrimaryXAxis、ChartPrimaryYAxis）

• ValueType — 軸の種類：Syncfusion.Blazor.Charts.ValueType.Category、ValueType.Double、ValueType.DateTime、ValueType.Logarithmic、ValueType.DateTimeCategory
• Title — 軸のタイトル
• Minimum / Maximum — 軸の範囲
• Interval — ラベル間隔
• LabelFormat — ラベルの書式文字列（例：「C0」、「N2」、「dd MMM」）
• EdgeLabelPlacement — 端のラベルの処理（None、Hide、Shift）
• LabelIntersectAction — ラベルの重なりの処理（None、Hide、Trim、Wrap、MultipleRows、Rotate45、Rotate90）
• ストリップライン — 水平方向／垂直方向の帯には、複数形の <ChartStriplines> を使用します

系列（ChartSeries）

• DataSource — データコレクション（IEnumerable）
• XName / YName — X 値と Y 値に使用するプロパティ名（大文字と小文字を区別）
• Type — グラフの種類：Syncfusion.Blazor.Charts.ChartSeriesType.Column、ChartSeriesType.Line など（API リファレンスを参照）
• Name — 凡例に表示する系列名
• Fill — 系列の色（CSS の色文字列）
• Width — 線／枠線の幅（ピクセル）
• DashArray — 破線のパターン（例：「5,5」）
• Opacity — 不透明度（0～1）

インタラクティブ機能

• ChartTooltipSettings - ツールチップの設定
  • Enable - ツールチップの表示／非表示
  • Shared - 複数の系列で共有ツールチップを有効化
  • Format - カスタムツールチップの書式
  • Template - カスタムツールチップのテンプレート（RenderFragment）
• ChartZoomSettings - ズームとパンのオプション
  • EnableSelectionZooming - 選択範囲によるズームを有効化
  • EnableMouseWheelZooming - マウスホイールによるズームを有効化
  • EnablePinchZooming - ピンチズームを有効化（タッチデバイス）
  • EnablePan - パンを有効化
  • Mode - ズームモード（X、Y、XY）
• SelectionMode - 選択動作（SelectionMode enumを参照）
• ChartCrosshairSettings - クロスヘアの設定
  • Enable - クロスヘアの表示／非表示
  • LineType - クロスヘアの線の種類（Vertical、Horizontal、Both）
  • ChartCrosshairLine - 線のスタイル（Width、Colorのみ。DashArrayはありません）

視覚要素

• ChartMarker - データポイントのマーカー
  • Visible - マーカーの表示／非表示
  • Shape - マーカーの形状（ChartShape enumを参照）
  • Width / Height - マーカーの寸法
• ChartDataLabel - データポイントのデータラベル
  • Visible - ラベルの表示／非表示
  • Position - ラベルの位置
  • Template - カスタムラベルのテンプレート
• SeriesLabelSettings - 系列ラベルの表示、テキスト、重なりの処理、スタイル
• ChartLegendSettings - 凡例の設定
  • Visible - 凡例の表示／非表示
  • Position - 凡例の位置（LegendPosition enumを参照）
• ChartAnnotations - カスタム注釈
  • テキスト、画像、図形に対応

---

追加リソース

• 公式ドキュメント： Syncfusion Blazor Chart Documentation
• API リファレンス： Chart API
• ライブデモ： Blazor Chart Demos