syncfusion-wpf-sunburst-chart

程序集要求

必需程序集：

• Syncfusion.SfSunburstChart.WPF

NuGet 包：

Install-Package Syncfusion.SfSunburstChart.WPF

最低 .NET Framework 版本： 4.5 或更高版本

实现旭日图

本指南介绍如何实现 Syncfusion WPF 旭日图（SfSunburstChart）控件，以同心圆环的形式可视化分层数据。旭日图可显示多级分类数据，每个圆环代表层次结构中的一个级别，中心代表根级别，外环则代表更深层级。

何时使用此技能

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

• 可视化多级分层数据，并采用圆形布局
• 显示组织结构（部门、团队、角色）
• 展示文件系统层次结构（文件夹、子文件夹、文件）
• 呈现按区域、类别、产品和子类别组织的销售数据
• 实现可交互缩放的下钻体验
• 创建以大小表示数值的多级圆形可视化
• 以紧凑直观的格式显示树状结构数据
• 支持对嵌套分类数据进行交互式探索

当分层数据包含 2 到 5 个级别，且需要同时展示分类结构和相对大小时，旭日图是理想选择。

组件概览

SfSunburstChart 是一种专用的 WPF 控件，用于以同心圆的形式可视化分层数据：

主要功能：

• 多级层次结构： 支持 2 到 5 个或更多层级
• 数据绑定： 兼容 MVVM，支持 IEnumerable 数据源
• 交互功能： 工具提示、选择、缩放/下钻
• 视觉自定义： 调色板、数据标签、图例
• 动画： FadeIn 和 Rotation 动画，实现流畅渲染
• 响应式设计： 可自定义半径和角度

核心属性：

• ItemsSource – 数据集合（分层数据模型）
• ValueMemberPath – 用于设置分段大小的属性名称
• Levels – 用于定义各层级的集合
• GroupMemberPath – 各层级的分组属性

文档与导航指南

入门

📄 阅读： references/getting-started.md

在以下情况下使用此参考文档：

• 设置新的旭日图项目
• 添加程序集引用（Syncfusion.SfSunburstChart.WPF）
• 创建数据模型和 ViewModel
• 将数据绑定到图表
• 添加基本视觉元素（标题、图例、数据标签）
• 了解完整的可运行示例

涵盖主题：

• 程序集引用和安装
• 命名空间导入（XAML 和 C#）
• 分层数据的数据模型结构
• 使用 ObservableCollection 初始化 ViewModel
• 基本图表配置（ItemsSource、ValueMemberPath）
• 添加标题、图例和数据标签
• 主题集成

分层级配置

📄 阅读： references/hierarchical-levels.md

在以下情况下使用此参考文档：

• 定义层次结构
• 配置多个层级（2 到 5 个或更多层级）
• 了解 GroupMemberPath 映射
• 按类别和子类别组织数据

涵盖主题：

• SunburstHierarchicalLevel 概览
• Levels 集合管理
• GroupMemberPath 属性用法
• 多级层次结构示例
• 层级顺序和结构

数据标签

📄 阅读： references/data-labels.md

在以下情况下使用此参考文档：

• 在分段上显示类别名称和值
• 自定义标签外观和位置
• 处理标签溢出（Hide 或 Trim）
• 旋转标签以提高可读性
• 创建自定义标签模板

涵盖主题：

• 启用/禁用标签（ShowLabel）
• LabelOverflowMode（Hide、Trim）
• LabelRotationMode（Normal、Angle）
• 字体自定义（FontFamily、FontSize、FontStyle、FontWeight）
• 自定义模板（LabelTemplate）
• 前景色自定义

图例配置

📄 阅读： references/legend.md

在以下情况下使用此参考：

• 添加图例以标识类别
• 自定义图例图标和布局
• 设置图例位置（左、右、上、下）
• 实现图例交互功能（单击以选择/隐藏）
• 创建自定义图例模板

涵盖主题：

• 图例初始化
• LegendIcon 形状（圆形、五边形、矩形等）
• 图标大小（IconHeight、IconWidth）
• 自定义图例模板（LegendIconTemplate）
• 位置设置（DockPosition）
• 图例交互功能（ClickAction：ToggleSegmentSelection、ToggleSegmentVisibility）

