mcpField
S
syncfusion-winui-radial-gauge

syncfusion-winui-radial-gauge

github.com/syncfusion数据与数据库147 次安装1 周前更新
代码仓库

关于 syncfusion-winui-radial-gauge

为 Syncfusion WinUI Radial Gauge 提供圆形数据可视化实现指导，面向构建指标和测量界面的 WinUI 开发者。内容包括坐标轴、指针、范围、注释、动画及交互。

主要功能

  1. 01配置圆形坐标轴与刻度
  2. 02添加四种指针类型
  3. 03显示颜色区分的数值范围
  4. 04放置文本、图像和界面注释
  5. 05为数值变化添加动画并支持拖动
  6. 06显示多个坐标轴

适用场景

  1. 01制作速度或温度仪表
  2. 02显示 KPI 或进度指标
  3. 03构建可交互的音量控件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/syncfusion/winui-ui-components-skills --skill syncfusion-winui-radial-gauge

安装后在 Claude Code 中输入/syncfusion-winui-radial-gauge确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
animation.md
annotations.md
api-reference.md
axis-configuration.md
getting-started.md
pointers.md
ranges.md

详细介绍

实现径向仪表

Syncfusion WinUI 径向仪表（SfRadialGauge）是一种多用途数据可视化控件，可在圆形刻度上显示数值。它非常适合创建速度计、温度监视器、仪表盘仪表、计量仪表、多轴时钟、手表、活动仪表、指南针及其他圆形指示器。

何时使用此技能

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

  • 以圆形方式显示指标 - 速度计、转速表、燃油表、压力表
  • 创建仪表盘指示器 - KPI 仪表、性能监视器、进度指示器
  • 构建测量显示 - 温度监视器、湿度仪表、电压表
  • 实现活动追踪器 - 健身环、进度圆环、目标追踪器
  • 设计自定义表盘 - 指南针显示、钟面、方向指示器
  • 直观显示范围 - 颜色编码区域（红／黄／绿）、危险／警告／安全区域
  • 动态显示数值变化 - 使用指针动画实现平滑过渡
  • 支持用户交互 - 可拖动指针以调整数值
  • 显示多个指标 - 使用多轴仪表显示相关数据点

组件概览

主要功能：

  • 圆形轴，具有可自定义的刻度、标签、刻度线和样式
  • 四种指针类型 - 针形、形状、内容和范围指针
  • 可视化范围 - 支持渐变的颜色编码区段
  • 注释 - 添加文本、图像或自定义 UI 元素
  • 动画 - 使用缓动函数实现平滑的指针移动
  • 交互式拖动 - 用户可调整指针数值
  • 多轴 - 在一个仪表中显示多个刻度
  • 灵活样式 - 使用像素或比例设置尺寸，适用于响应式布局

文档与导航指南

入门

📄 阅读： references/getting-started.md

在以下情况下阅读：

  • 安装并设置 Syncfusion WinUI 径向仪表
  • 创建第一个径向仪表
  • 添加基本轴、范围、指针和注释
  • 了解组件结构
  • 获取完整的可运行示例
轴配置

📄 阅读： references/axis-configuration.md

在以下情况下阅读：

  • 配置轴的最小值、最大值和间隔
  • 自定义起始角度和结束角度（180°、270°、360° 等）
  • 调整轴半径和位置
  • 设置轴线样式（宽度、颜色、渐变）
  • 自定义标签（格式、模板、旋转、位置）
  • 配置刻度线（主／次刻度线、长度、样式、位置）
  • 显示／隐藏轴元素
  • 实现多轴
  • 创建自定义刻度范围
  • 处理轴事件
指针

📄 阅读： references/pointers.md

在以下情况下阅读：

  • 添加带有旋钮和尾部的针形指针
  • 使用形状指针（圆形、菱形、三角形等）
  • 创建带有自定义 UI 的内容指针
  • 实现用于弧形区段的范围指针
  • 在一个轴上添加多个指针
  • 启用指针交互式拖动
  • 为指针移动添加动画
  • 处理指针数值更改事件
  • 自定义指针外观和偏移量
范围

📄 阅读： references/ranges.md

在以下情况下阅读：

  • 创建颜色编码数值范围
  • 定义范围的起始值和结束值
  • 自定义范围宽度（均匀或渐缩）
  • 为范围应用渐变
  • 设置范围位置（相对于轴的偏移量）
  • 为范围添加标签
  • 使用范围颜色设置轴元素
  • 创建基于模板的范围标签
注释

📄 阅读： references/annotations.md

在以下情况下阅读：

  • 在指定位置添加文本标签
  • 在仪表上显示图像
  • 使用角度或轴数值设置注释位置
  • 调整注释与中心的距离
  • 对齐注释（水平／垂直）
  • 将自定义 UI 元素添加为注释
动画

📄 阅读： references/animation.md

适用于以下需求：

  • 启用指针动画
  • 控制动画时长
  • 应用缓动函数（线性、弹跳、弹性等）
  • 创建平滑的数值过渡
API 参考

📄 阅读： references/api-reference.md

适用于以下需求：

  • 查找特定属性
  • 了解类层次结构
  • 查找可用的自定义选项
  • 查阅完整的 API 文档

快速入门示例

以下是一个包含范围和指针的基本速度表：

<Window x:Class="RadialGaugeApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:gauge="using:Syncfusion.UI.Xaml.Gauges">
    
    <gauge:SfRadialGauge>
        <gauge:SfRadialGauge.Axes>
            <gauge:RadialAxis Maximum="150"
                              Interval="10">
                
                
                <gauge:RadialAxis.Ranges>
                    <gauge:GaugeRange StartValue="0"
                                      EndValue="50"
                                      Background="Green" />
                    <gauge:GaugeRange StartValue="50"
                                      EndValue="100"
                                      Background="Orange" />
                    <gauge:GaugeRange StartValue="100"
                                      EndValue="150"
                                      Background="Red" />
                </gauge:RadialAxis.Ranges>
                
                
                <gauge:RadialAxis.Pointers>
                    <gauge:NeedlePointer Value="90"
                                         EnableAnimation="True" />
                </gauge:RadialAxis.Pointers>
                
                
                <gauge:RadialAxis.Annotations>
                    <gauge:GaugeAnnotation DirectionUnit="Angle"
                                           DirectionValue="90"
                                           PositionFactor="0.5">
                        <gauge:GaugeAnnotation.Content>
                            <TextBlock Text="90"
                                       FontSize="25"
                                       FontWeight="Bold" />
                        </gauge:GaugeAnnotation.Content>
                    </gauge:GaugeAnnotation>
                </gauge:RadialAxis.Annotations>
                
            </gauge:RadialAxis>
        </gauge:SfRadialGauge.Axes>
    </gauge:SfRadialGauge>
    
</Window>

using Syncfusion.UI.Xaml.Gauges;
using Microsoft.UI.Xaml;

namespace RadialGaugeApp
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
            
            // Can also create gauge programmatically
            SfRadialGauge gauge = new SfRadialGauge();
            
            RadialAxis axis = new RadialAxis();
            axis.Maximum = 150;
            axis.Interval = 10;
            
            // Add ranges
            axis.Ranges.Add(new GaugeRange { 
                StartValue = 0, 
                EndValue = 50, 
                Background = new SolidColorBrush(Colors.Green) 
            });
            
            // Add pointer
            axis.Pointers.Add(new NeedlePointer { 
                Value = 90, 
                EnableAnimation = true 
            });
            
            gauge.Axes.Add(axis);
        }
    }
}

常见模式

模式 1：温度监视器
<gauge:SfRadialGauge>
    <gauge:SfRadialGauge.Axes>
        <gauge:RadialAxis Minimum="-60"
                          Maximum="60"
                          Interval="20"
                          StartAngle="180"
                          EndAngle="0">
            
            <gauge:RadialAxis.Ranges>
                <gauge:GaugeRange StartValue="-60"
                                  EndValue="0"
                                  Background="#2196F3" />
                <gauge:GaugeRange StartValue="0"
                                  EndValue="30"
                                  Background="#4CAF50" />
                <gauge:GaugeRange StartValue="30"
                                  EndValue="60"
                                  Background="#FF5722" />
            </gauge:RadialAxis.Ranges>
            
            <gauge:RadialAxis.Pointers>
                <gauge:RangePointer Value="25"
                                    PointerWidth="15"
                                    EnableAnimation="True" />
            </gauge:RadialAxis.Pointers>
            
            <gauge:RadialAxis.Annotations>
                <gauge:GaugeAnnotation>
                    <gauge:GaugeAnnotation.Content>
                        <TextBlock Text="25°C"
                                   FontSize="30"
                                   FontWeight="Bold" />
                    </gauge:GaugeAnnotation.Content>
                </gauge:GaugeAnnotation>
            </gauge:RadialAxis.Annotations>
            
        </gauge:RadialAxis>
    </gauge:SfRadialGauge.Axes>
</gauge:SfRadialGauge>
模式 2：可交互的可拖动仪表
<gauge:SfRadialGauge>
    <gauge:SfRadialGauge.Axes>
        <gauge:RadialAxis ShowTicks="False"
                          AxisLineFill="CornflowerBlue"
                          AxisLineWidth="30">
            
            <gauge:RadialAxis.Pointers>
                <gauge:ShapePointer Value="60"
                                    IsInteractive="True"
                                    MarkerOffset="-30"
                                    Background="Indigo"
                                    ValueChanged="Pointer_ValueChanged" />
            </gauge:RadialAxis.Pointers>
            
        </gauge:RadialAxis>
    </gauge:SfRadialGauge.Axes>
</gauge:SfRadialGauge>

private void Pointer_ValueChanged(object sender, ValueChangedEventArgs e)
{
    // Handle pointer value changes
    Debug.WriteLine($"New value: {e.Value}");
}
模式 3：多轴时钟
<gauge:SfRadialGauge>
    <gauge:SfRadialGauge.Axes>
        
        <gauge:RadialAxis Maximum="12"
                          Interval="1"
                          RadiusFactor="0.8"
                          LabelPosition="Outside">
            <gauge:RadialAxis.Pointers>
                <gauge:NeedlePointer Value="10"
                                     NeedleLength="0.5"
                                     NeedleEndWidth="8" />
            </gauge:RadialAxis.Pointers>
        </gauge:RadialAxis>
        
        
        <gauge:RadialAxis Maximum="60"
                          Interval="5"
                          RadiusFactor="0.95"
                          LabelPosition="Outside">
            <gauge:RadialAxis.Pointers>
                <gauge:NeedlePointer Value="35"
                                     NeedleLength="0.7"
                                     NeedleEndWidth="4" />
            </gauge:RadialAxis.Pointers>
        </gauge:RadialAxis>
    </gauge:SfRadialGauge.Axes>
</gauge:SfRadialGauge>
模式 4：带百分比的进度环
<gauge:SfRadialGauge>
    <gauge:SfRadialGauge.Axes>
        <gauge:RadialAxis ShowLabels="False"
                          ShowTicks="False"
                          StartAngle="270"
                          EndAngle="270"
                          Maximum="100"
                          AxisLineWidth="20"
                          AxisLineFill="LightGray">
            
            <gauge:RadialAxis.Pointers>
                <gauge:RangePointer Value="73"
                                    PointerWidth="20"
                                    Background="#4CAF50"
                                    CornerStyle="BothCurve"
                                    EnableAnimation="True" />
            </gauge:RadialAxis.Pointers>
            
            <gauge:RadialAxis.Annotations>
                <gauge:GaugeAnnotation>
                    <gauge:GaugeAnnotation.Content>
                        <TextBlock>
                            <Run Text="73" FontSize="40" FontWeight="Bold" />
                            <Run Text="%" FontSize="20" />
                        </TextBlock>
                    </gauge:GaugeAnnotation.Content>
                </gauge:GaugeAnnotation>
            </gauge:RadialAxis.Annotations>
            
        </gauge:RadialAxis>
    </gauge:SfRadialGauge.Axes>
</gauge:SfRadialGauge>

按类别划分的关键属性

SfRadialGauge
  • Axes - RadialAxis 对象集合
  • CanScaleToFit - 根据起始角度和结束角度调整轴的位置
轴配置
  • Minimum / Maximum - 轴的数值范围
  • Interval - 标签之间的间距
  • StartAngle / EndAngle - 圆弧角度（0-360°）
  • RadiusFactor - 轴的大小（可用空间的 0-1 倍）
  • IsInversed - 逆时针方向
轴样式
  • AxisLineWidth / AxisLineWidthUnit - 线条粗细（Pixel/Factor）
  • AxisLineFill - 线条颜色/画刷
  • GradientStops - 轴线上渐变的颜色
  • ShowAxisLine - 轴线可见性
标签与刻度
  • ShowLabels / ShowTicks - 元素可见性
  • LabelFormat - 数字格式（货币、百分比等）
  • LabelTemplate - 自定义标签模板
  • LabelPosition / TickPosition - 内侧/外侧/跨轴
  • LabelOffset / TickOffset - 与轴的距离
  • MajorTickLength / MinorTickLength - 刻度长度
  • MinorTicksPerInterval - 次刻度数量
指针（所有类型）
  • Value - 当前指针数值
  • EnableAnimation - 数值变化时播放动画
  • AnimationDuration - 动画时长（ms）
  • AnimationEasingFunction - 缓动函数
  • IsInteractive - 启用拖动
针形指针专属
  • NeedleLength / NeedleStartWidth / NeedleEndWidth - 针形
  • KnobRadius / KnobFill / KnobStroke - 中心旋钮
  • TailLength / TailWidth - 指针尾部
形状指针专属
  • ShapeType - 圆形、菱形、三角形等
  • ShapeHeight / ShapeWidth - 形状大小
  • MarkerOffset - 与轴的距离
范围指针专属
  • PointerWidth - 圆弧宽度
  • CornerStyle - BothFlat、BothCurve、StartCurve、EndCurve
范围
  • StartValue / EndValue - 范围边界
  • StartWidth / EndWidth - 范围粗细
  • WidthUnit - 像素或比例
  • RangeOffset - 与轴的距离
  • Background - 范围颜色
  • GradientStops - 渐变颜色
  • Label / LabelTemplate - 范围标签
注释
  • DirectionUnit - 角度或轴值
  • DirectionValue - 位置值
  • PositionFactor - 与中心的距离（0-1）
  • Content - 任意 UIElement

常见用例

  1. 速度表/转速表 - 显示车辆速度/RPM，并用颜色标示危险区域
  2. 温度计 - 带有低温/适中/高温范围的温度监视器
  3. 压力计 - 用于轮胎压力、液压压力，并显示阈值指示
  4. 电池电量 - 带百分比注释的圆形电池指示器
  5. 健身追踪器 - 显示步数、卡路里和距离的活动环
  6. KPI 仪表盘 - 带有目标阈值的业务指标
  7. 音量控制 - 可拖动的圆形音量调节器
  8. 罗盘 - 带有度数刻度的方向仪表
  9. 计时器/秒表 - 可视化已用时间
  10. 进度指示器 - 任务完成进度、下载进度
  11. 评分显示 - 可视化分数（1-10 分制）
  12. 多指标显示 - 使用多个轴显示相关测量值

备注

  • 所有尺寸属性都支持 Pixel 或 Factor 单位，适用于响应式布局
  • Factor 值（0-1）会乘以轴半径，以实现按比例调整尺寸
  • 更新值时使用 animations 实现平滑过渡
  • 启用 IsInteractive，支持用户拖动并调整指针
  • 多个轴可以共享同一中心，并使用不同的半径系数
  • GradientStops 根据轴值实现平滑的颜色过渡
  • 注释可以包含任意 WinUI UIElement（TextBlock、Image、Grid 等）

安装： 安装 Syncfusion.Gauge.WinUI NuGet 包

命名空间： Syncfusion.UI.Xaml.Gauges

GitHub 示例： WinUI Radial Gauge Demos

评论

支持 Markdown