syncfusion-blazor-linear-gauge

实现 Syncfusion Blazor Linear Gauges

NuGet： Syncfusion.Blazor.LinearGauge + Syncfusion.Blazor.Themes
命名空间： Syncfusion.Blazor.LinearGauge

何时使用此技能

当用户需要执行以下操作时，请使用此技能：

• 在线性刻度（水平或垂直）上可视化数值
• 显示温度、压力、速度或进度等测量数据
• 创建包含仪表可视化效果的仪表板组件
• 实现包含范围和指示器的 KPI 显示
• 通过动画指针显示实时数据
• 构建交互式仪表，让用户可以拖动指针来更改数值
• 创建包含多个轴和指针的多刻度可视化效果

Syncfusion Blazor Linear Gauge 非常适合需要使用可自定义刻度、指针和范围来精确呈现数值的应用程序。

---

组件概览

Blazor Linear Gauge (SfLinearGauge) 是一种数据可视化组件，可在线性刻度上显示数值，功能包括：

• 多个轴，具有可自定义的范围和样式
• 多种指针类型（标记形状、条形指针、文本、图像）
• 按颜色编码的范围，用于对数值进行分类
• 注释，用于添加标签和自定义内容
• 交互功能，包括拖动以更改指针数值
• 事件和方法，用于动态更新
• 无障碍支持，符合 WCAG 标准
• 国际化，适用于全球应用程序

---

文档与导航指南

此技能针对 Linear Gauge 组件的各个方面提供了全面且独立的参考文件。请根据当前需求阅读相应的参考文件。

入门

📄 阅读： references/getting-started.md

何时阅读： 首次设置、新项目初始化、安装相关问题

涵盖内容：

• 通过 Visual Studio、VS Code 和 .NET CLI 安装
• NuGet 包安装（Syncfusion.Blazor.LinearGauge、Syncfusion.Blazor.Themes）
• 命名空间导入和服务注册
• 样式表和脚本引用
• 基本的 LinearGauge 组件实现
• 添加指针并设置数值
• 添加标题和范围
• 运行第一个仪表应用程序

核心组件

轴配置

📄 阅读： references/axes-configuration.md

何时阅读： 设置仪表刻度、自定义轴外观、使用多个轴

涵盖内容：

• 设置刻度的最小值和最大值
• 线条自定义（高度、宽度、颜色、偏移量）
• 主刻度配置（间隔、高度、颜色、宽度、位置、偏移量）
• 次刻度配置（间隔、高度、颜色、宽度、位置、偏移量）
• 标签自定义（格式、字体、位置、偏移量）
• 在单个仪表上使用多个轴
• 反转轴方向
• 轴的对置位置
• 所有配置的完整代码示例

指针

📄 阅读： references/pointers.md

何时阅读： 添加数值指示器、自定义指针外观、实现多个指针

涵盖内容：

• 设置指针数值
• 具有多种形状的标记指针（圆形、矩形、三角形、菱形、倒三角形）
• 可自定义的条形指针
• 使用自定义图像的图像指针
• 带有自定义样式的文本指针
• 指针位置和放置方式
• 平滑过渡的动画配置
• 在单个轴上使用多个指针
• 通过拖放交互更改数值
• 各种指针类型的完整示例

范围

📄 阅读： references/ranges.md

阅读时机： 添加颜色编码的数值区域、实现性能区间或创建可视化阈值时

涵盖内容：

• 设置范围的起始值和结束值
• 自定义范围颜色
• 范围位置（内部、外部、跨越）
• 配置范围偏移量
• 设置渐变效果的起始宽度和结束宽度
• 在单个轴上设置多个范围
• 实用场景（温度区间、性能指标、状态范围）
• 含可视化结果的完整代码示例

外观和样式

注释

📄 阅读： references/annotations.md

阅读时机： 为仪表添加标签、自定义内容、单位或动态文本时

涵盖内容：

• 添加文本注释
• 在注释中添加 HTML 内容
• 使用 x、y 坐标定位注释
• 使用 z-index 对多个注释分层
• 设置文本注释的字体样式
• 设置水平和垂直对齐方式
• 在仪表上添加多个注释
• 更新动态内容
• 实用示例（单位标签、数值显示、警告）

外观和样式

📄 阅读： references/appearance-and-styling.md

阅读时机： 自定义仪表外观、主题、响应式设计或打印样式时

涵盖内容：

