syncfusion-react-accumulation-chart

实现 Syncfusion React 积累图表

一份全面的技能指南，介绍如何实现 Syncfusion 的 React 积累图表组件（AccumulationChartComponent）。这些组件提供饼图、圆环图、漏斗图和金字塔图等圆形及层级数据可视化，并支持丰富的交互功能、导出能力和完整的无障碍访问。

何时使用此技能

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

• 创建饼图或圆环图，以展示数据比例
• 实现漏斗图或金字塔图，以可视化层级或流程
• 在圆形布局中展示基于百分比或类别的数据
• 添加工具提示、图例和数据标签等交互功能
• 实现智能标签定位，避免标签重叠
• 创建下钻或多层积累图表
• 应用分离效果以突出显示特定数据点
• 对较小的数据值进行分组，以便更好地可视化
• 使用主题、颜色和图案自定义图表外观
• 优雅地处理空数据点或缺失数据点
• 实现符合 WCAG 标准的无障碍数据可视化

组件概述

Syncfusion React 积累图表组件提供四种主要图表类型：

• 饼图： 将圆形划分为多个扇区，以表示数据比例
• 圆环图： 中心为空心的饼图（可配置内半径）
• 漏斗图： 展示逐步减少过程的倒三角形图表（销售漏斗、转化率）
• 金字塔图： 展示层级数据的三角形图表（人口金字塔、组织结构）

主要功能：

• 避免重叠的智能标签
• 根据数值或数据点数量进行分组
• 交互式工具提示和图例
• 用于突出显示的分离效果
• 可自定义角度的半饼图
• 多层下钻功能
• 让外观更现代的圆角边框
• 图案填充和自定义颜色

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装 @syncfusion/ej2-react-charts 软件包
• 设置 React 项目（Vite 或 Create React App）
• 导入 AccumulationChartComponent
• 注册 CSS 主题
• 通过数据绑定创建第一个饼图
• 了解 AccumulationSeriesCollectionDirective 模式
• 基本系列配置（xName、yName、dataSource）

饼图和圆环图

📄 阅读： references/pie-doughnut-charts.md

• 使用 PieSeries 注入创建基本饼图
• 自定义半径（默认值为 80%，也可设置自定义值）
• 定位饼图中心（centerX、centerY 属性）
• 使用 innerRadius 创建圆环图
• 创建各种半径的饼图（扇区大小不同）
• 使用 startAngle 和 endAngle 创建半饼图
• 从数据源映射颜色和文本
• 设置圆角边框，让扇区外观更现代
• 鼠标悬停时隐藏或显示边框
• 应用图案填充（条纹、圆点、网格）
• 使用 pointClick 事件实现多层下钻
• 使用 pointRender 事件自定义数据点

漏斗图和金字塔图

📄 阅读： references/funnel-pyramid-charts.md

• 使用 FunnelSeries 注入创建漏斗图
• 自定义漏斗尺寸（宽度和高度）
• 配置颈部尺寸（neckWidth、neckHeight）
• 设置各段之间的间距（gapRatio 为 0 到 1）
• 漏斗渲染模式（Standard 或 Trapezoidal）
• 使用 PyramidSeries 注入创建金字塔图
• 金字塔渲染模式（Linear 或 Surface）
• 自定义金字塔尺寸
• 分离效果（explode、explodeOffset、explodeIndex）
• 为漏斗图和金字塔图智能定位数据标签

数据标签

📄 阅读： references/data-labels.md

• 启用数据标签（visible 属性，注入 AccumulationDataLabel）
• 设置标签位置（Inside 与 Outside）
• 旋转数据标签（angle 和 enableRotation）
• 使用智能标签避免重叠（enableSmartLabels）
• 设置标签文本格式（n、p、c 数字格式）
• 使用 HTML 自定义数据标签模板
• 自定义连接线（type、color、width、length、dashArray）
• 从数据源映射文本（name 属性）
• 使用 textRender 事件自定义标签
• 文本换行（textWrap、maxWidth）
• 在标签中显示百分比（textRender 与模板两种方式）

