syncfusion-blazor-treemap

TreeMap の実装

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

このスキルでは、Syncfusion Blazor TreeMap コンポーネントの実装に関するガイダンスをまとめています。必要なリファレンストピックは、以下のナビゲーションガイドから開いてください。各リファレンスファイルは単独で利用でき、例、エッジケース、トラブルシューティングが含まれています。

公式 API の概要

• コンポーネント：SfTreeMap<TValue>
• インターフェイス：ITreeMap
• 主な子設定：TreeMapLevels、TreeMapLeafItemSettings、TreeMapLegendSettings、TreeMapTooltipSettings、TreeMapSelectionSettings、TreeMapHighlightSettings、TreeMapEvents
• 主な列挙型：LayoutMode、RenderingMode、LabelPosition、LabelPlacement、LabelIntersectAction、LegendMode、LegendPosition、LegendOrientation、LegendShape、SelectionMode、HighLightMode
• 主なイベント引数：LoadEventArgs、LoadedEventArgs、ItemRenderingEventArgs、ItemClickEventArgs、ItemSelectedEventArgs、ItemMoveEventArgs、LegendRenderingEventArgs、LegendItemRenderingEventArgs、TreeMapTooltipArgs

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

• Blazor アプリで階層型の面積比例可視化を組み込む場合。
• レイアウト、カラーマッピング、ラベル、凡例、ドリルダウンに関するガイダンスが必要な場合。
• 階層型またはフラットなデータセットのデータバインディングを設定する場合。
• アクセシビリティ、ローカライズ、印刷／エクスポート、パフォーマンス最適化を実装する場合。

⚠️ セキュリティ警告

適切な検証を行わずに、TreeMap を信頼できない公開 API やサードパーティのデータソースにバインドしないでください。 リモートデータは操作され、悪意のあるコードの挿入、可視化の破損、サービス拒否攻撃を引き起こす可能性があります。必ず以下を行ってください。

• ✅ 自分が所有し、管理する社内の認証済み API のみを使用する
• ✅ バインド前に、すべてのリモートデータを検証してサニタイズする
• ✅ サーバー側で認可とレート制限を実装する
• ✅ HTTPS を使用し、SSL/TLS 証明書を検証する
• ✅ XSS を防ぐため、文字列プロパティを HTML エンコードする

詳細なセキュリティガイダンスについては、こちらを参照してください： Security Considerations in data-binding.md

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

API リファレンス

📄 参照： references/api-reference.md

• TreeMap のメインコンポーネント、子設定、イベント、メソッド、列挙型をすばやく確認できます。

はじめに

📄 参照： references/getting-started.md

• インストール、NuGet パッケージ、プロジェクトの設定、最小限の例。

データバインディングとデータソース

📄 参照： references/data-binding.md

• フラットデータと階層型データ、ローカル／リモートデータソース、データアダプター。
• リモートデータのバインディング：自分が管理する社内の認証済み API のみに限定してください。信頼できないサードパーティのエンドポイントに直接バインドしないでください。必須のセキュリティチェックリストと安全なパターン（サーバー側プロキシ、検証、サニタイズ、レート制限）については、references/data-binding.md を参照してください。

レイアウトとレベル

📄 参照： references/layout-and-levels.md

• レイアウトアルゴリズム、レベルのグループ化、ヘッダー、間隔。

リーフアイテム

📄 参照： references/leaf-items.md

• リーフノードのスタイル設定、テンプレート、ラベルの位置。

カラーマッピング

📄 参照： references/color-mapping.md

• 範囲、均等、彩度低下、パレットのマッピングと各種戦略。

ラベル

📄 参照： references/labels.md

• データラベルのテンプレート、書式設定、オーバーフローの処理。

凡例

📄 参照： references/legend.md

• 凡例モード、配置、スマート凡例の動作。

ツールチップ

📄 参照： references/tooltip.md

• 既定およびテンプレートを使用したツールチップ、スタイル設定、動的コンテンツ。

ドリルダウン

📄 参照： references/drill-down.md

• ドリルダウンの有効化、パンくずリスト、カスタムナビゲーション。

選択とハイライト

📄 参照： references/selection-and-highlight.md

• 選択モード、ハイライト、プログラムによる選択。

