syncfusion-blazor-heatmap-chart

Syncfusion Blazor HeatMap Chart の実装

NuGet: Syncfusion.Blazor.HeatMap + Syncfusion.Blazor.Themes
Namespace: Syncfusion.Blazor.HeatMap

マトリックスレイアウトの色分けされたセルを使って多次元データを可視化する、Syncfusion Blazor HeatMap Chart コンポーネントの実装に関する包括的なガイドです。

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

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

• 値を表す色のグラデーションでマトリックスデータを可視化する
• 2 つの次元にまたがる相関行列や比較データを表示する
• データの強度を示す熱分布や密度の可視化を作成する
• セルの色で大きさやカテゴリを表す表形式のデータを表示する
• 複数のデータ次元を表すためにサイズと色を組み合わせたバブル HeatMap を実装する
• 直感的なグリッドベースの可視化を必要とするデータダッシュボードを構築する
• カテゴリ軸または日時軸で時系列データを表示する
• インタラクティブなツールチップと凡例を備えた大規模データセットを可視化する
• WCAG 準拠の機能を備えたアクセシブルなデータ可視化を作成する

コンポーネントの概要

Syncfusion Blazor HeatMap Chart コンポーネント（SfHeatMap）は、各セルの色で値を表す、セルのマトリックスとして多次元データを表示する強力なデータ可視化ツールです。次の機能をサポートしています。

• 複数のデータバインドモード：配列（2D）、JSON／テーブル、セルベース
• 柔軟な軸の種類：カテゴリ、数値、日時、および複数レベルのラベル
• 2 つの可視化モード：矩形セルとバブル HeatMap
• 豊富なカスタマイズ機能：パレット（グラデーション／固定）、凡例、ツールチップ、タイトル、ラベル
• インタラクティブな機能：セル選択、イベント、動的レンダリング
• アクセシビリティ：WCAG 準拠、キーボード操作、スクリーンリーダーのサポート
• 高度な機能：コンテンツセキュリティポリシーへの対応、レスポンシブなサイズ設定、パフォーマンスの最適化

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

はじめにとインストール

📄 参照： references/getting-started.md

• 前提条件とシステム要件
• Blazor WebAssembly アプリの作成（Visual Studio、VS Code、.NET CLI）
• Syncfusion.Blazor.HeatMap NuGet パッケージのインストール
• Syncfusion Blazor サービスの登録
• スタイルシートとスクリプトリソースの追加
• 名前空間のインポート
• 最初の HeatMap コンポーネントの実装
• 基本的なデータソースの構成
• アプリケーションの実行とテスト

データバインドとデータの操作

📄 参照： references/working-with-data.md

• データソースの種類の概要（配列、JSON／テーブル、セル）
• 2D 配列および多次元配列を使用した配列データのバインド
• アダプター構成を使用した JSON／テーブルデータのバインド
• 個々のセルをカスタマイズするセルデータバインド
• x 軸と y 軸のフィールドマッピング
• データ変換のパターン
• 空のセルと null 値の処理
• 大規模データセットのパフォーマンスに関する考慮事項

軸の構成

📄 参照： references/axis.md

• 軸の種類：カテゴリ、数値、日時
• カスタムラベルを使用したカテゴリ軸
• 範囲設定（最小値、最大値、間隔）を使用した数値軸
• 書式設定と間隔の種類を使用した日時軸
• 軸ラベルのカスタマイズ（回転、配置、スタイル）
• 軸ラベルのテンプレート
• 階層データ用の複数レベルラベル
• 軸の反転と反対側への配置
• 軸タイトルの構成

外観とカスタマイズ

📄 参照： references/appearance.md

• セルのカスタマイズ（枠線、強調表示、タイルの種類）
• 余白の設定
• タイトルの設定（テキスト、配置、テキストスタイル）
• データラベルの構成（表示／非表示、書式、テンプレート）
• 枠線の構成（幅、角丸、色）
• 背景とコンテナーのスタイル設定
• テキストスタイルのカスタマイズ（サイズ、色、フォントファミリー、太さ）
• データラベルのテンプレート対応
• レスポンシブデザインに関する考慮事項

カラーパレット

📄 参照： references/palette.md

