Blazor Radial Gauge Overview

The Blazor radial gauge component provides a number of visual elements, like a needle, tick marks, ranges, and labels, in order to create a predefined shape and scale. The IgbRadialGauge also has built-in support for animated transitions. This animation is easily customizable by setting the TransitionDuration property.

Blazor Radial Gauge Example

The following sample demonstrates how setting multiple properties on the same IgbRadialGauge can transform it to completely different radial gauge.

Please refer to these topics on adding the IgniteUI.Blazor package.

Afterwards you may start implementing the control by adding the following namespaces:

@using IgniteUI.Blazor.Controls

Component Modules

The IgbRadialGauge requires the following modules:

// in Program.cs file

builder.Services.AddIgniteUIBlazor(typeof(IgbRadialGaugeModule));

Usage

O código a seguir demonstra como criar um medidor radial contendo uma agulha e três faixas comparativas na escala.

<IgbRadialGauge Height="100%" Width="100%"
      MinimumValue="0" Value="25"
      MaximumValue="100" Interval="5" >
    <IgbRadialGaugeRange
          StartValue="0"
          EndValue="30"
          Brush="red">
    </IgbRadialGaugeRange>
    <IgbRadialGaugeRange
          StartValue="30"
          EndValue="60"
          Brush="Yellow" >
    </IgbRadialGaugeRange>
    <IgbRadialGaugeRange
          StartValue="60"
          EndValue="100"
          Brush="Green">
    </IgbRadialGaugeRange>
</IgbRadialGauge>

Backing

O componente do medidor radial vem com um formato de apoio desenhado atrás da escala que atua como um plano de fundo para o medidor radial.

O elemento de apoio representa o fundo e a borda do componente de calibre radial. Ele é sempre o primeiro elemento renderizado e todos os outros elementos, como agulha, rótulos e marcas de escala, são sobrepostos em cima dele.

The backing can be circular or fitted. A circular shape creates a 360 degree circle gauge while a fitted shape creates a filled arc segment encompassing the ScaleStartAngle and ScaleEndAngle properties. This can be set by setting the BackingShape property.

 <IgbRadialGauge Height="100%" Width="100%"
    BackingShape="RadialGaugeBackingShape.Fitted"
    BackingBrush="#FCFCFC"
    BackingOutline="DodgerBlue"
    BackingOversweep="5"
    BackingCornerRadius="10"
    BackingStrokeThickness="5"
    BackingOuterExtent="0.8"
    BackingInnerExtent="0.15"

    ScaleStartAngle="135"
    ScaleEndAngle="45"
    MinimumValue="0"
    MaximumValue="80"
    Value="50"
    Interval="10">
</IgbRadialGauge>

Scale

The scale is visual element that highlights full range of values in the gauge which can be created by supplying MinimumValue and MaximumValue values. Together with backing, it defines overall shape of gauge. The ScaleStartAngle and ScaleEndAngle properties define bounds of arc of the scale. While, the ScaleSweepDirection property specifies whether the scale sweeps in clockwise or counter-clockwise direction. You can customize appearance of the scale by setting ScaleBrush, ScaleStartExtent, and ScaleEndExtent properties.

<IgbRadialGauge
  ScaleStartAngle="135"
  ScaleEndAngle="45"
  ScaleBrush="DodgerBlue"
  ScaleSweepDirection="SweepDirection.Clockwise"
  ScaleOversweep="1"
  ScaleOversweepShape="RadialGaugeScaleOversweepShape.Fitted"
  ScaleStartExtent="0.45"
  ScaleEndExtent="0.575"
  MinimumValue="0"
  MaximumValue="80"
  Value="50"
  Interval="10">
</IgbRadialGauge>

Labels and Titles

The radial gauge labels are visual elements displaying numeric values at a specified interval between values of the MinimumValue and MaximumValue properties. You can position labels by setting the LabelExtent property to a fraction, where 0 represents center of gauge and 1 represents outer extent of the gauge backing. Also, you can customize labels setting various styling properties such as FontBrush and Font.

Each of these labels for the needle have various styling attributes you can apply to change the font, angle, brush and distance from the center of the gauge such as TitleExtent, TitleAngle, SubtitleFontSize, HighlightLabelBrush.

