syncfusion-flutter-treemap

Flutter TreeMap の実装

このスキルでは、Syncfusion Flutter TreeMap（SfTreemap）ウィジェットを実装する方法を説明します。ネストされた長方形を使用して、階層データや比率データを表示する強力な可視化コンポーネントです。TreeMap は複雑なデータ間の関係を示すのに優れており、ダッシュボード、分析、データ探索インターフェースに最適です。

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

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

• Flutter で階層型またはネストされたデータ構造を可視化する
• ネストされた長方形を使用して比率データを表示する
• ドリルダウン機能を備えたインタラクティブなツリーマップを作成する
• 色分けしたタイルでカテゴリデータを表示する
• 大規模なデータセットを省スペースで表現する
• 階層データを表示するダッシュボードを構築する
• 選択やツールチップに対応したデータ探索インターフェースを実装する
• 定量値に基づくヒートマップを作成する

コンポーネントの概要

Syncfusion Flutter TreeMap（SfTreemap）は、ネストされた長方形を使用して階層データを表示する強力なデータ可視化ウィジェットです。各長方形のサイズは定量値に比例するため、異なるカテゴリや階層の値を簡単に比較できます。

TreeMap の活用に適した用途：

• ファイルシステムの可視化
• カテゴリ別の予算内訳
• 市場シェア分析
• 指標を含む組織階層
• リソース配分の表示
• ポートフォリオ構成
• 地域／製品／カテゴリ別の売上データ

主な機能

• 複数のレイアウトアルゴリズム： Squarified（デフォルト）、Slice、Dice
• データ対応： フラット構造と階層構造の両方に対応
• カスタマイズ可能なラベル： 任意の Flutter ウィジェットをラベルとして使用可能
• インタラクティブな機能： 選択、ツールチップ、タップイベント
• 色のマッピング： 値ベースおよび範囲ベースの色分け
• 凡例のサポート： バー形式およびグラデーション形式の凡例
• ドリルダウンナビゲーション： 階層レベル間を移動
• アクセシビリティ： RTL サポート、セマンティックラベル
• テーマ設定： 色やスタイルを全面的にカスタマイズ可能

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

はじめに

📄 参照： references/getting-started.md

• パッケージのインストールとセットアップ
• pubspec.yaml への依存関係の追加
• treemap パッケージのインポート
• 最初のツリーマップの作成
• 基本的なデータソース構造
• 主要なプロパティ：dataCount、weightValueMapper、levels
• 最小限の実行可能なサンプル

レイアウトの設定

📄 参照： references/layouts.md

• レイアウトアルゴリズムの理解
• Squarified レイアウト（デフォルト、バランスの取れた長方形）
• Slice レイアウト（水平分割）
• Dice レイアウト（垂直分割）
• 各レイアウトタイプの使い分け
• パフォーマンスに関する考慮事項
• レイアウトの切り替え

データ構造と階層

📄 参照： references/hierarchical-data.md

• フラットなデータ構造と階層型データ構造
• グループ化するための TreemapLevel の設定
• groupMapper を使用したデータの整理
• タイルのサイズ設定に使用する weightValueMapper
• 複数レベルの階層の作成
• dataCount プロパティの使用方法
• 複雑なネストデータの構築

カスタマイズ：ラベルとスタイル

📄 参照： references/labels-customization.md

• labelBuilder によるラベルの追加
• TreemapTile のプロパティとデータへのアクセス
• カスタムラベルウィジェット
• ラベルの配置とパディング
• テキストのスタイル設定と書式設定
• 条件に応じたラベルの表示
• レスポンシブなラベルサイズ

カスタマイズ：色とテーマ

📄 参照： references/colors-theming.md

• 色のマッピングの概要
• 値ベースの色のマッピング
• 範囲ベースの色のマッピング
• グラデーションのサポート
• テーマとの統合
• カスタムカラーパレット
• タイルごとの色のカスタマイズ

インタラクティブ機能：ツールチップと選択

📄 参照： references/tooltip-selection.md

