syncfusion-blazor-accumulation-chart

实现 Syncfusion Blazor 累积图表

NuGet： Syncfusion.Blazor.Charts + Syncfusion.Blazor.Themes
命名空间： Syncfusion.Blazor.Charts

本指南全面介绍如何实现 Syncfusion Blazor 累积图表组件，以创建交互式饼图、圆环图、漏斗图和金字塔图，在 Blazor 应用程序中可视化比例数据和层级数据。

何时使用此技能

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

• 创建饼图，展示比例数据分布
• 构建圆环图，添加中心标签或多个系列
• 实现多个圆环图（嵌套同心圆环），比较共享类别中的相关指标
• 实现漏斗图，展示分阶段数据（销售渠道、转化率）
• 创建金字塔图，可视化层级数据
• 显示百分比分布和部分与整体的关系
• 可视化市场份额、调查结果或类别比例
• 通过交互式切片和图例展示组成数据
• 添加数据标签，并设置智能定位和连接线
• 为圆环图实现中心标签，显示动态内容
• 使用渐变、主题和注释自定义外观
• 对较小切片进行分组，提升可读性
• 通过工具提示、选择和事件处理用户交互
• 创建可访问图表，支持 ARIA 和键盘导航

组件概述

Syncfusion Blazor 累积图表组件专用于展示比例数据的圆形和三角形可视化：

• **4 种图表类型：**饼图、圆环图、漏斗图、金字塔图
• **数据标签：**智能定位、连接线、模板、文本换行
• **图例：**可自定义位置、分页、点击行为
• **工具提示：**格式化显示、自定义模板
• **中心标签：**圆环图专属功能，支持动态内容
• **多个圆环图：**嵌套同心圆环，使用 MappingKey 对图例进行分组
• **分组：**将较小切片合并到“其他”类别
• **自定义：**渐变、注释、主题、颜色、边框
• **交互性：**选择、分离、悬停效果、动画
• **无障碍访问：**符合 WCAG 标准，支持 ARIA 和键盘导航
• **导出：**支持打印和导出图像

文档与导航指南

入门

📄 阅读： references/getting-started.md

在以下情况下使用：

• 设置新的 Blazor 累积图表项目
• 安装 NuGet 包和依赖项
• 创建第一个饼图或圆环图
• 了解基本组件结构
• 使用 Visual Studio、VS Code 或 .NET CLI
• 将数据绑定到累积图表

涵盖主题：

• 安装前提条件和系统要求
• NuGet 包安装（Syncfusion.Blazor.Charts）
• 服务注册和命名空间导入
• 主题和脚本引用
• 基本的 SfAccumulationChart 实现
• 数据源配置（XName、YName 属性）
• 添加标题、数据标签、工具提示和图例
• 运行应用程序

---

图表类型

📄 阅读： references/chart-types.md

在以下情况下使用：

• 为数据选择合适的图表类型
• 实现饼图（默认类型）
• 创建带内半径的圆环图
• 构建漏斗图以展示转化情况
• 设计用于层级数据的金字塔图
• 了解特定类型的属性
• 设置同心（嵌套）多环圆环图布局

涵盖主题：

• **饼图：**默认圆形可视化，适用场景
• **圆环图：**内半径配置、中心内容区域、多个圆环图概述
• **漏斗图：**颈部尺寸、宽高比、数据流
• **金字塔图：**线性模式与表面模式、底部定位
• 类型属性配置
• 视觉差异和使用场景
• 每种类型的代码示例

多重环形图

📄 阅读： references/multiple-doughnut.md

适用于：

• 在单个图表中绘制两个或更多同心环形
• 跨共享类别比较相关指标（例如，销售额与利润）
• 使用 MappingKey 对多个系列的图例项进行分组
• 为每个系列调整 Radius/InnerRadius，创建整洁的嵌套布局
• 为多环图配置工具提示、数据标签和动画
• 排查环形重叠、图例项重复或标签冲突问题

涵盖主题：

• 嵌套环形的工作方式： 外环与内盘布局
• 必需属性： Type、Radius、InnerRadius、MappingKey
• 使用 MappingKey 对图例进行分组： 合并重复的图例项
• 按系列自定义： 颜色、边框、工具提示、标签
• 三个或更多环形： 缩放指南与间距
• 嵌套环形的工具提示和数据标签技巧
• 按系列禁用动画
• 故障排查表： 常见问题与解决方法
• 完整的生产环境示例

