syncfusion-wpf-radial-gauge

实现圆形仪表（径向仪表）

关于实现 Syncfusion® WPF Radial Gauge (SfCircularGauge) 组件的综合指南，用于在圆形刻度上可视化数值。本指南可帮助你创建高度可自定义的仪表，包括速度计、温度指示器、KPI 仪表板和进度仪表，并支持指针、范围和交互功能。

何时使用本指南

在以下情况下使用本指南：

• 创建圆形仪表以进行数据可视化（速度计、KPI 仪表、温度仪表）
• 实现指针，以在圆形刻度上指示当前值
• 添加范围指针以显示进度或完成情况（彩色圆弧）
• 配置符号指针，用于标记样式的数值指示器
• 设置刻度的起始值、结束值、角度和间隔
• 添加可视范围以指示不同区域（低、中、高、危险区域）
• 自定义仪表刻度上的标签和刻度线
• 启用指针拖动以交互式选择数值
• 为指针移动添加动画以实现平滑过渡
• 添加注释以在仪表上显示其他信息
• 创建多刻度仪表以比较多项指标
• 构建包含多个仪表的仪表板可视化

当你需要在圆形刻度上显示数值，并使用可自定义的指针、范围和可视指示器时，本指南对于创建任何圆形／径向可视化都必不可少。

组件概述

SfCircularGauge 是一个功能强大的数据可视化组件，可在圆形刻度上显示数值。它具有高度可自定义性，并支持多种可视元素：

关键元素

• **刻度：**可配置起始值、结束值、角度和扫描方向的圆形刻度
• **指针：**三种类型——指针式（传统仪表指针）、范围式（彩色圆弧）、符号式（标记图标）
• **范围：**用于标记不同数值范围（例如，低／中／高）的可视区域
• **标签：**沿刻度显示的数值标签
• **刻度线：**用于精确读取数值的主刻度线和次刻度线
• **边框：**刻度周围的圆形边框
• **标题：**仪表的标题或标签
• **注释：**叠加在仪表上的自定义视图、文本或图像

常见用例

• 速度计——使用指针指示车辆速度
• KPI 仪表板——使用范围指针显示进度的业务指标
• 温度仪表——带有彩色区域的气候控制显示
• 进度仪表——带有百分比显示的完成情况指示器
• 性能指示器——系统指标（CPU、内存、电池）
• 医疗仪器——健康监测显示
• 工业控制——机器运行指示器

文档与导航指南

本指南按功能全面介绍圆形仪表的所有特性。

入门

📄 阅读： references/getting-started.md

**阅读时机：**设置你的第一个圆形仪表、安装软件包并了解基本结构时。

涵盖主题：

• 安装 Syncfusion.SfGauge.WPF NuGet 软件包
• 程序集引用和命名空间导入
• 创建第一个 SfCircularGauge
• 添加基本刻度、指针和标题
• 完整的最小可运行示例
• 许可证配置

刻度配置

📄 阅读： references/scales-and-configuration.md

**阅读时机：**配置圆形刻度的数值、角度、间隔和外观时。

涵盖主题：

• 设置刻度范围的 StartValue 和 EndValue
• 配置 StartAngle 和 SweepAngle（部分圆或整圆）
• 设置标签频率的 Interval
• 扫描方向（顺时针／逆时针）
• 在单个仪表中添加多个刻度
• 使用 SpacingMargin 设置刻度半径和大小
• 用于自适应大小的 RadiusFactor

指针（值指示器）

📄 阅读： references/pointers.md

适用场景： 添加指针、范围指针或符号标记来指示值。

涵盖主题：

• 指针类型（矩形、三角形、锥形、箭头）
• 指针自定义（长度、描边、厚度、旋钮、尾部）
• 用于进度可视化的范围指针
• 范围指针位置（内部、外部、交叉、自定义）
• 符号指针类型（箭头、菱形、椭圆、三角形、五边形等）
• 自定义符号模板
• 在一个刻度上使用多个指针
• 指针值绑定和更新

范围（可视化区域）

📄 阅读： references/ranges.md

适用场景： 添加彩色区域，以指示不同的值范围（低／中／高）。

涵盖主题：

• 使用 StartValue 和 EndValue 创建范围
• 自定义范围描边和厚度
• 使用 Offset 设置范围位置
• 使用多个范围可视化不同区域
• 设置范围起始／结束偏移量以自定义位置
• 渐变填充样式
• 使用场景（温度区域、性能区间、危险区域）

标签和刻度线

📄 阅读： references/labels-and-ticks.md