• 自定义容器（宽度、高度、背景、边框）
• 方向（水平与垂直）
• 调整边距和容器
• 自定义标题（文本、字体、位置）
• 选择主题（Bootstrap、Material、Fabric、Fluent、Tailwind 等）
• 自定义 CSS 样式
• 响应式设计注意事项
• 配色方案和调色板
• 适合打印的样式
• 完整的样式示例

高级功能

方法和事件

📄 阅读： references/methods-and-events.md

阅读时机： 实现动态更新、处理用户交互或进行程序化控制时

涵盖内容：

• 用于动态更新指针的 setPointerValue() 方法
• 用于更新注释的 setAnnotationValue() 方法
• 用于打印仪表的 print() 方法
• 用于重新渲染的 refresh() 方法
• Load 和 Loaded 事件
• AnimationComplete 事件
• 用于自定义标签的 AxisLabelRendering 事件
• AnnotationRendering 事件
• 用于用户交互的 ValueChange 事件
• TooltipRendering 事件
• ResizeCompleted 事件
• 包含实用场景的完整事件处理程序示例

用户交互

📄 阅读： references/user-interaction.md

阅读时机： 启用工具提示、拖动交互、鼠标/触摸事件或数值更改时

涵盖内容：

• 配置和自定义工具提示
• 使用自定义 HTML 的工具提示模板
• 拖动指针以更改数值
• 启用/禁用指针交互
• 处理鼠标和触摸事件
• 跟踪数值更改并设置回调
• 用户交互时的动画
• 完整的交互示例

无障碍访问和国际化

📄 阅读： references/accessibility-and-internationalization.md

阅读时机： 实现 WCAG 合规、键盘导航、屏幕阅读器支持或面向全球用户的应用时

涵盖内容：

• 无障碍访问概述（符合 WCAG 2.1 AA 级标准）
• 支持键盘导航
• 兼容屏幕阅读器
• ARIA 属性和标签
• 支持高对比度模式
• 焦点指示器
• 设置国际化（i18n）
• 不同区域设置下的数字格式
• RTL（从右向左）支持
• 完整的无障碍访问实现示例

---

快速入门示例

以下是一个简短示例，帮助你开始使用 Blazor Linear Gauge：

@using Syncfusion.Blazor.LinearGauge

<SfLinearGauge Title="Temperature Monitor">
    <LinearGaugeAxes>
        <LinearGaugeAxis Minimum="0" Maximum="120">
            <LinearGaugeAxisLabelStyle Format="{value}°C"></LinearGaugeAxisLabelStyle>
            <LinearGaugePointers>
                <LinearGaugePointer PointerValue="65" Color="#007bff">
                </LinearGaugePointer>
            </LinearGaugePointers>
            <LinearGaugeRanges>
                <LinearGaugeRange Start="0" End="40" Color="#4CAF50"></LinearGaugeRange>
                <LinearGaugeRange Start="40" End="80" Color="#FFC107"></LinearGaugeRange>
                <LinearGaugeRange Start="80" End="120" Color="#F44336"></LinearGaugeRange>
            </LinearGaugeRanges>
        </LinearGaugeAxis>
    </LinearGaugeAxes>
</SfLinearGauge>

结果： 一个垂直线性仪表，显示从 0°C 到 120°C 的温度，包含三个颜色编码的范围（绿色、黄色、红色），指针指向 65°C。

---

常见模式

模式 1：简单的进度指示器

使用场景： 显示完成百分比或进度状态

@using Syncfusion.Blazor.LinearGauge

<SfLinearGauge Orientation="Syncfusion.Blazor.LinearGauge.Orientation.Horizontal" Width="400px" Height="80px">
    <LinearGaugeAxes>
        <LinearGaugeAxis Minimum="0" Maximum="100">
            <LinearGaugePointers>
                <LinearGaugePointer PointerValue="75" Type="Syncfusion.Blazor.LinearGauge.Point.Bar" 
                                    Color="#28a745" Width="20">
                </LinearGaugePointer>
            </LinearGaugePointers>
        </LinearGaugeAxis>
    </LinearGaugeAxes>
</SfLinearGauge>

模式 2：多刻度仪表盘

用例： 在一个仪表上显示多个指标

@using Syncfusion.Blazor.LinearGauge