图例配置

📄 阅读： references/legend.md

• 启用图例（注入 AccumulationLegend）
• 设置位置和对齐方式（left、right、top、bottom、center、far、near）
• 反转图例项顺序
• 自定义图例形状（Circle、Rectangle、Triangle 等）
• 配置图例和图例项的尺寸
• 为大量图例项自动分页
• 长标签文本换行（textWrap、maximumLabelWidth）
• 点击图例时切换动画
• 配置和设置图例标题样式
• 使用箭头翻页导航（enablePages false）
• 调整图例项内边距
• 布局选项（horizontal、vertical、使用 maximumColumns 的 auto）
• 使用 HTML 自定义图例模板
• 固定图例项宽度

工具提示自定义

📄 阅读： references/tooltip.md

• 启用工具提示（注入 AccumulationTooltip）
• 自定义工具提示标题
• 格式字符串（${point.x}、${point.y}、${series.name}）
• 从数据源映射工具提示（tooltipMappingName）
• 使用 HTML/React 组件自定义工具提示模板
• 固定工具提示位置（location 属性）
• 设置工具提示样式和外观

数据分组

📄 阅读： references/grouping.md

• 按值阈值分组（groupTo 属性）
• 按数据点数量分组
• 配置分组模式（Value 与 Point）
• 自定义组名和标签
• 自定义组的外观
• 了解何时使用分组以获得更好的可视化效果

注释

📄 阅读： references/annotations.md

• 通过注入 AccumulationAnnotation 添加注释
• 注释内容和 HTML 模板
• 设置注释位置（x、y 坐标）
• 坐标单位（Pixel 与 Point）
• 每个图表添加多个注释
• 动态更新注释

自定义和样式设置

📄 阅读： references/customization.md

• 使用 pointRender 事件自定义数据点
• 自定义配色方案和调色板
• 为每个数据点设置颜色（fill 属性）
• 自定义边框（width、color）
• 为扇区应用图案填充（applyPattern）
• 根据数据值设置数据点专属样式
• 条件样式模式

无障碍功能

📄 阅读： references/accessibility.md

• 符合 WCAG 2.1 标准的功能
• 支持键盘导航（Tab、箭头键）
• 配置 ARIA 属性
• 支持屏幕阅读器和播报
• 兼容高对比度模式
• 高级无障碍配置
• 焦点指示器和可见焦点

空数据点处理

📄 阅读： references/empty-points.md

• 处理 null、undefined 或 NaN 数据
• 空数据点模式（Zero、Drop、Average、Gap）
• 自定义空数据点的外观
• 配置空数据点的填充和边框
• 了解何时使用各种空数据点模式

外观和主题

📄 阅读： references/appearance-theming.md

• 内置主题（Material、Bootstrap、Fluent、Tailwind、Fabric）
• 导入和应用主题
• 为扇区应用渐变填充
• 配置标题和副标题
• 动态数据更新和动画
• 图表尺寸和响应式大小调整

导出和打印

📄 阅读：references/export-print.md

• 使用 Export 模块启用导出功能
• 导出为图像格式（PNG、JPEG）
• 导出为 PDF 和 SVG
• 通过 beforeExport 事件自定义导出
• 打印图表功能
• 导出多个图表
• 导出后的事件处理
• 文件命名规范和最佳实践

API 参考

📄 阅读：references/api-reference.md

• 完整的 AccumulationChartComponent 属性参考
• AccumulationSeriesDirective 属性
• 所有方法（export、print、setAnnotationValue、calculateBounds）
• 所有事件（生命周期、渲染、鼠标、选择、导出）
• 常用模型接口（LegendSettings、TooltipSettings、DataLabel）
• 模块服务和注入要求
• 事件参数接口
• 选择模式参考
• 主题参考
• 完整的 TypeScript 用法示例

