syncfusion-wpf-linear-gauge

实现线性仪表

本指南全面介绍如何在 Windows Presentation Foundation 应用程序中实现 Syncfusion WPF 线性仪表（SfLinearGauge）控件。线性仪表沿线性刻度以图形方式显示数值，非常适合用于温度计、进度指示器、滑动仪表，以及水平或垂直方向的数值可视化。

何时使用此技能

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

• 在 WPF 应用程序中实现 SfLinearGauge
• 创建温度计样式的显示，用于温度或测量值可视化
• 构建带刻度和数值标记的进度指示器
• 通过刻度、指针和范围线性显示数值
• 创建用于性能监控或数值跟踪的滑动仪表
• 使用彩色区域显示数值，以指示不同的数值范围
• 实现可自定义方向的水平或垂直仪表
• 添加动画指针，使其平滑过渡到新数值
• 配置多个指针，在同一刻度上比较数值
• 设计可灵活调整位置和样式的自定义仪表布局

组件概述

SfLinearGauge 控件沿线性刻度测量并显示数值，支持水平或垂直方向。它提供完整的仪表可视化系统，包括：

• 线性刻度 - 仪表的基础，可配置最小值/最大值、间隔和方向
• 指针 - 用于标记刻度上特定数值的条形指针和符号指针
• 范围 - 用于突出显示特定数值范围的彩色区域
• 标签 - 数值标签，支持格式设置、前缀/后缀和位置选项
• 刻度线 - 用于指示刻度间隔的主刻度线和次刻度线
• 方向 - 支持水平（横向）或垂直（纵向）布局
• 动画 - 可配置时长的平滑指针动画
• 主题 - 内置主题支持，确保 UI 样式统一

主要功能：

• 在同一刻度上使用多种指针类型（条形和符号）
• 用颜色区分范围，以可视化阈值
• 全面支持通过 XAML 和代码隐藏进行自定义
• 支持 MVVM 数据绑定
• 响应式尺寸和布局
• 专业的仪表外观

文档与导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 开始新的线性仪表实现或进行初次设置时。

内容包括：

• 安装 Syncfusion.SfGauge.WPF NuGet 包
• 添加程序集引用（三种方法）
• 在 XAML 和 C# 中导入命名空间
• 初始化空的 SfLinearGauge 控件
• 使用基本属性配置第一个刻度
• 添加符号指针以标记数值
• 添加条形指针以指示进度
• 创建用于数值区间的彩色范围
• 完整的最简可运行示例
• 使用 SfSkinManager 应用主题

刻度配置

📄 阅读： references/scale-configuration.md

阅读时机： 配置刻度的外观、范围、间隔、尺寸、方向或位置时。

内容包括：

• 了解 MainScale 属性和 LinearScale
• 设置刻度范围的最小值和最大值
• 配置标签和刻度线间距
• 自定义刻度外观（颜色、边框、描边）
• 自定义刻度尺寸（ScaleBarSize、ScaleBarLength）
• 设置刻度方向（Forward 或 Backward）
• 使用 ScaleBarPositionFactor 定位刻度
• 使用 ElementsPositionMode 自定义位置
• 自动计算间隔
• 完整的 XAML 和 C# 代码示例

指针

📄 阅读： references/pointers.md

何时阅读： 添加指针以标记值、实现条形或符号指针、自定义指针外观、启用动画或添加多个指针时。

涵盖内容：

• 指针类型概览（BarPointer 和 SymbolPointer）
• 实现条形指针以指示进度或填充
• 自定义条形指针（描边颜色、粗细）
• 实现符号指针以标记值
• 自定义符号指针（大小、形状、描边）
• 符号指针定位（Above、Below、Cross）
• 使用模板自定义符号指针形状
• 在单个刻度上添加多个指针
• 使用 EnableAnimation 启用指针动画
• 使用 AnimationDuration 控制动画速度
• 将指针值绑定到数据
• 各类指针的完整示例

范围

📄 阅读： references/ranges.md

