syncfusion-angular-treemap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Angular TreeMap

实现Syncfusion Angular TreeMap

The TreeMap component visualizes hierarchical or grouped data as nested rectangles. Each rectangle represents a data item, and its size is determined by a numeric field mapped through

weightValuePath

. TreeMaps are useful for displaying structures such as product categories, regional breakdowns, market segments, or any grouped dataset where relative magnitude matters.

TreeMap组件将层级或分组数据可视化为嵌套矩形。每个矩形代表一个数据项，其大小由通过

weightValuePath

映射的数字字段决定。TreeMap适用于展示产品类别、区域细分、市场细分等结构，或任何相对量级重要的分组数据集。

When to Use This Skill

何时使用此技能

Visualizing hierarchical data: Display grouped or multi-level data such as regions, departments, or product categories
Multi-level data visualization: Show parent-child relationships using
```
levels
```
and
```
groupPath
```
Creating drill-down interfaces: Enable interactive navigation through hierarchy levels
Color-coding data: Use range, equal, desaturation, palette, or direct color binding
Adding interactive features: Implement selection, highlight, click, double-click, and right-click interactions
Customizing appearance: Modify layout, colors, borders, labels, headers, legends, and templates
Displaying supplementary information: Add labels, tooltips, legends, and formatted values
Exporting visualizations: Print or export as PNG, JPEG, SVG, or PDF
International support: Enable RTL, locale-specific number formatting, and culture-aware display
Accessibility: Improve screen reader support, ARIA naming, contrast, and focus behavior

可视化层级数据：展示区域、部门或产品类别等分组或多级数据
多级数据可视化：使用
```
levels
```
和
```
groupPath
```
展示父子关系
创建钻取界面：启用层级间的交互式导航
数据颜色编码：使用范围、相等、饱和度调整、调色板或直接颜色绑定
添加交互功能：实现选择、高亮、单击、双击和右键交互
自定义外观：修改布局、颜色、边框、标签、标题、图例和模板
展示补充信息：添加标签、工具提示、图例和格式化值
导出可视化内容：打印或导出为PNG、JPEG、SVG或PDF格式
国际化支持：启用RTL、区域特定数字格式和文化感知显示
无障碍功能：提升屏幕阅读器支持、ARIA命名、对比度和焦点行为

Documentation and Navigation Guide

文档与导航指南

Choose your reference based on what you need to accomplish:

根据你的需求选择参考文档：

API Reference

API参考

📄 Read:

references/api-reference.md

📄 阅读：

references/api-reference.md

Getting Started

快速入门

📄 Read:

references/getting-started.md

Installation and npm package setup
Importing
```
TreeMapModule
```
Creating your first TreeMap component
Theme and style configuration
Basic component with simple data

📄 阅读：

references/getting-started.md

安装与npm包设置
导入
```
TreeMapModule
```
创建你的第一个TreeMap组件
主题与样式配置
带简单数据的基础组件

Data Binding

数据绑定

📄 Read:

references/data-binding.md

Binding flat collections
Grouping data with
```
levels
```
Mapping data source properties to TreeMap fields
Configuring
```
weightValuePath
```
for item sizing
Dynamic data updates and state-driven binding

📄 阅读：

references/data-binding.md

绑定扁平集合
使用
```
levels
```
分组数据
将数据源属性映射到TreeMap字段
配置
```
weightValuePath
```
用于项大小设置
动态数据更新与状态驱动绑定

Color Mapping

颜色映射

📄 Read:

references/color-mapping.md

Range color mapping for numeric values
Equal color mapping for category-based colors
Desaturation color mapping with opacity
Palette-based coloring
Direct color binding with
```
colorValuePath
```
Gradient colors with
```
leafItemSettings.colorMapping
```

📄 阅读：

references/color-mapping.md

数值的范围颜色映射
基于类别的相等颜色映射
带透明度的饱和度调整颜色映射
基于调色板的着色
使用
```
colorValuePath
```
直接颜色绑定
通过
```
leafItemSettings.colorMapping
```
实现渐变色

Drilldown and Navigation

钻取与导航

📄 Read:

references/drilldown-and-navigation.md

