syncfusion-flutter-treemap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Flutter TreeMaps

实现 Flutter TreeMap

This skill guides you through implementing the Syncfusion Flutter TreeMap (SfTreemap) widget - a powerful visualization component for displaying hierarchical and proportional data using nested rectangles. TreeMaps excel at showing complex data relationships, making them ideal for dashboards, analytics, and data exploration interfaces.

本技能将指导你实现 Syncfusion Flutter TreeMap (SfTreemap) 组件——这是一个功能强大的可视化组件，通过嵌套矩形展示分层和比例数据。TreeMap 非常适合展示复杂的数据关系，是开发仪表盘、分析工具、数据探索界面的理想选择。

When to Use This Skill

何时使用本技能

Use this skill when the user needs to:

Visualize hierarchical or nested data structures in Flutter
Display proportional data using nested rectangles
Create interactive treemap visualizations with drilldown
Show categorical data with color-coded tiles
Represent large datasets in a space-efficient manner
Build dashboards with hierarchical data displays
Implement data exploration interfaces with selection and tooltips
Create heat maps based on quantitative values

当用户需要实现以下需求时可使用本技能：

在 Flutter 中可视化分层或嵌套数据结构
用嵌套矩形展示比例数据
开发支持下钻功能的交互式树图可视化效果
用颜色编码的区块展示分类数据
以节省空间的方式呈现大型数据集
开发带分层数据展示功能的仪表盘
实现支持选择和工具提示的数据探索界面
基于定量数值创建热力图

Component Overview

组件概述

The Syncfusion Flutter TreeMap (SfTreemap) is a powerful data visualization widget that displays hierarchical data using nested rectangles. Each rectangle's size is proportional to a quantitative value, making it easy to compare values across different categories and levels.

TreeMap is ideal for:

File system visualizations
Budget breakdowns by category
Market share analysis
Organization hierarchies with metrics
Resource allocation displays
Portfolio compositions
Sales data by region/product/category

Syncfusion Flutter TreeMap (SfTreemap) 是一款功能强大的数据可视化组件，通过嵌套矩形展示分层数据。每个矩形的大小与对应定量值成正比，便于用户跨不同分类和层级比较数值大小。

TreeMap 适用场景：

文件系统可视化
按分类划分的预算明细
市场份额分析
带指标的组织层级结构
资源分配展示
投资组合构成
按区域/产品/分类划分的销售数据

Key Capabilities

核心功能

Multiple Layout Algorithms: Squarified (default), Slice, Dice
Data Support: Both flat and hierarchical structures
Customizable Labels: Use any Flutter widget as labels
Interactive Features: Selection, tooltips, tap events
Color Mapping: Value-based and range-based coloring
Legend Support: Bar and gradient legends
Drilldown Navigation: Navigate through hierarchical levels
Accessibility: RTL support, semantic labels
Theming: Full customization of colors and styles

多种布局算法： Squarified（默认）、Slice、Dice
数据支持： 同时支持扁平结构和分层结构数据
可自定义标签： 可使用任意 Flutter 组件作为标签
交互功能： 选择、工具提示、点击事件
颜色映射： 支持基于值和基于区间的着色方案
图例支持： 条形图例和渐变图例
下钻导航： 可在不同数据层级之间导航
无障碍支持： RTL（从右到左）布局支持、语义标签
主题定制： 完全自定义颜色和样式

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Package installation and setup
Adding dependency to pubspec.yaml
Importing the treemap package
Creating your first treemap
Basic data source structure
Essential properties:
```
dataCount
```
,
```
weightValueMapper
```
,
```
levels
```
Minimal working example

📄 阅读： references/getting-started.md

包安装与配置
向 pubspec.yaml 添加依赖
导入 treemap 包
创建你的第一个树图
基础数据源结构
核心属性：
```
dataCount
```
、
```
weightValueMapper
```
、
```
levels
```
最小可运行示例

Layout Configuration

布局配置

📄 Read: references/layouts.md

Understanding layout algorithms
Squarified layout (default, balanced rectangles)
Slice layout (horizontal divisions)
Dice layout (vertical divisions)
When to use each layout type
Performance considerations
Switching between layouts

📄 阅读： references/layouts.md

理解布局算法
Squarified 布局（默认，平衡矩形）
Slice 布局（水平分割）
Dice 布局（垂直分割）
不同布局类型的适用场景
性能注意事项
布局切换方法

Data Structure and Hierarchy

数据结构与层级

📄 Read: references/hierarchical-data.md

Flat vs hierarchical data structures
Configuring TreemapLevel for grouping
Using
```
groupMapper
```
to organize data
Using
```
weightValueMapper
```
to size tiles
Creating multi-level hierarchies
```
dataCount
```
property usage
Building complex nested data

📄 阅读： references/hierarchical-data.md

扁平数据结构与分层数据结构的区别
配置 TreemapLevel 实现分组
使用
```
groupMapper
```
组织数据
使用
```
weightValueMapper
```
设定区块大小
创建多层级结构
```
dataCount
```
属性用法
构建复杂嵌套数据