何时阅读： 使用颜色突出显示数值范围、创建阈值区域、添加多个范围，或自定义范围外观和位置时。

涵盖内容：

• 范围概览及其视觉用途
• 为范围设置 StartValue 和 EndValue
• 自定义范围（描边颜色、宽度、不透明度）
• 可变宽度范围（StartWidth、EndWidth）
• 将范围颜色绑定到刻度线和标签
• 使用 RangeOffset 定位范围
• RangePosition 属性（Above、Below）
• 添加多个范围以创建颜色编码区域
• 常见范围模式（安全／警告／危险区域）
• 完整的多范围示例

标签和刻度线

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

何时阅读： 自定义刻度标签、设置标签文本格式、定位标签、配置刻度线或调整刻度间隔时。

涵盖内容：

• 标签：
  • 使用 LabelStroke 自定义标签颜色
  • 自定义字体（LabelSize、FontFamily、FontStyle）
  • 定位标签（LabelPosition：Above、Below）
  • 设置标签偏移以控制间距
  • 为标签文本添加前缀和后缀
  • 控制标签可见性
• 刻度线：
  • 自定义主刻度线和次刻度线（描边、大小、粗细）
  • 定位刻度线（TickPosition：Above、Below、Cross）
  • 配置 MinorTicksPerInterval
  • 设置刻度线外观和样式
• 结合标签和刻度线的完整示例

方向

📄 阅读： references/orientation.md

何时阅读： 将仪表方向从水平改为垂直，或从垂直改为水平时。

涵盖内容：

• Orientation 属性概览
• 水平方向（默认横向布局）
• 垂直方向（纵向布局）
• 方向的适用场景和注意事项
• 方向对指针和范围的布局影响
• 两种方向的完整示例

快速入门示例

以下是一个最简可运行的线性仪表，包含刻度、条形指针、符号指针和有色范围：

XAML

<Window xmlns:gauge="clr-namespace:Syncfusion.UI.Xaml.Gauges;assembly=Syncfusion.SfGauge.Wpf">
    <Grid>
        <gauge:SfLinearGauge>
            <gauge:SfLinearGauge.MainScale>
                <gauge:LinearScale 
                    Minimum="0" 
                    Maximum="100"
                    Interval="10"
                    ScaleBarStroke="#E0E0E0"
                    LabelStroke="#424242"
                    MajorTickStroke="Gray"
                    MajorTickSize="15"
                    MinorTickStroke="Gray"
                    MinorTickSize="7"
                    MinorTicksPerInterval="3"
                    ScaleBarSize="10"
                    ScaleBarLength="300">
                    
                    
                    <gauge:LinearScale.Pointers>
                        <gauge:LinearPointer 
                            PointerType="BarPointer"
                            Value="65"
                            BarPointerStroke="#36D1DC"
                            BarPointerStrokeThickness="10"/>
                        
                        
                        <gauge:LinearPointer 
                            PointerType="SymbolPointer"
                            Value="65"
                            SymbolPointerHeight="15"
                            SymbolPointerWidth="15"
                            SymbolPointerPosition="Above"
                            SymbolPointerStroke="#5B86E5"/>
                    </gauge:LinearScale.Pointers>
                    
                    
                    <gauge:LinearScale.Ranges>
                        <gauge:LinearRange 
                            StartValue="0" 
                            EndValue="35"
                            RangeStroke="#27BEB7"
                            StartWidth="10"
                            EndWidth="10"
                            RangeOffset="0.4"/>
                        
                        <gauge:LinearRange 
                            StartValue="35" 
                            EndValue="70"
                            RangeStroke="Orange"
                            StartWidth="10"
                            EndWidth="10"
                            RangeOffset="0.4"/>
                        
                        <gauge:LinearRange 
                            StartValue="70" 
                            EndValue="100"
                            RangeStroke="Red"
                            StartWidth="10"
                            EndWidth="10"
                            RangeOffset="0.4"/>
                    </gauge:LinearScale.Ranges>
                </gauge:LinearScale>
            </gauge:SfLinearGauge.MainScale>
        </gauge:SfLinearGauge>
    </Grid>
