syncfusion-winui-linear-gauge（syncfusion winui Linear gauge 前端）

WinUI Linear Gauge (SfLinearGauge)

Comprehensive guide for implementing the Syncfusion WinUI Linear Gauge (SfLinearGauge) control for data visualization in Windows desktop applications. The Linear Gauge control displays numerical values on a linear scale horizontally or vertically with extensive customization options, ranges, multiple pointer types, and animation support.

When to Use This Skill

Use this skill when you need to:

• Create linear gauge controls for data visualization in WinUI desktop applications
• Display numerical values on horizontal or vertical linear scales
• Add range indicators to visualize value categories with color-coded segments
• Use bar pointers to show current values with filled indicators
• Use shape pointers to mark values with different shapes (circle, diamond, triangle, etc.)
• Use content pointers to display custom content (text, images, icons) at values
• Animate pointer movements with customizable duration and easing functions
• Enable interactive gauges with draggable pointers for value input
• Customize axis appearance with labels, ticks, intervals, and formatting
• Build dashboards with temperature, pressure, speed, or other measurement displays
• Create progress indicators with visual feedback and ranges
• Troubleshoot gauge rendering, pointer positioning, or interaction issues

Component Overview

SfLinearGauge is a multipurpose data visualization control that displays numerical values on a linear scale, offering:

• Orientation: Horizontal or vertical gauge layouts
• Axis Customization: Configurable scale with labels, ticks, intervals, and custom ranges
• Range Support: Multiple color-coded ranges to visualize value categories
• Three Pointer Types:

- Bar Pointer: Filled bar from start to value - Shape Pointer: Markers with built-in shapes or custom templates - Content Pointer: Custom content (text, images, icons) at value position

• Multiple Pointers: Add multiple pointers to show different values on same scale
• Animation: Smooth pointer transitions with customizable easing functions
• Interactivity: Draggable shape pointers for user input
• Customization: Extensive styling, templates, gradients, and child content support
• Data Binding: MVVM-friendly with Value property binding

Control Structure:

• Single axis with configurable minimum, maximum, and interval
• Multiple ranges for color-coded value segments
• Bar pointers collection for filled indicators
• Marker pointers collection for shape and content pointers
• Full control over appearance, positioning, and behavior

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Creating a WinUI 3 desktop application
• Installing Syncfusion.Gauge.WinUI NuGet package
• Adding Linear Gauge control in XAML
• Adding Linear Gauge control in C#
• Adding axis to the gauge
• Adding ranges for value visualization
• Adding bar pointers
• Adding marker pointers (shape and content)
• Complete working example

Axis Customization

📄 Read: references/axis-customization.md

• Setting minimum and maximum values
• Configuring intervals between labels
• Axis direction customization (IsInversed)
• Mirrored axis support (IsMirrored)
• Axis orientation (horizontal/vertical)
• Maximum labels count per 100 pixels
• Axis line styling (stroke, thickness, color)
• Axis line visibility control
• Label customization (fonts, colors, formats)
• Label templates for custom appearance
• Label visibility and placement (inside/outside)
• Label position and offset adjustment
• Tick customization (major and minor ticks)
• Tick styling and dashed patterns
• Tick placement and offset
• Custom scale ranges (logarithmic, etc.)

Ranges

📄 Read: references/ranges.md

• Setting start and end values for ranges
• Range width customization (StartWidth, MidWidth, EndWidth)
• Equal vs. different width ranges
• Background color customization
• Gradient brush support with multiple stops
• Range position (inside/outside/cross axis)
• Using range colors for axis elements
• Range child content support for labels

Pointers

📄 Read: references/pointers.md

• Overview of three pointer types
• Bar Pointer implementation and customization
• Shape Pointer with built-in and custom shapes
• Content Pointer for text, images, and icons
• Multiple pointers on single gauge
• Pointer dragging and interactivity
• Pointer events (ValueChangeStarted, ValueChanging, ValueChanged, ValueChangeCompleted)
• Pointer positioning and anchoring
• Pointer sizing and styling

Animation

📄 Read: references/animation.md

• Enabling pointer animation
• Animation duration configuration
• Animation easing functions
• Applying animation to bar pointers
• Applying animation to marker pointers
• Custom animation timing and effects

Quick Start Example

Here's a minimal working example to get started:

1. Add Namespace

XAML:

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

C#:

using Syncfusion.UI.Xaml.Gauges;

2. Create Basic Linear Gauge (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. Or Create Programmatically (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. Set Pointer Value (Optional)

// Update pointer value
barPointer.Value = 75;

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

Common Patterns

Pattern 1: Basic Horizontal Gauge with Bar Pointer

<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>

Pattern 2: Vertical Temperature Gauge

<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>

Pattern 3: Gauge with Multiple Pointers

<gauge:SfLinearGauge>
    <gauge:SfLinearGauge.Axis>
        <gauge:LinearAxis Maximum="140" Interval="10">
            <!-- Bar pointer for current value -->
            <gauge:LinearAxis.BarPointers>
                <gauge:BarPointer Value="90" />
            </gauge:LinearAxis.BarPointers>

            <!-- Shape pointer for threshold -->
            <gauge:LinearAxis.MarkerPointers>
                <gauge:LinearShapePointer Value="90"
                                          VerticalAnchor="End"
                                          OffsetPoint="0,-8" />

                <!-- Content pointer for label -->
                <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>

Pattern 4: Interactive Gauge with Draggable Pointer

<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;
}

Pattern 5: Gauge with Color-Coded Ranges

<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>

Pattern 6: Animated Pointer Updates

<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>

Pattern 7: Gradient Bar Pointer

<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>

Pattern 8: ViewModel Data Binding

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>

Key Properties Reference

Gauge Properties (SfLinearGauge)

Axis Properties (LinearAxis)

Pointer Properties (Base: LinearGaugePointer)

Bar Pointer Properties

Shape Pointer Properties (LinearShapePointer)

Content Pointer Properties (LinearContentPointer)

Range Properties (LinearGaugeRange)

Common Use Cases

Temperature Gauge for Weather App

Create vertical temperature gauges displaying current temperature with color-coded ranges (blue for cold, orange for moderate, red for hot) and animated pointer transitions.

Battery Level Indicator

Build horizontal battery level gauges with green/yellow/red ranges, bar pointers showing charge level, and content pointers displaying percentage text.

Speed Meter for Vehicle Dashboard

Implement horizontal or vertical speed gauges with tick marks every 10 units, shape pointers for current speed, and range indicators for speed limits.

Progress Bar with Percentage

Create progress indicators using bar pointers with rounded corners, child content displaying percentage text, and smooth animations as values update.

Pressure Gauge for Industrial Monitoring

Design pressure gauges with custom axis ranges, multiple ranges for safe/warning/danger zones, and interactive pointers for threshold adjustment.

Volume Control Slider

Build interactive volume controls using horizontal gauges with draggable shape pointers, custom axis styling, and value change events for audio level adjustment.

Data Analytics Dashboard

Create dashboard panels with multiple linear gauges showing KPIs, each with different orientations, color schemes, and ranges for performance visualization.

System Resource Monitor

Implement CPU/memory/disk usage gauges with animated bar pointers, gradient fills showing resource consumption, and real-time value updates.

Next Steps: Read the reference documentation above based on what you need to implement. Start with getting-started.md for initial setup, then explore specific features as needed.