• tooltipBuilder を使用したツールチップの作成
• カスタムツールチップウィジェットとスタイル設定
• タイル選択の有効化
• onSelectionChanged イベントの処理
• 選択したタイルのハイライト表示
• 複数選択のサポート
• タッチ操作とホバー操作

凡例

📄 参照： references/legend.md

• TreemapLegend ウィジェットの追加
• バー凡例とグラデーション凡例
• 凡例の配置（上、下、左、右）
• アイコンとテキストのカスタマイズ
• 凡例項目のスタイル設定
• カラーマッパーとの統合

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

📄 参照： references/drilldown.md

• ドリルダウン動作の実装
• onTap コールバックの使用
• 階層データのナビゲーション
• ドリルダウン状態の管理
• パンくずナビゲーションの構築
• 戻る／上へ移動するナビゲーション
• ユーザーコンテキストの維持

高度な機能

📄 参照： references/advanced-features.md

• itemBuilder を使用したカスタムタイルウィジェット
• 右から左への（RTL）サポート
• アクセシビリティ機能
• キーボードナビゲーション
• パフォーマンス最適化の手法
• レスポンシブデザインのパターン
• 状態管理との統合

クイックスタートの例

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

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_treemap/treemap.dart';

class BasicTreemapExample extends StatefulWidget {
  @override
  _BasicTreemapExampleState createState() => _BasicTreemapExampleState();
}

class _BasicTreemapExampleState extends State<BasicTreemapExample> {
  late List<SalesData> _salesData;

  @override
  void initState() {
    _salesData = [
      SalesData(region: 'North America', sales: 8500),
      SalesData(region: 'Europe', sales: 6200),
      SalesData(region: 'Asia', sales: 9800),
      SalesData(region: 'South America', sales: 3400),
      SalesData(region: 'Africa', sales: 2100),
    ];
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Sales by Region')),
      body: Center(
        child: Container(
          height: 400,
          width: 400,
          padding: EdgeInsets.all(16),
          child: SfTreemap(
            dataCount: _salesData.length,
            weightValueMapper: (int index) {
              return _salesData[index].sales;
            },
            levels: [
              TreemapLevel(
                groupMapper: (int index) {
                  return _salesData[index].region;
                },
                labelBuilder: (BuildContext context, TreemapTile tile) {
                  return Padding(
                    padding: EdgeInsets.all(4),
                    child: Text(
                      tile.group,
                      style: TextStyle(color: Colors.black),
                    ),
                  );
                },
              ),
            ],
          ),
        ),
      ),
    );
  }
}

class SalesData {
  SalesData({required this.region, required this.sales});
  
  final String region;
  final double sales;
}

よく使われるパターン

パターン 1：ドリルダウンを使った階層データ

// Multi-level data structure
class SalesData {
  SalesData({
    required this.region,
    required this.country,
    required this.sales,
  });
  
  final String region;
  final String country;
  final double sales;
}

// TreeMap with two levels
SfTreemap(
  dataCount: _salesData.length,
  weightValueMapper: (int index) => _salesData[index].sales,
  levels: [
    TreemapLevel(
      groupMapper: (int index) => _salesData[index].region,
    ),
    TreemapLevel(
      groupMapper: (int index) => _salesData[index].country,
    ),
  ],
)

パターン 2：値に応じた色分け

SfTreemap(
  dataCount: _data.length,
  weightValueMapper: (int index) => _data[index].value,
  colorMappers: [
    TreemapColorMapper.range(
      from: 0,
      to: 25,
      color: Colors.green,
      name: 'Low',
    ),
    TreemapColorMapper.range(
      from: 25,
      to: 50,
      color: Colors.yellow,
      name: 'Medium',
    ),
    TreemapColorMapper.range(
      from: 50,
      to: 100,
      color: Colors.red,
      name: 'High',
    ),
  ],
  legend: TreemapLegend.bar(),
  levels: [
    TreemapLevel(
      groupMapper: (int index) => _data[index].category,
    ),
  ],
)

パターン 3：選択可能なインタラクティブ表示

