syncfusion-winui-linear-gauge

WinUI 线性仪表盘（SfLinearGauge）

在 Windows 桌面应用中实现 Syncfusion WinUI 线性仪表盘（SfLinearGauge）控件的数据可视化综合指南。线性仪表盘控件可在水平或垂直线性刻度上显示数值，并提供丰富的自定义选项、范围、多种指针类型和动画支持。

何时使用此技能

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

• 创建线性仪表盘控件，用于 WinUI 桌面应用中的数据可视化
• 显示数值，采用水平或垂直线性刻度
• 添加范围指示器，通过颜色编码的区段直观展示数值类别
• 使用条形指针，通过填充指示器显示当前值
• 使用形状指针，通过不同形状（圆形、菱形、三角形等）标记数值
• 使用内容指针，在数值位置显示自定义内容（文本、图像、图标）
• 为指针移动添加动画，并自定义持续时间和缓动函数
• 启用交互式仪表盘，支持拖动指针来输入数值
• 自定义坐标轴外观，包括标签、刻度、间隔和格式
• 构建仪表板，显示温度、压力、速度或其他测量值
• 创建进度指示器，提供视觉反馈和范围
• 排查问题，例如仪表盘渲染、指针定位或交互问题

组件概述

SfLinearGauge 是一种多用途数据可视化控件，可在线性刻度上显示数值，并提供以下功能：

• 方向： 水平或垂直仪表盘布局
• 坐标轴自定义： 可配置带标签、刻度、间隔和自定义范围的刻度
• 范围支持： 多个颜色编码范围，用于直观展示数值类别
• 三种指针类型：
  • 条形指针： 从起点延伸到数值位置的填充条
  • 形状指针： 使用内置形状或自定义模板的标记
  • 内容指针： 在数值位置显示自定义内容（文本、图像、图标）
• 多个指针： 在同一刻度上添加多个指针以显示不同数值
• 动画： 通过可自定义的缓动函数实现平滑的指针过渡
• 交互性： 可拖动形状指针以输入数值
• 自定义： 支持丰富的样式、模板、渐变和子内容
• 数据绑定： 支持通过 Value 属性进行 MVVM 友好型绑定

控件结构：

• 单个坐标轴，可配置最小值、最大值和间隔
• 多个范围，用于创建颜色编码的数值区段
• 条形指针集合，用于显示填充指示器
• 标记指针集合，用于显示形状指针和内容指针
• 全面控制外观、位置和行为

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 创建 WinUI 3 桌面应用
• 安装 Syncfusion.Gauge.WinUI NuGet 包
• 在 XAML 中添加线性仪表盘控件
• 在 C# 中添加线性仪表盘控件
• 向仪表盘添加坐标轴
• 添加范围以直观展示数值
• 添加条形指针
• 添加标记指针（形状和内容）
• 完整的可运行示例

坐标轴自定义

📄 阅读： references/axis-customization.md

• 设置最小值和最大值
• 配置标签之间的间隔
• 自定义坐标轴方向（IsInversed）
• 支持镜像坐标轴（IsMirrored）
• 坐标轴方向（水平/垂直）
• 每 100 像素的最大标签数
• 坐标轴线样式（描边、粗细、颜色）
• 控制坐标轴线的可见性
• 自定义标签（字体、颜色、格式）
• 使用标签模板自定义外观
• 设置标签可见性和位置（内侧/外侧）
• 调整标签位置和偏移量
• 自定义刻度（主刻度和次刻度）
• 设置刻度样式和虚线模式
• 设置刻度位置和偏移量
• 自定义刻度范围（对数等）

范围

📄 阅读： references/ranges.md

• 设置范围的起始值和结束值
• 自定义范围宽度（StartWidth、MidWidth、EndWidth）
• 等宽与不同宽度范围
• 自定义背景颜色
• 支持带多个色标的渐变画笔
• 范围位置（轴内、轴外或跨轴）
• 将范围颜色用于轴元素
• 支持将范围子内容用于标签

