syncfusion-winui-circular-charts

实现 Syncfusion WinUI 圆形图表

本技能将指导你实现 Syncfusion WinUI 圆形图表（SfCircularChart），使用饼图和圆环图可视化比例数据。该组件提供丰富的交互功能，包括图例、数据标签、工具提示、选择和扇区分离。

何时使用此技能

当用户需要以下功能时，请使用此技能：

• 在 WinUI 应用程序中创建饼图或圆环图
• 以可视化方式展示比例或百分比数据
• 实现圆形数据可视化（市场份额、预算明细、调查结果）
• 为圆形图表添加交互功能（工具提示、选择、分离扇区）
• 配置圆形图表的数据标签、图例或工具提示
• 使用调色板、渐变或自定义颜色自定义外观
• 创建半圆形或四分之一圆形图表变体
• 实现组合图表（在同一图表中组合饼图和圆环图）
• 处理用户交互（选择扇区、点击以分离）

组件概述

Syncfusion SfCircularChart 是适用于 WinUI 的强大数据可视化组件，可用圆形格式显示数据。它支持：

• **两种图表类型：**饼图和圆环图系列
• **丰富的视觉元素：**图例、数据标签、工具提示、标题
• **用户交互：**选择、分离扇区、切换可见性
• **多个系列：**同时显示多个饼图或圆环图系列
• **动态更新：**实时数据绑定和更新
• **丰富的自定义选项：**调色板、渐变、模板、样式

文档和导航指南

入门

📄 阅读： references/getting-started.md

当用户需要以下内容时，请阅读此参考文档：

• 安装 Syncfusion.Chart.WinUI NuGet 包
• 在 XAML 或 C# 中设置基本圆形图表
• 创建包含数据模型的 ViewModel
• 将数据绑定到图表系列
• 了解完整的初始设置和配置
• 查看可运行的最简示例

图表类型

饼图

📄 阅读： references/pie-charts.md

当用户需要以下功能时，请阅读此参考文档：

• 创建和配置 PieSeries
• 调整饼图半径
• 将较小的数据点归入“其他”类别（GroupTo、GroupMode）
• 创建半饼图或四分之一饼图（StartAngle、EndAngle）
• 实现组合图表（饼图和圆环图）
• 了解饼图专属功能和配置

圆环图

📄 阅读： references/doughnut-charts.md

当用户需要以下功能时，请阅读此参考文档：

• 创建和配置 DoughnutSeries
• 设置内半径（InnerRadius 属性）
• 在一个图表中显示多个圆环图系列
• 创建半圆环或四分之一圆环形状
• 了解饼图系列和圆环图系列之间的区别
• 设置圆环图的大小和位置

视觉元素

图例

📄 阅读： references/legend.md

当用户需要以下功能时，请阅读此参考文档：

• 启用并配置图表图例
• 添加图例标题或页眉
• 自定义图例图标（类型、大小、模板）
• 调整图例位置（Left、Right、Top、Bottom）
• 添加用于切换扇区可见性的复选框
• 自定义图例外观（背景、边框、间距）
• 创建自定义图例项模板
• 控制图例项边距和对齐方式

数据标签

📄 阅读： references/data-labels.md

当用户需要以下功能时，请阅读此参考文档：

• 启用并显示扇区上的数据标签
• 配置标签上下文（Percentage、YValue、DataLabelItem）
• 自定义标签外观（字体、颜色、边框）
• 设置标签位置（Inside、Outside、OutsideExtended）
• 在标签和扇区之间添加连接线
• 自定义连接线样式和类型（Line、Bezier、StraightLine）
• 旋转数据标签
• 创建自定义数据标签模板
• 将系列调色板应用于标签

工具提示

📄 阅读： references/tooltips.md

用户需要以下操作时，请阅读此参考：

• 启用鼠标悬停在扇区上时显示工具提示
• 配置工具提示行为（持续时间、动画、延迟）
• 自定义工具提示样式（背景、边框）
• 设置工具提示标签的样式（字体、颜色）
• 设置工具提示的位置（对齐方式、偏移量）
• 创建自定义工具提示模板
• 控制工具提示显示设置

标题和页眉

📄 阅读： references/title-header.md

用户需要以下操作时，请阅读此参考：

• 为图表添加标题或页眉
• 使用自定义 UIElements 作为图表页眉
• 设置图表页眉的对齐方式（左、中、右）
• 设置图表标题的样式和格式
• 创建带边框或装饰效果的页眉

