syncfusion-react-treemaps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React TreeMap

Syncfusion React TreeMap 实现指南

A comprehensive guide for implementing and customizing the Syncfusion React TreeMap component for hierarchical data visualization. The TreeMap displays nested rectangles where area represents data values, supporting multiple hierarchy levels, interactive drill-down, and rich customization.

本文是关于实现和自定义Syncfusion React TreeMap组件以进行层级数据可视化的完整指南。TreeMap通过嵌套矩形展示数据，其中矩形面积代表数据值，支持多层级结构、交互式钻取和丰富的自定义功能。

When to Use This Skill

何时使用本指南

Use this skill when you need to:

Install and set up the TreeMap component
Bind hierarchical or flat data to TreeMap
Visualize tree-structured data with multiple levels
Implement drill-down interactions for data exploration
Apply color mapping strategies (range, equal, desaturation)
Configure layouts (square, horizontal, vertical, auto)
Add legends, tooltips, and data labels
Implement selection and highlight features
Customize leaf items and label positioning
Handle accessibility requirements
Export or print TreeMap visualizations
Internationalize or apply RTL support

当你需要以下帮助时，可使用本指南：

安装和设置TreeMap组件
为TreeMap绑定层级或扁平数据
可视化具有多层级的树形结构数据
实现用于数据探索的钻取交互
应用颜色映射策略（范围映射、等值映射、饱和度映射）
配置布局（方形、水平、垂直、自动）
添加图例、工具提示和数据标签
实现选择和高亮功能
自定义叶节点项和标签位置
处理无障碍访问要求
导出或打印TreeMap可视化内容
实现国际化或RTL（从右到左）支持

Component Overview

组件概述

The TreeMap component is a powerful hierarchical data visualization tool that:

Renders nested rectangles using SVG for scalability
Supports any number of hierarchy levels
Provides four layout algorithms for optimal space utilization
Enables drill-down for exploring nested data
Offers three color mapping types for data-driven styling
Includes interactive features: selection, highlight, tooltips
Supports data labels, legends, and custom templates
Provides accessibility and internationalization support

TreeMap组件是一款强大的层级数据可视化工具，具备以下特性：

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

When to Choose TreeMap

何时选择TreeMap

Choose TreeMap when:

Visualizing hierarchical data (organizational charts, file systems, category hierarchies)
Comparing multiple values across categories using area encoding
Exploring nested categories through drill-down interaction
Displaying tree-structured data with many items at multiple levels
Need space-efficient visualization that uses area encoding

Don't use TreeMap for:

Simple flat data with few items (use Bar/Column charts)
Time-series data (use Line/Area charts)
Relationships between entities (use Diagram/Graph)
Single hierarchy with few nodes (consider alternative layouts)

选择TreeMap的场景：

可视化层级数据（组织结构图、文件系统、分类层级）
使用面积编码比较跨类别的多个值
通过钻取交互探索嵌套分类
展示包含大量项目的多层级树形结构数据
需要利用面积编码的空间高效型可视化

不适合使用TreeMap的场景：

少量项目的简单扁平数据（使用柱状图）
时间序列数据（使用折线图/面积图）
实体间的关系（使用关系图/网络图）
节点较少的单层级结构（考虑其他布局）

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installing @syncfusion/ej2-react-treemap
Package dependencies and setup
Module injection for features
Creating your first TreeMap
Rendering basic hierarchical data

📄 阅读： references/getting-started.md

安装@syncfusion/ej2-react-treemap
包依赖与设置
功能模块注入
创建你的第一个TreeMap
渲染基础层级数据

Data Binding & Hierarchies

数据绑定与层级结构

📄 Read: references/data-binding.md

Flat vs hierarchical data structures
Configuring weightValuePath for sizing
Binding multilevel hierarchies with levels
Remote data source integration
Data transformation patterns

📄 阅读： references/data-binding.md

扁平数据与层级数据结构对比
配置weightValuePath以设置项的大小
使用levels配置绑定多层级结构
远程数据源集成
数据转换模式

Color Mapping Strategies

颜色映射策略