<SfLinearGauge>
    <LinearGaugeAxes>
        <LinearGaugeAxis Minimum="0" Maximum="100">
            <LinearGaugePointers>
                <LinearGaugePointer PointerValue="60" Color="#007bff"></LinearGaugePointer>
                <LinearGaugePointer PointerValue="80" Color="#dc3545"></LinearGaugePointer>
            </LinearGaugePointers>
        </LinearGaugeAxis>
    </LinearGaugeAxes>
</SfLinearGauge>

模式 3：交互式数值调节器

用例： 允许用户通过拖动指针来更改数值

@using Syncfusion.Blazor.LinearGauge

<SfLinearGauge>
    <LinearGaugeEvents ValueChange="@OnValueChange"></LinearGaugeEvents>
    <LinearGaugeAxes>
        <LinearGaugeAxis Minimum="0" Maximum="100">
            <LinearGaugePointers>
                <LinearGaugePointer PointerValue="@currentValue" 
                                    EnableDrag="true">
                </LinearGaugePointer>
            </LinearGaugePointers>
        </LinearGaugeAxis>
    </LinearGaugeAxes>
</SfLinearGauge>

@code {
    private double currentValue = 50;
    
    private void OnValueChange(ValueChangeEventArgs args)
    {
        currentValue = args.Value;
    }
}

模式 4：样式化温度计

用例： 使用可视化区域显示温度

@using Syncfusion.Blazor.LinearGauge

<SfLinearGauge Width="150px" Height="400px">
    <LinearGaugeAxes>
        <LinearGaugeAxis Minimum="-20" Maximum="120">
            <LinearGaugeAxisLabelStyle Format="{value}°">
            </LinearGaugeAxisLabelStyle>
            <LinearGaugePointers>
                <LinearGaugePointer PointerValue="@temperature" 
                                    Type="Syncfusion.Blazor.LinearGauge.Point.Bar"
                                    Color="#ff6b6b"
                                    Width="20">
                </LinearGaugePointer>
            </LinearGaugePointers>
            <LinearGaugeRanges>
                <LinearGaugeRange Start="-20" End="0" Color="#0099ff"></LinearGaugeRange>
                <LinearGaugeRange Start="0" End="25" Color="#00e676"></LinearGaugeRange>
                <LinearGaugeRange Start="25" End="120" Color="#ff5252"></LinearGaugeRange>
            </LinearGaugeRanges>
        </LinearGaugeAxis>
    </LinearGaugeAxes>
</SfLinearGauge>

@code {
    private double temperature = 35;
}

---

API 参考

官方 Linear Gauge API 以 SfLinearGauge 组件为核心，并提供全面的子组件，用于配置坐标轴、指针、范围、注释、渐变、工具提示和事件处理程序。本参考基于官方的 Syncfusion Blazor Linear Gauge API 文档。

SfLinearGauge

仪表的主要容器组件。它是承载所有仪表元素的根组件。

组件属性：

尺寸和布局：

• Width（string）：设置线性仪表容器的宽度
• Height（string）：设置线性仪表容器的高度
• Orientation（Orientation）：设置仪表方向（Horizontal 或 Vertical）
• Description（string）：设置用于无障碍访问的说明

外观：

• Title（string）：设置仪表上显示的标题文本
• TitleStyle（LinearGaugeTitleStyle）：配置标题字体、位置和样式
• Background（string）：设置仪表容器的背景颜色
• Theme（Theme）：应用预定义主题（Bootstrap、Material、Fabric、Fluent、Tailwind 等）
• Container（LinearGaugeContainer）：配置容器外观和边框
• Margin（LinearGaugeMargin）：设置左、右、上、下边距

行为：

• AnimationDuration（double）：设置初始渲染和指针更新的动画时长（毫秒）
• Format（string）：设置坐标轴标签的数字格式
• EnableGroupingSeparator（bool）：启用数字的千位分隔符
• ID（string）：设置仪表组件的唯一标识符
• TabIndex（int）：设置键盘导航的 Tab 顺序

导出和打印：

• AllowPrint（bool）：启用打印功能
• AllowPdfExport（bool）：启用 PDF 导出功能
• AllowImageExport（bool）：启用图像导出功能（PNG、SVG）
• AllowMargin（bool）：打印或导出时包含边距

样式：

• RangePalettes（string[]）：定义范围的自动配色方案

方法：

// Update pointer value programmatically (async version)
public async Task SetPointerValueAsync(int axisIndex, int pointerIndex, double value)

// Update annotation content dynamically (async version)
public async Task SetAnnotationValueAsync(int annotationIndex, string content)