Customization: Labels and Styling

自定义：标签与样式

📄 Read: references/labels-customization.md

Adding labels with
```
labelBuilder
```
TreemapTile properties and data access
Custom label widgets
Label positioning and padding
Text styling and formatting
Conditional label display
Responsive label sizing

📄 阅读： references/labels-customization.md

通过
```
labelBuilder
```
添加标签
TreemapTile 属性与数据访问
自定义标签组件
标签位置与内边距设置
文本样式与格式化
条件性标签展示
响应式标签大小

Customization: Colors and Theming

自定义：颜色与主题

📄 Read: references/colors-theming.md

Color mapping overview
Value-based color mapping
Range-based color mapping
Gradient support
Theme integration
Custom color palettes
Per-tile color customization

📄 阅读： references/colors-theming.md

颜色映射概述
基于值的颜色映射
基于区间的颜色映射
渐变支持
主题集成
自定义调色板
单个区块颜色自定义

Interactive Features: Tooltip and Selection

交互功能：工具提示与选择

📄 Read: references/tooltip-selection.md

Creating tooltips with
```
tooltipBuilder
```
Custom tooltip widgets and styling
Enabling tile selection
Handling
```
onSelectionChanged
```
events
Selected tile highlighting
Multi-select support
Touch and hover interactions

📄 阅读： references/tooltip-selection.md

通过
```
tooltipBuilder
```
创建工具提示
自定义工具提示组件与样式
启用区块选择功能
处理
```
onSelectionChanged
```
事件
选中区块高亮
多选支持
触摸与悬停交互

Legend

图例

📄 Read: references/legend.md

Adding TreemapLegend widget
Bar legends vs gradient legends
Legend positioning (top, bottom, left, right)
Icon and text customization
Legend item styling
Integration with color mappers

📄 阅读： references/legend.md

添加 TreemapLegend 组件
条形图例与渐变图例的区别
图例位置设置（上、下、左、右）
图标与文本自定义
图例项样式
与颜色映射器集成

Drilldown Navigation

下钻导航

📄 Read: references/drilldown.md

Implementing drilldown behavior
Using
```
onTap
```
callback
Navigating hierarchical data
Managing drilldown state
Building breadcrumb navigation
Back/up navigation
Preserving user context

📄 阅读： references/drilldown.md

实现下钻行为
使用
```
onTap
```
回调
分层数据导航
下钻状态管理
构建面包屑导航
返回/向上导航
保留用户上下文

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Custom tile widgets with
```
itemBuilder
```
Right-to-left (RTL) support
Accessibility features
Keyboard navigation
Performance optimization techniques
Responsive design patterns
Integration with state management

📄 阅读： references/advanced-features.md

通过
```
itemBuilder
```
自定义区块组件
RTL（从右到左）布局支持
无障碍功能
键盘导航
性能优化技巧
响应式设计模式
与状态管理方案集成

Quick Start Example

快速启动示例

Here's a minimal example to get you started:

dart

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;
}

以下是一个最小示例帮助你快速上手：

dart

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;
}

Common Patterns

常用模式

Pattern 1: Hierarchical Data with Drilldown

模式1：带下钻功能的分层数据

dart

// 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,
    ),
  ],
)

dart

// 多层级数据结构
class SalesData {
  SalesData({
    required this.region,
    required this.country,
    required this.sales,
  });
  
  final String region;
  final String country;
  final double sales;
}

// 两级 TreeMap
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,
    ),
  ],
)

Pattern 2: Color-Coded by Value

模式2：按值进行颜色编码

dart

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,
    ),
  ],
)

dart

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,
    ),
  ],
)

Pattern 3: Interactive with Selection

模式3：支持选择的交互功能

dart

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),
          ),
        );
      },
    ),
  ],
)

dart

SfTreemap(
  dataCount: _data.length,
  weightValueMapper: (int index) => _data[index].value,
  onSelectionChanged: (TreemapTile tile) {
    setState(() {
      // 在这里添加选择变化的处理逻辑
    });
  },
  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),
          ),
        );
      },
    ),
  ],
)

Key Properties Reference

核心属性参考

Essential Properties

必要属性

Property	Type	Description
`dataCount`	int	Number of data points in the source
`weightValueMapper`	IndexedDoubleValueMapper	Callback returning numeric value for tile size
`levels`	List<TreemapLevel>	Hierarchy levels configuration

属性	类型	描述
`dataCount`	int	数据源中的数据点数量
`weightValueMapper`	IndexedDoubleValueMapper	返回区块大小对应数值的回调函数
`levels`	List<TreemapLevel>	分层层级配置

TreemapLevel Properties

TreemapLevel 属性

Property	Type	Description
`groupMapper`	IndexedStringValueMapper	Groups data for this level
`labelBuilder`	TreemapLabelBuilder?	Custom label widget builder
`tooltipBuilder`	TreemapTooltipBuilder?	Custom tooltip widget builder
`color`	Color?	Default tile color for this level
`border`	RoundedRectangleBorder?	Tile border styling
`padding`	EdgeInsetsGeometry?	Padding around tiles