---

数据标签

📄 阅读： references/data-label.md

适用于：

• 启用并自定义数据标签
• 将标签放置在扇区内或外
• 实现智能标签以避免碰撞
• 添加从标签指向扇区的连接线
• 自定义标签文本、格式和模板
• 处理文本换行和溢出
• 使用自定义数据字段作为标签文本

涵盖主题：

• 使用 Visible 属性启用标签
• 位置选项（Inside、Outside）
• 使用 MaxWidth 控制文本换行
• 智能标签定位
• 连接线自定义（类型、长度、颜色、宽度）
• 从数据源字段映射文本
• 格式模式（数字/百分比/货币：N1、P1、C1）
• 使用 HTML 和上下文值自定义模板
• 字体样式、边框和背景

---

图例

📄 阅读： references/legend.md

适用于：

• 为累积图表添加图例
• 设置图例位置（顶部、底部、左侧、右侧）
• 自定义图例外观和行为
• 为包含大量数据点的图例实现分页
• 创建自定义图例模板
• 处理图例点击事件

涵盖主题：

• 使用 Visible 属性启用图例
• 位置和对齐选项
• 自定义图例形状
• 文本样式和截断
• 点击图例时切换可见性的行为
• 图例分页配置
• 图例项的自定义模板
• 点击和悬停事件

---

工具提示

📄 阅读： references/tooltip.md

适用于：

• 启用悬停工具提示
• 设置工具提示内容格式
• 创建自定义工具提示模板
• 设置工具提示样式
• 配置工具提示行为和动画

涵盖主题：

• 用于启用工具提示的 Enable 属性
• 用于显示值的格式字符串
• 自定义标题
• 使用 HTML 的自定义模板
• 边框、填充和字体样式
• 动画设置
• 共享工具提示（如适用）

---

中心标签

📄 阅读： references/center-label.md

适用于：

• 在环形图中心添加文本
• 显示静态或动态中心内容
• 自定义中心标签外观
• 在中心显示聚合数据
• 实现基于悬停的中心文本更新

涵盖主题：

• 中心标签的 Text 属性
• TextStyle 自定义（字体、大小、颜色）
• 使用模板显示动态文本
• 使用事件更新基于悬停的文本
• 控制中心标签的可见性
• 使用场景和最佳实践

---

自定义与样式

📄 阅读： references/customization-styling.md

适用于以下场景：

• 为扇区应用渐变填充
• 将较小的扇区归为“其他”
• 添加注释（文本、形状、图像）
• 处理数据中的空点
• 自定义主题和调色板
• 设置边框样式和圆角
• 实现响应式布局
• 在移动设备上使用自适应设计

涵盖主题：

• 渐变： 扇区的径向和线性填充
• 分组： 使用 GroupTo 和 GroupMode 合并较小的值
• 注释： 带定位的文本、形状和图像注释
• 空点： 模式选项（Zero、Drop、Average、Gap）
• 主题： 内置主题和自定义主题应用
• 颜色： 自定义调色板和单个数据点的颜色
• 边框： 宽度、颜色和虚线数组
• 半径： 内半径（圆环图）和图表整体半径
• 响应式： 适配不同屏幕尺寸的布局

---

动画与事件

📄 阅读： references/animation-events.md

适用于以下场景：

• 配置图表加载动画
• 处理数据点选择和点击事件
• 响应鼠标悬停和移出事件
• 实现自定义交互
• 访问图表生命周期事件
• 处理系列和数据点渲染事件

涵盖主题：

• 动画： 启用、时长和延迟配置
• 图表事件： Load、Loaded、BeforeResize、Resized
• 数据点事件： OnPointClick、OnPointMove、PointRender
• 系列事件： SeriesRender、OnLegendClick
• 数据标签事件： OnDataLabelRender、TextRender
• 选择： OnSelectionComplete、选择模式
• 工具提示事件： TooltipRender
• 事件数据结构和参数
• 实用的事件处理示例

---

无障碍功能与打印

📄 阅读： references/accessibility-printing.md

适用于以下场景：

• 实现符合 WCAG 标准的图表
• 为屏幕阅读器添加 ARIA 属性
• 启用键盘导航
• 支持从右向左（RTL）的布局
• 实现打印功能
• 将图表导出为图像
• 本地化图表文本