📄 Read: references/color-mapping.md

Range-based color mapping (gradient by values)
Equal value color mapping (categorical colors)
Desaturation mapping (opacity-based variation)
Dynamic color assignment
Choosing color mapping strategies

📄 阅读： references/color-mapping.md

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

Layouts and Layout Selection

布局与布局选择

📄 Read: references/layouts.md

Square layout (balanced aspect ratio)
Horizontal layout (left-to-right ordering)
Vertical layout (top-to-bottom ordering)
Auto layout (default optimal layout)
When to use each layout type

📄 阅读： references/layouts.md

方形布局（平衡宽高比）
水平布局（从左到右排序）
垂直布局（从上到下排序）
自动布局（默认最优布局）
各布局类型的适用场景

Drill-Down and Navigation

钻取与导航

📄 Read: references/drilldown.md

Enabling drill-down with enableDrillDown
Configuring levels for multi-level exploration
Drill-down events and callbacks
Breadcrumb navigation patterns
Back navigation handling

📄 阅读： references/drilldown.md

通过enableDrillDown启用钻取
配置levels以支持多层级探索
钻取事件与回调
面包屑导航模式
返回导航处理

Leaf Items, Labels & Templates

叶节点项、标签与模板

📄 Read: references/leaf-items-and-labels.md

Leaf item configuration and styling
Label positioning (TopLeft, Center, BottomRight, etc.)
Data label formatting and templates
Border and fill customization
Label overflow handling

📄 阅读： references/leaf-items-and-labels.md

叶节点项配置与样式设置
标签位置（TopLeft、Center、BottomRight等）
数据标签格式化与模板
边框与填充自定义
标签溢出处理

Legends, Tooltips & Selection

图例、工具提示与选择功能

📄 Read: references/legends-tooltips-selection.md

Creating and configuring legends
Tooltip templates and styling
Selection and highlight modes
Interactive features and events
Responding to user interactions

📄 阅读： references/legends-tooltips-selection.md

创建和配置图例
工具提示模板与样式设置
选择与高亮模式
交互功能与事件
响应用户交互

Customization, Accessibility & Export

自定义、无障碍访问与导出

📄 Read: references/customization-accessibility.md

WCAG compliance and keyboard navigation
RTL (right-to-left) support
Internationalization and localization
Theming and CSS customization
Print and export functionality

📄 阅读： references/customization-accessibility.md

WCAG合规性与键盘导航
RTL（从右到左）支持
国际化与本地化
主题与CSS自定义
打印与导出功能

Quick Start Example

快速入门示例

jsx

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

jsx

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

Common Patterns

常见模式

Pattern 1: Hierarchical Data with Drill-Down

模式1：带钻取的层级数据

jsx

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

When to use: Exploring multilevel hierarchies with progressive disclosure through drill-down interaction.

jsx

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

适用场景： 通过钻取交互逐步展示多层级结构，进行数据探索。

Pattern 2: Color-Coded Categories

模式2：颜色编码分类

jsx

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

When to use: Categorizing items with distinct colors for quick visual identification.

jsx

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

适用场景： 使用不同颜色对项目进行分类，便于快速视觉识别。

Pattern 3: Value-Range Color Gradient

模式3：基于值范围的颜色渐变

jsx

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

When to use: Showing magnitude differences through color intensity for performance metrics, sales, or other continuous values.

jsx

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

适用场景： 通过颜色深浅展示数值大小差异，适用于性能指标、销售额或其他连续值。

Key Props and Configuration

关键属性与配置

Prop	Purpose	Common Values
`dataSource`	Hierarchical or flat data array	Array of objects
`weightValuePath`	Property path for item sizing	e.g., 'Sales', 'Count'
`equalColorValuePath`	Property for categorical coloring	e.g., 'Category', 'Type'
`rangeColorValuePath`	Property for range-based coloring	e.g., 'Sales', 'Value'
`enableDrillDown`	Enable click-to-drill interaction	true/false
`layoutType`	Spatial layout algorithm	'Squarified', 'Horizontal', 'Vertical', 'SliceAndDice'
`height`	Component height	e.g., '350px', '100%'
`palette`	Array of colors for items	['#color1', '#color2', ...]

