syncfusion-flutter-treemap

实现 Flutter TreeMaps

本技能将指导你实现 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：组织层级

展示组织结构，并显示每个团队的人数或预算等指标。

使用场景： HR 仪表板、资源规划、组织结构图可视化

故障排查速查

看不到图块？

• 检查 dataCount 是否与数据长度一致
• 确认 weightValueMapper 返回正数
• 确保 groupMapper 返回非空字符串

未显示标签？

• 为 TreemapLevel 添加 labelBuilder
• 检查标签组件尺寸是否适合图块
• 确认文字颜色与图块背景形成对比

颜色未生效？

• 确保 colorMappers 的值与数据范围匹配
• 检查颜色映射器的类型是否正确（值或范围）
• 使用颜色映射器时，确认已配置图例

选择功能不起作用？

• 添加 onSelectionChanged 回调
• 确保调用 setState 以触发重建
• 检查图块是否足够大，便于点击

如需详细的故障排查信息和解决方案，请参阅相应的参考文档。