指针

📄 阅读： references/pointers.md

• 三种指针类型概览
• 条形指针的实现与自定义
• 具有内置形状和自定义形状的形状指针
• 用于文本、图像和图标的内容指针
• 在单个仪表上使用多个指针
• 指针拖动与交互
• 指针事件（ValueChangeStarted、ValueChanging、ValueChanged、ValueChangeCompleted）
• 指针定位与锚定
• 指针尺寸与样式

动画

📄 阅读： references/animation.md

• 启用指针动画
• 配置动画时长
• 动画缓动函数
• 为条形指针应用动画
• 为标记指针应用动画
• 自定义动画时序和效果

快速入门示例

以下是一个可运行的最小示例，帮助你开始使用：

1. 添加命名空间

XAML：

<Window xmlns:gauge="using:Syncfusion.UI.Xaml.Gauges">

C#：

using Syncfusion.UI.Xaml.Gauges;

2. 创建基本线性仪表（XAML）

<Window
    x:Class="GaugeApp.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">
    
    <Grid>
        <gauge:SfLinearGauge>
            <gauge:SfLinearGauge.Axis>
                <gauge:LinearAxis Minimum="0"
                                  Maximum="100"
                                  Interval="10">
                    <gauge:LinearAxis.BarPointers>
                        <gauge:BarPointer Value="60" />
                    </gauge:LinearAxis.BarPointers>
                </gauge:LinearAxis>
            </gauge:SfLinearGauge.Axis>
        </gauge:SfLinearGauge>
    </Grid>
</Window>

3. 或通过编程方式创建（C#）

using Syncfusion.UI.Xaml.Gauges;

namespace GaugeApp
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
            
            // Create gauge programmatically
            SfLinearGauge sfLinearGauge = new SfLinearGauge();
            sfLinearGauge.Axis.Minimum = 0;
            sfLinearGauge.Axis.Maximum = 100;
            sfLinearGauge.Axis.Interval = 10;
            
            // Add bar pointer
            BarPointer barPointer = new BarPointer();
            barPointer.Value = 60;
            sfLinearGauge.Axis.BarPointers.Add(barPointer);
            
            this.Content = sfLinearGauge;
        }
    }
}

4. 设置指针值（可选）

// Update pointer value
barPointer.Value = 75;

// With animation
barPointer.EnableAnimation = true;
barPointer.AnimationDuration = 1000; // 1 second
barPointer.Value = 90;

常见模式

模式 1：带条形指针的基本水平仪表

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Minimum="0" Maximum="100" Interval="10">
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="60" Background="Green" />
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

模式 2：垂直温度仪表

<gauge:SfLinearGauge Orientation="Vertical">
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Minimum="-60" Maximum="60" Interval="20">
            <gauge:LinearAxis.Ranges>
                <gauge:LinearGaugeRange StartValue="-60" EndValue="0" Background="Blue" />
                <gauge:LinearGaugeRange StartValue="0" EndValue="30" Background="Orange" />
                <gauge:LinearGaugeRange StartValue="30" EndValue="60" Background="Red" />
            </gauge:LinearAxis.Ranges>
            
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="25" />
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

模式 3：带多个指针的仪表

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Maximum="140" Interval="10">
            
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="90" />
            </gauge:LinearAxis.BarPointers>
            
            
            <gauge:LinearAxis.MarkerPointers>
                <gauge:LinearShapePointer Value="90"
                                          VerticalAnchor="End"
                                          OffsetPoint="0,-8" />
                
                
                <gauge:LinearContentPointer Value="90"
                                            VerticalAnchor="End"
                                            OffsetPoint="0,-28">
                    <gauge:LinearContentPointer.Content>
                        <TextBlock Text="90%" />
                    </gauge:LinearContentPointer.Content>
                </gauge:LinearContentPointer>
            </gauge:LinearAxis.MarkerPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