Enabling drilldown functionality
Parent-child navigation with
```
levels
```
```
drillDownView
```
behavior
Breadcrumb navigation
Drill events (
```
drillStart
```
,
```
drillEnd
```
)
Resetting to root through application state when needed

📄 阅读：

references/drilldown-and-navigation.md

启用钻取功能
使用
```
levels
```
实现父子导航
```
drillDownView
```
行为
面包屑导航
钻取事件（
```
drillStart
```
、
```
drillEnd
```
）
必要时通过应用状态重置到根层级

Levels and Layout

层级与布局

📄 Read:

references/levels-and-layout.md

Configuring multiple hierarchy levels
```
groupPath
```
and grouped rendering

Layout types (

Squarified

SliceAndDiceVertical

SliceAndDiceHorizontal

SliceAndDiceAuto

)

Group spacing and leaf gaps
Header formatting and styling
Header templates and header sizing

📄 阅读：

references/levels-and-layout.md

配置多个层级
```
groupPath
```
与分组渲染

布局类型（

Squarified

、

SliceAndDiceVertical

、

SliceAndDiceHorizontal

、

SliceAndDiceAuto

）

组间距与叶子项间隙
标题格式化与样式
标题模板与标题大小

Labels, Tooltips, and Legend

标签、工具提示与图例

📄 Read:

references/labels-tooltips-legend.md

Data label configuration and formatting
Label templates and template positioning
Handling label intersections and overflow
Tooltip visibility and formatting
Custom tooltip templates
Legend display and configuration
Coordinating legend with color mapping, selection, and highlight

📄 阅读：

references/labels-tooltips-legend.md

数据标签配置与格式化
标签模板与模板定位
处理标签交叉与溢出
工具提示可见性与格式化
自定义工具提示模板
图例显示与配置
协调图例与颜色映射、选择和高亮

Selection and Interactivity

选择与交互性

📄 Read:

references/selection-interactivity.md

Enabling selection and highlight
Customizing selection colors and borders
Legend-based selection and hover interaction
Click, item-selected, double-click, and right-click events
Programmatic selection with
```
selectItem(...)
```
Managing single-item or multi-item workflows in application state

📄 阅读：

references/selection-interactivity.md

启用选择与高亮
自定义选择颜色与边框
基于图例的选择与悬停交互
单击、项选中、双击和右键事件
使用
```
selectItem(...)
```
进行程序化选择
在应用状态中管理单项或多项工作流

Print, Export, and Accessibility

打印、导出与无障碍功能

📄 Read:

references/print-export-accessibility.md

Print functionality
Image export (PNG, JPEG, SVG)
PDF export with orientation options
Base64 export handling
WCAG accessibility support
Screen reader support and ARIA labels
Contrast and focus considerations

📄 阅读：

references/print-export-accessibility.md

打印功能
图片导出（PNG、JPEG、SVG）
带方向选项的PDF导出
Base64导出处理
WCAG无障碍支持
屏幕阅读器支持与ARIA标签
对比度与焦点注意事项

Internationalization

国际化

📄 Read:

references/internationalization.md

Right-to-left (RTL) rendering
Locale configuration and number formatting
Globalization for labels and tooltips
Render direction configuration
Multi-language data binding
Cultural customization with
```
setCulture()
```
and
```
setCurrencyCode()
```

📄 阅读：

references/internationalization.md

从右到左（RTL）渲染
区域配置与数字格式化
标签与工具提示的全球化
渲染方向配置
多语言数据绑定
使用
```
setCulture()
```
和
```
setCurrencyCode()
```
进行文化自定义

Quick Start

快速开始

typescript

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Size"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `,
  styles: [`
    #treemap-container {
      display: block;
      width: 100%;
      height: 500px;
    }
  `]
})
export class TreeMapComponent {
  public data = signal([
    { Category: 'Electronics', Item: 'Laptops', Size: 150 },
    { Category: 'Electronics', Item: 'Phones', Size: 200 },
    { Category: 'Furniture', Item: 'Chairs', Size: 100 },
    { Category: 'Furniture', Item: 'Tables', Size: 120 }
  ]);

  public levels = [
    { groupPath: 'Category' }
  ];