// Refresh the entire gauge (async version)
public async Task RefreshAsync()

// Print the gauge (requires AllowPrint="true")
public async Task PrintAsync()

// Export gauge to file (requires corresponding AllowXyzExport="true")
public async Task ExportAsync(ExportType type, string fileName, 
    PdfPageOrientation? orientation = null, bool allowDownload = true)

导出类型：

• ExportType.PNG
• ExportType.SVG
• ExportType.PDF

LinearGaugeAxes 和 LinearGaugeAxis

用于容纳一个或多个坐标轴的容器（LinearGaugeAxes）。每个 LinearGaugeAxis 定义一个包含范围、刻度、标签、指针和区间的刻度尺。

LinearGaugeAxis 属性：

刻度配置：

• Minimum（double）：设置坐标轴刻度的最小值
• Maximum（double）：设置坐标轴刻度的最大值
• IsInversed（bool）：反转坐标轴方向（由高到低，而非由低到高）
• OpposedPosition（bool）：将坐标轴放在另一侧（垂直方向为左侧/右侧，水平方向为顶部/底部）
• ShowLastLabel（bool）：显示或隐藏坐标轴上的最后一个标签

子组件：

• LinearGaugeLine - 配置坐标轴线的外观
• LinearGaugeMajorTicks - 坐标轴上的主刻度线
• LinearGaugeMinorTicks - 坐标轴上的次刻度线
• LinearGaugeAxisLabelStyle - 标签样式和位置
• LinearGaugeAxisLabelFont - 坐标轴标签的字体属性
• LinearGaugeContainer - 坐标轴的容器
• LinearGaugePointers - 此坐标轴的指针集合
• LinearGaugeRanges - 此坐标轴的范围集合
• LinearGaugeLinearGradient - 坐标轴元素的线性渐变填充
• LinearGaugeRadialGradient - 坐标轴元素的径向渐变填充

轴线与刻度

LinearGaugeLine - 定义轴线的外观

• Height (double)：轴线高度
• Width (double)：轴线宽度
• Color (string)：轴线颜色
• Offset (double)：相对于轴的偏移量

LinearGaugeMajorTicks - 主刻度配置

• Interval (double)：主刻度之间的间隔
• Height (double)：主刻度线的高度
• Width (double)：主刻度线的宽度
• Color (string)：主刻度颜色
• Position (Position)：相对于轴的位置（Inside、Outside、Cross）
• Offset (double)：相对于轴线的偏移量

LinearGaugeMinorTicks - 次刻度配置

• Interval (double)：次刻度之间的间隔
• Height (double)：次刻度线的高度
• Width (double)：次刻度线的宽度
• Color (string)：次刻度颜色
• Position (Position)：相对于轴的位置
• Offset (double)：相对于轴线的偏移量

轴标签

LinearGaugeAxisLabelStyle - 标签样式与定位

• Format (string)：标签值的格式字符串（例如，"{value}°C"）
• Position (Position)：标签位置（Inside、Outside、Cross）
• Offset (double)：与轴线的距离
• FontFamily (string)：标签字体系列
• Color (string)：标签文字颜色
• Opacity (double)：标签不透明度（0 到 1）

LinearGaugeAxisLabelFont - 轴标签的字体属性

• FontFamily (string)：字体系列名称
• FontSize (string)：以像素或相对单位表示的字体大小
• FontStyle (string)：字体样式（normal、italic、oblique）
• FontWeight (string)：字体粗细（normal、bold、lighter、bolder、100-900）

LinearGaugePointers 与 LinearGaugePointer

用于包含一个或多个数值指示器的容器（LinearGaugePointers）。每个 LinearGaugePointer 表示轴上的一个数值。

LinearGaugePointer 属性：

数值与类型：

• PointerValue (double)：设置指针数值
• Type (PointerType)：指针类型（Marker 或 Bar）
• MarkerType (MarkerType)：标记指针的形状：
  • Circle
  • Rectangle
  • Triangle
  • Diamond
  • InvertedTriangle

外观：

• Color (string)：指针颜色
• Width (double)：指针宽度
• Height (double)：指针高度
• Opacity (double)：指针不透明度（0 到 1）
• Offset (double)：相对于轴线的偏移量
• Placement (Placement)：相对于轴的位置（Center、Near、Far）
• RoundedCornerRadius (double)：圆角半径（条形指针）

内容：

• ImageUrl (string)：图像指针的 URL
• Text (string)：文本指针要显示的文本