属性	用途	常见值
`dataSource`	层级或扁平数据数组	对象数组
`weightValuePath`	用于设置项大小的属性路径	例如：'Sales'、'Count'
`equalColorValuePath`	用于分类颜色的属性	例如：'Category'、'Type'
`rangeColorValuePath`	用于范围颜色映射的属性	例如：'Sales'、'Value'
`enableDrillDown`	启用点击钻取交互	true/false
`layoutType`	空间布局算法	'Squarified'、'Horizontal'、'Vertical'、'SliceAndDice'
`height`	组件高度	例如：'350px'、'100%'
`palette`	项的颜色数组	['#color1', '#color2', ...]

Common Use Cases

常见使用场景

API Reference

—

This section summarizes the most commonly used

TreeMap

props, methods, and events. For the complete API with typed models, see the official docs: https://ej2.syncfusion.com/react/documentation/api/treemap/index-default

组织层级结构： 可视化跨部门、区域和分部的员工数量
文件系统浏览器： 通过钻取展示文件夹和子文件夹的磁盘使用情况
销售业绩： 比较区域销售额、产品类别和销售区域
网站分析： 层级化探索流量来源、页面和用户细分
投资组合分配： 可视化跨类别和子类别的资产分布
市场份额： 展示包含公司层级的竞争格局
预算分析： 跨部门和项目分配并可视化预算

Important Properties (selected)

API参考

```
dataSource
```
(Array|DataManager) — The data source for TreeMap. Can be flat or hierarchical. Default:
```
null
```
```
weightValuePath
```
(string) — Path to numeric value used for sizing each item. Default:
```
null
```
```
colorValuePath
```
(string) — Field used for continuous color mapping (range palettes).
```
equalColorValuePath
```
(string[]) — Field(s) for categorical/equal color mapping.
```
rangeColorValuePath
```
(string[]) — Field(s) used for range-based color mapping.
```
leafItemSettings
```
(object) — Configuration for leaf items (e.g.,
```
labelPath
```
,
```
colorMapping
```
,
```
border
```
,
```
gap
```
).
```
levels
```
(LevelSettingsModel[]) — Array of level configuration objects to define grouping and appearance per hierarchy level.

layoutType

(string) — Layout algorithm:

Squarified

(default),

SliceAndDiceHorizontal

SliceAndDiceVertical

SliceAndDiceAuto

, etc.

```
enableDrillDown
```
(boolean) — Enable drill-down interaction. Default:
```
false
```
```
drillDownView
```
(boolean) — Use drill-down view layout. Default:
```
false
```
```
enableBreadcrumb
```
(boolean) — Show breadcrumb when drilling. Default:
```
false
```
```
breadcrumbConnector
```
(string) — Separator shown between breadcrumb items.
```
initialDrillDown
```
(object) — Configure initial drill-down level/state.
```
enableHtmlSanitizer
```
(boolean) — Sanitize HTML in templates/tooltips. Default:
```
true
```
```
enablePersistence
```
(boolean) — Persist component state between reloads. Default:
```
false
```
```
enableRtl
```
(boolean) — Enable right-to-left rendering. Default:
```
false
```
```
palette
```
(string[]) — Array of palette colors used for fills.
```
highlightSettings
```
(object) — Highlight configuration and styling.
```
selectionSettings
```
(object) — Selection configuration (mode, enable, etc.).
```
legendSettings
```
(object) — Legend configuration (position, title, shape, etc.).
```
titleSettings
```
(object) — Title and subtitle configuration.
```
tooltipSettings
```
(object) — Tooltip templates and behavior.
```
format
```
(string) — Formatting string for labels or values.
```
useGroupingSeparator
```
(boolean) — Apply grouping separator for numeric values. Default:
```
true
```
```
description
```
(string) — Accessibility description for the TreeMap.
```
margin
```
(object) — Margin settings for the component (
```
{ top, right, bottom, left }
```
).
```
height
```
/
```
width
```
(string|number) — Size of the component (e.g.,
```
350px
```
or
```
100%
```
).
```
theme
```
(string) — Theme name (e.g.,
```
Material
```
,
```
Bootstrap
```
).