  public leafItemSettings = {
    labelPath: 'Item',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

typescript

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Size"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `,
  styles: [`
    #treemap-container {
      display: block;
      width: 100%;
      height: 500px;
    }
  `]
})
export class TreeMapComponent {
  public data = signal([
    { Category: 'Electronics', Item: 'Laptops', Size: 150 },
    { Category: 'Electronics', Item: 'Phones', Size: 200 },
    { Category: 'Furniture', Item: 'Chairs', Size: 100 },
    { Category: 'Furniture', Item: 'Tables', Size: 120 }
  ]);

  public levels = [
    { groupPath: 'Category' }
  ];

  public leafItemSettings = {
    labelPath: 'Item',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Common Patterns

常见模式

Pattern 1: Basic Hierarchical Visualization

模式1：基础层级可视化

Display grouped hierarchical data using

levels

and

groupPath

typescript

public levels = [
  { groupPath: 'Region', headerFormat: '${Region}' },
  { groupPath: 'Country', headerFormat: '${Country}' }
];

public leafItemSettings = {
  labelPath: 'Country'
};

使用

levels

和

groupPath

展示分组层级数据。

typescript

public levels = [
  { groupPath: 'Region', headerFormat: '${Region}' },
  { groupPath: 'Country', headerFormat: '${Country}' }
];

public leafItemSettings = {
  labelPath: 'Country'
};

Pattern 2: Color-Mapped Values

模式2：颜色映射值

Use range color mapping through

rangeColorValuePath

and

leafItemSettings.colorMapping

typescript

<ejs-treemap
  [dataSource]="data()"
  weightValuePath="Value"
  rangeColorValuePath="Value"
  [leafItemSettings]="leafItemSettings">
</ejs-treemap>

typescript

public leafItemSettings = {
  labelPath: 'Name',
  colorMapping: [
    { from: 0, to: 50, color: '#3498db' },
    { from: 50, to: 100, color: '#e74c3c' }
  ]
};

通过

rangeColorValuePath

和

leafItemSettings.colorMapping

使用范围颜色映射。

typescript

<ejs-treemap
  [dataSource]="data()"
  weightValuePath="Value"
  rangeColorValuePath="Value"
  [leafItemSettings]="leafItemSettings">
</ejs-treemap>

typescript

public leafItemSettings = {
  labelPath: 'Name',
  colorMapping: [
    { from: 0, to: 50, color: '#3498db' },
    { from: 50, to: 100, color: '#e74c3c' }
  ]
};

Pattern 3: Interactive Drilldown

模式3：交互式钻取

Enable drilldown with breadcrumb navigation for exploring grouped levels.

typescript

<ejs-treemap
  [dataSource]="data()"
  weightValuePath="Value"
  [enableDrillDown]="true"
  [enableBreadcrumb]="true"
  breadcrumbConnector=" / "
  [levels]="levels"
  [leafItemSettings]="leafItemSettings">
</ejs-treemap>

启用钻取并搭配面包屑导航，用于探索分组层级。

typescript

<ejs-treemap
  [dataSource]="data()"
  weightValuePath="Value"
  [enableDrillDown]="true"
  [enableBreadcrumb]="true"
  breadcrumbConnector=" / "
  [levels]="levels"
  [leafItemSettings]="leafItemSettings">
</ejs-treemap>

Key Props and Configuration

关键属性与配置

Property	Type	Purpose
`dataSource`	`object[]`	Data collection for TreeMap items
`weightValuePath`	`string`	Numeric field used to size each item
`leafItemSettings`	`object`	Leaf item configuration such as labels, borders, templates, and color mapping
`levels`	`object[]`	Hierarchy configuration using `groupPath` and header settings
`layoutType`	`'Squarified' \| 'SliceAndDiceVertical' \| 'SliceAndDiceHorizontal' \| 'SliceAndDiceAuto'`	Rectangle arrangement algorithm
`colorValuePath`	`string`	Data field used for direct item color assignment
`equalColorValuePath`	`string`	Data field used for category-based color mapping
`rangeColorValuePath`	`string`	Data field used for numeric range color mapping
`enableDrillDown`	`boolean`	Enables drilldown navigation through grouped levels
`enableBreadcrumb`	`boolean`	Displays breadcrumb navigation during drilldown
`legendSettings`	`object`	Legend display and styling configuration
`tooltipSettings`	`object`	Tooltip visibility, formatting, and template configuration
`selectionSettings`	`object`	Selection appearance and behavior configuration
`highlightSettings`	`object`	Hover highlight appearance configuration
`enableRtl`	`boolean`	Enables right-to-left rendering
`locale`	`string`	Overrides the component culture
`format`	`string`	Applies numeric formatting such as `n2` , `c` , or `p`
`useGroupingSeparator`	`boolean`	Enables culture-aware number grouping separators
`allowPrint`	`boolean`	Enables print support
`allowImageExport`	`boolean`	Enables image export support
`allowPdfExport`	`boolean`	Enables PDF export support
`description`	`string`	Adds descriptive accessibility text for the component
`tabIndex`	`number`	Controls focus order for the TreeMap container

属性	类型	用途
`dataSource`	`object[]`	TreeMap项的数据集合
`weightValuePath`	`string`	用于设置每个项大小的数字字段
`leafItemSettings`	`object`	叶子项配置，如标签、边框、模板和颜色映射
`levels`	`object[]`	使用 `groupPath` 和标题设置的层级配置
`layoutType`	`'Squarified' \| 'SliceAndDiceVertical' \| 'SliceAndDiceHorizontal' \| 'SliceAndDiceAuto'`	矩形排列算法
`colorValuePath`	`string`	用于直接分配项颜色的数据字段
`equalColorValuePath`	`string`	用于基于类别颜色映射的数据字段
`rangeColorValuePath`	`string`	用于数值范围颜色映射的数据字段
`enableDrillDown`	`boolean`	启用分组层级间的钻取导航
`enableBreadcrumb`	`boolean`	钻取期间显示面包屑导航
`legendSettings`	`object`	图例显示与样式配置
`tooltipSettings`	`object`	工具提示可见性、格式化和模板配置
`selectionSettings`	`object`	选择外观与行为配置
`highlightSettings`	`object`	悬停高亮外观配置
`enableRtl`	`boolean`	启用从右到左渲染
`locale`	`string`	覆盖组件文化设置
`format`	`string`	应用数值格式化，如 `n2` 、 `c` 或 `p`
`useGroupingSeparator`	`boolean`	启用文化感知的数字分组分隔符
`allowPrint`	`boolean`	启用打印支持
`allowImageExport`	`boolean`	启用图片导出支持
`allowPdfExport`	`boolean`	启用PDF导出支持
`description`	`string`	为组件添加描述性无障碍文本
`tabIndex`	`number`	控制TreeMap容器的焦点顺序

Implementation Notes

实现注意事项

Prefer
```
TreeMapModule
```
for focused standalone Angular components.

Use

TreeMapLegendService

TreeMapTooltipService

TreeMapSelectionService

TreeMapHighlightService

PrintService

ImageExportService

, and

PdfExportService

only when the corresponding features are enabled.

For color mapping, configure

leafItemSettings.colorMapping

and pair it with

equalColorValuePath

rangeColorValuePath

when needed.

For programmatic selection, use
```
selectItem(levelOrder, isSelected?)
```
rather than unsupported helper methods.
For accessibility, rely on TreeMap’s built-in ARIA support, meaningful titles, labels, legends, descriptions, and strong color contrast.
For keyboard and advanced interaction workflows, provide surrounding Angular controls where needed rather than assuming extra undocumented TreeMap keyboard APIs.

对于聚焦的独立Angular组件，优先使用
```
TreeMapModule
```
。

仅在启用对应功能时，才使用

TreeMapLegendService

、

TreeMapTooltipService

、

TreeMapSelectionService

、

TreeMapHighlightService

、

PrintService

、

ImageExportService

和

PdfExportService

。

颜色映射方面，配置

leafItemSettings.colorMapping

，必要时搭配

equalColorValuePath

或

rangeColorValuePath

。

程序化选择请使用
```
selectItem(levelOrder, isSelected?)
```
，而非不支持的辅助方法。
无障碍功能方面，依赖TreeMap内置的ARIA支持、有意义的标题、标签、图例、描述和高颜色对比度。
对于键盘和高级交互工作流，需在周边提供Angular控件，而非依赖未文档化的TreeMap额外键盘API。