• パレットの種類：固定とグラデーション
• 色のマッピングと値の範囲を設定した固定パレット
• 色の変化を設定したグラデーションパレット
• カスタムカラースキーム
• 空のセルと null セルの色
• 組み込みのパレットプリセット
• 色のアクセシビリティに関する考慮事項
• カラーグラデーションのモード（テーブル、行、列）

凡例の設定

📄 参照： references/legend.md

• 凡例の表示と配置
• 凡例の種類（グラデーション、リスト）
• 凡例のカスタマイズ（幅、高さ、配置）
• セルの表示を切り替えられるスマート凡例
• 凡例に割合を表示
• 凡例テキストのスタイルのカスタマイズ
• 凡例タイトルの設定
• セグメントの設定
• 凡例項目のテンプレート対応

ツールチップ

📄 参照： references/tooltip.md

• ツールチップの有効化と設定
• ツールチップの内容のカスタマイズ
• 配列データ用のツールチップテンプレート
• JSON データ用のツールチップテンプレート
• ツールチップテキストのスタイルのカスタマイズ
• 枠線と塗りつぶしのカスタマイズ
• アニメーションの設定
• 条件に応じたツールチップの表示

イベントとインタラクティブ機能

📄 参照： references/events.md

• コンポーネントのライフサイクルイベント（Load、Loaded）
• イベント引数を伴う CellClick イベント
• CellDoubleClick イベント
• セルをカスタム描画する CellRender イベント
• 動的なツールチップコンテンツを設定する TooltipRender イベント
• 凡例をカスタマイズする LegendRender イベント
• カスタムの軸ラベルを設定する AxisLabelRender イベント
• イベント処理のパターンとベストプラクティス
• イベント使用時のパフォーマンスに関する考慮事項

バブル HeatMap のバリエーション

📄 参照： references/bubble-heatmap.md

• バブル HeatMap の概要と用途
• バブルタイプ（TileType.Bubble）の有効化
• 値に基づくバブルサイズの設定
• バブルサイズの種類（絶対値、割合）
• バブルの色のマッピング
• 多次元データ向けのバブルサイズと色の組み合わせ
• バブル HeatMap のデータ要件
• バブルを使ったビジュアライゼーションのベストプラクティス

高度な機能

📄 参照： references/advanced-features.md

• 寸法とサイズ設定（幅、高さ、レスポンシブなサイズ設定）
• セルの選択モード（セル、列、行）
• 選択のカスタマイズ
• コンテンツセキュリティポリシー（CSP）への準拠
• アクセシビリティ機能（WCAG、WAI-ARIA、キーボードナビゲーション）
• スクリーンリーダーのサポート
• 大規模なデータセット向けのパフォーマンス最適化
• 仮想化の戦略
• サーバーサイドレンダリングに関する考慮事項

API リファレンス

📄 参照： references/api-reference.md

• メインコンポーネント SfHeatMap
• コア設定クラス（Cell、Title、Palette、Legend、Tooltip）
• 軸クラス（HeatMapXAxis、HeatMapYAxis）
• マルチレベルラベルの設定
• バブル設定クラス
• スタイル設定クラス（枠線、テキストスタイル、マージン）
• イベント引数クラス
• 列挙型（CellType、PaletteType、AdaptorType など）
• プロパティとメソッドの完全なリファレンス

クイックスタートの例

HeatMap Chart コンポーネントを使い始めるための最小限の例を紹介します。

@page "/heatmap"
@using Syncfusion.Blazor.HeatMap

<SfHeatMap DataSource="@HeatMapData">
    <HeatMapTitleSettings Text="Sales Revenue per Employee (in 1000 US$)"></HeatMapTitleSettings>
    <HeatMapCellSettings ShowLabel="true" TileType="CellType.Rect"></HeatMapCellSettings>
</SfHeatMap>

@code {
    int[,] GetDefaultData()
    {
        int[,] dataSource = new int[,]
        {
            {52, 65, 67, 45, 37, 52},
            {68, 52, 63, 51, 30, 51},
            {7, 16, 47, 47, 88, 6},
            {66, 64, 46, 40, 47, 41},
            {14, 46, 97, 69, 69, 3},
            {54, 46, 61, 46, 40, 39}
        };
        return dataSource;
    }
    
    public object HeatMapData { get; set; }
    
    protected override void OnInitialized()
    {
        HeatMapData = GetDefaultData();
    }
}

前提条件：

1. Syncfusion.Blazor.HeatMap NuGet パッケージをインストールします
2. Syncfusion サービスを登録します：builder.Services.AddSyncfusionBlazor();
3. index.html にテーマのスタイルシートとスクリプトの参照を追加します
4. 名前空間を追加します：@using Syncfusion.Blazor.HeatMap

よくあるパターン

パターン 1：カスタム軸を使用した JSON データ

@using Syncfusion.Blazor.HeatMap

<SfHeatMap DataSource="@JsonData">
    <HeatMapDataSourceSettings IsJsonData="true" 
                               AdaptorType="AdaptorType.Table" 
                               XDataMapping="ProductName"
                               YDataMapping="Year" 
                               ValueMapping="Value">
    </HeatMapDataSourceSettings>
    <HeatMapXAxis Labels="@XAxisLabels"></HeatMapXAxis>
    <HeatMapYAxis Labels="@YAxisLabels"></HeatMapYAxis>
</SfHeatMap>

@code {
    private object[] JsonData = new object[]
    {
        new { ProductName = "Laptop", Year = "2022", Value = 150 },
        new { ProductName = "Desktop", Year = "2022", Value = 80 },
        // ... more data
    };
    
    private string[] XAxisLabels = new string[] { "Laptop", "Desktop", "Tablet", "Phone" };
    private string[] YAxisLabels = new string[] { "2022", "2023", "2024" };
}

パターン 2：カスタムカラーを使用したグラデーションパレット

@using Syncfusion.Blazor.HeatMap

<SfHeatMap DataSource="@HeatMapData">
    <HeatMapPaletteSettings Type="PaletteType.Gradient">
        <HeatMapPalettes>
            <HeatMapPalette Color="#C2E7EC" Value="0"></HeatMapPalette>
            <HeatMapPalette Color="#AEDFE6" Value="25"></HeatMapPalette>
            <HeatMapPalette Color="#7FCDC4" Value="50"></HeatMapPalette>
            <HeatMapPalette Color="#6EB5D0" Value="75"></HeatMapPalette>
            <HeatMapPalette Color="#2D6CA2" Value="100"></HeatMapPalette>
        </HeatMapPalettes>
    </HeatMapPaletteSettings>
</SfHeatMap>

パターン 3：サイズと色を設定したバブル HeatMap

@using Syncfusion.Blazor.HeatMap

<SfHeatMap DataSource="@BubbleData">
    <HeatMapCellSettings TileType="CellType.Bubble" 
                         BubbleType="BubbleType.SizeAndColor">
        <HeatMapBubbleSize Minimum="10" Maximum="30"></HeatMapBubbleSize>
    </HeatMapCellSettings>
    <HeatMapDataSourceSettings IsJsonData="true" 
                               AdaptorType="AdaptorType.Cell"
                               XDataMapping="XAxis"
                               YDataMapping="YAxis"
                               ValueMapping="Value">
        <HeatMapBubbleDataMapping Size="Size" Color="Value"></HeatMapBubbleDataMapping>
    </HeatMapDataSourceSettings>
</SfHeatMap>

パターン 4：イベントを使用したインタラクティブな HeatMap

@using Syncfusion.Blazor.HeatMap

<SfHeatMap DataSource="@HeatMapData">
    <HeatMapEvents CellClicked="@OnCellClick"
                   TooltipRendering="@OnTooltipRender">
    </HeatMapEvents>
    <HeatMapTooltipSettings>
        <Template>
            @{
                var data = context as TooltipEventArgs;
                <div>@data.XLabel - @data.YLabel: @data.Value</div>
            }
        </Template>
    </HeatMapTooltipSettings>
</SfHeatMap>

@code {
    private void OnCellClick(Syncfusion.Blazor.HeatMap.CellClickEventArgs args)
    {
        Console.WriteLine($"Cell clicked: {args.XLabel}, {args.YLabel}, Value: {args.Value}");
    }
    
    private void OnTooltipRender(Syncfusion.Blazor.HeatMap.TooltipEventArgs args)
    {
        // Customize tooltip content dynamically
    }
}

主要プロパティのリファレンス