イベントとメソッド

📄 参照： references/events-and-methods.md

• ライフサイクルイベント、レンダリングイベント、印刷／エクスポートメソッド。

高度な機能

📄 参照： references/advanced-features.md

• アクセシビリティ、ローカライズ、パフォーマンス、TreeMap を他のコンポーネント内に配置する方法。

トラブルシューティング

📄 参照： references/troubleshooting.md

• よくある問題、レンダリングやデータバインディングの修正方法。

クイックスタート（最小限の例）

@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@Data"> 
  <TreeMapLevels>
    <TreeMapLevel GroupPath="Category" />
  </TreeMapLevels>
</SfTreeMap>

@code {
  public object[] Data = new[] { new { Category = "A", Value = 10 } };
}

よく使われるパターン

• 階層構造を探索するには、選択とドリルダウンをすばやく組み合わせます。
• 値に応じた色付けには RangeColorMapping を使用し、明示的な色を割り当てる場合は Palette を使用します。
• 非常に大きなデータセットにはサーバー側のページング／集計を優先し、中規模のデータセットにはクライアント側のレンダリングを使用します。

参照資料

• すべての参照ファイルは references/ にあり、目次を含む独立したファイルです。

---

Syncfusion Blazor TreeMap の実装

Syncfusion Blazor TreeMap コンポーネントを使用して、階層データを可視化するための包括的なガイドです。TreeMap は、各長方形のサイズと色が異なるデータの次元を表す、入れ子になった長方形として階層データを表示します。

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

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

• 階層データ構造を可視化する - 組織図、ファイルシステム、親子関係を持つ入れ子状のデータを表示します
• 比率データを表示する - 長方形のサイズで定量値（売上、人口、ディスク容量）を表現します
• ドリルダウンによるナビゲーションを可能にする - ユーザーが複数レベルの階層データをインタラクティブに探索できるようにします
• データ分布を比較する - 色のマッピングを使用して、追加の次元（成長、パフォーマンス、カテゴリ）を示します
• 大規模なデータセットを表示する - 限られたスペースで数百から数千のデータポイントを効率的に可視化します
• インタラクティブなダッシュボードを作成する - 選択、ハイライト、ツールチップ、凡例を組み合わせて、豊かなユーザー体験を実現します

一般的なユースケース：

• ポートフォリオ分析と資産配分
• 市場シェアと競合分析
• 予算とリソースの配分
• ファイル／フォルダーサイズの可視化
• 組織構造の表示
• 製品カテゴリ別の売上分析
• ウェブサイト分析（ページ階層とトラフィック）

コンポーネントの概要

TreeMap コンポーネントは、さまざまなレイアウトアルゴリズム（Squarified、SliceDiceAuto、Horizontal、Vertical）を使用して、データを入れ子になった長方形に整理します。各長方形のサイズは指定されたデータ値に比例し、高度な色マッピング戦略によって、色で追加の次元を表すことができます。

主な機能：

• スペースを最適に活用する複数のレイアウトアルゴリズム
• 階層データバインディング（フラット構造またはネスト構造）
• パンくずナビゲーションを備えた複数レベルのドリルダウン
• 高度な色マッピング（範囲、均等、彩度低下、パレット）
• フィルタリングに対応したインタラクティブな凡例
• テンプレートを使用したリッチなツールチップ
• 選択モードとハイライトモード
• 印刷とエクスポート（PDF、PNG、JPEG、SVG）
• 完全なアクセシビリティ対応（ARIA、キーボードナビゲーション）

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

はじめに

📄 参照： references/getting-started.md

参照するタイミング： 初めて TreeMap を設定するとき、インストール時、基本的な実装を行うとき

内容：

• Visual Studio、VS Code、.NET CLI を使用したインストール
• NuGet パッケージの設定（Syncfusion.Blazor.TreeMap）
• サービスの登録と名前空間のインポート
• CSS テーマの設定
• サンプルデータを使用した基本的な TreeMap の実装
• 本番環境向けのライセンス登録
• Blazor WebAssembly と Web App の違い

データバインディングとデータソース

📄 参照： references/data-binding.md

読むタイミング： TreeMap をデータソースに接続するとき、さまざまなデータ構造を扱うとき

内容：

• フラットなデータ構造と階層型データ構造
• ローカルデータバインディング（コレクション、JSON ファイル）
• 認証と認可を伴うリモートデータバインディング
• セキュリティ上の考慮事項 - 適切な認証を備えた、信頼できる内部 API のみにバインドしてください
• WeightValuePath と RangeColorValuePath の設定
• 入れ子のオブジェクトや複雑なデータの処理
• Entity Framework との統合
• データ変換の手法
• 大規模なデータセットのベストプラクティス

レイアウトと階層

📄 参照： references/layout-and-levels.md

読むタイミング： TreeMap の外観や複数レベルの構造を設定するとき

内容：

• レイアウトアルゴリズム（Squarified、SliceDiceAuto、Horizontal、Vertical）
• 各レイアウトタイプの使い分け
• 複数レベルの TreeMap の設定
• レベルごとのカスタマイズ（ヘッダー、枠線、色）
• 階層型データを整理する GroupPath
• 間隔と枠線の設定
• ヘッダーテンプレートと配置

リーフアイテム

📄 参照： references/leaf-items.md

読むタイミング： TreeMap の個々の矩形（リーフノード）をカスタマイズするとき

内容：

• リーフアイテムのスタイルと外観
• ラベルの書式設定と配置
• テンプレートを使ったカスタマイズ
• 間隔、枠線、色の設定
• ラベルの表示／非表示
• はみ出しの処理
• リーフアイテムのインタラクティブなパターン

色のマッピング

📄 参照： references/color-mapping.md

読むタイミング： データの次元を色で表現したり、ヒートマップを作成したりするとき

内容：

• 範囲色マッピング（値の範囲に基づくグラデーション）
• 等色マッピング（カテゴリごとに異なる色）
• 彩度低下による色マッピング（強度の変化）
• 複数色を使った彩度低下
• パレット色マッピング
• データソースから直接色をバインド
• 色のマッピングから除外されたアイテムの処理
• カスタムの色設定方法

ラベル

📄 参照： references/labels.md

読むタイミング： TreeMap のアイテムにテキストラベルを追加するとき

内容：

• データラベルの設定と書式設定
• ラベルの配置オプション（Center、TopLeft、TopCenter など）
• フォントのカスタマイズ
• カスタムコンテンツを含むラベルテンプレート
• スマートなラベル配置（省略、非表示、折り返し）
• 書式文字列とデータバインディング
• レスポンシブなラベルの動作

凡例

📄 参照： references/legend.md

読むタイミング： 色のマッピングを読み取るための凡例を追加するとき

内容：

• 凡例モード（Default、Interactive、Smart）
• 凡例の配置と整列
• 凡例のカスタマイズ（色、形状、テキスト）
• 切り替え機能を備えたスマート凡例
• カスタム描画用の凡例テンプレート
• 表示の制御
• 色のマッピングと凡例の連携

ツールチップ

📄 参照： references/tooltip.md

読むタイミング： TreeMap のアイテムにホバー時の情報を追加するとき

内容：

• 既定のツールチップの設定
• カスタム HTML／Blazor コンポーネントを使ったツールチップテンプレート
• スタイルと書式設定
• データに応じて変化するツールチップのコンテンツ
• ツールチップの配置とアニメーション
• 値の書式文字列
• さまざまなデータ構造に対応したツールチップ

ドリルダウンナビゲーション

📄 参照： references/drill-down.md

読むタイミング： 階層をたどるインタラクティブなナビゲーションを有効にするとき

内容：

• アイテムのクリック時にドリルダウンを有効化
• パンくずナビゲーションの設定
• ドリルダウン用のヘッダーのカスタマイズ
• ドリルダウンのプログラムによる制御
• ドリルダウンのイベント（ItemClick、DrillStart、DrillEnd）
• 初期表示へのリセット
• 複数レベルのナビゲーションパターン

選択とハイライト

📄 参照： references/selection-and-highlight.md

読むタイミング： 項目の選択やハイライトなど、ユーザー操作を追加するとき

説明する内容：

• 選択モード（項目、子、親、すべて）
• 単一選択と複数選択
• ホバー時のハイライト設定
• 選択時の外観のカスタマイズ（色、枠線、不透明度）
• プログラムによる選択
• 選択イベント（ItemSelected）
• ドリルダウンとの組み合わせ