用户交互

选择

📄 阅读： references/selection.md

用户需要以下操作时，请阅读此参考：

• 启用扇区选择行为
• 配置单选或多选模式
• 自定义选择外观（SelectionBrush）
• 以编程方式选择扇区（SelectedIndex、SelectedIndexes）
• 处理选择事件（SelectionChanging、SelectionChanged）
• 实现取消选择行为
• 控制选择类型（Single、SingleDeselect、Multiple、None）

分离扇区

📄 阅读： references/explode-segments.md

用户需要以下操作时，请阅读此参考：

• 分离指定扇区以突出显示
• 设置分离半径以控制间距
• 同时分离所有扇区
• 启用点击分离交互
• 以编程方式控制分离的扇区
• 了解何时使用扇区分离

自定义

外观

📄 阅读： references/appearance.md

用户需要以下操作时，请阅读此参考：

• 应用预定义的调色板画笔
• 创建自定义调色板（PaletteBrushes）
• 为扇区应用渐变（LinearGradientBrush、RadialGradientBrush）
• 自定义扇区颜色和样式
• 了解视觉自定义模式

快速入门示例

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

1. 安装 NuGet 包：

Install-Package Syncfusion.Chart.WinUI

2. 创建数据模型和 ViewModel：

public class Sales
{
    public string Product { get; set; }
    public double SalesRate { get; set; }
}

public class ChartViewModel
{
    public List<Sales> Data { get; set; }

    public ChartViewModel()
    {
        Data = new List<Sales>()
        {
            new Sales() { Product = "iPad", SalesRate = 25 },
            new Sales() { Product = "iPhone", SalesRate = 35 },
            new Sales() { Product = "MacBook", SalesRate = 15 },
            new Sales() { Product = "Mac", SalesRate = 5 },
            new Sales() { Product = "Others", SalesRate = 10 }
        };
    }
}

3. 在 XAML 中创建环形图表：

<Window
    xmlns:chart="using:Syncfusion.UI.Xaml.Charts"
    xmlns:model="using:YourNamespace.ViewModel">

    <chart:SfCircularChart Header="Product Sales">
        
        <chart:SfCircularChart.DataContext>
            <model:ChartViewModel/>
        </chart:SfCircularChart.DataContext>
        
        
        <chart:SfCircularChart.Legend>
            <chart:ChartLegend/>
        </chart:SfCircularChart.Legend>
        
        
        <chart:SfCircularChart.Series>
            <chart:PieSeries ItemsSource="{Binding Data}"
                           XBindingPath="Product"
                           YBindingPath="SalesRate"
                           ShowDataLabels="True"
                           EnableTooltip="True"/>
        </chart:SfCircularChart.Series>
    </chart:SfCircularChart>
</Window>

4. 或在 C# 中创建：

SfCircularChart chart = new SfCircularChart();
chart.Header = "Product Sales";
chart.DataContext = new ChartViewModel();
chart.Legend = new ChartLegend();

PieSeries series = new PieSeries();
series.SetBinding(PieSeries.ItemsSourceProperty, new Binding() { Path = new PropertyPath("Data") });
series.XBindingPath = "Product";
series.YBindingPath = "SalesRate";
series.ShowDataLabels = true;
series.EnableTooltip = true;

chart.Series.Add(series);
this.Content = chart;

常见模式

模式 1：带数据标签和图例的饼图

<chart:SfCircularChart Header="Sales Distribution">
    <chart:SfCircularChart.Legend>
        <chart:ChartLegend/>
    </chart:SfCircularChart.Legend>
    
    <chart:SfCircularChart.Series>
        <chart:PieSeries ItemsSource="{Binding Data}"
                       XBindingPath="Category"
                       YBindingPath="Value"
                       ShowDataLabels="True">
            <chart:PieSeries.DataLabelSettings>
                <chart:CircularDataLabelSettings Context="Percentage"
                                               Position="Outside"
                                               ShowConnectorLine="True"/>
            </chart:PieSeries.DataLabelSettings>
        </chart:PieSeries>
    </chart:SfCircularChart.Series>
</chart:SfCircularChart>

模式 2：使用自定义颜色的环形图