适用场景： 自定义刻度标签、主刻度线和次刻度线。

涵盖主题：

• 标签描边和字体自定义
• 标签位置（内部、外部、自定义）
• 标签偏移量和格式
• 标签单位前缀／后缀
• MajorTickSettings 配置
• MinorTickSettings 和 MinorTicksPerInterval
• 刻度线长度、描边和厚度
• 隐藏标签或刻度线

边框和外观

📄 阅读： references/rim-and-appearance.md

适用场景： 设置仪表边框、背景和尺寸的样式，以及应用主题。

涵盖主题：

• ShowRim 属性和边框自定义
• RimStroke 和 RimStrokeThickness
• 仪表尺寸（Height、Width、Radius）
• 背景和视觉样式
• 使用 SfSkinManager 设置主题
• 内置主题（MaterialLight、FluentDark 等）
• 自定义样式方法

标题

📄 阅读： references/header.md

适用场景： 为仪表添加标题或标签。

涵盖主题：

• 用于文本标题的 GaugeHeader 属性
• 自定义标题视图
• 标题对齐选项
• 用于自定义位置的 GaugeHeaderPosition
• 标题样式和格式
• 标题中的多个文本元素

注释

📄 阅读： references/annotations.md

适用场景： 在圆形仪表上叠加自定义视图、文本、图像或嵌套仪表。

涵盖主题：

• 添加文本注释
• 图像注释
• 自定义视图注释（嵌套仪表、控件）
• 使用 Angle 属性定位
• Offset 属性（从中心到边缘的范围为 0 到 1）
• 使用 ViewMargin 进行像素级精确定位
• 多个注释
• 动态更新注释

高级功能

📄 阅读： references/advanced-features.md

适用场景： 实现动画、指针拖动、事件和 MVVM 模式。

涵盖主题：

• 指针动画（EnableAnimation、AnimationDuration）
• 交互式指针拖动（EnableDragging）
• 事件（ValueChangeStarted、ValueChanging、ValueChanged、ValueChangeCompleted）
• PointerPositionChanged 事件
• 使用数据绑定的 MVVM 模式
• INotifyPropertyChanged 实现
• 实时仪表更新
• 性能优化

快速入门示例

以下是一个完整示例，用于创建带有指针、范围区域和标题的速度表：

XAML 实现

<Window xmlns:gauge="clr-namespace:Syncfusion.UI.Xaml.Gauges;assembly=Syncfusion.SfGauge.Wpf">
    
    <gauge:SfCircularGauge Height="300" Width="300"
                           HeaderAlignment="Custom"
                           GaugeHeaderPosition="0.63,0.75">
        
        
        <gauge:SfCircularGauge.GaugeHeader>
            <TextBlock Text="Speedometer" 
                       FontSize="16" 
                       FontWeight="SemiBold"
                       Foreground="Black"/>
        </gauge:SfCircularGauge.GaugeHeader>
        
        <gauge:SfCircularGauge.Scales>
            <gauge:CircularScale StartValue="0" 
                                 EndValue="160" 
                                 Interval="20"
                                 StartAngle="130"
                                 SweepAngle="280"
                                 ShowRim="True"
                                 RimStroke="LightGray"
                                 RimStrokeThickness="5">
                
                
                <gauge:CircularScale.Ranges>
                    <gauge:CircularRange StartValue="0" EndValue="80" 
                                         Stroke="Green" StrokeThickness="5"/>
                    <gauge:CircularRange StartValue="80" EndValue="120" 
                                         Stroke="Orange" StrokeThickness="5"/>
                    <gauge:CircularRange StartValue="120" EndValue="160" 
                                         Stroke="Red" StrokeThickness="5"/>
                </gauge:CircularScale.Ranges>
                
                
                <gauge:CircularScale.Pointers>
                    <gauge:CircularPointer PointerType="NeedlePointer"
                                           Value="85"
                                           NeedlePointerType="Triangle"
                                           NeedleLengthFactor="0.6"
                                           NeedlePointerStroke="#333"
                                           NeedlePointerStrokeThickness="5"
                                           KnobFill="#333"
                                           KnobStroke="#333"
                                           PointerCapDiameter="15"/>
                </gauge:CircularScale.Pointers>
            </gauge:CircularScale>
        </gauge:SfCircularGauge.Scales>
    </gauge:SfCircularGauge>
    
</Window>

C# 代码隐藏

