syncfusion-react-treemaps

实现 Syncfusion React TreeMap

全面介绍如何实现和自定义 Syncfusion React TreeMap 组件，以可视化层次结构数据。TreeMap 以嵌套矩形展示数据，其中面积表示数据值；它支持多个层次、交互式下钻和丰富的自定义选项。

何时使用此技能

在以下情况下使用此技能：

• 安装和设置 TreeMap 组件
• 将层次结构数据或扁平数据绑定到 TreeMap
• 可视化多层树结构数据
• 实现用于数据探索的下钻交互
• 应用颜色映射策略（范围、相等值、去饱和）
• 配置布局（square、horizontal、vertical、auto）
• 添加图例、工具提示和数据标签
• 实现选择和高亮功能
• 自定义叶节点项和标签位置
• 满足无障碍要求
• 导出或打印 TreeMap 可视化内容
• 实现国际化或 RTL 支持

组件概览

TreeMap 是一款功能强大的层次结构数据可视化工具，具有以下特性：

• 使用 SVG 渲染嵌套矩形，确保良好的可扩展性
• 支持任意数量的层次
• 提供四种布局算法，以优化空间利用率
• 支持下钻，便于探索嵌套数据
• 提供三种颜色映射类型，用于数据驱动的样式设置
• 包含交互功能：选择、高亮和工具提示
• 支持数据标签、图例和自定义模板
• 提供无障碍和国际化支持

何时选择 TreeMap

适合选择 TreeMap 的情况：

• 可视化层次结构数据（组织结构图、文件系统、类别层次结构）
• 使用面积编码比较不同类别中的多个值
• 通过下钻交互探索嵌套类别
• 展示包含多个层次和大量项的树结构数据
• 需要使用面积编码的高效空间可视化

不适合使用 TreeMap 的情况：

• 数据简单且扁平，项数较少（使用 Bar/Column 图表）
• 时间序列数据（使用 Line/Area 图表）
• 实体之间的关系（使用 Diagram/Graph）
• 节点较少的单层次结构（考虑其他布局）

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装 @syncfusion/ej2-react-treemap
• 软件包依赖项和设置
• 为功能注入模块
• 创建第一个 TreeMap
• 渲染基本层次结构数据

数据绑定与层次结构

📄 阅读： references/data-binding.md

• 扁平数据与层次结构数据
• 配置 weightValuePath 以设置尺寸
• 使用 levels 绑定多层次结构
• 集成远程数据源
• 数据转换模式

颜色映射策略

📄 阅读： references/color-mapping.md

• 基于范围的颜色映射（按值渐变）
• 等值颜色映射（分类颜色）
• 去饱和映射（基于不透明度的变化）
• 动态颜色分配
• 选择颜色映射策略

布局与布局选择

📄 阅读： references/layouts.md

• Square 布局（均衡的宽高比）
• Horizontal 布局（从左到右排序）
• Vertical 布局（从上到下排序）
• Auto 布局（默认的最佳布局）
• 各布局类型的适用场景

下钻与导航

📄 阅读： 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 开始，或从上方的导航选项中选择特定功能指南。