<chart:SfCircularChart>
    <chart:SfCircularChart.Resources>
        <BrushCollection x:Key="customBrushes">
            <SolidColorBrush Color="#4dd0e1"/>
            <SolidColorBrush Color="#26c6da"/>
            <SolidColorBrush Color="#00bcd4"/>
        </BrushCollection>
    </chart:SfCircularChart.Resources>
    
    <chart:SfCircularChart.Series>
        <chart:DoughnutSeries ItemsSource="{Binding Data}"
                            XBindingPath="Name"
                            YBindingPath="Amount"
                            InnerRadius="0.6"
                            PaletteBrushes="{StaticResource customBrushes}"/>
    </chart:SfCircularChart.Series>
</chart:SfCircularChart>

模式 3：支持选择和分离交互的图表

<chart:SfCircularChart>
    <chart:SfCircularChart.Series>
        <chart:PieSeries ItemsSource="{Binding Data}"
                       XBindingPath="Product"
                       YBindingPath="Sales"
                       ExplodeOnTap="True"
                       ExplodeRadius="10">
            <chart:PieSeries.SelectionBehavior>
                <chart:DataPointSelectionBehavior SelectionBrush="Orange"
                                                Type="Single"/>
            </chart:PieSeries.SelectionBehavior>
        </chart:PieSeries>
    </chart:SfCircularChart.Series>
</chart:SfCircularChart>

模式 4：半圆形图表

<chart:SfCircularChart>
    <chart:SfCircularChart.Series>
        <chart:PieSeries ItemsSource="{Binding Data}"
                       XBindingPath="Category"
                       YBindingPath="Value"
                       StartAngle="180"
                       EndAngle="360"
                       ShowDataLabels="True"/>
    </chart:SfCircularChart.Series>
</chart:SfCircularChart>

关键属性

SfCircularChart 属性

• Header - 设置图表标题/页眉
• Legend - 配置图表图例
• Series - 环形系列集合（PieSeries、DoughnutSeries）
• TooltipBehavior - 配置工具提示显示行为

系列属性（PieSeries/DoughnutSeries）

• ItemsSource - 系列的数据源
• XBindingPath - 类别/标签值的属性路径
• YBindingPath - 数值的属性路径
• ShowDataLabels - 启用扇区上的数据标签
• EnableTooltip - 启用悬停工具提示
• PaletteBrushes - 扇区的自定义颜色
• Radius - 饼图/环形图的大小（0 到 1）
• InnerRadius - 环形图内孔的大小（0 到 1）
• StartAngle - 渲染起始角度（0-360）
• EndAngle - 渲染结束角度（0-360）
• ExplodeIndex - 要分离的扇区索引
• ExplodeAll - 分离所有扇区
• ExplodeRadius - 分离扇区的距离
• ExplodeOnTap - 启用点击分离交互
• GroupTo - 小扇区的分组阈值
• GroupMode - 分组模式（Value、Percentage、Angle）
• SelectionBehavior - 配置扇区选择
• DataLabelSettings - 配置数据标签外观
• LegendIcon - 图例项的图标类型

常见用例

何时使用饼图

• 展示整体中的各个部分（市场份额、预算分配）
• 显示百分比分布（调查结果、人口统计数据）
• 对 5-7 个类别进行简单比较
• 比例关系比精确数值更重要时
• 可视化单个数据系列

何时使用环形图

• 与饼图类似，但标签位置更灵活（可利用中心区域）
• 使用多个同心数据系列进行比较
• 想要展示中心内容（总计、摘要）时
• 偏好更现代的外观
• 类别较多、数据密集时效果更好

何时使用分离扇区

• 突出特定数据点（表现最佳者、重点领域）
• 吸引注意力至重要扇区
• 在演示中营造视觉强调效果
• 进行交互式探索（点击以分离扇区）

何时使用选择功能

• 允许用户筛选数据或深入查看数据
• 交互式仪表板中，选择扇区会触发其他视图
• 比较场景（选择多个扇区）
• 数据探索界面

相关组件

• 笛卡尔坐标图表 - 用于时间序列、趋势和比较（条形图、折线图、柱状图）
• 漏斗图/金字塔图 - 用于层级数据或阶段性数据
• 仪表盘图表 - 用于显示带有范围的单值指标

提示和最佳实践

1. 为确保可读性，将扇区数量限制在 5-7 个；对较小的数值使用 GroupTo
2. 使用数据标签显示精确数值；使用图例显示类别名称
3. 启用工具提示，以便进行交互式探索
4. 多个数据系列或需要中心内容时，考虑使用环形图
5. 谨慎使用选择功能；仅在需要强调时分离扇区
6. 选择对比鲜明的颜色，以更好地区分扇区
7. 测试响应性 - 环形图表能够很好地适应不同尺寸