<IgbRadialGauge
  Height="100%" Width="100%"
  LabelInterval="10"
  LabelInterval="10"
  Font="11px Verdana"
  FontBrush="DodgerBlue"
  MinimumValue="0"
  MaximumValue="80"
  Value="50"
  Interval="10">
</IgbRadialGauge>

Title & Subtitle

TitleText and SubtitleText properties are available and can both be used to display custom text for the needle. Alternatively, TitleDisplaysValue and SubtitleDisplaysValue, when set to true, will let display the needle's value and override TitleText and SubtitleText. So you can occupy custom text for the title but show the value via the subtitle and vice versa.

If the highlight needle is shown, as explained below, then custom text can be shown via HighlightLabelText, otherwise HighlightLabelDisplaysValue can be enabled and display it's value.

<IgbRadialGauge
  TitleText="Global Sales"
  SubTitleText="2024">
</IgbRadialGauge>

Optical Scaling

The radial gauge's labels and titles can change it's scaling. To enable this, first set OpticalScalingEnabled to true. Then you can set OpticalScalingSize which manages the size at which labels have 100% optical scaling. Labels will have larger fonts when gauge's size is larger. For example, labels will have a 200% larger font size when this property is set to 500 and the gauge px size is doubled to eg. 1000.

Tick Marks

Tick marks are thin lines radiating from the center of the radial gauge. There are two types of tick marks: major and minor. Major tick marks are displayed at the Interval between the MinimumValue and MaximumValue properties. Use the MinorTickCount property to specify the number of minor tick marks displayed between each major tick mark. You can control the length of tick marks by setting a fraction (between 0 and 1) to TickStartExtent, TickEndExtent, MinorTickStartExtent, and MinorTickEndExtent properties.

 <IgbRadialGauge Height="100%" Width="100%"
    TickStartExtent="0.5"
    TickEndExtent="0.57"
    TickStrokeThickness="2"
    TickBrush="DodgerBlue"
    MinorTickCount="4"
    MinorTickEndExtent="0.520"
    MinorTickStartExtent="0.57"
    MinorTickStrokeThickness="1"
    MinorTickBrush="DarkViolet"
    MinimumValue="0"
    MaximumValue="80"
    Value="50"
    Interval="10">
</IgbRadialGauge>

Ranges

A range highlights a set of continuous values bound by a specified MinimumValue and MaximumValue properties. You can add multiple ranges to the radial gauge by specifying their starting and ending values. Each range has a few customization properties such as Brush and Outline. Alternatively, you can set RangeBrushes and RangeOutlines properties to a list of colors for the ranges.

<IgbRadialGauge Height="100%" Width="100%"
      MinimumValue="0" Value="50"
      MaximumValue="80" Interval="10"
      RangeBrushes="#A4BD29, #F86232"
      RangeOutlines="#A4BD29, #F86232">
    <IgbRadialGaugeRange StartValue="10"
          EndValue="25"
          InnerStartExtent="0.50"
          InnerEndExtent="0.50"
          OuterStartExtent="0.57"
          OuterEndExtent="0.57">
    </IgbRadialGaugeRange>
    <IgbRadialGaugeRange StartValue="25"
          EndValue="40"
          InnerStartExtent="0.50"
          InnerEndExtent="0.50"
          OuterStartExtent="0.57"
          OuterEndExtent="0.57">
    </IgbRadialGaugeRange>
</IgbRadialGauge>

Needle

Agulhas de calibre radial são elementos visuais usados para significar um valor definido de calibre. As agulhas estão disponíveis em uma das várias formas predefinidas. A agulha pode ter uma forma de pivô, que é colocada no centro do calibre. A forma de pivô também assume uma das formas predefinidas. Formas de pivô que incluem uma sobreposição ou uma subposição podem ter um pincel de pivô separado aplicado à forma.

The supported needle shapes and caps are set using the NeedleShape and NeedlePivotShape properties.

You can enable an interactive mode of the gauge (using IsNeedleDraggingEnabled property) and the end-user will be able to change value by dragging the needle between values of MinimumValue and MaximumValue properties.

