syncfusion-winui-circular-charts
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion WinUI Circular Charts
实现Syncfusion WinUI环形图
This skill guides you in implementing Syncfusion WinUI Circular Charts (SfCircularChart) for visualizing proportional data with pie and doughnut charts. The component provides rich interactive features including legends, data labels, tooltips, selection, and segment explosion.
本技能将指导你实现Syncfusion WinUI环形图(SfCircularChart),通过饼图和圆环图可视化比例数据。该组件提供了丰富的交互功能,包括图例、数据标签、提示框、选择和扇区突出效果。
When to Use This Skill
何时使用本技能
Use this skill when the user needs to:
- Create pie charts or doughnut charts in WinUI applications
- Display proportional or percentage data visually
- Implement circular data visualizations (market share, budget breakdown, survey results)
- Add interactive features to circular charts (tooltips, selection, exploding segments)
- Configure data labels, legends, or tooltips for circular charts
- Customize appearance with palettes, gradients, or custom colors
- Create semi-circular or quarter-circular chart variations
- Implement combination charts (pie + doughnut in same chart)
- Handle user interactions (segment selection, tap to explode)
当用户需要完成以下需求时可使用本技能:
- 在WinUI应用中创建饼图或圆环图
- 可视化展示比例或百分比数据
- 实现环形数据可视化(市场份额、预算分解、调研结果)
- 为环形图添加交互功能(提示框、选择、扇区突出)
- 为环形图配置数据标签、图例或提示框
- 通过调色板、渐变或自定义颜色自定义外观
- 创建半圆形或四分之一圆形的变体图表
- 实现组合图表(同一图表中同时包含饼图+圆环图)
- 处理用户交互(扇区选择、点击突出)
Component Overview
组件概述
Syncfusion SfCircularChart is a powerful data visualization component for WinUI that displays data in circular formats. It supports:
- Two Chart Types: Pie and Doughnut series
- Rich Visual Elements: Legends, data labels, tooltips, headers
- User Interactions: Selection, explode segments, toggle visibility
- Multiple Series: Display multiple pie or doughnut series simultaneously
- Dynamic Updates: Real-time data binding and updates
- Extensive Customization: Palettes, gradients, templates, styling
Syncfusion SfCircularChart 是一款功能强大的WinUI数据可视化组件,用于以环形格式展示数据。它支持:
- 两种图表类型: 饼图和圆环图系列
- 丰富的视觉元素: 图例、数据标签、提示框、标题
- 用户交互: 选择、扇区突出、显隐切换
- 多系列支持: 同时展示多个饼图或圆环图系列
- 动态更新: 实时数据绑定和更新
- 高度自定义: 调色板、渐变、模板、样式
Documentation and Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
Read this reference when the user needs to:
- Install the Syncfusion.Chart.WinUI NuGet package
- Set up basic circular chart in XAML or C#
- Create a ViewModel with data model
- Bind data to the chart series
- Understand complete initial setup and configuration
- See a working minimal example
📄 阅读: references/getting-started.md
当用户需要完成以下需求时阅读本参考:
- 安装Syncfusion.Chart.WinUI NuGet包
- 用XAML或C#搭建基础环形图
- 创建包含数据模型的ViewModel
- 给图表系列绑定数据
- 了解完整的初始搭建和配置流程
- 查看可运行的最小示例
Chart Types
图表类型
Pie Charts
饼图
📄 Read: references/pie-charts.md
Read this reference when the user needs to:
- Create and configure PieSeries
- Adjust pie chart radius
- Group small data points into "Others" category (GroupTo, GroupMode)
- Create semi-pie or quarter-pie charts (StartAngle, EndAngle)
- Implement combination charts (pie + doughnut together)
- Understand pie-specific features and configurations
📄 阅读: references/pie-charts.md
当用户需要完成以下需求时阅读本参考:
- 创建和配置PieSeries
- 调整饼图半径
- 将小数据点分组到「其他」分类(GroupTo、GroupMode)
- 创建半圆或四分之一圆饼图(StartAngle、EndAngle)
- 实现组合图表(饼图+圆环图共存)
- 了解饼图专属功能和配置
Doughnut Charts
圆环图
📄 Read: references/doughnut-charts.md
Read this reference when the user needs to:
- Create and configure DoughnutSeries
- Set inner radius (InnerRadius property)
- Display multiple doughnut series in one chart
- Create semi-doughnut or quarter-doughnut shapes
- Understand differences between pie and doughnut series
- Size and position doughnut charts
📄 阅读: references/doughnut-charts.md
当用户需要完成以下需求时阅读本参考:
- 创建和配置DoughnutSeries
- 设置内半径(InnerRadius属性)
- 在同一图表中展示多个圆环图系列
- 创建半圆或四分之一圆环形
- 了解饼图和圆环图系列的区别
- 调整圆环图的尺寸和位置
Visual Elements
视觉元素
Legend
图例
📄 Read: references/legend.md
Read this reference when the user needs to:
- Enable and configure chart legend
- Add legend title or header
- Customize legend icons (type, size, template)
- Adjust legend placement (Left, Right, Top, Bottom)
- Add checkboxes for toggling segment visibility
- Customize legend appearance (background, borders, spacing)
- Create custom legend item templates
- Control legend item margins and alignment
📄 阅读: references/legend.md
当用户需要完成以下需求时阅读本参考:
- 启用和配置图表图例
- 添加图例标题或头部
- 自定义图例图标(类型、尺寸、模板)
- 调整图例位置(左、右、上、下)
- 添加复选框实现扇区显隐切换
- 自定义图例外观(背景、边框、间距)
- 创建自定义图例项模板
- 控制图例项的边距和对齐方式
Data Labels
数据标签
📄 Read: references/data-labels.md
Read this reference when the user needs to:
- Enable and display data labels on segments
- Configure label context (Percentage, YValue, DataLabelItem)
- Customize label appearance (fonts, colors, borders)
- Position labels (Inside, Outside, OutsideExtended)
- Add connector lines between labels and segments
- Customize connector line styles and types (Line, Bezier, StraightLine)
- Rotate data labels
- Create custom data label templates
- Apply series palette to labels
📄 阅读: references/data-labels.md
当用户需要完成以下需求时阅读本参考:
- 启用并在扇区上展示数据标签
- 配置标签内容(百分比、Y值、DataLabelItem)
- 自定义标签外观(字体、颜色、边框)
- 调整标签位置(内部、外部、扩展外部)
- 在标签和扇区间添加连接线
- 自定义连接线样式和类型(直线、贝塞尔曲线、直线段)
- 旋转数据标签
- 创建自定义数据标签模板
- 为标签应用系列调色板
Tooltips
提示框
📄 Read: references/tooltips.md
Read this reference when the user needs to:
- Enable tooltips on segment hover
- Configure tooltip behavior (duration, animation, delay)
- Customize tooltip styling (background, borders)
- Style tooltip labels (fonts, colors)
- Position tooltips (alignment, offsets)
- Create custom tooltip templates
- Control tooltip display settings
📄 阅读: references/tooltips.md
当用户需要完成以下需求时阅读本参考:
- 悬停扇区时启用提示框
- 配置提示框行为(展示时长、动画、延迟)
- 自定义提示框样式(背景、边框)
- 调整提示框标签样式(字体、颜色)
- 调整提示框位置(对齐、偏移)
- 创建自定义提示框模板
- 控制提示框展示设置
Title and Header
标题与头部
📄 Read: references/title-header.md
Read this reference when the user needs to:
- Add a title or header to the chart
- Use custom UIElements as chart header
- Align chart header (left, center, right)
- Style and format the chart title
- Create bordered or decorated headers
📄 阅读: references/title-header.md
当用户需要完成以下需求时阅读本参考:
- 为图表添加标题或头部
- 使用自定义UIElement作为图表头部
- 对齐图表头部(左、中、右)
- 样式化和格式化图表标题
- 创建带边框或装饰的头部
User Interactions
用户交互
Selection
选择
📄 Read: references/selection.md
Read this reference when the user needs to:
- Enable segment selection behavior
- Configure single or multi-selection modes
- Customize selection appearance (SelectionBrush)
- Programmatically select segments (SelectedIndex, SelectedIndexes)
- Handle selection events (SelectionChanging, SelectionChanged)
- Implement deselection behavior
- Control selection types (Single, SingleDeselect, Multiple, None)
📄 阅读: references/selection.md
当用户需要完成以下需求时阅读本参考:
- 启用扇区选择行为
- 配置单选或多选模式
- 自定义选择外观(SelectionBrush)
- 程序化选择扇区(SelectedIndex、SelectedIndexes)
- 处理选择事件(SelectionChanging、SelectionChanged)
- 实现取消选择行为
- 控制选择类型(单选、单选可取消、多选、无)
Explode Segments
扇区突出
📄 Read: references/explode-segments.md
Read this reference when the user needs to:
- Explode specific segments to highlight them
- Set explode radius for separation distance
- Explode all segments simultaneously
- Enable tap-to-explode interaction
- Programmatically control exploded segments
- Understand when to use segment explosion
📄 阅读: references/explode-segments.md
当用户需要完成以下需求时阅读本参考:
- 突出指定扇区进行强调
- 设置突出半径控制分离距离
- 同时突出所有扇区
- 启用点击突出交互
- 程序化控制突出的扇区
- 了解何时使用扇区突出功能
Customization
自定义
Appearance
外观
📄 Read: references/appearance.md
Read this reference when the user needs to:
- Apply predefined palette brushes
- Create custom color palettes (PaletteBrushes)
- Apply gradients to segments (LinearGradientBrush, RadialGradientBrush)
- Customize segment colors and styling
- Understand visual customization patterns
📄 阅读: references/appearance.md
当用户需要完成以下需求时阅读本参考:
- 应用预定义的调色板画笔
- 创建自定义调色板(PaletteBrushes)
- 为扇区应用渐变(LinearGradientBrush、RadialGradientBrush)
- 自定义扇区颜色和样式
- 了解视觉自定义模式
Quick Start Example
快速入门示例
Here's a minimal example to create a basic pie chart:
1. Install NuGet Package:
Install-Package Syncfusion.Chart.WinUI2. Create Data Model and ViewModel:
csharp
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. Create Circular Chart in XAML:
xml
<Window
xmlns:chart="using:Syncfusion.UI.Xaml.Charts"
xmlns:model="using:YourNamespace.ViewModel">
<chart:SfCircularChart Header="Product Sales">
<!-- Set DataContext -->
<chart:SfCircularChart.DataContext>
<model:ChartViewModel/>
</chart:SfCircularChart.DataContext>
<!-- Add Legend -->
<chart:SfCircularChart.Legend>
<chart:ChartLegend/>
</chart:SfCircularChart.Legend>
<!-- Add Pie Series -->
<chart:SfCircularChart.Series>
<chart:PieSeries ItemsSource="{Binding Data}"
XBindingPath="Product"
YBindingPath="SalesRate"
ShowDataLabels="True"
EnableTooltip="True"/>
</chart:SfCircularChart.Series>
</chart:SfCircularChart>
</Window>4. Or Create in C#:
csharp
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. 安装NuGet包:
Install-Package Syncfusion.Chart.WinUI2. 创建数据模型和ViewModel:
csharp
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创建环形图:
xml
<Window
xmlns:chart="using:Syncfusion.UI.Xaml.Charts"
xmlns:model="using:YourNamespace.ViewModel">
<chart:SfCircularChart Header="Product Sales">
<!-- Set DataContext -->
<chart:SfCircularChart.DataContext>
<model:ChartViewModel/>
</chart:SfCircularChart.DataContext>
<!-- Add Legend -->
<chart:SfCircularChart.Legend>
<chart:ChartLegend/>
</chart:SfCircularChart.Legend>
<!-- Add Pie Series -->
<chart:SfCircularChart.Series>
<chart:PieSeries ItemsSource="{Binding Data}"
XBindingPath="Product"
YBindingPath="SalesRate"
ShowDataLabels="True"
EnableTooltip="True"/>
</chart:SfCircularChart.Series>
</chart:SfCircularChart>
</Window>4. 或用C#创建:
csharp
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;Common Patterns
常用模式
Pattern 1: Pie Chart with Data Labels and Legend
模式1:带数据标签和图例的饼图
xml
<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>xml
<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>Pattern 2: Doughnut Chart with Custom Colors
模式2:带自定义颜色的圆环图
xml
<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>xml
<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>Pattern 3: Interactive Chart with Selection and Explode
模式3:带选择和突出功能的交互图表
xml
<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>xml
<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>Pattern 4: Semi-Circular Chart
模式4:半圆形图表
xml
<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>xml
<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>Key Properties
核心属性
SfCircularChart Properties
SfCircularChart属性
- Header - Sets the chart title/header
- Legend - Configures the chart legend
- Series - Collection of circular series (PieSeries, DoughnutSeries)
- TooltipBehavior - Configures tooltip display behavior
- Header - 设置图表标题/头部
- Legend - 配置图表图例
- Series - 环形系列集合(PieSeries、DoughnutSeries)
- TooltipBehavior - 配置提示框展示行为
Series Properties (PieSeries/DoughnutSeries)
系列属性(PieSeries/DoughnutSeries)
- ItemsSource - Data source for the series
- XBindingPath - Property path for category/label values
- YBindingPath - Property path for numeric values
- ShowDataLabels - Enables data labels on segments
- EnableTooltip - Enables tooltips on hover
- PaletteBrushes - Custom colors for segments
- Radius - Size of the pie/doughnut (0 to 1)
- InnerRadius - Inner hole size for doughnut (0 to 1)
- StartAngle - Starting angle for rendering (0-360)
- EndAngle - Ending angle for rendering (0-360)
- ExplodeIndex - Index of segment to explode
- ExplodeAll - Explodes all segments
- ExplodeRadius - Distance for exploded segments
- ExplodeOnTap - Enables tap-to-explode interaction
- GroupTo - Threshold for grouping small segments
- GroupMode - Grouping mode (Value, Percentage, Angle)
- SelectionBehavior - Configures segment selection
- DataLabelSettings - Configures data label appearance
- LegendIcon - Icon type for legend items
- ItemsSource - 系列的数据源
- XBindingPath - 分类/标签值的属性路径
- YBindingPath - 数值的属性路径
- ShowDataLabels - 启用扇区上的数据标签
- EnableTooltip - 悬停时启用提示框
- PaletteBrushes - 扇区的自定义颜色
- Radius - 饼图/圆环图的尺寸(0到1)
- InnerRadius - 圆环图的内孔尺寸(0到1)
- StartAngle - 渲染起始角度(0-360)
- EndAngle - 渲染结束角度(0-360)
- ExplodeIndex - 需要突出的扇区索引
- ExplodeAll - 突出所有扇区
- ExplodeRadius - 扇区突出的距离
- ExplodeOnTap - 启用点击突出交互
- GroupTo - 小扇区分组的阈值
- GroupMode - 分组模式(值、百分比、角度)
- SelectionBehavior - 配置扇区选择
- DataLabelSettings - 配置数据标签外观
- LegendIcon - 图例项的图标类型
Common Use Cases
常见使用场景
When to Use Pie Charts
何时使用饼图
- Showing parts of a whole (market share, budget allocation)
- Displaying percentage distributions (survey results, demographics)
- Simple comparisons with 5-7 categories
- When proportions are more important than exact values
- Single data series visualization
- 展示整体的组成部分(市场份额、预算分配)
- 展示百分比分布(调研结果、人口统计)
- 5-7个分类的简单对比
- 当比例比精确值更重要时
- 单数据系列可视化
When to Use Doughnut Charts
何时使用圆环图
- Similar to pie charts but with better label placement (can use center)
- Multiple concentric series for comparison
- When you want to display central content (total, summary)
- More modern aesthetic preference
- Better for dense data with many categories
- 与饼图场景类似,但标签放置更灵活(可利用中心区域)
- 用多个同心系列进行对比
- 当你需要展示中心内容(总数、摘要)时
- 偏好更现代的美学风格时
- 包含多分类的高密度数据更适合
When to Use Explode Segments
何时使用扇区突出
- Highlighting specific data points (best performer, focus area)
- Drawing attention to important segments
- Creating visual emphasis for presentation
- Interactive exploration (tap to explode)
- 高亮特定数据点(最佳表现项、重点关注领域)
- 吸引用户注意重要扇区
- 为演示创建视觉强调效果
- 交互式探索(点击突出)
When to Use Selection
何时使用选择功能
- Allowing users to filter or drill down into data
- Interactive dashboards where segment selection triggers other views
- Comparison scenarios (select multiple segments)
- Data exploration interfaces
- 允许用户筛选或下钻数据
- 选择扇区可触发其他视图变化的交互式仪表盘
- 对比场景(选择多个扇区)
- 数据探索界面
Related Components
相关组件
- Cartesian Charts - For time-series, trends, and comparisons (bar, line, column charts)
- Funnel/Pyramid Charts - For hierarchical or stage-based data
- Gauge Charts - For single-value indicators with ranges
- 笛卡尔图表 - 用于时间序列、趋势和对比(柱状图、折线图、条形图)
- 漏斗/金字塔图 - 用于分层或阶段式数据
- 仪表盘图表 - 用于带范围的单值指标
Tips and Best Practices
提示与最佳实践
- Limit segments to 5-7 for readability; use GroupTo for small values
- Use data labels for exact values; legends for category names
- Enable tooltips for interactive exploration
- Consider doughnut for multiple series or central content
- Use selection sparingly; explode for emphasis only
- Choose contrasting colors for better segment differentiation
- Test responsiveness - circular charts adapt well to different sizes
- 限制扇区数量在5-7个以保证可读性,小数值使用GroupTo分组
- 使用数据标签展示精确值,使用图例展示分类名称
- 启用提示框支持交互式探索
- 多系列或需要展示中心内容时优先考虑圆环图
- 谨慎使用选择功能,仅在需要强调时使用扇区突出
- 选择对比度高的颜色提升扇区分辨度
- 测试响应式表现 - 环形图对不同尺寸的适配性较好