using Syncfusion.UI.Xaml.Gauges;
using System.Windows;
using System.Windows.Media;

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
        
        // License registration (in App.xaml.cs OnStartup)
        // Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense("YOUR_LICENSE_KEY");
    }
}

以编程方式创建

SfCircularGauge gauge = new SfCircularGauge();
gauge.Height = 300;
gauge.Width = 300;

// Header
TextBlock header = new TextBlock
{
    Text = "Speedometer",
    FontSize = 16,
    FontWeight = FontWeights.SemiBold,
    Foreground = new SolidColorBrush(Colors.Black)
};
gauge.GaugeHeader = header;
gauge.HeaderAlignment = HeaderAlignment.Custom;
gauge.GaugeHeaderPosition = new Point(0.63, 0.75);

// Scale
CircularScale scale = new CircularScale
{
    StartValue = 0,
    EndValue = 160,
    Interval = 20,
    StartAngle = 130,
    SweepAngle = 280,
    ShowRim = true,
    RimStroke = new SolidColorBrush(Colors.LightGray),
    RimStrokeThickness = 5
};

// Ranges
scale.Ranges.Add(new CircularRange 
{ 
    StartValue = 0, EndValue = 80, 
    Stroke = new SolidColorBrush(Colors.Green), 
    StrokeThickness = 5 
});
scale.Ranges.Add(new CircularRange 
{ 
    StartValue = 80, EndValue = 120, 
    Stroke = new SolidColorBrush(Colors.Orange), 
    StrokeThickness = 5 
});
scale.Ranges.Add(new CircularRange 
{ 
    StartValue = 120, EndValue = 160, 
    Stroke = new SolidColorBrush(Colors.Red), 
    StrokeThickness = 5 
});

// Needle Pointer
CircularPointer pointer = new CircularPointer
{
    PointerType = PointerType.NeedlePointer,
    Value = 85,
    NeedlePointerType = NeedlePointerType.Triangle,
    NeedleLengthFactor = 0.6,
    NeedlePointerStroke = new SolidColorBrush(Color.FromRgb(51, 51, 51)),
    NeedlePointerStrokeThickness = 5,
    KnobFill = new SolidColorBrush(Color.FromRgb(51, 51, 51)),
    KnobStroke = new SolidColorBrush(Color.FromRgb(51, 51, 51)),
    PointerCapDiameter = 15
};
scale.Pointers.Add(pointer);

gauge.Scales.Add(scale);
this.Content = gauge;

常见模式

模式 1：使用范围指针的进度仪表

使用范围指针可视化进度／完成情况：

<gauge:SfCircularGauge>
    <gauge:SfCircularGauge.Scales>
        <gauge:CircularScale StartValue="0" EndValue="100" 
                             SweepAngle="360"
                             RimStroke="LightGray" 
                             RimStrokeThickness="20">
            <gauge:CircularScale.Pointers>
                <gauge:CircularPointer PointerType="RangePointer"
                                       Value="75"
                                       RangePointerStroke="DeepSkyBlue"
                                       RangePointerStrokeThickness="20"
                                       RangeCap="Both"/>
            </gauge:CircularScale.Pointers>
        </gauge:CircularScale>
    </gauge:SfCircularGauge.Scales>
</gauge:SfCircularGauge>

模式 2：带彩色区域的温度计

使用多个范围创建温度显示：

<gauge:CircularScale StartValue="-30" EndValue="50">
    <gauge:CircularScale.Ranges>
        <gauge:CircularRange StartValue="-30" EndValue="0" 
                             Stroke="Blue" StrokeThickness="10"/>
        <gauge:CircularRange StartValue="0" EndValue="25" 
                             Stroke="Green" StrokeThickness="10"/>
        <gauge:CircularRange StartValue="25" EndValue="50" 
                             Stroke="Red" StrokeThickness="10"/>
    </gauge:CircularScale.Ranges>
    <gauge:CircularScale.Pointers>
        <gauge:CircularPointer PointerType="NeedlePointer" Value="22"/>
    </gauge:CircularScale.Pointers>
</gauge:CircularScale>

模式 3：可交互的可拖动指针

启用用户通过拖动指针进行交互：

<gauge:CircularPointer PointerType="SymbolPointer"
                       Symbol="InvertedTriangle"
                       EnableDragging="True"
                       EnableAnimation="False"
                       Value="50"
                       ValueChanged="Pointer_ValueChanged"/>

private void Pointer_ValueChanged(object sender, ValueChangedEventArgs e)
{
    // Update UI or data model with new value
    CurrentValue = e.Value;
}

模式 4：多刻度仪表

在一个仪表中显示多项指标：