交互：

• EnableDrag (bool)：允许用户拖动指针以更改数值
• AnimationDuration (double)：数值变化动画的持续时间（毫秒）

子组件：

• LinearGaugePointerBorder - 指针边框样式
• LinearGaugeMarkerTextStyle - 文本指针的文本样式

指针样式

LinearGaugePointerBorder - 指针边框属性

• Color (string)：边框颜色
• Width (double)：边框宽度

LinearGaugeMarkerTextStyle - 指针文本样式

• FontFamily (string)：字体系列
• FontSize (string)：字体大小
• Color (string)：文本颜色
• FontWeight (string)：字体粗细
• Opacity (double)：文本不透明度

LinearGaugeRanges & LinearGaugeRange

用于定义颜色编码数值区域的容器（LinearGaugeRanges）。每个 LinearGaugeRange 定义一个有颜色的区域。

LinearGaugeRange 属性：

范围定义：

• Start (double)：范围起始值
• End (double)：范围结束值

外观：

• Color (string)：范围的背景颜色
• StartWidth (double)：范围起始处的宽度（用于产生渐变宽度效果）
• EndWidth (double)：范围末端的宽度
• Position (Position)：相对于轴的位置（Inside、Outside、Cross）
• Offset (double)：与轴线的偏移量

子组件：

• LinearGaugeRangeBorder - 范围边框样式
• LinearGaugeRangeTooltipSettings - 范围工具提示（悬停时显示）

LinearGaugeRangeBorder - 范围边框属性

• Color (string)：边框颜色
• Width (double)：边框宽度

LinearGaugeAnnotations & LinearGaugeAnnotation

用于放置文本或 HTML 覆盖层的容器（LinearGaugeAnnotations）。每个 LinearGaugeAnnotation 都会添加一个标签或自定义内容。

LinearGaugeAnnotation 属性：

内容与定位：

• AxisValue (double)：批注显示所在的轴位置
• AxisIndex (int)：轴的索引（多轴时）
• X (double)：相对于轴值的水平像素偏移量
• Y (double)：相对于轴值的垂直像素偏移量
• ZIndex (int)：图层顺序（数值越大越靠上）
• HorizontalAlignment (Alignment)：水平对齐方式（Near、Center、Far）
• VerticalAlignment (Alignment)：垂直对齐方式

内容：

• Content (string)：批注的文本或 HTML 内容
• ContentTemplate (RenderFragment)：用于渲染批注内容的模板

子组件：

• LinearGaugeAnnotationFont - 文本批注的字体样式

LinearGaugeAnnotationFont - 批注的字体属性

• FontFamily (string)：字体系列
• FontSize (string)：字号
• Color (string)：文本颜色
• FontWeight (string)：字重
• Opacity (double)：文本不透明度

渐变配置

LinearGaugeLinearGradient - 仪表元素的线性渐变

• StartValue (double)：渐变的起始位置
• EndValue (double)：渐变的结束位置
• ColorStops (ColorStops)：颜色渐变点集合

LinearGaugeRadialGradient - 仪表元素的径向渐变

• Radius (string)：径向渐变的半径
• InnerPosition (InnerPosition)：内圆位置
• OuterPosition (OuterPosition)：外圆位置
• ColorStops (ColorStops)：颜色渐变点集合

ColorStop / ColorStops - 渐变颜色定义

• Offset (string)：渐变中的位置（例如，“0%”、“100%”）
• Color (string)：此位置的颜色
• Opacity (double)：此位置的不透明度

容器与边框样式

LinearGaugeContainer - 仪表的外部容器

• Type (ContainerType)：容器类型（Normal、RoundedRectangle、Thermometer）
• Offset (double)：与轴的偏移量
• Width (double)：容器宽度
• BackgroundColor (string)：背景颜色
• Border (LinearGaugeContainerBorder)：边框样式

LinearGaugeContainerBorder - 容器边框属性

• Color (string)：边框颜色
• Width (double)：边框宽度

LinearGaugeBorder / LinearGaugeBorderSettings - 仪表边框属性

• Color (string)：边框颜色
• Width (double)：边框宽度

LinearGaugeMargin / LinearGaugeMarginSettings - 边距配置

• Left (double)：左边距
• Right (double)：右边距
• Top (double)：上边距
• Bottom (double)：下边距

工具提示配置

LinearGaugeTooltipSettings - 指针工具提示配置