イベントとメソッド

📄 参照： references/events-and-methods.md

読むタイミング： ユーザー操作やライフサイクルイベントを処理するとき、またはコンポーネントのメソッドを呼び出すとき

説明する内容：

• コンポーネントのライフサイクルイベント（Loaded、BeforeRender）
• ユーザー操作イベント（ItemClick、ItemSelected、ItemHighlight）
• レンダリングイベント（ItemRendering、TooltipRender、LegendRender）
• ドリルダウンイベント（DrillStart、DrillEnd）
• Print() および Export() メソッド（PDF、PNG、JPEG、SVG）
• Refresh() およびその他のユーティリティメソッド
• イベント処理のパターンとベストプラクティス

高度な機能

📄 参照： references/advanced-features.md

読むタイミング： 印刷／エクスポート、ローカライズ、アクセシビリティ、パフォーマンス最適化を実装するとき

説明する内容：

• 印刷およびエクスポート機能（PDF、PNG、JPEG、SVG）
• 国際化とローカライズ
• RTL（右から左への記述）サポート
• アクセシビリティ機能（ARIA、キーボード操作、スクリーンリーダー）
• パフォーマンス最適化の手法
• レスポンシブデザインのパターン
• TreeMap の他のコンポーネントへの埋め込み
• CSP（Content Security Policy）への準拠

クイックスタートの例

開始するための最小限の実用的な例を紹介します。

@page "/treemap-demo"
@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@GrowthReports"
            WeightValuePath="GDP"
            TValue="Country">
    <TreeMapLeafItemSettings LabelPath="Name">
    </TreeMapLeafItemSettings>
</SfTreeMap>

@code {
    public class Country
    {
        public string Name { get; set; }
        public double GDP { get; set; }
    }

    private List<Country> GrowthReports = new List<Country>
    {
        new Country { Name = "United States", GDP = 17946 },
        new Country { Name = "China", GDP = 10866 },
        new Country { Name = "Japan", GDP = 4123 },
        new Country { Name = "Germany", GDP = 3355 },
        new Country { Name = "United Kingdom", GDP = 2848 }
    };
}

前提条件：

• Syncfusion.Blazor.TreeMap NuGet パッケージをインストールする
• Program.cs でサービスを登録する：builder.Services.AddSyncfusionBlazor();
• レイアウトファイルにテーマ CSS への参照を追加する
• 本番環境で使用するために Syncfusion ライセンスを登録する

よく使われるパターン

パターン 1：カラー マッピングを使った階層データ

@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@SalesData"
            WeightValuePath="Sales"
            RangeColorValuePath="Growth"
            TValue="Region">
    <TreeMapLeafItemSettings LabelPath="Name">
        <TreeMapLeafLabelStyle Color="#FFFFFF"></TreeMapLeafLabelStyle>
    </TreeMapLeafItemSettings>
    <TreeMapLegendSettings Visible="true" Position="@using Syncfusion.Blazor.TreeMap.LegendPosition.Top">
    </TreeMapLegendSettings>
    <TreeMapLevels>
        <TreeMapLevel GroupPath="Continent" HeaderFormat="${Continent} - ${Sales}">
            <TreeMapLevelBorder Color="#FFFFFF" Width="1"></TreeMapLevelBorder>
        </TreeMapLevel>
    </TreeMapLevels>
    <TreeMapRangeColorMappings>
        <TreeMapRangeColorMapping From="0" To="5" Color="@("#70AD47")" />
        <TreeMapRangeColorMapping From="5" To="10" Color="@("#FFC000")" />
        <TreeMapRangeColorMapping From="10" To="20" Color="@("#FF5722")" />
    </TreeMapRangeColorMappings>
</SfTreeMap>

使用場面： パフォーマンス指標を含む階層的な業務データを表示するとき

パターン 2：パンくずナビゲーションを使ったドリルダウン