本节总结了

TreeMap

最常用的属性、方法和事件。如需完整的带类型模型的API文档，请查看官方文档：https://ej2.syncfusion.com/react/documentation/api/treemap/index-default

Common Methods

重要属性（精选）

```
destroy()
```
— Clean up the TreeMap instance and remove listeners.

export(type, fileName, orientation, allowDownload)

— Export the TreeMap as

PNG|JPEG|SVG|PDF

. Returns a Promise for PDF export flows.

```
print(id)
```
— Print TreeMap content by element id, DOM element, or array of ids.
```
doubleClickOnTreeMap(e)
```
— Programmatically trigger double-click behavior.
```
selectItem(levelOrder, isSelected)
```
— Select or deselect an item by level order array.

```
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
```
）。

Common Events

常用方法

```
load
```
/
```
loaded
```
— Lifecycle events fired before/after component load.
```
itemRendering
```
— Fired while items are rendered; use to customize item appearance.
```
click
```
/
```
itemClick
```
— Fired on item click.
```
doubleClick
```
— Fired on item double click.
```
drillStart
```
/
```
drillEnd
```
— Fired when drill-down starts/ends.
```
itemHighlight
```
/
```
itemSelected
```
— Events for highlight/selection lifecycle.
```
legendRendering
```
/
```
legendItemRendering
```
— Events during legend rendering.
```
tooltipRendering
```
— Fired when tooltip content is prepared.
```
resize
```
— Fired on component resize.
```
beforePrint
```
/
```
print
```
— Hooks around printing/export.

```
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)
```
— 通过层级顺序数组选择或取消选择项。

Quick Import Example

常用事件

jsx

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>

Organization Hierarchies: Visualize employee counts across departments, regions, and divisions
File System Browser: Display disk usage by folders and subfolders with drill-down
Sales Performance: Compare regional sales, product categories, and territories
Website Analytics: Explore traffic sources, pages, and user segments hierarchically
Portfolio Allocation: Visualize asset distribution across categories and subcategories
Market Share: Display competitive landscape with company hierarchies
Budget Analysis: Allocate and visualize budget across departments and line items

```
load
```
/
```
loaded
```
— 组件加载前后触发的生命周期事件。
```
itemRendering
```
— 项渲染时触发；用于自定义项外观。
```
click
```
/
```
itemClick
```
— 点击项时触发。
```
doubleClick
```
— 双击项时触发。
```
drillStart
```
/
```
drillEnd
```
— 钻取开始/结束时触发。
```
itemHighlight
```
/
```
itemSelected
```
— 高亮/选择生命周期事件。
```
legendRendering
```
/
```
legendItemRendering
```
— 图例渲染期间触发的事件。
```
tooltipRendering
```
— 工具提示内容准备时触发。
```
resize
```
— 组件调整大小时触发。
```
beforePrint
```
/
```
print
```
— 打印/导出前后的钩子事件。

Next Steps

快速导入示例

Start with Getting Started guide to install and render your first TreeMap
Choose a data binding pattern based on your data structure
Select color mapping strategy (range, equal, or desaturation)
Configure layout and drill-down if exploring hierarchies
Customize leaf items, labels, and tooltips for your use case
Add interactivity with selection and events
Ensure accessibility and internationalization requirements

Ready to implement TreeMap? Start with references/getting-started.md or choose a specific feature guide from the navigation options above.

jsx

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>

—

下一步

—

从快速入门指南开始，安装并渲染你的第一个TreeMap
根据数据结构选择数据绑定模式
选择颜色映射策略（范围、等值或饱和度）
配置布局和钻取功能（如果需要探索层级结构）
自定义叶节点项、标签和工具提示以适配你的使用场景
添加交互功能，如选择和事件响应
确保满足无障碍访问和国际化要求

准备好实现TreeMap了吗？ 从references/getting-started.md开始，或从上方导航选项中选择特定功能指南。