• Enable (bool)：启用或禁用工具提示
• Format (string)：工具提示文本格式
• Position (TooltipPosition)：工具提示位置（Top、Bottom、Left、Right）
• Fill (string)：工具提示背景颜色
• Opacity (double)：工具提示不透明度
• ShowAtMousePosition (bool)：在光标位置而非指针位置显示
• TextStyle (LinearGaugeTooltipTextStyle)：文本样式
• Border (LinearGaugeTooltipBorder)：边框样式

LinearGaugeRangeTooltipSettings - 范围悬停工具提示配置

• 范围悬停工具提示的属性与工具提示设置类似

LinearGaugeTooltipTextStyle - 工具提示文本样式

• FontFamily (string)、FontSize (string)、Color (string)、FontWeight (string)、Opacity (double)

事件和事件参数

LinearGaugeEvents - 事件处理组件

@using Syncfusion.Blazor.LinearGauge

<LinearGaugeEvents 
    Load="OnLoad"
    Loaded="OnLoaded"
    AxisLabelRendering="OnAxisLabelRendering"
    AnnotationRendering="OnAnnotationRendering"
    ValueChange="OnValueChange"
    TooltipRendering="OnTooltipRendering"
    DragStart="OnDragStart"
    DragMove="OnDragMove"
    DragEnd="OnDragEnd"
    AnimationComplete="OnAnimationComplete"
    ResizeCompleted="OnResizeCompleted"
    OnGaugeMouseDown="OnMouseDown"
    OnGaugeMouseLeave="OnMouseLeave"
    OnGaugeMouseUp="OnMouseUp"
    Print="OnPrint">
</LinearGaugeEvents>

事件类型和参数：

事件	参数类型	描述
Load	LoadEventArgs	在量规渲染前触发；可通过 args.Cancel = true 取消
Loaded	LoadedEventArgs	量规成功渲染后触发
AxisLabelRendering	AxisLabelRenderEventArgs	每个轴标签渲染前触发；修改 args.Text 以自定义
AnnotationRendering	AnnotationRenderEventArgs	注释渲染前触发；修改 args.Content 以自定义
ValueChange	ValueChangeEventArgs	指针值更改时触发（用户拖动或以编程方式更改）；提供 Value、PointerIndex、AxisIndex
TooltipRendering	TooltipRenderEventArgs	工具提示显示前触发；自定义 args.Content
DragStart	PointerDragEventArgs	用户开始拖动指针时触发；提供 CurrentValue、PointerIndex、AxisIndex
DragMove	PointerDragEventArgs	指针拖动期间持续触发；提供当前值
DragEnd	PointerDragEventArgs	用户拖动后释放指针时触发
AnimationComplete	AnimationCompleteEventArgs	指针动画完成时触发
ResizeCompleted	ResizeEventArgs	量规调整大小后触发；提供 CurrentSize、PreviousSize
OnGaugeMouseDown	MouseEventArgs	在量规上按下鼠标时触发
OnGaugeMouseLeave	MouseEventArgs	鼠标离开量规时触发
OnGaugeMouseUp	MouseEventArgs	在量规上松开鼠标时触发
Print	PrintEventArgs	打印前触发

枚举

Orientation - 量规布局方向

Orientation.Horizontal  // Horizontal scale
Orientation.Vertical    // Vertical scale

Position - 元素相对于坐标轴的位置

Position.Inside      // Inside the axis
Position.Outside     // Outside the axis
Position.Cross       // Crossing the axis line

PointerType - 数值指示器类型

PointerType.Marker   // Shaped marker (circle, square, etc.)
PointerType.Bar      // Bar/rectangle pointer

MarkerType - 标记指针形状

MarkerType.Circle
MarkerType.Rectangle
MarkerType.Triangle
MarkerType.Diamond
MarkerType.InvertedTriangle

Placement - 指针相对于坐标轴的位置

Placement.Center     // Centered on axis
Placement.Near       // Near side
Placement.Far        // Far side

ContainerType - 容器形状

ContainerType.Normal              // Rectangular container
ContainerType.RoundedRectangle    // Rounded rectangle
ContainerType.Thermometer         // Thermometer shape

ExportType - 导出格式

ExportType.PNG   // Export as PNG image
ExportType.SVG   // Export as SVG image
ExportType.PDF   // Export as PDF document

TooltipPosition - 工具提示位置