</Window>

C# 后置代码

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

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
        CreateLinearGauge();
    }
    
    private void CreateLinearGauge()
    {
        // Create gauge
        SfLinearGauge gauge = new SfLinearGauge();
        
        // Create scale
        LinearScale scale = new LinearScale
        {
            Minimum = 0,
            Maximum = 100,
            Interval = 10,
            ScaleBarStroke = new SolidColorBrush(Color.FromRgb(224, 224, 224)),
            LabelStroke = new SolidColorBrush(Color.FromRgb(66, 66, 66)),
            MajorTickStroke = new SolidColorBrush(Colors.Gray),
            MajorTickSize = 15,
            MinorTickStroke = new SolidColorBrush(Colors.Gray),
            MinorTickSize = 7,
            MinorTicksPerInterval = 3,
            ScaleBarSize = 10,
            ScaleBarLength = 300
        };
        
        // Add bar pointer
        scale.Pointers.Add(new LinearPointer
        {
            PointerType = LinearPointerType.BarPointer,
            Value = 65,
            BarPointerStroke = new SolidColorBrush(Color.FromRgb(54, 209, 220)),
            BarPointerStrokeThickness = 10
        });
        
        // Add symbol pointer
        scale.Pointers.Add(new LinearPointer
        {
            PointerType = LinearPointerType.SymbolPointer,
            Value = 65,
            SymbolPointerHeight = 15,
            SymbolPointerWidth = 15,
            SymbolPointerPosition = LinearSymbolPointersPosition.Above,
            SymbolPointerStroke = new SolidColorBrush(Color.FromRgb(91, 134, 229))
        });
        
        // Add ranges
        scale.Ranges.Add(new LinearRange
        {
            StartValue = 0,
            EndValue = 35,
            RangeStroke = new SolidColorBrush(Color.FromRgb(39, 190, 183)),
            StartWidth = 10,
            EndWidth = 10,
            RangeOffset = 0.4
        });
        
        gauge.MainScale = scale;
        this.Content = gauge;
    }
}

常见模式

温度计模式

创建一个垂直方向的温度计式仪表：

<gauge:SfLinearGauge Orientation="Vertical">
    <gauge:SfLinearGauge.MainScale>
        <gauge:LinearScale 
            Minimum="-20" 
            Maximum="120"
            LabelPostfix="°C"
            ScaleBarSize="15">
            <gauge:LinearScale.Pointers>
                <gauge:LinearPointer 
                    PointerType="BarPointer"
                    Value="37"
                    BarPointerStroke="Red"
                    BarPointerStrokeThickness="15"/>
            </gauge:LinearScale.Pointers>
        </gauge:LinearScale>
    </gauge:SfLinearGauge.MainScale>
</gauge:SfLinearGauge>

进度指示器模式

使用带动画的指针显示进度：

<gauge:LinearScale.Pointers>
    <gauge:LinearPointer 
        PointerType="BarPointer"
        Value="{Binding ProgressValue}"
        EnableAnimation="True"
        AnimationDuration="500"
        BarPointerStroke="#36D1DC"
        BarPointerStrokeThickness="12"/>
</gauge:LinearScale.Pointers>

多区域数值仪表模式

创建安全／警告／危险区域：

<gauge:LinearScale.Ranges>
    
    <gauge:LinearRange 
        StartValue="0" 
        EndValue="60"
        RangeStroke="Green"
        StartWidth="15"
        EndWidth="15"/>
    
    
    <gauge:LinearRange 
        StartValue="60" 
        EndValue="80"
        RangeStroke="Yellow"
        StartWidth="15"
        EndWidth="15"/>
    
    
    <gauge:LinearRange 
        StartValue="80" 
        EndValue="100"
        RangeStroke="Red"
        StartWidth="15"
        EndWidth="15"/>
</gauge:LinearScale.Ranges>

多指针对比模式

在一个刻度上对比两个数值：