@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@OrganizationData"
            WeightValuePath="EmployeeCount"
            EnableDrillDown="true"
            TValue="Department">
    <TreeMapLeafItemSettings LabelPath="Name">
    </TreeMapLeafItemSettings>
    <TreeMapBreadcrumbSettings Visible="true">
    </TreeMapBreadcrumbSettings>
    <TreeMapLevels>
        <TreeMapLevel GroupPath="Division" HeaderFormat="${Division}">
        </TreeMapLevel>
        <TreeMapLevel GroupPath="Team" HeaderFormat="${Team}">
        </TreeMapLevel>
    </TreeMapLevels>
</SfTreeMap>

使用場面： 複数レベルの組織データや階層データをユーザーが移動する必要があるとき

パターン 3：選択とツールチップを備えたインタラクティブな TreeMap

@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@PortfolioData"
            WeightValuePath="Value"
            TValue="Investment">
    <TreeMapLeafItemSettings LabelPath="Name">
    </TreeMapLeafItemSettings>
    <TreeMapTooltipSettings Visible="true">
        <Template>
            @{
                var data = context as Investment;
                <div style="padding:5px;background:#fff;border:1px solid #ccc">
                    <b>@data.Name</b><br/>
                    Value: [email protected]("N0")<br/>
                    Return: @data.Return%
                </div>
            }
        </Template>
    </TreeMapTooltipSettings>
    <TreeMapSelectionSettings Enable="true" Fill="#58a0d3" Opacity="0.8">
    </TreeMapSelectionSettings>
    <TreeMapHighlightSettings Enable="true" Fill="#e5e5e5" Opacity="0.6">
    </TreeMapHighlightSettings>
</SfTreeMap>

使用場面： ユーザーの操作を必要とするインタラクティブなダッシュボードを構築するとき

パターン 4：カスタムパレットを使ったスクエア化レイアウト

@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@Categories"
            WeightValuePath="Sales"
            LayoutType="LayoutMode.Squarified"
            Palette="@(new string[] {"#9999ff", "#CBCBCB", "#E8DAFF", "#E4E4E4"})"
            TValue="Category">
    <TreeMapLeafItemSettings LabelPath="Name" Fill="#8ebfe2">
        <TreeMapLeafBorder Color="#FFFFFF" Width="2"></TreeMapLeafBorder>
    </TreeMapLeafItemSettings>
    <TreeMapTitleSettings Text="Product Category Sales">
    </TreeMapTitleSettings>
</SfTreeMap>

使用場面： 視覚的に区別しやすいカテゴリ比較を作成するとき

主なプロパティと設定

主なプロパティ：

プロパティ	型	用途
DataSource	IEnumerable	バインドするデータコレクション
WeightValuePath	string	矩形のサイズを決定するプロパティ
RangeColorValuePath	string	カラー マッピングに使用する値のプロパティ
TValue	Type	データ項目のジェネリック型
LayoutType	LayoutMode	レイアウトアルゴリズム（Squarified、SliceDiceAuto など）
EnableDrillDown	bool	階層ナビゲーションを有効にする
Palette	string[]	項目のカラーパレット

子コンポーネント：

• TreeMapLeafItemSettings - リーフノードの設定
• TreeMapLevels - 複数レベルの階層
• TreeMapRangeColorMappings / TreeMapEqualColorMappings - カラー設定方式
• TreeMapLegendSettings - 凡例の設定
• TreeMapTooltipSettings - ツールチップの設定
• TreeMapSelectionSettings - 選択動作
• TreeMapHighlightSettings - ホバー効果

関連スキル

• ヒートマップチャート - マトリックスベースのヒートマップを可視化するために使用
• その他のデータ可視化コンポーネントについては、データ可視化カテゴリをご覧ください

トラブルシューティングのクイックヒント

• TreeMap が描画されない： NuGet パッケージがインストールされ、サービスが登録され、CSS テーマが参照されていることを確認してください
• データが表示されない： WeightValuePath がデータモデル内の数値プロパティと一致していることを確認してください
• 色が適用されない： RangeColorValuePath が設定され、色のマッピングが正しく構成されていることを確認してください
• ドリルダウンが機能しない： EnableDrillDown="true" を設定し、GroupPath を指定して TreeMapLevels を構成してください
• パフォーマンスの問題： 大規模なデータセット（>1000 項目）の場合は、ページネーションまたはドリルダウンによる階層読み込みを検討してください

各トピックの詳細については、上記のナビゲーションガイドに記載されている該当するリファレンスファイルを参照してください。