动画

📄 阅读： references/animation.md

在以下情况下使用此参考：

• 添加平滑的入场动画
• 配置动画时长
• 在 FadeIn 和 Rotation 动画之间进行选择

涵盖主题：

• EnableAnimation 属性
• AnimationDuration 配置
• AnimationType 选项（FadeIn、Rotation）
• 性能注意事项

视觉自定义

📄 阅读： references/visual-customization.md

在以下情况下使用此参考：

• 应用颜色调色板（预定义或自定义）
• 创建自定义配色方案
• 调整图表尺寸（半径、内半径）
• 自定义起始角度和结束角度
• 使用渐变画笔

涵盖主题：

• 预定义调色板（Metro、AutumnBrights、FloraHues 等）
• 自定义调色板（ColorModel、CustomBrushes）
• 渐变画笔示例
• 区域属性（StartAngle、EndAngle、Radius、InnerRadius）
• 视觉结构自定义

交互功能

📄 阅读： references/interactivity.md

在以下情况下使用此参考：

• 添加悬停提示
• 实现扇区选择
• 启用下钻/缩放
• 配置交互行为
• 自定义用户体验

涵盖主题：

• 工具提示： ShowToolTip、对齐方式、偏移量、时长、自定义模板
• 选择： SelectionDisplayMode、SelectionMode、SelectionType、SelectionBrush
• 缩放： SunburstZoomingBehavior、工具栏配置、下钻

事件处理

📄 阅读： references/events.md

在以下情况下使用此参考：

• 响应扇区创建
• 处理选择变更
• 动态自定义扇区
• 根据用户操作实现自定义行为

涵盖主题：

• SegmentCreated 事件
• SelectionChanged 事件
• 事件参数属性
• 动态扇区自定义
• 事件处理程序模式

快速入门示例

下面是一个用于创建显示员工分布的旭日图的最简示例：

1. 添加程序集引用

<Window xmlns:sunburst="clr-namespace:Syncfusion.UI.Xaml.SunburstChart;assembly=Syncfusion.SfSunburstChart.WPF">

2. 创建数据模型

public class EmployeeData
{
    public string Country { get; set; }
    public string Department { get; set; }
    public string Team { get; set; }
    public double EmployeeCount { get; set; }
}

3. 创建 ViewModel

public class ViewModel
{
    public ObservableCollection<EmployeeData> Data { get; set; }
    
    public ViewModel()
    {
        Data = new ObservableCollection<EmployeeData>
        {
            new EmployeeData { Country = "USA", Department = "Sales", Team = "Field Sales", EmployeeCount = 45 },
            new EmployeeData { Country = "USA", Department = "Sales", Team = "Inside Sales", EmployeeCount = 30 },
            new EmployeeData { Country = "USA", Department = "Engineering", Team = "Development", EmployeeCount = 85 },
            new EmployeeData { Country = "USA", Department = "Engineering", Team = "QA", EmployeeCount = 35 },
            new EmployeeData { Country = "India", Department = "Engineering", Team = "Development", EmployeeCount = 120 },
            new EmployeeData { Country = "India", Department = "Engineering", Team = "QA", EmployeeCount = 40 },
            new EmployeeData { Country = "UK", Department = "Sales", Team = "Field Sales", EmployeeCount = 25 },
            new EmployeeData { Country = "UK", Department = "Marketing", Team = "Digital", EmployeeCount = 20 }
        };
    }
}

4. XAML 配置

<sunburst:SfSunburstChart ItemsSource="{Binding Data}" ValueMemberPath="EmployeeCount"
                          Header="Employee Distribution" FontSize="20">
    
    
    <sunburst:SfSunburstChart.Levels>
        <sunburst:SunburstHierarchicalLevel GroupMemberPath="Country"/>
        <sunburst:SunburstHierarchicalLevel GroupMemberPath="Department"/>
        <sunburst:SunburstHierarchicalLevel GroupMemberPath="Team"/>
    </sunburst:SfSunburstChart.Levels>
    
    
    <sunburst:SfSunburstChart.Legend>
        <sunburst:SunburstLegend DockPosition="Left"/>
    </sunburst:SfSunburstChart.Legend>
    
    
    <sunburst:SfSunburstChart.DataLabelInfo>
        <sunburst:SunburstDataLabelInfo ShowLabel="True"/>
    </sunburst:SfSunburstChart.DataLabelInfo>
    