涵盖主题：

• 无障碍功能： 符合 WCAG 2.1 标准的功能
• ARIA： 角色、标签和描述属性
• 键盘： Tab 导航和选择
• 屏幕阅读器： 替代文本和描述
• 打印： 打印方法和配置
• 导出： 图像导出（PNG、JPG、SVG）
• RTL： 支持从右向左的语言
• 本地化： 特定区域设置的格式

---

API 参考

📄 阅读： references/api-reference.md

适用于以下场景：

• 查找枚举值及其准确名称
• 了解公共方法的签名和参数
• 查找正确的属性类型和默认值
• 排查 API 使用问题
• 参考快速代码模式
• 查看重要的使用说明和注意事项

涵盖主题：

• 常用枚举： AccumulationType、AccumulationLabelPosition、GroupMode、LegendPosition、ExportType
• 关键属性： Type、InnerRadius、Radius、GroupTo、GroupMode、Visible、Enable
• 公共方法： ExportAsync、PrintAsync、Refresh、SetAnnotationValueAsync
• 重要使用说明： 中心标签限制、GroupTo 语义、枚举限定
• 常见模式： 基本饼图、带中心标签的圆环图、分组示例
• 故障排查： 标签重叠、中心标签问题、枚举编译错误

---

快速入门示例

以下是一个最简饼图实现：

@page "/pie-chart"
@using Syncfusion.Blazor.Charts

<SfAccumulationChart Title="Sales Distribution">
    <AccumulationChartSeriesCollection>
        <AccumulationChartSeries DataSource="@SalesData" 
                                 XName="Product" 
                                 YName="Sales">
            <AccumulationDataLabelSettings Visible="true" 
                                           Name="Product">
            </AccumulationDataLabelSettings>
        </AccumulationChartSeries>
    </AccumulationChartSeriesCollection>
    
    <AccumulationChartLegendSettings Visible="true">
    </AccumulationChartLegendSettings>
</SfAccumulationChart>

@code {
    public class SalesInfo
    {
        public string Product { get; set; }
        public double Sales { get; set; }
    }

    public List<SalesInfo> SalesData = new List<SalesInfo>
    {
        new SalesInfo { Product = "Product A", Sales = 35 },
        new SalesInfo { Product = "Product B", Sales = 28 },
        new SalesInfo { Product = "Product C", Sales = 22 },
        new SalesInfo { Product = "Product D", Sales = 15 }
    };
}

常见模式

带中心标签的圆环图

<SfAccumulationChart Title="Revenue by Region">
    <AccumulationChartSeriesCollection>
        <AccumulationChartSeries DataSource="@RevenueData" 
                                 XName="Region" 
                                 YName="Revenue"
                                 InnerRadius="40%">
            <AccumulationDataLabelSettings Visible="true" Position="Syncfusion.Blazor.Charts.AccumulationLabelPosition.Outside">
                <AccumulationChartConnector Length="20px">
                </AccumulationChartConnector>
            </AccumulationDataLabelSettings>
            <AccumulationChartCenterLabel 
                Text="Total<br/>$1.2M">
                <AccumulationChartCenterLabelFont 
                    Size="16px" 
                    FontWeight="600">
                </AccumulationChartCenterLabelFont>
            </AccumulationChartCenterLabel>
        </AccumulationChartSeries>
    </AccumulationChartSeriesCollection>
</SfAccumulationChart>

用于转化分析的漏斗图

<SfAccumulationChart Title="Sales Funnel">
    <AccumulationChartSeriesCollection>
        <AccumulationChartSeries DataSource="@ConversionData" 
                                 XName="Stage" 
                                 YName="Count"
                                 Type="Syncfusion.Blazor.Charts.AccumulationType.Funnel"
                                 NeckWidth="25%"
                                 NeckHeight="10%">
            <AccumulationDataLabelSettings Visible="true" Name="Stage">
            </AccumulationDataLabelSettings>
        </AccumulationChartSeries>
    </AccumulationChartSeriesCollection>
</SfAccumulationChart>

带渐变的分组饼图

