syncfusion-angular-treemap

实现 Syncfusion Angular TreeMap

TreeMap 组件会将层次结构或分组数据可视化为嵌套矩形。每个矩形代表一个数据项，其大小由通过 weightValuePath 映射的数值字段决定。TreeMap 适用于展示产品类别、区域细分、市场细分等结构，或任何需要体现相对大小的分组数据集。

何时使用此技能

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

文档与导航指南

根据要完成的任务选择参考文档：

API 参考

📄 阅读： references/api-reference.md

快速入门

📄 阅读： references/getting-started.md

• 安装和 npm 包设置
• 导入 TreeMapModule
• 创建第一个 TreeMap 组件
• 主题和样式配置
• 使用简单数据创建基础组件

数据绑定

📄 阅读： references/data-binding.md

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

颜色映射

📄 阅读： references/color-mapping.md

• 为数值配置范围颜色映射
• 为基于类别的颜色配置相等颜色映射
• 配置带透明度的去饱和度颜色映射
• 使用调色板着色
• 使用 colorValuePath 直接绑定颜色
• 使用 leafItemSettings.colorMapping 设置渐变色

下钻与导航

📄 阅读： references/drilldown-and-navigation.md

• 启用下钻功能
• 使用 levels 进行父子导航
• drillDownView 行为
• 面包屑导航
• 下钻事件（drillStart、drillEnd）
• 需要时通过应用状态重置到根级别

层级与布局

📄 阅读： references/levels-and-layout.md

• 配置多个层次级别
• groupPath 和分组渲染
• 布局类型（Squarified、SliceAndDiceVertical、SliceAndDiceHorizontal、SliceAndDiceAuto）
• 分组间距和叶节点间距
• 标题格式和样式
• 标题模板和标题大小

标签、工具提示和图例

📄 阅读： references/labels-tooltips-legend.md

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

选择与交互

📄 阅读： references/selection-interactivity.md

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

打印、导出和无障碍访问

📄 阅读： references/print-export-accessibility.md

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

国际化

📄 阅读： references/internationalization.md

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

快速入门

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

常见模式

模式 1：基本层次可视化

使用 levels 和 groupPath 显示分组的层次数据。

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

public leafItemSettings = {
  labelPath: 'Country'
};

模式 2：值颜色映射

通过 rangeColorValuePath 和 leafItemSettings.colorMapping 使用范围颜色映射。

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

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

模式 3：交互式下钻

启用下钻和面包屑导航，以浏览分组层级。

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

关键属性和配置

属性	类型	用途
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 容器的焦点顺序

实现说明

• 对于专用的独立 Angular 组件，优先使用 TreeMapModule。
• 仅在启用相应功能时使用 TreeMapLegendService、TreeMapTooltipService、TreeMapSelectionService、TreeMapHighlightService、PrintService、ImageExportService 和 PdfExportService。
• 对于颜色映射，请配置 leafItemSettings.colorMapping，并根据需要将其与 equalColorValuePath 或 rangeColorValuePath 配合使用。
• 对于以编程方式进行选择，请使用 selectItem(levelOrder, isSelected?)，而不要使用不受支持的辅助方法。
• 对于无障碍访问，请使用 TreeMap 内置的 ARIA 支持、有意义的标题、标签、图例、描述和高对比度配色。
• 对于键盘和高级交互工作流，请根据需要提供周边的 Angular 控件，不要假设 TreeMap 还提供未记录的键盘 API。