TooltipPosition.Top      // Above the pointer
TooltipPosition.Bottom   // Below the pointer
TooltipPosition.Left     // Left of pointer
TooltipPosition.Right    // Right of pointer

Theme - 预定义颜色主题

Theme.Bootstrap
Theme.Material
Theme.Fabric
Theme.Fluent
Theme.Tailwind
Theme.Bootstrap5
Theme.FluentDark
Theme.MaterialDark
Theme.BootstrapDark
Theme.TailwindDark
// ... and others

主要组件层级

SfLinearGauge (root)
├── LinearGaugeTitleStyle
├── LinearGaugeMargin
├── LinearGaugeBorder
├── LinearGaugeContainer
│   └── LinearGaugeContainerBorder
├── LinearGaugeAxes
│   └── LinearGaugeAxis (repeatable)
│       ├── LinearGaugeLine
│       ├── LinearGaugeMajorTicks
│       ├── LinearGaugeMinorTicks
│       ├── LinearGaugeAxisLabelStyle
│       ├── LinearGaugeAxisLabelFont
│       ├── LinearGaugeContainer
│       ├── LinearGaugeLinearGradient
│       ├── LinearGaugeRadialGradient
│       ├── LinearGaugePointers
│       │   └── LinearGaugePointer (repeatable)
│       │       ├── LinearGaugePointerBorder
│       │       └── LinearGaugeMarkerTextStyle
│       └── LinearGaugeRanges
│           └── LinearGaugeRange (repeatable)
│               ├── LinearGaugeRangeBorder
│               └── LinearGaugeRangeTooltipSettings
├── LinearGaugeAnnotations
│   └── LinearGaugeAnnotation (repeatable)
│       └── LinearGaugeAnnotationFont
├── LinearGaugeTooltipSettings
│   ├── LinearGaugeTooltipTextStyle
│   └── LinearGaugeTooltipBorder
└── LinearGaugeEvents
    ├── Load handler
    ├── Loaded handler
    ├── AxisLabelRendering handler
    ├── AnnotationRendering handler
    ├── ValueChange handler
    ├── TooltipRendering handler
    ├── DragStart/Move/End handlers
    ├── AnimationComplete handler
    └── ... more event handlers

API 实用说明

1. 异步方法：所有组件方法（SetPointerValueAsync、SetAnnotationValueAsync、RefreshAsync、PrintAsync、ExportAsync）都是异步的，必须使用 await 等待。

2. 导出前提条件：调用相应的导出或打印方法之前，请确保在仪表上设置了 AllowPdfExport="true"、AllowImageExport="true" 或 AllowPrint="true"。

3. 动画：将 AnimationDuration="0" 设置为即时更新，或设置更高的值以实现平滑的动画过渡。

4. 事件参数：事件处理程序参数由框架提供，并包含特定上下文信息（例如，ValueChangeEventArgs 包含新值）。

5. 基于索引的访问：使用 SetPointerValueAsync 或 SetAnnotationValueAsync 时，轴、指针和注释的索引从 0 开始。

6. 性能：对于频繁更新（例如，每 100ms 一次），请考虑批量处理更新或使用 AnimationDuration="0"，以避免动画开销。

7. 无障碍：如果仪表需要支持屏幕阅读器，请使用 Description、Title 和适当的 ARIA 标签。

完整组件列表

组件类（来自 Syncfusion.Blazor.LinearGauge 命名空间）：

