syncfusion-react-treemaps

Syncfusion React TreeMap の実装

階層データを視覚化する Syncfusion React TreeMap コンポーネントの実装とカスタマイズに関する包括的なガイドです。TreeMap は、面積でデータ値を表す入れ子状の長方形を表示し、複数の階層レベル、インタラクティブなドリルダウン、豊富なカスタマイズに対応しています。

このスキルを使用するタイミング

次のことが必要な場合に、このスキルを使用してください。

• TreeMap コンポーネントをインストールしてセットアップする
• 階層データまたはフラットデータを TreeMap にバインドする
• 複数のレベルを持つツリー構造データを視覚化する
• データ探索のためのドリルダウン操作を実装する
• カラーマッピング方式（範囲、均等、彩度低下）を適用する
• レイアウト（正方形、水平、垂直、自動）を設定する
• 凡例、ツールチップ、データラベルを追加する
• 選択機能とハイライト機能を実装する
• リーフ項目とラベルの位置をカスタマイズする
• アクセシビリティ要件に対応する
• TreeMap の視覚化をエクスポートまたは印刷する
• 国際化または RTL サポートを適用する

コンポーネントの概要

TreeMap コンポーネントは、次の機能を備えた強力な階層データ視覚化ツールです。

• スケーラビリティに優れた SVG を使用して、入れ子状の長方形を描画します
• 任意の数の階層レベルに対応します
• 空間を最適に利用するための 4 種類のレイアウトアルゴリズムを提供します
• 入れ子状のデータを探索するためのドリルダウン機能を備えています
• データに基づくスタイル設定に 3 種類のカラーマッピング方式を提供します
• 選択、ハイライト、ツールチップなどのインタラクティブ機能を備えています
• データラベル、凡例、カスタムテンプレートに対応しています
• アクセシビリティと国際化をサポートします

TreeMap を選ぶタイミング

次の場合は TreeMap を選んでください。

• 階層データ（組織図、ファイルシステム、カテゴリ階層）を視覚化する
• 面積によるエンコードを使用して、複数カテゴリの値を比較する
• ドリルダウン操作で入れ子状のカテゴリを探索する
• 複数のレベルに多数の項目があるツリー構造データを表示する
• 面積によるエンコードを使用する、省スペースな視覚化が必要である

次の場合は TreeMap を使用しないでください。

• 項目数が少ない単純なフラットデータ（棒グラフ／縦棒グラフを使用してください）
• 時系列データ（折れ線グラフ／面グラフを使用してください）
• エンティティ間の関係（ダイアグラム／グラフを使用してください）
• ノード数が少ない単一階層（別のレイアウトを検討してください）

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

はじめに

📄 参照： references/getting-started.md

• @syncfusion/ej2-react-treemap のインストール
• パッケージの依存関係とセットアップ
• 機能のモジュールインジェクション
• 最初の TreeMap の作成
• 基本的な階層データのレンダリング

データバインディングと階層

📄 参照： references/data-binding.md

• フラットデータと階層データの構造
• サイズ設定のための weightValuePath の構成
• levels を使用した複数レベルの階層のバインド
• リモートデータソースの統合
• データ変換のパターン

カラーマッピング方式

📄 参照： references/color-mapping.md

• 範囲ベースのカラーマッピング（値に応じたグラデーション）
• 均等値のカラーマッピング（カテゴリ別の色）
• 彩度低下マッピング（不透明度による変化）
• 動的な色の割り当て
• カラーマッピング方式の選択

レイアウトとレイアウトの選択

📄 参照： references/layouts.md

• 正方形レイアウト（縦横比のバランスを調整）
• 水平レイアウト（左から右への並び順）
• 垂直レイアウト（上から下への並び順）
• 自動レイアウト（デフォルトの最適なレイアウト）
• 各レイアウトタイプを使用するタイミング

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

📄 参照： references/drilldown.md

• enableDrillDown によるドリルダウンの有効化
• 複数レベルの探索に向けた levels の構成
• ドリルダウンイベントとコールバック
• パンくずナビゲーションのパターン
• 戻るナビゲーションの処理

リーフ項目、ラベル、テンプレート

📄 参照： references/leaf-items-and-labels.md

• リーフ項目の構成とスタイル設定
• ラベルの位置（TopLeft、Center、BottomRight など）
• データラベルの書式設定とテンプレート
• 枠線と塗りつぶしのカスタマイズ
• ラベルのはみ出し処理

凡例、ツールチップ、選択

📄 参照： references/legends-tooltips-selection.md

• 凡例の作成と設定
• ツールチップのテンプレートとスタイル設定
• 選択モードとハイライトモード
• インタラクティブ機能とイベント
• ユーザー操作への応答

カスタマイズ、アクセシビリティ、エクスポート

📄 参照： references/customization-accessibility.md

• WCAG 準拠とキーボードナビゲーション
• RTL（右から左）への対応
• 国際化とローカライズ
• テーマ設定と CSS のカスタマイズ
• 印刷とエクスポート機能

クイックスタートの例

import * as React from 'react';
import { TreeMapComponent } from '@syncfusion/ej2-react-treemap';

export function TreeMapDemo() {
  const data = [
    { Title: 'USA', State: 'California', Sales: 2830 },
    { Title: 'USA', State: 'Texas', Sales: 2020 },
    { Title: 'USA', State: 'Florida', Sales: 1880 },
    { Title: 'Germany', State: 'Berlin', Sales: 1880 },
    { Title: 'Germany', State: 'Munich', Sales: 1550 },
  ];

  return (
    <TreeMapComponent
      height="350px"
      dataSource={data}
      weightValuePath="Sales"
      leafItemSettings={{
        labelPath: 'State',
        colorMapping: [
          { from: 1500, to: 2000, color: '#FF6B6B' },
          { from: 2000, to: 2500, color: '#4ECDC4' },
          { from: 2500, to: 3000, color: '#45B7D1' }
        ]
      }}
    />
  );
}

よくあるパターン

パターン 1：ドリルダウンによる階層データの表示

<TreeMapComponent
  enableDrillDown={true}
  dataSource={data}
  weightValuePath="Sales"
>
  <LevelsDirective>
    <LevelDirective groupPath="Country" />
    <LevelDirective groupPath="State" />
    <LevelDirective groupPath="City" />
  </LevelsDirective>
</TreeMapComponent>

使用する場面： ドリルダウン操作を通じた段階的な詳細表示で、多層階層を探索する場合。

パターン 2：色分けされたカテゴリ

<TreeMapComponent
  equalColorValuePath="Category"
  leafItemSettings={{
    colorMapping: [
      { value: 'Electronics', color: '#3498db' },
      { value: 'Furniture', color: '#e74c3c' },
      { value: 'Clothing', color: '#2ecc71' }
    ]
  }}
/>

使用する場面： 項目を異なる色で分類し、視覚的にすばやく識別する場合。

パターン 3：値の範囲に応じたカラーグラデーション

<TreeMapComponent
  rangeColorValuePath="Sales"
  leafItemSettings={{
    colorMapping: [
      { from: 0, to: 10000, color: '#90EE90' },
      { from: 10000, to: 50000, color: '#FFD700' },
      { from: 50000, to: 100000, color: '#FF6347' }
    ]
  }}
/>

使用する場面： パフォーマンス指標、売上、その他の連続値について、色の濃淡で大きさの違いを示す場合。

主なプロパティと設定

プロパティ	目的	一般的な値
dataSource	階層データまたはフラットデータの配列	オブジェクトの配列
weightValuePath	項目のサイズを決定するプロパティパス	例：'Sales'、'Count'
equalColorValuePath	カテゴリ別の色分けに使用するプロパティ	例：'Category'、'Type'
rangeColorValuePath	範囲に基づく色分けに使用するプロパティ	例：'Sales'、'Value'
enableDrillDown	クリックしてドリルダウンする操作を有効化	true/false
layoutType	空間レイアウトのアルゴリズム	'Squarified'、'Horizontal'、'Vertical'、'SliceAndDice'
height	コンポーネントの高さ	例：'350px'、'100%'
palette	項目に使用する色の配列	['#color1'、'#color2'、...]

よくあるユースケース

API リファレンス

このセクションでは、よく使用される TreeMap のプロパティ、メソッド、イベントをまとめています。型付きモデルを含む完全な API については、公式ドキュメントを参照してください：https://ej2.syncfusion.com/react/documentation/api/treemap/index-default

重要なプロパティ（一部）