</sunburst:SfSunburstChart>

5. 设置 DataContext

public MainWindow()
{
    InitializeComponent();
    this.DataContext = new ViewModel();
}

常见模式

模式 1：包含 3–4 个层级的层次结构数据

<sunburst:SfSunburstChart ItemsSource="{Binding HierarchicalData}" 
                          ValueMemberPath="Value"
                          Palette="Metro">
    <sunburst:SfSunburstChart.Levels>
        <sunburst:SunburstHierarchicalLevel GroupMemberPath="Level1"/>
        <sunburst:SunburstHierarchicalLevel GroupMemberPath="Level2"/>
        <sunburst:SunburstHierarchicalLevel GroupMemberPath="Level3"/>
        <sunburst:SunburstHierarchicalLevel GroupMemberPath="Level4"/>
    </sunburst:SfSunburstChart.Levels>
</sunburst:SfSunburstChart>

适用场景： 显示组织结构、文件系统或多层级销售数据。

模式 2：带选择和工具提示的交互式图表

<sunburst:SfSunburstChart ItemsSource="{Binding Data}" ValueMemberPath="Value">
    
    <sunburst:SfSunburstChart.Behaviors>
        
        <sunburst:SunburstSelectionBehavior EnableSelection="True"
                                           SelectionMode="MouseClick"
                                           SelectionType="Single"/>
        
        
        <sunburst:SunburstToolTipBehavior ShowToolTip="True"
                                         ShowDuration="3000"/>
    </sunburst:SfSunburstChart.Behaviors>
    
</sunburst:SfSunburstChart>

适用场景： 用户需要与扇区交互以获取详细信息。

模式 3：使用缩放进行下钻

<sunburst:SfSunburstChart ItemsSource="{Binding Data}" 
                          ValueMemberPath="Value">
    
    <sunburst:SfSunburstChart.Behaviors>
        
        <sunburst:SunburstZoomingBehavior EnableZooming="True"
                                         ToolBarHorizontalAlignment="Right"
                                         ToolBarVerticalAlignment="Top"/>
    </sunburst:SfSunburstChart.Behaviors>
    
</sunburst:SfSunburstChart>

适用场景： 用户需要通过缩放特定类别来探索深层次结构。

模式 4：使用渐变画笔的自定义调色板

<sunburst:SfSunburstChart ItemsSource="{Binding Data}" ValueMemberPath="Value" Palette="Custom">
    
    <sunburst:SfSunburstChart.ColorModel>
        <sunburst:SunburstColorModel>
            <sunburst:SunburstColorModel.CustomBrushes>
                <LinearGradientBrush>
                    <GradientStop Color="#FF6B88E6" Offset="0"/>
                    <GradientStop Color="#FF2C5AA0" Offset="1"/>
                </LinearGradientBrush>
                <LinearGradientBrush>
                    <GradientStop Color="#FFE67E6B" Offset="0"/>
                    <GradientStop Color="#FFA0422C" Offset="1"/>
                </LinearGradientBrush>
            </sunburst:SunburstColorModel.CustomBrushes>
        </sunburst:SunburstColorModel>
    </sunburst:SfSunburstChart.ColorModel>
    
</sunburst:SfSunburstChart>

适用场景： 匹配企业品牌形象或创建自定义配色主题。

模式 5：带旋转效果的入场动画

<sunburst:SfSunburstChart ItemsSource="{Binding Data}" 
                          ValueMemberPath="Value"
                          EnableAnimation="True"
                          AnimationType="Rotation"
                          AnimationDuration="1500">
    
</sunburst:SfSunburstChart>

适用场景： 添加平滑的入场动画以提升视觉效果。

关键属性

核心数据绑定

• ItemsSource – IEnumerable 数据源（层次结构数据集合）
• ValueMemberPath – 用于计算扇区大小的属性名称
• Levels – 定义层次结构的 SunburstHierarchicalLevel 集合
• GroupMemberPath（在层级上）– 各层级用于类别分组的属性

视觉元素