1. SfLinearGauge - 主组件
2. LinearGaugeAnnotation - 注释元素
3. LinearGaugeAnnotationFont - 注释字体样式
4. LinearGaugeAnnotations - 注释集合
5. LinearGaugeAxes - 坐标轴集合
6. LinearGaugeAxis - 坐标轴配置
7. LinearGaugeAxisLabelFont - 坐标轴标签字体
8. LinearGaugeAxisLabelStyle - 坐标轴标签样式
9. LinearGaugeBorder - 仪表边框
10. LinearGaugeBorderSettings - 边框设置
11. LinearGaugeContainer - 容器配置
12. LinearGaugeContainerBorder - 容器边框
13. LinearGaugeEvents - 事件处理程序
14. LinearGaugeFontSettings - 字体配置
15. LinearGaugeLine - 坐标轴线
16. LinearGaugeLinearGradient - 线性渐变
17. LinearGaugeMajorTicks - 主刻度线
18. LinearGaugeMargin - 边距设置
19. LinearGaugeMarginSettings - 边距配置
20. LinearGaugeMarkerTextStyle - 标记文本样式
21. LinearGaugeMinorTicks - 次刻度线
22. LinearGaugePointer - 指针元素
23. LinearGaugePointerBorder - 指针边框
24. LinearGaugePointers - 指针集合
25. LinearGaugeRadialGradient - 径向渐变
26. LinearGaugeRange - 范围元素
27. LinearGaugeRangeBorder - 范围边框
28. LinearGaugeRangeTooltipBorder - 范围提示框边框
29. LinearGaugeRangeTooltipSettings - 范围提示框
30. LinearGaugeRangeTooltipTextStyle - 范围提示框文本
31. LinearGaugeRanges - 范围集合
32. LinearGaugeTickSettings - 刻度配置
33. LinearGaugeTitleStyle - 标题样式
34. LinearGaugeTooltipBorder - 提示框边框
35. LinearGaugeTooltipSettings - 提示框配置
36. LinearGaugeTooltipTextStyle - 提示框文本样式
37. LinearGradient - 线性渐变定义
38. RadialGradient - 径向渐变定义
39. ColorStop - 渐变颜色节点
40. ColorStops - 渐变颜色节点集合
41. Point - 指针类型枚举
42. GradientPosition - 渐变位置
43. InnerPosition - 渐变内部位置
44. OuterPosition - 渐变外部位置

事件参数类：

• LoadEventArgs
• LoadedEventArgs
• AxisLabelRenderEventArgs
• AnnotationRenderEventArgs
• ValueChangeEventArgs
• TooltipRenderEventArgs
• PointerDragEventArgs
• ResizeEventArgs
• MouseEventArgs
• PrintEventArgs
• AnimationCompleteEventArgs

枚举类型：

• Orientation - 水平或垂直
• Position - 内部、外部、交叉
• PointerType - 标记或条形
• MarkerType - 圆形、矩形、三角形、菱形、倒三角形
• Placement - 居中、近端、远端
• ContainerType - 普通、圆角矩形、温度计
• ExportType - PNG、SVG、PDF
• TooltipPosition - 上、下、左、右
• Theme - 各种主题选项
• Alignment - 近端、居中、远端
• PdfPageOrientation - 纵向、横向

---

常见用例

1. 仪表板 KPI 显示

使用颜色编码的范围显示关键绩效指标，以便快速评估状态。可使用多个仪表显示不同指标。

2. 温度监控

使用不同区域（冰冻、正常、警告、危急）的适当范围来可视化温度读数。

3. 进度跟踪

在水平仪表上使用条形指针显示任务完成情况、项目进度或目标达成情况。

4. 速度表／转速表

创建车辆仪表板组件，使用样式化指针和范围显示速度或 RPM。

5. 传感器数据可视化

通过动态更新指针和阈值指示器，显示实时传感器读数（压力、湿度、电压）。

6. 调查／评分显示

在刻度上可视化调查结果或评分，并通过标记显示平均值，通过范围显示分布情况。

7. 预算与实际值对比

在同一坐标轴上使用多个指针，显示预算值与实际值的财务指标对比。

8. 库存水平

使用颜色编码的范围（危急、偏低、充足、满仓）显示库存水平，便于快速查看状态。

---

实施技巧

开始时

1. 从 getting-started.md 开始进行设置
2. 添加基本坐标轴和指针，以验证功能
3. 逐步添加范围、样式和交互功能

自定义

1. 使用 axes-configuration.md 自定义刻度
2. 使用 pointers.md 设置指针样式
3. 使用 appearance-and-styling.md 设置整体外观

添加交互功能

1. 启用指针拖动，供用户输入
2. 添加工具提示以显示数值
3. 使用事件响应用户操作
4. 请参阅 user-interaction.md 和 methods-and-events.md

用于生产环境

1. 根据 accessibility-and-internationalization.md 实现无障碍功能
2. 使用键盘导航进行测试
3. 验证屏幕阅读器兼容性
4. 配置适当的 ARIA 标签

---

后续步骤

1. 刚接触 Linear Gauge？ 从 getting-started.md 开始
2. 需要特定功能？ 根据需求查阅相关参考文件
3. 正在构建仪表板？ 组合多种模式，并参阅 appearance-and-styling.md
4. 需要交互功能？ 查看 user-interaction.md 和 methods-and-events.md

所有参考文件都内容详尽且独立完整——针对单个主题，无需在多个文件之间来回查阅。