<gauge:LinearScale.Pointers>
    
    <gauge:LinearPointer 
        PointerType="SymbolPointer"
        Value="75"
        SymbolPointerStroke="Blue"
        SymbolPointerPosition="Above"/>
    
    
    <gauge:LinearPointer 
        PointerType="SymbolPointer"
        Value="90"
        SymbolPointerStroke="Green"
        SymbolPointerPosition="Below"/>
</gauge:LinearScale.Pointers>

关键属性

SfLinearGauge 属性

属性	类型	描述
MainScale	LinearScale	包含所有仪表元素的主刻度
Orientation	Orientation	水平（默认）或垂直布局

LinearScale 属性

属性	类型	描述
Minimum	double	刻度的最小值（默认值：0）
Maximum	double	刻度的最大值（默认值：100）
Interval	double	主刻度线和标签之间的间距
ScaleBarStroke	Brush	刻度条的背景色
ScaleBarSize	double	刻度条的粗细（水平布局时为高度）
ScaleBarLength	double	刻度条的长度（水平布局时为宽度）
ScaleDirection	LinearScaleDirection	正向或反向
Pointers	ObservableCollection	LinearPointer 对象集合
Ranges	ObservableCollection	LinearRange 对象集合
LabelStroke	Brush	标签文本颜色
LabelPosition	LinearLabelsPosition	刻度上方或下方
LabelPrefix	string	添加到标签前面的文本
LabelPostfix	string	添加到标签后面的文本
MajorTickStroke	Brush	主刻度线颜色
MajorTickSize	double	主刻度线长度
MinorTickStroke	Brush	次刻度线颜色
MinorTickSize	double	次刻度线长度
MinorTicksPerInterval	int	相邻主刻度线之间的次刻度线数量
TickPosition	LinearTicksPosition	上方、下方或穿过

LinearPointer 属性

属性	类型	描述
PointerType	LinearPointerType	BarPointer 或 SymbolPointer
Value	double	指针在刻度上的值
BarPointerStroke	Brush	条形指针颜色
BarPointerStrokeThickness	double	条形指针宽度
SymbolPointerStroke	Brush	符号指针颜色
SymbolPointerHeight	double	符号指针高度
SymbolPointerWidth	double	符号指针宽度
SymbolPointerPosition	LinearSymbolPointersPosition	上方、下方或穿过
EnableAnimation	bool	启用平滑的指针过渡效果
AnimationDuration	int	动画时长，单位为毫秒

LinearRange 属性

属性	类型	描述
StartValue	double	范围起始值
EndValue	double	范围结束值
RangeStroke	Brush	范围颜色
StartWidth	double	范围起始处的宽度
EndWidth	double	范围结束处的宽度（用于锥形范围）
RangeOffset	double	与刻度条之间的距离
RangeOpacity	double	范围的不透明度（0.0 至 1.0）

常见用例

温度监控

使用颜色编码的范围显示温度读数，以区分正常、警告和危险温度。采用垂直方向可呈现温度计样式的可视化效果。

性能指标

使用条形指针显示当前值，并以范围标示可接受的阈值，从而跟踪 KPI、CPU 使用率、内存占用或其他性能指标。

进度跟踪

显示任务、下载或进程的完成百分比，并使用动画条形指针在数值更新时平滑过渡。

测量仪表显示

创建压力计、速度计、电压表等虚拟仪表，或任何适合使用线性刻度可视化的测量仪表。

数值比较

使用多个指针对比实际值与目标值、当前值与先前值，或在单个刻度上比较多个指标。

仪表板组件

将线性仪表集成到仪表板中，作为紧凑、美观的组件，一目了然地监控数据。

API 文档

在线 API 参考：

• SfLinearGauge 类
• LinearScale 类
• LinearPointer 类
• LinearRange 类
• Syncfusion.UI.Xaml.Gauges 命名空间

---

后续步骤： 根据实现需求，导航至上方的参考文件。先阅读 getting-started.md 进行初始设置，然后根据需要了解特定功能。