<SfAccumulationChart Title="Market Share Analysis">
    <AccumulationChartSeriesCollection>
        <AccumulationChartSeries DataSource="@MarketData" 
                                 XName="Company" 
                                 YName="Share"
                                 GroupTo="5"
                                 GroupMode="Syncfusion.Blazor.Charts.GroupMode.Value">
            <AccumulationDataLabelSettings Visible="true" Position="Syncfusion.Blazor.Charts.AccumulationLabelPosition.Outside">
            </AccumulationDataLabelSettings>
        </AccumulationChartSeries>
    </AccumulationChartSeriesCollection>
    <AccumulationChartLegendSettings Visible="true" Position="Syncfusion.Blazor.Charts.LegendPosition.Right">
    </AccumulationChartLegendSettings>
</SfAccumulationChart>

@code {
    // Data source with gradient applied
    public List<MarketInfo> MarketData = new List<MarketInfo>
    {
        new MarketInfo { Company = "Company A", Share = 35 },
        new MarketInfo { Company = "Company B", Share = 20 },
        new MarketInfo { Company = "Company C", Share = 15 },
        new MarketInfo { Company = "Others", Share = 30 }
    };
}

关键属性和组件

SfAccumulationChart

• Title： 图表标题文本
• Height/Width： 图表尺寸
• Theme： 视觉主题（Bootstrap5、Material、Fluent 等）
• EnableAnimation： 启用/禁用加载动画
• SelectionMode： 数据点或系列选择
• Background： 图表背景颜色

AccumulationChartSeries

• DataSource： 要可视化的数据集合
• XName： 类别/标签的属性名称
• YName： 数值的属性名称
• Type： Pie（默认）、Doughnut、Funnel、Pyramid
• InnerRadius： Doughnut 内半径百分比
• Radius： 图表整体半径
• StartAngle/EndAngle： 弧线位置
• GroupTo： 分组的数值/数据点数量阈值
• GroupMode： 按数值或数据点分组的模式
• Explode/ExplodeIndex： 加载时分离扇区

AccumulationDataLabelSettings

• Visible： 显示/隐藏数据标签
• Name： 标签文本对应的属性
• Position： 标签放置在内部或外部
• Format： 数值格式字符串
• MaxWidth： 文本换行宽度
• Template： 自定义 HTML 模板

AccumulationChartLegendSettings

• Visible： 显示/隐藏图例
• Position： Top、Bottom、Left、Right
• Height/Width： 图例尺寸
• ToggleVisibility： 启用点击以隐藏/显示数据点

AccumulationChartTooltipSettings

• Enable： 显示/隐藏工具提示
• Format： 工具提示文本格式
• Header： 自定义标题文本
• Template： 自定义 HTML 模板

公共方法

SfAccumulationChart 组件提供以下公共方法。有关完整的方法签名和其他详细信息，请参阅 api-reference.md。

ExportAsync

以指定格式导出图表。

await chart.ExportAsync(ExportType.PNG, "chart.png");

参数：

• type (ExportType)：PNG、JPEG、SVG 或 PDF
• fileName (string)：导出文件的名称
• orientation (PdfPageOrientation?)：PDF 方向（Portrait/Landscape），可选
• allowDownload (bool)：是否下载文件，默认为 true

PrintAsync

打印图表。

await chart.PrintAsync();

Refresh

刷新图表，可选择是否播放动画。

chart.Refresh(shouldAnimate: true);

参数：

• shouldAnimate (bool)：刷新时是否播放动画，默认为 true

SetAnnotationValueAsync

动态更新批注内容。

await chart.SetAnnotationValueAsync(0, "Updated Content");

参数：

• annotationIndex (double)：要更新的批注索引
• content (string)：批注的新内容

常见用例

市场份额可视化

使用饼图或环形图展示竞争市场的分布情况，并通过图例标识各家公司。

销售管道跟踪

使用漏斗图可视化销售流程各阶段的转化情况，展示每一步的流失情况。

组织层级结构

使用金字塔图展示公司组织或食物链等层级结构。

调查结果展示

使用带数据标签的饼图展示调查答复的分布情况，并清晰显示百分比。

金融投资组合构成

使用带中心标签的环形图展示资产配置，并在中心显示总价值。

区域收入分布

使用带渐变色的饼图突出显示各地理区域的收入贡献。

另请参阅

• Syncfusion Blazor Charts 概述
• Accumulation Chart API 参考
• Blazor Accumulation Chart 示例