模式 4：带可拖动指针的交互式仪表

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis ShowTicks="False"
                          AxisLineStroke="CornflowerBlue"
                          AxisLineStrokeThickness="30">
            <gauge:LinearAxis.MarkerPointers>
                <gauge:LinearShapePointer Value="30"
                                          IsInteractive="True"
                                          OffsetPoint="0,-15"
                                          VerticalAnchor="End"
                                          Fill="Indigo"
                                          ValueChanged="OnPointerValueChanged" />
            </gauge:LinearAxis.MarkerPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

private void OnPointerValueChanged(object sender, ValueChangedEventArgs e)
{
    // Handle value change
    double newValue = e.NewValue;
}

模式 5：带颜色编码范围的仪表

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Maximum="140" Interval="10">
            <gauge:LinearAxis.Ranges>
                <gauge:LinearGaugeRange StartValue="0" EndValue="50" Background="Red" />
                <gauge:LinearGaugeRange StartValue="50" EndValue="100" Background="Orange" />
                <gauge:LinearGaugeRange StartValue="100" EndValue="140" Background="Green" />
            </gauge:LinearAxis.Ranges>
            
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="90" />
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

模式 6：动画指针更新

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Interval="10">
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="60"
                                  EnableAnimation="True"
                                  AnimationDuration="1500">
                    <gauge:BarPointer.AnimationEasingFunction>
                        <CircleEase EasingMode="EaseOut" />
                    </gauge:BarPointer.AnimationEasingFunction>
                </gauge:BarPointer>
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

模式 7：渐变条形指针

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis>
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="40">
                    <gauge:BarPointer.GradientStops>
                        <gauge:GaugeGradientStop Value="0" Color="#FFCC2B5E" />
                        <gauge:GaugeGradientStop Value="40" Color="#FF753A88" />
                    </gauge:BarPointer.GradientStops>
                </gauge:BarPointer>
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

模式 8：ViewModel 数据绑定

public class GaugeViewModel : INotifyPropertyChanged
{
    private double currentValue;
    
