关于 syncfusion-javascript-accumulation-chart
该 Skill 为 Syncfusion EJ2 提供累积图表的 TypeScript 和 JavaScript 实现指导,涵盖饼图、圆环图、漏斗图与金字塔图。内容还包括数据绑定、交互、样式、无障碍支持及性能验证,适合开发这些图表的应用开发者。
主要功能
- 01实现饼图、圆环图、漏斗图和金字塔图
- 02配置图例、数据标签与工具提示
- 03处理本地或远程数据及动态更新
- 04设置选择、高亮和注释
- 05涵盖主题、无障碍和性能验证
适用场景
- 01展示分类数据的整体占比
- 02呈现有序的流程阶段或转化过程
- 03为图表添加数据标签、图例和交互
- 04在 TypeScript 或 JavaScript 应用中实现累积图表
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ syncfusion/ javascript-ui-controls-skills --skill syncfusion-javascript-accumulation-chart安装后在 Claude Code 中输入/syncfusion-javascript-accumulation-chart确认已加载。
包含的文件
除 SKILL.md 外,安装时一起下载的参考资料和脚本。
references/accessibility-and-advanced.mdannotations-and-features.mdapi-reference.mdAPI-Refernce_JavaScript.mdAPI-Refernce_TypeScript.mdchart-types.mdcustomization-and-styling.mddata-labels.mdgetting-started.mdlegend-configuration.mdtooltips-and-selection.md详细介绍
在 Syncfusion TypeScript 和 JavaScript 中实现累积图表
Syncfusion EJ2 累积图表通过饼图、圆环图、漏斗图和金字塔图来可视化分类值。
此技能涵盖与框架无关的实现方式,包括:
- 使用 npm 和 ES 模块的 TypeScript。
- 使用 npm 和 ES 模块的 JavaScript。
- 使用完整全局 EJ2 捆绑包的 JavaScript。
- 饼图和圆环图可视化。
- 漏斗图和金字塔图可视化。
- 图例、数据标签、工具提示和注释。
- 选择和高亮。
- 本地和远程数据。
- 动态更新。
- 内部主题。
- 无障碍访问、性能、验证和清理。
对于此处的累积图表示例,无需单独的 Syncfusion 主题样式表。通过图表级 theme 属性应用视觉主题。
平台支持
TypeScript
当应用需要以下功能时,请使用 TypeScript:
- 类型定义和 IDE 支持。
- npm 包管理。
- ES 模块导入。
- 显式注入功能模块。
- 编译时验证。
- 兼容 TypeScript 的构建流程。
安装:
npm install @syncfusion/ej2-charts
导入:
import {
AccumulationChart
} from '@syncfusion/ej2-charts';
可选功能需要在构建图表之前导入并注入相应模块。
使用 npm 和 ES 模块的 JavaScript
当应用使用以下技术时,请使用基于模块的 JavaScript:
- npm。
- ES 模块导入。
- 打包工具。
- 显式调用
AccumulationChart.Inject(...)。
安装:
npm install @syncfusion/ej2-charts
导入:
import {
AccumulationChart
} from '@syncfusion/ej2-charts';
全局 JavaScript
当应用使用以下技术时,请使用全局 JavaScript:
- 带版本号的 EJ2 全局捆绑包。
- 传统 HTML 和 JavaScript 文件。
ej.charts.AccumulationChart构造函数。- 无需 TypeScript 编译。
使用带版本号的完整捆绑包:
<script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script>
使用完整全局 EJ2 捆绑包时,不要调用 AccumulationChart.Inject(...)。
浏览器兼容性必须符合所安装 EJ2 版本的受支持浏览器矩阵。
何时使用此技能
当任务需要以下功能时,请使用此技能:
- 创建饼图。
- 创建圆环图。
- 创建漏斗图。
- 创建金字塔图。
- 显示分类值对整体的贡献。
- 显示比例构成。
- 显示按顺序排列的漏斗阶段。
- 显示分层的金字塔分段。
- 添加图例。
- 添加数据标签。
- 添加工具提示。
- 添加圆环图中心标签。
- 分离数据点。
- 对较小的数据点进行分组。
- 处理空数据点。
- 启用选择或高亮。
- 添加注释。
- 应用颜色、渐变或调色板。
- 绑定本地或远程数据。
- 动态更新数据。
- 支持无障碍解读。
- 验证性能并进行清理。
当其他可视化方式能更准确地传达数据时,请使用其他图表:
- 使用条形图或柱形图来精确比较数值相近的数据。
- 使用折线图展示随时间变化的趋势。
- 仅当阶段顺序有意义时,才使用漏斗图。
- 仅当与整体的关系有意义时,才使用饼图或圆环图。
累积图表类型
饼图
使用饼图展示分类值对整体的贡献。
type:
'Pie'
圆环图
圆环图使用 innerRadius 非零的饼图系列。
type:
'Pie',
innerRadius:
'40%'
除非已安装的 API 明确引入该系列值,否则不要使用:
type:
'Doughnut'
漏斗图
使用漏斗图展示有序阶段、流程管道或转化流程。
type:
'Funnel'
金字塔图
使用金字塔图展示比例分段或分层分段。
type:
'Pyramid'
导航指南
选择与任务相符的参考资料。
入门
📄 阅读: references/getting-started.md
在以下情况下使用此参考资料:
- 安装软件包。
- 导入 TypeScript 模块。
- 注入模块。
- 配置 JavaScript 捆绑包。
- 创建并验证宿主元素。
- 创建基本饼图。
- 配置内部主题。
- 查看完整的 TypeScript 和 JavaScript 示例。
- 验证运行时。
- 排查基本问题。
图表类型和选择
📄 阅读: references/chart-types.md
请参考此文档了解:
- 饼图。
- 圆环图。
- 漏斗图。
- 金字塔图。
- 特定系列的模块注入。
- 半径和内半径。
- 漏斗颈部尺寸。
- 金字塔模式。
- 间隙比例。
- 选择合适的图表类型。
图例配置
📄 阅读: references/legend-configuration.md
请参考此文档了解:
- 图例可见性。
- 图例位置。
- 对齐方式。
- 图例标题。
- 文本样式。
- 切换数据点。
- 响应式图例行为。
- 图例交互。
- 图例无障碍功能。
数据标签
📄 阅读: references/data-labels.md
请参考此文档了解:
- 启用数据标签。
- 内部和外部标签。
- 标签字段映射。
- 数值和百分比标签。
- 连接线。
- 智能标签。
- 文本截断和换行。
- 标签模板。
- 防止重叠。
工具提示和选择
📄 阅读: references/tooltips-and-selection.md
请参考此文档了解:
- 累积图表工具提示。
- 工具提示格式。
- 工具提示模板。
- 数据点选择。
- 支持时的多选。
- 选择图案。
- 高亮。
- 交互事件。
- 工具提示之外的持久详情。
注释和功能
📄 阅读: references/annotations-and-features.md
请参考此文档了解:
- 注释。
- 圆环图中心标签。
- 扇出数据点。
- 数据点分组。
- 空数据点处理。
- 数据点颜色映射。
- 渐变填充。
- 起始角度和结束角度。
- 饼图中心定位。
- 漏斗颈部配置。
- 金字塔模式。
自定义和样式
📄 阅读: references/customization-and-styling.md
请参考此文档了解:
- 内置主题。
- 调色板。
- 系列填充。
- 边框。
- 不透明度。
- 背景。
- 标题和副标题。
- 应用自有的 CSS。
- 响应式尺寸。
- 已验证的打印和导出功能。
无障碍功能和高级特性
📄 阅读: references/accessibility-and-advanced.md
请参考此文档了解:
- 语义描述。
- 持久文本替代内容。
- 语义数据表。
- 无障碍配置。
- 系列描述。
- 焦点可见性。
- 键盘和屏幕阅读器测试。
- 动态更新。
- 动画。
- 性能。
- 远程数据。
- 清理。
- 故障排除。
未经验证其 Accumulation Chart 专用模块和模型,请勿照搬普通笛卡尔图表的 API。
功能模块参考
仅导入和注入实现所需的模块。
Pie and Doughnut -> PieSeries
Funnel -> FunnelSeries
Pyramid -> PyramidSeries
Data labels -> AccumulationDataLabel
Legend -> AccumulationLegend
Tooltip -> AccumulationTooltip
Selection -> AccumulationSelection
Highlight -> AccumulationHighlight
Annotations -> AccumulationAnnotation
Print -> Validated Accumulation Chart print module
Image export -> Validated Accumulation Chart image-export module
PDF export -> Validated Accumulation Chart PDF-export module
请根据已安装的 @syncfusion/ej2-charts 声明验证可选模块名称。
TypeScript 模块注入
包含标签、图例和工具提示的饼图需要:
import {
AccumulationChart,
AccumulationDataLabel,
AccumulationLegend,
AccumulationTooltip,
PieSeries
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
PieSeries,
AccumulationDataLabel,
AccumulationLegend,
AccumulationTooltip
);
最精简的饼图需要:
import {
AccumulationChart,
PieSeries
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
PieSeries
);
漏斗图需要:
import {
AccumulationChart,
FunnelSeries
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
FunnelSeries
);
金字塔图需要:
import {
AccumulationChart,
PyramidSeries
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
PyramidSeries
);
确保导入和注入保持同步。
请勿使用普通图表工具提示模块:
Tooltip
请使用:
AccumulationTooltip
宿主和尺寸
使用一致的宿主:
<div id="accumulation-chart"></div>
提供可测量的尺寸:
.chart-wrapper {
width: 100%;
max-width: 1000px;
margin: 0 auto;
}
#accumulation-chart {
width: 100%;
min-height: 500px;
}
验证宿主:
const host:
HTMLElement | null =
document.getElementById(
'accumulation-chart'
);
if (!host) {
throw new Error(
'The Accumulation Chart host "#accumulation-chart" was not found.'
);
}
优先使用显式构造和挂载:
const chart:
AccumulationChart =
new AccumulationChart({
// Configuration
});
chart.appendTo(
host
);
数据模型和验证
使用类型化模型:
interface CategoryShare {
category: string;
value: number;
label: string;
}
定义有意义的数据:
const chartData:
CategoryShare[] = [
{
category:
'January',
value:
22,
label:
'January: 22%'
},
{
category:
'February',
value:
24,
label:
'February: 24%'
},
{
category:
'March',
value:
26,
label:
'March: 26%'
},
{
category:
'April',
value:
28,
label:
'April: 28%'
}
];
渲染前进行验证:
const validateCategoryShares = (
data:
CategoryShare[],
requirePercentageTotal:
boolean
): void => {
if (
data.length ===
0
) {
throw new Error(
'The Accumulation Chart requires at least one data point.'
);
}
const categories:
Set<string> =
new Set<string>();
let positiveValueFound:
boolean =
false;
let total:
number =
0;
data.forEach(
(
item:
CategoryShare,
index:
number
): void => {
const category:
string =
item.category.trim();
if (!category) {
throw new Error(
'Data point ' +
index +
' requires a category.'
);
}
if (
categories.has(
category
)
) {
throw new Error(
'Duplicate category: ' +
category
);
}
if (
!Number.isFinite(
item.value
) ||
item.value < 0
) {
throw new Error(
'Data point "' +
category +
'" requires a finite nonnegative value.'
);
}
if (
item.value > 0
) {
positiveValueFound =
true;
}
if (
!item.label.trim()
) {
throw new Error(
'Data point "' +
category +
'" requires a label.'
);
}
total +=
item.value;
categories.add(
category
);
}
);
if (
!positiveValueFound
) {
throw new Error(
'At least one data point must have a positive value.'
);
}
if (
requirePercentageTotal &&
Math.abs(
total -
100
) >
0.0001
) {
throw new Error(
'Percentage data must total 100.'
);
}
};
调用验证:
validateCategoryShares(
chartData,
true
);
当图表显示原始数值而非百分比时,不要要求总和为 100。
快速入门示例
TypeScript
import {
AccumulationChart,
AccumulationDataLabel,
AccumulationLegend,
AccumulationTooltip,
PieSeries
} from '@syncfusion/ej2-charts';
interface CategoryShare {
category: string;
value: number;
label: string;
}
AccumulationChart.Inject(
PieSeries,
AccumulationDataLabel,
AccumulationLegend,
AccumulationTooltip
);
const chartData:
CategoryShare[] = [
{
category:
'January',
value:
22,
label:
'January: 22%'
},
{
category:
'February',
value:
24,
label:
'February: 24%'
},
{
category:
'March',
value:
26,
label:
'March: 26%'
},
{
category:
'April',
value:
28,
label:
'April: 28%'
}
];
const host:
HTMLElement | null =
document.getElementById(
'accumulation-chart'
);
if (!host) {
throw new Error(
'The Accumulation Chart host was not found.'
);
}
const chart:
AccumulationChart =
new AccumulationChart({
width:
'100%',
height:
'500px',
theme:
'Fluent2',
title:
'Monthly Distribution',
series: [
{
dataSource:
chartData,
xName:
'category',
yName:
'value',
type:
'Pie',
name:
'Distribution',
dataLabel: {
visible:
true,
position:
'Outside',
name:
'label'
}
}
],
tooltip: {
enable:
true
},
legendSettings: {
visible:
true,
position:
'Right'
}
});
chart.appendTo(
host
);
对于此精简的 Accumulation Chart 示例,无需仅为此目的单独引入 Syncfusion 主题样式表。
使用完整包的 JavaScript
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta
name="viewport"
content="width=device-width, initial-scale=1.0"
>
<title>EJ2 Accumulation Chart</title>
<script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script>
<style>
#accumulation-chart {
width: 100%;
min-height: 500px;
}
</style>
</head>
<body>
<div id="accumulation-chart"></div>
<script>
if (
typeof window.ej ===
'undefined' ||
!window.ej.charts ||
!window.ej.charts.AccumulationChart
) {
throw new Error(
'The EJ2 Accumulation Chart global bundle was not loaded.'
);
}
var chartData = [
{
category:
'January',
value:
22,
label:
'January: 22%'
},
{
category:
'February',
value:
24,
label:
'February: 24%'
},
{
category:
'March',
value:
26,
label:
'March: 26%'
},
{
category:
'April',
value:
28,
label:
'April: 28%'
}
];
var chart =
new ej.charts.AccumulationChart({
width:
'100%',
height:
'500px',
theme:
'Fluent2',
title:
'Monthly Distribution',
series: [
{
dataSource:
chartData,
xName:
'category',
yName:
'value',
type:
'Pie',
name:
'Distribution',
dataLabel: {
visible:
true,
position:
'Outside',
name:
'label'
}
}
],
tooltip: {
enable:
true
},
legendSettings: {
visible:
true,
position:
'Right'
}
});
chart.appendTo(
'#accumulation-chart'
);
</script>
</body>
</html>
使用完整全局包时,请勿调用 AccumulationChart.Inject(...)。
常见模式
带图例的基本饼图
const chart:
AccumulationChart =
new AccumulationChart({
series: [
{
dataSource:
chartData,
xName:
'category',
yName:
'value',
type:
'Pie'
}
],
legendSettings: {
visible:
true,
position:
'Right'
}
});
chart.appendTo(
'#accumulation-chart'
);
带中心标签的圆环图
使用带有 innerRadius 的饼图系列:
const chart:
AccumulationChart =
new AccumulationChart({
series: [
{
dataSource:
chartData,
xName:
'category',
yName:
'value',
type:
'Pie',
innerRadius:
'40%'
}
],
centerLabel: {
text:
'Sales',
hoverTextFormat:
'${point.x}: ${point.y}'
}
});
chart.appendTo(
'#accumulation-chart'
);
不要使用:
type:
'Doughnut'
中心标签适用于饼图或圆环图样式的可视化。
漏斗图
import {
AccumulationChart,
AccumulationDataLabel,
FunnelSeries
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
FunnelSeries,
AccumulationDataLabel
);
interface FunnelStage {
stage: string;
users: number;
label: string;
}
const stageData:
FunnelStage[] = [
{
stage:
'Visited',
users:
1000,
label:
'Visited: 1,000'
},
{
stage:
'Downloaded',
users:
760,
label:
'Downloaded: 760'
},
{
stage:
'Subscribed',
users:
420,
label:
'Subscribed: 420'
},
{
stage:
'Renewed',
users:
190,
label:
'Renewed: 190'
}
];
const chart:
AccumulationChart =
new AccumulationChart({
series: [
{
dataSource:
stageData,
xName:
'stage',
yName:
'users',
type:
'Funnel',
width:
'70%',
height:
'80%',
neckWidth:
'15%',
neckHeight:
'5%',
gapRatio:
0.08,
dataLabel: {
visible:
true,
position:
'Inside',
name:
'label'
}
}
]
});
chart.appendTo(
'#accumulation-chart'
);
漏斗图不会自动计算转化率。需要时,请在应用代码中计算转化率。
金字塔图
import {
AccumulationChart,
AccumulationDataLabel,
PyramidSeries
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
PyramidSeries,
AccumulationDataLabel
);
const chart:
AccumulationChart =
new AccumulationChart({
series: [
{
dataSource:
chartData,
xName:
'category',
yName:
'value',
type:
'Pyramid',
pyramidMode:
'Linear',
gapRatio:
0.05,
dataLabel: {
visible:
true,
position:
'Inside',
name:
'label'
}
}
]
});
chart.appendTo(
'#accumulation-chart'
);
使用经过验证的金字塔模式,例如:
Linear
Surface
不要添加:
reverse:
true
除非已安装的金字塔模型明确支持该属性。
数据标签
导入并注入:
import {
AccumulationDataLabel
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
AccumulationDataLabel
);
在系列内部配置标签:
dataLabel: {
visible:
true,
position:
'Outside',
name:
'label'
}
不要在图表根级别配置累积图数据标签。
仅当应用中的值表示百分比,或百分比已正确计算时,才使用百分比标签。
工具提示
导入并注入:
import {
AccumulationTooltip
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
AccumulationTooltip
);
启用:
tooltip: {
enable:
true,
format:
'${point.x}: ${point.y}'
}
仅在受支持且确有必要时,才可使用可执行 HTML:
format:
'${point.x}: <b>${point.y}</b>'
不要使用经过编码的 HTML:
format:
'${point.x}: <b>${point.y}</b>'
除非数值表示百分比,否则不要附加 %。
选择
导入并注入:
import {
AccumulationSelection
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
AccumulationSelection
);
配置经过已安装的累积图模型验证的选择模式。
selectionMode:
'Point'
记录选择模式和多选支持情况之前,请先验证。
不要假设普通笛卡尔图表系列的选择行为完全适用。
高亮
导入并注入:
import {
AccumulationHighlight
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
AccumulationHighlight
);
仅配置已安装的软件包支持的模式和样式。
如果启用高亮会降低对比度或可读性,不要仅为装饰而启用。
注释
导入并注入:
import {
AccumulationAnnotation
} from '@syncfusion/ej2-charts';
AccumulationChart.Inject(
AccumulationAnnotation
);
注释和圆环图中心标签是不同的功能。
使用注释放置相对于图表定位的上下文 HTML 内容。
使用 centerLabel 显示圆环图中心的内容。
不要将注释内容作为必要信息的唯一来源。
数据点颜色
需要时,根据数据映射数据点颜色:
interface CategoryShare {
category: string;
value: number;
color: string;
}
series: [
{
dataSource:
chartData,
xName:
'category',
yName:
'value',
pointColorMapping:
'color',
type:
'Pie'
}
]
不要将普通图表的 marker 属性列为适用于所有累积图系列的选项。
饼图、漏斗图和金字塔图的数据点渲染为分段,而不是笛卡尔标记。
分离数据点
启用数据点分离:
series: [
{
type:
'Pie',
explode:
true,
explodeIndex:
0,
explodeOffset:
'10%'
}
]
谨慎使用分离效果。过多的分离分段会让整体更难理解。
漏斗图和金字塔图间隙验证
验证 gapRatio:
const validateGapRatio = (
value:
number
): void => {
if (
!Number.isFinite(
value
) ||
value < 0 ||
value > 1
) {
throw new Error(
'The gap ratio must be between 0 and 1.'
);
}
};
内置主题和应用 CSS
应用内置图表主题:
theme:
'Fluent2'
单独的 Syncfusion 主题包或样式表并非专注于累积图的示例所必需。
使用应用自有 CSS 设置:
- 宿主尺寸。
- 页面背景。
- 卡片布局。
- 文本摘要。
- 数据表。
- 外部按钮。
- 响应式间距。
示例:
.chart-card {
width: 100%;
max-width: 1000px;
margin: 0 auto;
padding: 20px;
background: #ffffff;
border: 1px solid #cbd5e1;
border-radius: 12px;
}
#accumulation-chart {
width: 100%;
min-height: 500px;
}
请根据已安装的累积图主题模型验证所选主题。
动态更新数据
替换系列数据源:
chart.series[0]
.dataSource =
updatedData;
chart.dataBind();
更新标题:
chart.title =
'Updated Distribution';
chart.dataBind();
批量更改:
chart.title =
'Updated Distribution';
chart.series[0]
.dataSource =
updatedData;
chart.dataBind();
普通属性更改使用 dataBind()。
以下情况使用 refresh():
- 宿主尺寸发生变化。
- 隐藏的父元素变为可见。
- 图表类型发生重大变化。
- 需要完整重新计算布局。
无障碍指南
通过以下方式支持无障碍实现:
- 语义化标题。
- 简洁的图表说明。
- 持续显示的文本摘要。
- 语义化数据表。
- 有意义的类别标签。
- 足够的对比度。
- 外部控件具有可见的焦点状态。
- 键盘和屏幕阅读器测试。
- 浏览器缩放和响应式重排测试。
- 将工具提示作为补充内容。
- 提供不只依靠颜色传达信息的方式。
不要声称自动符合 WCAG。
不要仅依赖:
- 分段颜色。
- 分段角度。
- 切片面积。
- 漏斗宽度。
- 金字塔位置。
- 悬停工具提示。
提供精确数值的数据表:
<table>
<caption>
Category distribution
</caption>
<thead>
<tr>
<th scope="col">Category</th>
<th scope="col">Value</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">January</th>
<td>22%</td>
</tr>
</tbody>
</table>
配置高级无障碍属性之前,请根据已安装的软件包验证图表级和系列级的无障碍模型。
性能与清理
- 在渲染前验证数据。
- 限制类别数量。
- 适当时将较小的数据点分组。
- 保持工具提示模板简洁。
- 保持数据标签模板简洁。
- 避免不必要的动画。
- 有意处理空值和零值。
- 批量更新。
- 完成相关更改后,仅调用一次
dataBind()。 - 仅使用
refresh()重新计算布局。 - 移除应用拥有的监听器。
- 清除计时器。
- 取消待处理的远程请求。
- 移除动态宿主时销毁图表。
chart.destroy();
运行时验证清单
✅ @syncfusion/ej2-charts is installed.
✅ No external theme package is required solely for AccumulationChart.
✅ A supported built-in theme is configured through theme.
✅ AccumulationChart is imported.
✅ PieSeries is injected for Pie and Doughnut.
✅ FunnelSeries is injected for Funnel.
✅ PyramidSeries is injected for Pyramid.
✅ AccumulationDataLabel is injected when labels are visible.
✅ AccumulationLegend is injected when the legend is visible.
✅ AccumulationTooltip is injected when tooltips are enabled.
✅ AccumulationSelection is injected when selection is enabled.
✅ AccumulationHighlight is injected