• dataSource (Array|DataManager) — TreeMap のデータソースです。フラット形式または階層形式を指定できます。デフォルト：null
• weightValuePath (string) — 各項目のサイズ設定に使用する数値へのパスです。デフォルト：null
• colorValuePath (string) — 連続的な色のマッピング（範囲パレット）に使用するフィールドです。
• equalColorValuePath (string[]) — カテゴリ別／同一色のマッピングに使用するフィールドです。
• rangeColorValuePath (string[]) — 範囲ベースの色のマッピングに使用するフィールドです。
• leafItemSettings (object) — 葉項目の設定です（例：labelPath、colorMapping、border、gap）。
• levels (LevelSettingsModel[]) — 階層レベルごとのグループ化と外観を定義する、レベル設定オブジェクトの配列です。
• layoutType (string) — レイアウトアルゴリズムです：Squarified（デフォルト）、SliceAndDiceHorizontal、SliceAndDiceVertical、SliceAndDiceAuto など。
• enableDrillDown (boolean) — ドリルダウン操作を有効にします。デフォルト：false
• drillDownView (boolean) — ドリルダウン表示のレイアウトを使用します。デフォルト：false
• enableBreadcrumb (boolean) — ドリルダウン時にパンくずリストを表示します。デフォルト：false
• breadcrumbConnector (string) — パンくずリストの項目間に表示する区切り文字です。
• initialDrillDown (object) — 初期ドリルダウンのレベル／状態を設定します。
• enableHtmlSanitizer (boolean) — テンプレート／ツールチップ内の HTML をサニタイズします。デフォルト：true
• enablePersistence (boolean) — コンポーネントの状態を再読み込み後も保持します。デフォルト：false
• enableRtl (boolean) — 右から左への描画を有効にします。デフォルト：false
• palette (string[]) — 塗りつぶしに使用するパレットカラーの配列です。
• highlightSettings (object) — ハイライトの設定とスタイルです。
• selectionSettings (object) — 選択の設定（モード、有効化など）です。
• legendSettings (object) — 凡例の設定（位置、タイトル、形状など）です。
• titleSettings (object) — タイトルとサブタイトルの設定です。
• tooltipSettings (object) — ツールチップのテンプレートと動作の設定です。
• format (string) — ラベルまたは値の書式設定文字列です。
• useGroupingSeparator (boolean) — 数値に桁区切り文字を適用します。デフォルト：true
• description (string) — TreeMap のアクセシビリティ向け説明です。
• margin (object) — コンポーネントのマージン設定です（{ top, right, bottom, left }）。
• height / width (string|number) — コンポーネントのサイズです（例：350px または 100%）。
• theme (string) — テーマ名です（例：Material、Bootstrap）。

主なメソッド

• destroy() — TreeMap インスタンスをクリーンアップし、リスナーを削除します。
• export(type, fileName, orientation, allowDownload) — TreeMap を PNG|JPEG|SVG|PDF としてエクスポートします。PDF のエクスポート処理では Promise を返します。
• print(id) — 要素 ID、DOM 要素、または ID の配列を指定して TreeMap のコンテンツを印刷します。
• doubleClickOnTreeMap(e) — ダブルクリックの動作をプログラムから実行します。
• selectItem(levelOrder, isSelected) — レベル順の配列で項目を選択または選択解除します。

主なイベント

• load / loaded — コンポーネントの読み込み前後に発生するライフサイクルイベントです。
• itemRendering — 項目の描画中に発生します。項目の外観のカスタマイズに使用します。
• click / itemClick — 項目のクリック時に発生します。
• doubleClick — 項目のダブルクリック時に発生します。
• drillStart / drillEnd — ドリルダウンの開始時／終了時に発生します。
• itemHighlight / itemSelected — ハイライト／選択のライフサイクルイベントです。
• legendRendering / legendItemRendering — 凡例の描画中に発生するイベントです。
• tooltipRendering — ツールチップのコンテンツを準備する際に発生します。
• resize — コンポーネントのサイズ変更時に発生します。
• beforePrint / print — 印刷／エクスポート前後のフックです。

クイックインポートの例

import { TreeMapComponent, LevelsDirective, LevelDirective, Inject, TreeMapTooltip } from '@syncfusion/ej2-react-treemap';

<TreeMapComponent dataSource={data} weightValuePath="value" enableDrillDown={true}>
  <LevelsDirective>
    <LevelDirective groupPath="category" />
  </LevelsDirective>
  <Inject services={[TreeMapTooltip]} />
</TreeMapComponent>

1. 組織階層： 部門、地域、事業部ごとの従業員数を可視化します
2. ファイルシステムブラウザー： フォルダーやサブフォルダーごとのディスク使用量をドリルダウン表示します
3. 営業実績： 地域別の売上、製品カテゴリ、販売地域を比較します
4. ウェブサイト分析： 階層的にトラフィックソース、ページ、ユーザーセグメントを調査します
5. ポートフォリオ配分： カテゴリやサブカテゴリごとの資産配分を可視化します
6. 市場シェア： 企業階層を含む競争環境を表示します
7. 予算分析： 部門や明細項目ごとに予算を配分し、可視化します

次のステップ

1. はじめにガイドから開始すると、最初の TreeMap をインストールしてレンダリングできます
2. データ構造に応じてデータバインディングパターンを選択します
3. カラー マッピング戦略（範囲、均等、または彩度低下）を選択します
4. 階層を調査する場合は、レイアウトとドリルダウンを設定します
5. ユースケースに合わせてリーフ項目、ラベル、ツールチップをカスタマイズします
6. 選択とイベントを使ってインタラクティブ機能を追加します
7. アクセシビリティと国際化の要件を満たしていることを確認します

---

TreeMap の実装を始める準備はできましたか？ references/getting-started.mdから開始するか、上記のナビゲーションオプションから特定の機能ガイドを選択してください。