属性	类型	描述
`groupMapper`	IndexedStringValueMapper	对当前层级的数据进行分组的回调
`labelBuilder`	TreemapLabelBuilder?	自定义标签组件的构建器
`tooltipBuilder`	TreemapTooltipBuilder?	自定义工具提示组件的构建器
`color`	Color?	当前层级区块的默认颜色
`border`	RoundedRectangleBorder?	区块边框样式
`padding`	EdgeInsetsGeometry?	区块内边距

Optional Configuration

可选配置

Note: The layout algorithm is determined by the constructor used, not by a property. Use
SfTreemap()
for squarified (default),
SfTreemap.slice()
for slice, or
SfTreemap.dice()
for dice.

Property	Type	Description
`colorMappers`	List<TreemapColorMapper>?	Value/range-based coloring
`legend`	TreemapLegend?	Legend widget configuration
`onSelectionChanged`	ValueChanged<TreemapTile>?	Selection event handler
`layoutDirection`	TreemapLayoutDirection	Layouts the tiles in top-left, top-right, bottom-left and bottom-right directions; default `topLeft`
`sortAscending`	bool	Sort tiles by weight (slice/dice only)

注意： 布局算法由使用的构造函数决定，不是通过属性配置。使用
SfTreemap()
获得 Squarified 布局（默认），
SfTreemap.slice()
获得 Slice 布局，
SfTreemap.dice()
获得 Dice 布局。

属性	类型	描述
`colorMappers`	List<TreemapColorMapper>?	基于值/区间的着色配置
`legend`	TreemapLegend?	图例组件配置
`onSelectionChanged`	ValueChanged<TreemapTile>?	选择事件处理函数
`layoutDirection`	TreemapLayoutDirection	区块的布局方向，支持左上、右上、左下、右下，默认值为 `topLeft`
`sortAscending`	bool	按权重对区块排序（仅 Slice/Dice 布局支持）

Common Use Cases

常见使用场景

Use Case 1: Budget Dashboard

场景1：预算仪表盘

Display organizational budget breakdown by department and sub-categories with color coding for spending levels.

When to use: Multi-level budget tracking, resource allocation

按部门和子分类展示组织预算明细，通过颜色编码标识支出水平。

适用时机： 多层级预算追踪、资源分配

Use Case 2: Sales Analysis

场景2：销售分析

Visualize sales data across regions, countries, and products with interactive drilldown.

When to use: Regional sales comparison, market analysis, performance dashboards

跨区域、国家、产品维度可视化销售数据，支持交互式下钻。

适用时机： 区域销售对比、市场分析、绩效仪表盘

Use Case 3: File System Visualization

场景3：文件系统可视化

Show disk space usage by folders and files with proportional sizing.

When to use: Storage analysis, file management tools, disk cleanup utilities

按文件夹和文件展示磁盘空间使用情况，区块大小与占用空间成正比。

适用时机： 存储分析、文件管理工具、磁盘清理工具

Use Case 4: Market Share Analysis

场景4：市场份额分析

Display market share data for different companies, products, or categories.

When to use: Competitive analysis, portfolio composition, market research

展示不同公司、产品或分类的市场份额数据。

适用时机： 竞品分析、投资组合构成、市场调研

Use Case 5: Organization Hierarchy

场景5：组织层级结构

Show organizational structure with metrics like headcount or budget per team.

When to use: HR dashboards, resource planning, org chart visualizations

展示组织架构，附带团队人数或预算等指标。

适用时机： HR 仪表盘、资源规划、组织架构可视化

Troubleshooting Quick Reference

故障排查快速参考

No tiles visible?

Check that
```
dataCount
```
matches your data length
Verify
```
weightValueMapper
```
returns positive numbers
Ensure
```
groupMapper
```
returns non-null strings

Labels not showing?

Add
```
labelBuilder
```
to TreemapLevel
Check label widget size fits within tile
Verify text color contrasts with tile background

Colors not applying?

Ensure
```
colorMappers
```
values match your data range
Check that color mapper has the correct type (value vs range)
Verify legend is configured if using color mappers

Selection not working?

Add
```
onSelectionChanged
```
callback
Ensure you're calling
```
setState
```
to rebuild
Check that tiles are large enough to tap

For detailed troubleshooting and solutions, refer to the specific reference documentation.

没有区块显示？

检查
```
dataCount
```
是否与数据长度匹配
确认
```
weightValueMapper
```
返回正数
确保
```
groupMapper
```
返回非空字符串

标签不显示？

为 TreemapLevel 添加
```
labelBuilder
```
检查标签组件大小是否适合区块尺寸
确认文本颜色与区块背景有足够对比度

颜色不生效？

确保
```
colorMappers
```
的值与数据范围匹配
检查颜色映射器类型是否正确（基于值/基于区间）
如果使用颜色映射器，确认已配置图例

选择功能不工作？

添加
```
onSelectionChanged
```
回调
确保调用了
```
setState
```
触发重绘
检查区块尺寸是否足够支持点击

如需详细的故障排查与解决方案，请参考对应的参考文档。