    public double CurrentValue
    {
        get => currentValue;
        set
        {
            currentValue = value;
            OnPropertyChanged(nameof(CurrentValue));
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis>
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="{x:Bind ViewModel.CurrentValue, Mode=TwoWay}" />
            </gauge:LinearAxis.BarPointers>
        </gauge:LinearAxis>
    </gauge:SfLinearGauge.Axis>
</gauge:SfLinearGauge>

关键属性参考

仪表属性（SfLinearGauge）

属性	类型	描述
Axis	LinearAxis	获取或设置线性轴配置
IsInversed	bool	获取或设置轴是否反向（从右到左或从下到上）
IsMirrored	bool	获取或设置轴是否镜像（位于相反的一侧）
Orientation	Orientation	获取或设置仪表方向：水平、垂直

轴属性（LinearAxis）

属性	类型	描述
Minimum	double	轴的最小值（默认值：0）
Maximum	double	轴的最大值（默认值：100）
Interval	double	轴上标签之间的间隔
ShowAxisLine	bool	显示或隐藏轴线（默认值：true）
ShowLabels	bool	显示或隐藏轴标签（默认值：true）
ShowTicks	bool	显示或隐藏刻度线（默认值：true）
AxisLineStroke	Brush	轴线颜色
AxisLineStrokeThickness	double	轴线粗细
LabelPosition	GaugeLabelsPosition	标签位置：内部、外部
LabelOffset	double	轴线与标签之间的距离
LabelFormat	string	标签的格式字符串（例如，货币格式使用 "c"）
TickPosition	GaugeElementPosition	刻度位置：内部、外部、跨轴
MajorTickLength	double	主刻度线长度
MinorTickLength	double	次刻度线长度
MinorTicksPerInterval	int	每个间隔中的次刻度数量
UseRangeColorForAxis	bool	将范围颜色应用于轴标签和刻度

指针属性（基类：LinearGaugePointer）

属性	类型	描述
Value	double	指针的当前值
EnableAnimation	bool	启用指针动画（默认值：false）
AnimationDuration	double	动画时长，单位为毫秒（默认值：1500）
AnimationEasingFunction	EasingFunctionBase	动画缓动函数

条形指针属性

属性	类型	描述
Background	Brush	条形指针的填充颜色
PointerSize	double	条形指针的粗细
CornerStyle	CornerStyle	圆角样式：BothFlat、BothCurve、StartCurve、EndCurve
Offset	double	与轴线的距离（正值：内侧；负值：外侧）
GradientStops	ObservableCollection	用于颜色过渡的渐变色标集合
Child	UIElement	显示在条形指针内部的子内容

形状指针属性（LinearShapePointer）

属性	类型	描述
ShapeType	GaugeShapeType	形状：Circle、Diamond、Triangle、InvertedTriangle、Rectangle
ShapeHeight	double	形状指针的高度
ShapeWidth	double	形状指针的宽度
Fill	Brush	形状的填充颜色
Stroke	Brush	形状的边框颜色
StrokeThickness	double	形状的边框粗细
HasShadow	bool	启用阴影效果（默认值：false）
IsInteractive	bool	启用拖动（默认值：false）
ShapeTemplate	DataTemplate	自定义形状模板
OffsetPoint	Point	相对于默认位置的 X/Y 偏移量
HorizontalAnchor	GaugeAnchor	水平对齐方式：Start、Center、End
VerticalAnchor	GaugeAnchor	垂直对齐方式：Start、Center、End

内容指针属性（LinearContentPointer）

属性	类型	描述
Content	object	自定义内容（TextBlock、Image 等）
OffsetPoint	Point	相对于默认位置的 X/Y 偏移量
HorizontalAnchor	GaugeAnchor	水平对齐方式：Start、Center、End
VerticalAnchor	GaugeAnchor	垂直对齐方式：Start、Center、End

范围属性（LinearGaugeRange）

属性	类型	描述
StartValue	double	范围的起始值
EndValue	double	范围的结束值
StartWidth	double	范围起点处的宽度
MidWidth	double	范围中点处的宽度（可选）
EndWidth	double	范围终点处的宽度
Background	Brush	范围的填充颜色
RangePosition	GaugeElementPosition	位置：Inside、Outside、Cross
GradientStops	ObservableCollection	用于颜色过渡的渐变色标集合
Child	UIElement	显示在范围内部的子内容

常见使用场景

天气应用中的温度计

创建垂直温度计，显示当前温度，并使用颜色区分温度范围（蓝色表示寒冷、橙色表示温和、红色表示炎热），同时为指针过渡添加动画效果。

电量指示器

构建水平电量指示器，使用绿色/黄色/红色范围，以条形指针显示电量，并通过内容指针显示百分比文本。

车辆仪表盘中的速度表

实现水平或垂直速度表，每隔 10 个单位显示刻度线，使用形状指针显示当前速度，并通过范围指示速度限制。

带百分比的进度条

使用带圆角的条形指针创建进度指示器，通过子内容显示百分比文本，并在数值更新时添加平滑动画。

工业监控中的压力表

设计具有自定义轴范围的压力表，使用多个范围标示安全/警告/危险区域，并通过交互式指针调整阈值。

音量控制滑块

使用带有可拖动形状指针的水平量表、自定义轴样式和数值变化事件，构建交互式音量控件以调节音频音量。

数据分析仪表板

创建包含多个线性量表的仪表板面板，以不同方向、配色方案和范围显示 KPI，用于可视化性能表现。

系统资源监控器

实现 CPU、内存和磁盘使用量量表，采用动画条形指针、显示资源消耗情况的渐变填充，并实时更新数值。

---

后续步骤： 根据实现需求阅读上述参考文档。先从 getting-started.md 开始进行初始设置，然后按需探索具体功能。