SfTreemap(
  dataCount: _data.length,
  weightValueMapper: (int index) => _data[index].value,
  onSelectionChanged: (TreemapTile tile) {
    setState(() {
      // Add selection changed functionalities here
    });
  },
  levels: [
    TreemapLevel(
      groupMapper: (int index) => _data[index].category,
      color: Colors.blue[200],
      tooltipBuilder: (BuildContext context, TreemapTile tile) {
        return Container(
          padding: EdgeInsets.all(8),
          decoration: BoxDecoration(
            color: Colors.black87,
            borderRadius: BorderRadius.circular(4),
          ),
          child: Text(
            '${tile.group}: ${tile.weight}',
            style: TextStyle(color: Colors.white),
          ),
        );
      },
    ),
  ],
)

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

基本プロパティ

プロパティ	型	説明
dataCount	int	データソース内のデータポイント数
weightValueMapper	IndexedDoubleValueMapper	タイルのサイズに使用する数値を返すコールバック
levels	List<TreemapLevel>	階層レベルの設定

TreemapLevel のプロパティ

プロパティ	型	説明
groupMapper	IndexedStringValueMapper	このレベルのデータをグループ化します
labelBuilder	TreemapLabelBuilder?	カスタムラベルウィジェットビルダー
tooltipBuilder	TreemapTooltipBuilder?	カスタムツールチップウィジェットビルダー
color	Color?	このレベルのデフォルトのタイル色
border	RoundedRectangleBorder?	タイルの境界線のスタイル設定
padding	EdgeInsetsGeometry?	タイル周囲のパディング

オプションの設定

注： レイアウトアルゴリズムはプロパティではなく、使用するコンストラクターによって決まります。 矩形分割（デフォルト）には SfTreemap()、スライスには SfTreemap.slice()、ダイスには SfTreemap.dice() を使用してください。

プロパティ	型	説明
colorMappers	List<TreemapColorMapper>?	値／範囲に基づく色分け
legend	TreemapLegend?	凡例ウィジェットの設定
onSelectionChanged	ValueChanged<TreemapTile>?	選択イベントハンドラー
layoutDirection	TreemapLayoutDirection	タイルを左上、右上、左下、右下の方向に配置します。デフォルトは topLeft です
sortAscending	bool	重みによるタイルの並べ替え（スライス／ダイスのみ）

よくあるユースケース

ユースケース 1：予算ダッシュボード

組織の予算内訳を部署とサブカテゴリーごとに表示し、支出レベルを色分けします。

使用場面： 複数レベルの予算管理、リソース配分

ユースケース 2：売上分析

インタラクティブなドリルダウンを使って、地域、国、製品ごとの売上データを可視化します。

使用場面： 地域別売上比較、市場分析、パフォーマンスダッシュボード

ユースケース 3：ファイルシステムの可視化

フォルダーとファイルのディスク容量使用量を、容量に比例したサイズで表示します。

使用場面： ストレージ分析、ファイル管理ツール、ディスククリーンアップユーティリティ

ユースケース 4：市場シェア分析

さまざまな企業、製品、カテゴリーの市場シェアデータを表示します。

使用場面： 競合分析、ポートフォリオ構成、市場調査

ユースケース 5：組織階層

チームごとの人員数や予算などの指標を使って、組織構造を表示します。

使用する場面： 人事ダッシュボード、リソース計画、組織図の可視化

トラブルシューティングのクイックリファレンス

タイルが表示されない場合

• dataCount がデータの長さと一致していることを確認します
• weightValueMapper が正の数を返すことを確認します
• groupMapper が null 以外の文字列を返すことを確認します

ラベルが表示されない場合

• TreemapLevel に labelBuilder を追加します
• ラベルウィジェットがタイル内に収まるサイズであることを確認します
• テキストの色がタイルの背景色と十分なコントラストを持つことを確認します

色が適用されない場合

• colorMappers の値がデータ範囲と一致していることを確認します
• カラーマッパーの型（値または範囲）が正しいことを確認します
• カラーマッパーを使用している場合は、凡例が設定されていることを確認します

選択が機能しない場合

• onSelectionChanged コールバックを追加します
• 再構築のために setState を呼び出していることを確認します
• タイルがタップできる十分な大きさであることを確認します

詳細なトラブルシューティングと解決策については、該当するリファレンスドキュメントを参照してください。