プロパティ	型	目的
DataSource	object	ヒートマップのデータ（配列、JSON、またはセルデータ）を設定します
Width	string	ヒートマップの幅を設定します（例："100%"、"600px"）
Height	string	ヒートマップの高さを設定します（例："400px"）
HeatMapCellSettings.ShowLabel	bool	セルラベルの表示／非表示を設定します
HeatMapCellSettings.TileType	CellType	セルの種類（Rect または Bubble）を設定します
HeatMapDataSourceSettings.IsJsonData	bool	データソースが JSON 形式かどうかを示します
HeatMapDataSourceSettings.AdaptorType	AdaptorType	アダプターの種類（Table、Cell、None）を設定します
HeatMapPaletteSettings.Type	PaletteType	パレットの種類（Fixed または Gradient）を設定します
HeatMapLegendSettings.Visible	bool	凡例の表示／非表示を設定します
HeatMapTooltipSettings	object	ツールチップの外観とコンテンツを設定します
HeatMapXAxis.ValueType	ValueType	X 軸の種類（Category、Numeric、DateTime）を設定します
HeatMapYAxis.ValueType	ValueType	Y 軸の種類（Category、Numeric、DateTime）を設定します

一般的なユースケース

ユースケース 1：売上実績ダッシュボード

グラデーションカラーを使ったヒートマップで、製品別および期間別の売上実績を可視化し、実績の高い項目と低い項目を強調表示します。

使用する場面： 月次／四半期の売上追跡、製品比較、地域別の実績分析。

ユースケース 2：相関行列

複数の変数間の相関係数を、発散型の配色を用いた行列形式で表示します。

使用する場面： 統計分析、データサイエンスプロジェクト、特徴量の相関分析。

ユースケース 3：サーバーリソースの監視

複数のサーバーにおける CPU、メモリ、またはネットワークの使用状況を、期間ごとに監視します。

使用する場面： DevOps ダッシュボード、インフラストラクチャの監視、キャパシティプランニング。

ユースケース 4：カレンダーヒートマップ

カレンダー形式のレイアウトで、日や月ごとのアクティビティレベルやイベントの頻度を表示します。

使用する場面： GitHub 風のコントリビューショングラフ、出席状況の追跡、アクティビティログ。

ユースケース 5：多次元データ向けバブルヒートマップ

バブルのサイズで 1 つの指標（例：販売量）を、色で別の指標（例：利益率）を表します。

使用する場面： 関連する 2 つの指標の同時比較、ポートフォリオ分析、競争上の位置付けの分析。

関連スキル

• TreeMap の可視化については、Syncfusion Blazor TreeMap を参照してください
• その他のデータ可視化コンポーネントについては、データ可視化カテゴリをご覧ください

ベストプラクティス

1. 適切なパレットの種類を選択する：連続データにはグラデーションパレットを、カテゴリデータには固定パレットを使用します
2. ツールチップを有効にする：データをより適切に解釈できるよう、常にツールチップを設定します
3. 意味のある軸ラベルを使用する：軸ラベルからデータの次元が明確にわかるようにします
4. 大規模なデータセットに最適化する：数千のセルを含むデータセットでは、データのサンプリングや仮想化を検討します
5. アクセシビリティをテストする：キーボードナビゲーションとスクリーンリーダーとの互換性を確認します
6. レスポンシブなサイズ設定：レスポンシブレイアウトには、パーセンテージベースの幅を使用します
7. 色のアクセシビリティ：十分な色のコントラストを確保し、情報を伝える際に色だけに頼らないようにします
8. パフォーマンス：パフォーマンスを向上させるため、複雑なイベントハンドラーやテンプレートのレンダリングを最小限に抑えます

トラブルシューティング早見ガイド

問題	解決策
ヒートマップが表示されない	NuGet パッケージのインストールとサービスの登録を確認します
データが表示されない	DataSource のバインドを確認し、データ形式がアダプターの種類と一致しているか確認します
色が表示されない	適切なパレットの種類を指定して HeatMapPaletteSettings を設定します
ツールチップが動作しない	HeatMapTooltipSettings が有効なコンテンツで設定されていることを確認します
軸ラベルが表示されない	HeatMapXAxis/HeatMapYAxis の Labels プロパティを設定します
パフォーマンスの問題	セル数を減らす、アニメーションを無効にする、または仮想化を実装します

詳細なトラブルシューティングについては、各機能領域のリファレンスファイルを参照してください。