快速入门示例

以下是创建基本饼图的最简示例：

import { 
  AccumulationChartComponent, 
  AccumulationSeriesCollectionDirective, 
  AccumulationSeriesDirective,
  Inject,
  AccumulationLegend,
  AccumulationDataLabel,
  AccumulationTooltip,
  PieSeries
} from '@syncfusion/ej2-react-charts';

function App() {
  const data = [
    { x: 'Chrome', y: 61.3, text: 'Chrome: 61.3%' },
    { x: 'Safari', y: 24.6, text: 'Safari: 24.6%' },
    { x: 'Edge', y: 5.0, text: 'Edge: 5.0%' },
    { x: 'Firefox', y: 4.8, text: 'Firefox: 4.8%' },
    { x: 'Others', y: 4.3, text: 'Others: 4.3%' }
  ];

  return (
    <AccumulationChartComponent 
      id='pie-chart'
      title='Browser Market Share'
      legendSettings={{ visible: true }}
      tooltip={{ enable: true }}
      enableSmartLabels={true}
    >
      <Inject services={[
        AccumulationLegend, 
        AccumulationDataLabel, 
        AccumulationTooltip, 
        PieSeries
      ]} />
      <AccumulationSeriesCollectionDirective>
        <AccumulationSeriesDirective
          dataSource={data}
          xName='x'
          yName='y'
          radius='90%'
          dataLabel={{
            visible: true,
            position: 'Outside',
            name: 'text'
          }}
        />
      </AccumulationSeriesCollectionDirective>
    </AccumulationChartComponent>
  );
}

常用模式

模式 1：带图例的圆环图

<AccumulationChartComponent 
  id='doughnut-chart'
  legendSettings={{ visible: true, position: 'Right' }}
>
  <Inject services={[AccumulationLegend, PieSeries]} />
  <AccumulationSeriesCollectionDirective>
    <AccumulationSeriesDirective
      dataSource={data}
      xName='category'
      yName='value'
      innerRadius='40%'  // Creates doughnut hole
      radius='100%'
    />
  </AccumulationSeriesCollectionDirective>
</AccumulationChartComponent>

模式 2：带数据标签的漏斗图

<AccumulationChartComponent id='funnel-chart'>
  <Inject services={[FunnelSeries, AccumulationDataLabel]} />
  <AccumulationSeriesCollectionDirective>
    <AccumulationSeriesDirective
      dataSource={salesData}
      xName='stage'
      yName='count'
      type='Funnel'
      neckWidth='25%'
      neckHeight='5%'
      gapRatio={0.08}
      dataLabel={{ visible: true, position: 'Outside' }}
    />
  </AccumulationSeriesCollectionDirective>
</AccumulationChartComponent>

模式 3：半饼图（仪表样式）

<AccumulationSeriesDirective
  dataSource={data}
  xName='x'
  yName='y'
  startAngle={270}  // Start from bottom
  endAngle={90}     // End at bottom (semi-circle)
  radius='100%'
  innerRadius='40%'
  dataLabel={{ visible: true, position: 'Inside' }}
/>

模式 4：分离式饼图

<AccumulationSeriesDirective
  dataSource={data}
  xName='product'
  yName='sales'
  explode={true}           // Enable click-to-explode
  explodeOffset='10%'      // Distance when exploded
  explodeIndex={2}         // Explode third slice by default
  explodeAll={false}       // Don't explode all at once
/>

API 参考

AccumulationChartComponent 属性

核心属性

属性	类型	默认值	描述
dataSource	Object[] | DataManager	''	图表的数据源
series	AccumulationSeriesModel[]	-	系列配置集合
title	string	null	图表主标题
subTitle	string	null	显示在主标题下方的副标题
width	string	null	图表宽度（'100px'、'100%'）
height	string	null	图表高度（'100px'、'100%'）
theme	AccumulationTheme	'Material'	视觉主题（Material、Bootstrap5、Fluent、Tailwind 等）
background	string	null	背景颜色（十六进制或 rgba）
backgroundImage	string	null	背景图像 URL

功能属性

属性	类型	默认值	描述
enableSmartLabels	boolean	true	通过智能定位避免标签重叠
enableAnimation	boolean	true	启用图表渲染动画
enableBorderOnMouseMove	boolean	true	鼠标悬停时显示边框
enableExport	boolean	true	启用导出功能（JPEG、PNG、SVG、PDF）
useGroupingSeparator	boolean	false	数字使用千位分隔符
enablePersistence	boolean	false	在页面重新加载后保留组件状态
enableRtl	boolean	false	启用从右到左的渲染
enableHtmlSanitizer	boolean	false	清理不受信任的 HTML 值

交互属性

属性	类型	默认值	描述
selectionMode	AccumulationSelectionMode	'None'	数据点选择模式（'None'、'Point'）
selectionPattern	SelectionPattern	'None'	已选数据点的图案（棋盘、圆点等）
highlightMode	AccumulationHighlightMode	'None'	数据点高亮模式（'None'、'Point'）
highlightPattern	SelectionPattern	'None'	高亮数据点的图案
highlightColor	string	''	高亮数据点的颜色
isMultiSelect	boolean	false	允许选择多个数据点
selectedDataIndexes	IndexesModel[]	[]	初始选中的数据点索引

布局属性

属性	类型	默认值	描述
center	PieCenterModel	{x: '50%', y: '50%'}	饼图的中心位置
margin	MarginModel	-	图表边距（左、右、上、下）
border	BorderModel	-	图表边框（颜色、宽度）
legendSettings	LegendSettingsModel	-	图例配置
tooltip	TooltipSettingsModel	-	工具提示配置
annotations	AccumulationAnnotationSettingsModel[]	-	图表注释
centerLabel	CenterLabelModel	-	图表中心的标签

无障碍属性

属性	类型	默认值	描述
accessibility	AccessibilityModel	-	屏幕阅读器的无障碍配置
focusBorderColor	string	null	自定义焦点边框颜色
focusBorderWidth	number	1.5	焦点边框宽度（像素）
focusBorderMargin	number	0	焦点边框边距（像素）
locale	string	'en-US'	本地化区域设置字符串

AccumulationSeriesDirective 属性

属性	类型	默认值	描述
type	string	'Pie'	图表类型（'Pie'、'Funnel'、'Pyramid'）
dataSource	Object[]	-	系列的数据数组
xName	string	-	类别/标签值的属性名称
yName	string	-	数值的属性名称
radius	string	'80%'	饼图/圆环图的外半径
innerRadius	string	'0%'	内半径（圆环图空洞）
startAngle	number	0	起始角度（0-360 度）
endAngle	number	360	结束角度（0-360 度）
explode	boolean	false	启用单击分离扇区功能
explodeAll	boolean	false	初始时分离所有扇区
explodeIndex	number	-	默认分离的扇区索引
explodeOffset	string	'30%'	扇区分离时的距离
neckWidth	string	'20%'	漏斗颈部宽度
neckHeight	string	'20%'	漏斗颈部高度
gapRatio	number	0	漏斗/金字塔分段之间的间隙（0-1）
width	string	'80%'	漏斗/金字塔宽度
height	string	'80%'	漏斗/金字塔高度
groupTo	string	-	分组的值/数量阈值
groupMode	string	'Value'	分组模式（'Value'、'Point'）
pointColorMapping	string	-	数据点颜色的属性名称
borderRadius	number	0	圆角扇区的圆角半径
applyPattern	boolean	false	为扇区应用图案填充

方法