• Header – 图表标题
• Legend – 用于识别类别的 SunburstLegend
• DataLabelInfo – 用于显示分区标签的 SunburstDataLabelInfo
• Palette – 配色方案（Metro、AutumnBrights、Custom 等）
• ColorModel – 自定义画笔定义

区域属性

• Radius – 图表外半径（0.0 到 1.0，默认值：0.9）
• InnerRadius – 中心圆半径（0.0 到 1.0，默认值：0.2）
• StartAngle – 起始角度（度，默认值：0）
• EndAngle – 结束角度（度，默认值：360）

动画

• EnableAnimation – 启用／禁用入场动画
• AnimationType – FadeIn 或 Rotation
• AnimationDuration – 动画时长（毫秒）

行为

• SunburstToolTipBehavior – 工具提示配置
• SunburstSelectionBehavior – 选择交互
• SunburstZoomingBehavior – 下钻／缩放

常见用例

用例 1：组织层级可视化

场景： 按地区、部门、团队和职位展示公司结构。

解决方案：

• 4 个层级（地区 → 部门 → 团队 → 职位）
• ValueMemberPath = "EmployeeCount"
• 启用选择功能以突出显示部门
• 添加显示员工人数的工具提示

用例 2：文件系统浏览器

场景： 按文件夹层级可视化磁盘使用情况。

解决方案：

• 3-5 个层级（驱动器 → 文件夹 → 子文件夹 → 文件）
• ValueMemberPath = "SizeInBytes"
• 启用缩放功能以便下钻浏览
• 使用自定义调色板，通过颜色深浅显示大小

用例 3：销售仪表板

场景： 按地区、类别、产品和 SKU 展示销售情况。

解决方案：

• 4 个层级（地区 → 类别 → 产品 → SKU）
• ValueMemberPath = "SalesAmount"
• 使用 ToggleSegmentVisibility 实现可交互图例
• 使用自定义数据标签显示销售额

用例 4：预算分配查看器

场景： 展示各部门和项目的预算分配情况。

解决方案：

• 3 个层级（部门 → 项目 → 阶段）
• ValueMemberPath = "BudgetAmount"
• 使用与预算类别相匹配的自定义调色板
• 使用自定义画笔突出显示所选内容

用例 5：网站分析层级

场景： 按国家、页面类别和页面展示网站流量。

解决方案：

• 3 个层级（国家 → 类别 → 页面）
• ValueMemberPath = "PageViews"
• 使用入场动画（FadeIn）
• 工具提示中显示其他指标（跳出率、页面停留时间）

最佳实践

1. 数据结构： 确保数据模型中每个层级都有独立属性，并包含一个用于 ValueMemberPath 的数值属性。

2. 层级数量： 限制为 3-5 个层级，以获得最佳可读性。层级过多会导致外环过于拥挤。

3. 数值一致性： 确保 ValueMemberPath 指向表示大小／数量／金额的正数值。

4. 标签可读性： 使用 LabelOverflowMode="Trim" 或 "Hide"，避免较小分区上的标签过于拥挤。

5. 交互功能： 结合使用工具提示和选择功能，以获得最佳用户体验。对于深层级结构，可添加缩放功能。

6. 性能： 对于大型数据集（1000+ 项），可考虑聚合数据或限制可见层级。

7. 颜色一致性： 使用预定义调色板以保持一致性，或创建与应用主题相匹配的自定义调色板。

8. MVVM 模式： 在 ViewModel 中实现 INotifyPropertyChanged，以便动态更新数据。

故障排除

图表未显示：

• 确认 ItemsSource 绑定正确
• 检查 ValueMemberPath 是否与数值属性匹配
• 确保至少定义了一个 SunburstHierarchicalLevel
• 确认数据集合不为空

扇区大小不正确：

• 确认 ValueMemberPath 指向数值属性
• 检查数据中是否存在 null 或负值
• 确保属性名称完全匹配（区分大小写）

标签重叠：

• 将 LabelOverflowMode 设置为 "Hide" 或 "Trim"
• 减小 DataLabelInfo 上的 FontSize
• 考虑隐藏较小扇区上的标签

图例未显示：

• 确认已设置 Legend 属性（非 null）
• 检查 DockPosition 是否有效
• 确保数据中存在一级类别