<gauge:SfCircularGauge SpacingMargin="0.7">
    <gauge:SfCircularGauge.Scales>
        
        <gauge:CircularScale Radius="180">
            <gauge:CircularScale.Pointers>
                <gauge:CircularPointer Value="60"/>
            </gauge:CircularScale.Pointers>
        </gauge:CircularScale>
        
        
        <gauge:CircularScale Radius="100">
            <gauge:CircularScale.Pointers>
                <gauge:CircularPointer Value="80"/>
            </gauge:CircularScale.Pointers>
        </gauge:CircularScale>
    </gauge:SfCircularGauge.Scales>
</gauge:SfCircularGauge>

模式 5：MVVM 数据绑定

将指针值绑定到 ViewModel 属性：

<gauge:CircularPointer Value="{Binding CurrentSpeed, Mode=TwoWay}"/>

public class GaugeViewModel : INotifyPropertyChanged
{
    private double _currentSpeed;
    public double CurrentSpeed
    {
        get => _currentSpeed;
        set
        {
            _currentSpeed = value;
            OnPropertyChanged(nameof(CurrentSpeed));
        }
    }
    
    // INotifyPropertyChanged implementation
}

关键属性摘要

SfCircularGauge

属性	类型	描述
Scales	ObservableCollection	仪表中的刻度集合
GaugeHeader	object	仪表的标题内容
HeaderAlignment	HeaderAlignment	标题位置（顶部、底部、自定义）
GaugeHeaderPosition	Point	自定义标题位置（0-1，0-1）
Annotations	CircularGaugeAnnotationCollection	自定义注释叠层
SpacingMargin	double	多个刻度之间的间距（0.1-1）

CircularScale

属性	类型	描述
StartValue	double	刻度的最小值
EndValue	double	刻度的最大值
Interval	double	标签间隔
StartAngle	double	起始角度（0-360）
SweepAngle	double	扫掠角度（0-360）
SweepDirection	SweepDirection	顺时针或逆时针
Radius	double	刻度半径
RadiusFactor	double	半径系数（0-1）
ShowRim	bool	显示/隐藏边框
RimStroke	Brush	边框颜色
RimStrokeThickness	double	边框粗细
Pointers	ObservableCollection	指针集合
Ranges	ObservableCollection	范围集合

CircularPointer

属性	类型	描述
PointerType	PointerType	NeedlePointer、RangePointer、SymbolPointer
Value	double	当前指针值
EnableAnimation	bool	启用平滑动画
AnimationDuration	int	动画时长（ms）
EnableDragging	bool	启用交互式拖动
NeedlePointerType	NeedlePointerType	Rectangle、Triangle、Tapered、Arrow
NeedleLengthFactor	double	指针长度（0-1）
Symbol	Symbol	SymbolPointer 的符号类型
RangeCap	RangeCap	范围端点样式（Start、End、Both、None）

CircularRange

属性	类型	描述
StartValue	double	范围起始值
EndValue	double	范围结束值
Stroke	Brush	范围颜色
StrokeThickness	double	范围粗细
Offset	double	位置偏移（0-1）

常见用例

业务仪表板

创建 KPI 仪表板，使用多个仪表显示销售额、绩效、客户满意度等指标，并通过颜色区分目标区域。

工业监控

构建控制面板，通过仪表显示压力、温度、转速、电压，并实时更新和显示警报区域。

车辆仪表

实现速度表、转速表、燃油表和温度指示器，并模拟逼真的指针运动和警告区域。

健康与健身

显示心率监测器、步数计数器、卡路里追踪器，并通过可视化展示进度和目标区域。

系统监控

创建 CPU 使用率、内存利用率、磁盘空间和网络带宽指示器，并实时更新。

API 参考

• SfCircularGauge API： https://help.syncfusion.com/cr/wpf/Syncfusion.UI.Xaml.Gauges.SfCircularGauge.html
• CircularScale API： https://help.syncfusion.com/cr/wpf/Syncfusion.UI.Xaml.Gauges.CircularScale.html
• CircularPointer API： https://help.syncfusion.com/cr/wpf/Syncfusion.UI.Xaml.Gauges.CircularPointer.html
• CircularRange API： https://help.syncfusion.com/cr/wpf/Syncfusion.UI.Xaml.Gauges.CircularRange.html
• 完整文档： https://help.syncfusion.com/wpf/radial-gauge/overview

---

后续步骤： 根据具体需求查阅上述参考文件。先从“快速入门”开始进行设置，然后按需深入了解特定功能。