方法	参数	描述
export()	type: ExportType, fileName: string	导出图表（JPEG、PNG、SVG、PDF）
print()	id?: string[] | string | Element	打印图表
calculateBounds()	-	计算图表边界
setAnnotationValue()	annotationIndex: number, content: string	动态更新注释

事件

事件	参数类型	描述
load	IAccLoadedEventArgs	图表加载前
loaded	IAccLoadedEventArgs	图表加载后
seriesRender	IAccSeriesRenderEventArgs	系列渲染前
pointRender	IAccPointRenderEventArgs	每个数据点渲染前
textRender	IAccTextRenderEventArgs	数据标签渲染前
legendRender	ILegendRenderEventArgs	图例渲染前
legendClick	IAccLegendClickEventArgs	点击图例项时
annotationRender	IAnnotationRenderEventArgs	注释渲染前
tooltipRender	ITooltipRenderEventArgs	工具提示渲染前
pointClick	IPointEventArgs	点击数据点时
pointMove	IPointEventArgs	鼠标移到数据点上时
chartMouseClick	IMouseEventArgs	点击图表时
chartMouseDown	IMouseEventArgs	鼠标按下时
chartMouseUp	IMouseEventArgs	鼠标抬起时
chartMouseMove	IMouseEventArgs	鼠标在图表上移动时
chartMouseLeave	IMouseEventArgs	鼠标离开图表时
chartDoubleClick	IMouseEventArgs	双击图表时
animationComplete	IAccAnimationCompleteEventArgs	动画完成后
selectionComplete	IAccSelectionCompleteEventArgs	选择完成后
resized	IAccResizeEventArgs	窗口调整大小后
beforeResize	IAccBeforeResizeEventArgs	窗口调整大小前
beforePrint	IPrintEventArgs	开始打印前
beforeExport	IExportEventArgs	开始导出前
afterExport	IAfterExportEventArgs	导出完成后

关键属性摘要

属性	用途	示例值
type	图表类型	'Pie'、'Funnel'、'Pyramid'
radius	外部尺寸	'90%'、'100%'
innerRadius	环形图孔洞	'0%'（饼图）、'40%'（环形图）
startAngle / endAngle	扇区范围	0 至 360
explode	启用分离效果	true、false
neckWidth / neckHeight	漏斗颈部	'25%'、'5%'
gapRatio	分段间距	0 至 1
enableSmartLabels	智能定位	true、false

常见用例

1. 市场份额分析： 使用饼图/环形图展示竞争分布
2. 销售漏斗： 使用漏斗图跟踪各阶段的转化情况
3. 预算分配： 使用饼图展示支出类别
4. 调查结果： 使用环形图展示百分比明细
5. 人口统计： 使用金字塔图展示年龄分布
6. 流程效率： 使用漏斗图展示流失率
7. 投资组合分布： 使用饼图展示资产分配
8. 网站流量来源： 使用环形图展示引荐数据
9. 项目时间分配： 使用饼图展示资源分布
10. 客户细分： 使用多个饼图进行群组分析

提示和最佳实践

• 处理大量小扇区时使用智能标签，以避免重叠
• 将较小的值（< 5%）归入“其他”类别，以便清晰呈现
• 显示中心关键指标时优先使用环形图而非饼图
• 使用漏斗模式 'Trapezoidal' 进行更清晰的阶段比较
• 启用工具提示，以便在不让标签显得杂乱的情况下展示详细信息
• 选择对比度足够的颜色
• 考虑无障碍性，提供文本替代内容和键盘导航
• 谨慎使用分离效果来突出重要数据点
• 对于包含 8 个或更多数据点的图表，将 enableSmartLabels 设为 true
• 与应用中的其他图表统一应用主题

相关组件

构建综合仪表板时，可将 Accumulation Charts 与以下组件结合使用：

• 用于趋势分析的折线图/面积图
• 用于比较的条形图/柱形图
• 用于项目时间线的甘特图
• 用于分层比例数据的树图