<IgbRadialGauge Height="100%" Width="100%"
    IsNeedleDraggingEnabled="true"
    IsNeedleDraggingConstrained="true"
    NeedleShape="RadialGaugeNeedleShape.NeedleWithBulb"
    NeedleBrush="DodgerBlue"
    NeedleOutline="DodgerBlue"
    NeedleEndExtent="0.475"
    NeedleStrokeThickness="1"
    NeedlePivotShape="RadialGaugePivotShape.CircleOverlay"
    NeedlePivotBrush="#9F9FA0"
    NeedlePivotOutline="#9F9FA0"
    NeedlePivotWidthRatio="0.2"
    NeedlePivotStrokeThickness="1"
    Value="50"
    MinimumValue="0"
    MaximumValue="80"
    Interval="10">
</IgbRadialGauge>

Highlight Needle

The radial gauge can be modified to show a second needle. This will make the main needle's Value appear with a lower opacity. To enable this first set HighlightValueDisplayMode to Overlay and then apply a HighlightValue.

<IgbLinearGauge Height="80px" Width="100%"
    MinimumValue="0"
    MaximumValue="100"
    Value="30"
    Interval="10"
    LabelInterval="10"
    LabelExtent="0.65"
    HighlightValue="50"
    HighlightValueDisplayMode=HighlightedValueDisplayMode.Overlay
    HighlightLabelDisplaysValue=true
    HighlightLabelSnapsToNeedlePivot=true
    IsHighlightNeedleDraggingEnabled=true
</IgbLinearGauge>

Summary

Para sua conveniência, todos os trechos de código acima são combinados em um bloco de código abaixo que você pode copiar facilmente para seu projeto e ver o medidor radial com todos os recursos e visuais habilitados.

<IgbRadialGauge Height="100%" Width="100%"
             MinimumValue="0"
             MaximumValue="80"
             Value="50"
             Interval="10"

             ScaleStartAngle="135"
             ScaleEndAngle="45"
             ScaleBrush="DodgerBlue"
             ScaleSweepDirection="SweepDirection.Clockwise"
             ScaleOversweep="1"
             ScaleOversweepShape="RadialGaugeScaleOversweepShape.Fitted"
             ScaleStartExtent="0.45"
             ScaleEndExtent="0.575"

             IsNeedleDraggingEnabled="true"
             IsNeedleDraggingConstrained="true"
             NeedleShape="RadialGaugeNeedleShape.NeedleWithBulb"
             NeedleBrush="DodgerBlue"
             NeedleOutline="DodgerBlue"
             NeedleEndExtent="0.475"
             NeedleStrokeThickness="1"
             NeedlePivotShape="RadialGaugePivotShape.CircleOverlay"
             NeedlePivotBrush="#9F9FA0"
             NeedlePivotOutline="#9F9FA0"
             NeedlePivotWidthRatio="0.2"
             NeedlePivotStrokeThickness="1"
             TickStartExtent="0.5"
             TickEndExtent="0.57"
             TickStrokeThickness="2"
             TickBrush="DodgerBlue"

             MinorTickCount="4"
             MinorTickEndExtent="0.520"
             MinorTickStartExtent="0.57"
             MinorTickStrokeThickness="1"
             MinorTickBrush="DarkViolet"

             LabelExtent="0.65"
             LabelInterval="10"
             Font="11px Verdana"
             FontBrush="Black"
             BackingShape="RadialGaugeBackingShape.Fitted"
             BackingBrush="#FCFCFC"
             BackingOutline="DodgerBlue"
             BackingOversweep="5"
             BackingCornerRadius="10"
             BackingStrokeThickness="5"
             BackingOuterExtent="0.8"
             BackingInnerExtent="0.15"

             RangeBrushes="#A4BD29, #F86232"
             RangeOutlines="#A4BD29, #F86232">
    <IgbRadialGaugeRange StartValue="20"
        EndValue="40"
        InnerStartExtent="0.50"
        InnerEndExtent="0.50"
        OuterStartExtent="0.57"
        OuterEndExtent="0.57">
    </IgbRadialGaugeRange>
    <IgbRadialGaugeRange StartValue="40"
        EndValue="60"
        InnerStartExtent="0.50"
        InnerEndExtent="0.50"
        OuterStartExtent="0.57"
        OuterEndExtent="0.57">
    </IgbRadialGaugeRange>
</IgbRadialGauge>

API References

A seguir está uma lista de membros da API mencionados nas seções acima:

Additional Resources

Você pode encontrar mais informações sobre outros tipos de medidores nestes tópicos: