syncfusion-flutter-gauges

Syncfusion Flutter Gauges

此技能涵盖两个相关的 Syncfusion Flutter 组件，用于数据可视化和测量显示：SfLinearGauge（线性仪表）和 SfRadialGauge（径向仪表）。虽然它们有许多相同的视觉和配置功能，但用途不同，视觉呈现方式也各不相同。

何时使用此技能

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

• 在线性或径向刻度上显示数据，以直观呈现测量结果
• 创建进度指示器，并自定义样式和动画
• 构建仪表板可视化效果，展示 KPI、指标或性能指示器
• 实现测量显示（速度表、温度计、压力表）
• 添加交互式仪表，支持拖动指针和更改数值
• 在线性或圆形刻度上可视化范围和阈值
• 创建自定义仪表控件，用于音量、亮度或评分输入
• 在现代 Flutter 应用中显示模拟风格的指示器
• 通过仪表呈现方式构建电池、信号或状态指示器
• 自定义仪表外观，包括颜色、渐变、动画和样式

选择合适的组件

在以下情况下使用 SfLinearGauge（线性仪表）：

• 需要水平或垂直测量显示
• 数据最适合用线性刻度（条形样式）表示
• 需要使用条形指针显示进度或级别
• 方向灵活性很重要（可轻松旋转 90°）
• 对称显示需要镜像效果
• 构建：进度条、滑块、电池指示器、音量控件、水平仪表板

在以下情况下使用 SfRadialGauge（径向仪表）：

• 需要圆形或弧形显示
• 可视化需要使用指针（经典仪表样式）
• 需要360 度或半圆形呈现
• 需要在仪表上放置带小部件的注释
• 需要在仪表上方显示标题
• 需要导出为图像功能
• 构建：速度表、转速表、温度仪、指南针显示、钟面、圆形进度指示器

主要差异摘要：

功能	SfLinearGauge	SfRadialGauge
主要形状	线性（水平/垂直）	圆形/弧形
方向	水平、垂直	圆形（360°）
条形指针	✅ 是	❌ 否
指针	❌ 否	✅ 是
范围指针	❌ 否	✅ 是
标记指针	✅ 形状和小部件	✅ 形状和小部件
镜像效果	✅ 是	❌ 否
注释	❌ 否	✅ 是
标题支持	❌ 否	✅ 是
导出为图像	❌ 否	✅ 是
多个轴	❌ 有限支持	✅ 是
轴角度	不适用	✅ 可配置

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 两个组件的安装和软件包设置
• SfLinearGauge 基本实现
• SfRadialGauge 基本实现
• 软件包依赖项和导入
• 快速比较和首个示例

组件概览

📄 线性仪表： references/linear-gauge-overview.md

• SfLinearGauge 小部件概览和功能
• 何时使用线性仪表而非径向仪表
• 方向选项（水平/垂直）
• 线性仪表专属功能
• 线性仪表基本配置

📄 径向仪表： references/radial-gauge-overview.md

• SfRadialGauge 小部件概览和功能
• 何时使用径向仪表而非线性仪表
• 圆形和弧形配置
• 径向仪表专属功能
• 标题和多轴支持
• 径向仪表基本配置

轴和刻度

📄 阅读： references/axes.md

• 两种仪表的轴自定义
• 线性轴（轨道、粗细、颜色）
• 径向轴（圆弧、角度、半径）
• 最小值和最大值
• 轴间隔和刻度
• 轴线样式和渐变
• 标签和刻度线的位置
• 反向轴方向
• 自定义刻度和渲染器
• 多个轴（径向）

指针

📄 阅读： references/pointers.md

• 指针类型概览
• 形状/标记指针（两种仪表）
• Widget 指针（两种仪表）
• 条形指针（仅线性仪表）
• 指针指针（仅径向仪表）
• 范围指针（仅径向仪表）
• 多个指针的配置
• 指针定位和样式
• 指针对比和选择指南

范围

📄 阅读： references/ranges.md

• 范围可视化概念
• 向线性仪表添加范围
• 向径向仪表添加范围
• 范围颜色和渐变
• 范围定位和粗细
• 多个范围的配置
• 范围用例和模式

自定义和样式

📄 阅读： references/customization.md

• 两种仪表的视觉外观
• 颜色（纯色和渐变）
• 粗细和尺寸
• 边框自定义
• 圆角和边缘样式
• 背景颜色和图像
• 主题集成
• 标签和刻度线样式

动画

📄 阅读： references/animation.md

• 两种仪表的动画支持
• 指针动画
• 轴和范围动画
• 动画时长和缓动
• enableAnimation 属性
• 动画回调
• 加载动画

交互

📄 阅读： references/interaction.md

• 两种仪表的指针拖动
• enableDragging 属性
• 值变更事件
• onValueChangeStart、onValueChanging、onValueChanged、onValueChangeEnd
• 触控和手势支持
• 交互式值更新
• 限制拖动范围

无障碍功能

📄 阅读： references/accessibility.md

• 屏幕阅读器支持
• 仪表的语义标签
• WCAG 合规性
• 键盘导航
• 线性仪表的无障碍功能
• 径向仪表的无障碍功能
• 最佳实践

高级功能

📄 阅读： references/advanced-features.md

• 镜像仪表（线性仪表）
• 使用 Widget 添加注释（径向仪表）
• 导出为图像（径向仪表）
• 背景图像（径向仪表）
• 自定义标签格式
• 自定义渲染器和构建器
• 特殊配置
• 边缘情况和故障排除

快速入门示例

如需详细的设置说明，请参阅 入门指南。

基本线性仪表

import 'package:syncfusion_flutter_gauges/gauges.dart';

SfLinearGauge(
  minimum: 0,
  maximum: 100,
  barPointers: [LinearBarPointer(value: 60)],
  markerPointers: [LinearShapePointer(value: 60)],
)

基本径向仪表

import 'package:syncfusion_flutter_gauges/gauges.dart';

SfRadialGauge(
  axes: [
    RadialAxis(
      minimum: 0,
      maximum: 150,
      pointers: [NeedlePointer(value: 90)],
    ),
  ],
)

交互式仪表（可拖动）

double _value = 50.0;

// Linear with dragging
SfLinearGauge(
  markerPointers: [
    LinearShapePointer(
      value: _value,
      enableDragging: true,
      onChanged: (v) => setState(() => _value = v),
    ),
  ],
)

// Radial with dragging
SfRadialGauge(
  axes: [
    RadialAxis(
      pointers: [
        NeedlePointer(
          value: _value,
          enableDragging: true,
          onValueChanged: (v) => setState(() => _value = v),
        ),
      ],
    ),
  ],
)

常见模式

多范围状态指示器：

ranges: [
  LinearGaugeRange(startValue: 0, endValue: 30, color: Colors.red),
  LinearGaugeRange(startValue: 30, endValue: 70, color: Colors.yellow),
  LinearGaugeRange(startValue: 70, endValue: 100, color: Colors.green),
]

渐变样式：

axisTrackStyle: LinearAxisTrackStyle(
  gradient: LinearGradient(colors: [Colors.blue, Colors.purple]),
)

垂直方向：

SfLinearGauge(
  orientation: LinearGaugeOrientation.vertical,
  barPointers: [LinearBarPointer(value: 75)],
)

自定义角度（半圆）：

RadialAxis(startAngle: 180, endAngle: 0)

镜像效果：

SfLinearGauge(isMirrored: true)

关键属性

SfLinearGauge 基本属性

• minimum - 轴的最小值（默认值：0）
• maximum - 轴的最大值（默认值：100）
• interval - 轴标签之间的间隔
• orientation - 水平或垂直方向
• isMirrored - 镜像仪表元素
• isAxisInversed - 反转轴方向
• axisTrackStyle - 轴轨道样式（颜色、厚度、渐变、边框）
• axisTrackExtent - 延伸轴轨道的两端
• showAxisTrack - 显示/隐藏轴轨道
• showLabels - 显示/隐藏轴标签
• showTicks - 显示/隐藏刻度线
• labelPosition - 标签置于内侧或外侧
• tickPosition - 刻度置于内侧或外侧
• labelOffset - 刻度线与标签之间的距离
• labelFormatterCallback - 自定义标签格式化
• ranges - 用于彩色分段的 LinearGaugeRange 列表
• markerPointers - 形状或组件指针列表
• barPointers - 条形指针列表（进度样式）
• animationDuration - 动画时长（毫秒）
• onGenerateLabels - 自定义标签生成回调
• valueToFactorCallback - 自定义比例转换

SfRadialGauge 基本属性

• title - 仪表标题 GaugeTitle
• backgroundColor - 仪表背景颜色
• axes - RadialAxis 列表（支持多个）
• enableLoadingAnimation - 显示加载动画
• animationDuration - 动画时长（毫秒）

RadialAxis 基本属性

• minimum - 轴的最小值（默认值：0）
• maximum - 轴的最大值（默认值：100）
• interval - 标签之间的间隔
• startAngle - 轴的起始角度（默认值：270）
• endAngle - 轴的结束角度（默认值：270）
• radiusFactor - 半径大小因子（0-1）
• centerX - 水平中心位置（0-1）
• centerY - 垂直中心位置（0-1）
• isInversed - 反转轴方向
• canScaleToFit - 根据角度定位轴
• canRotateLabels - 根据角度旋转标签
• showFirstLabel - 显示/隐藏第一个标签
• showLastLabel - 显示/隐藏最后一个标签
• maximumLabels - 每 100 个逻辑像素的最大标签数
• axisLineStyle - 轴线的 AxisLineStyle
• showAxisLine - 显示/隐藏轴线
• showLabels - 显示/隐藏标签
• showTicks - 显示/隐藏刻度线
• axisLabelStyle - 标签的 GaugeTextStyle
• labelFormat - 标签格式字符串（前缀/后缀）
• numberFormat - 用于本地化的 NumberFormat
• labelsPosition - 标签置于内侧或外侧
• ticksPosition - 刻度置于内侧或外侧
• majorTickStyle - 自定义 MajorTickStyle
• minorTickStyle - 自定义 MinorTickStyle
• minorTicksPerInterval - 每个间隔内的次刻度数
• tickOffset - 与轴的距离
• labelOffset - 与刻度线的距离
• offsetUnit - 逻辑像素或因子
• backgroundImage - 轴背景的 AssetImage
• ranges - GaugeRange 列表
• pointers - GaugePointer 列表
• annotations - GaugeAnnotation 列表
• onLabelCreated - 标签创建回调
• onAxisTapped - 轴点击回调
• onCreateAxisRenderer - 自定义渲染器回调

LinearGauge 范围属性

• startValue - 范围起始值
• endValue - 范围结束值
• color - 范围颜色
• startWidth - 起始宽度
• endWidth - 结束宽度
• position - 内侧、外侧或横跨
• rangeShapeType - 平直或曲线形状

RadialGauge 范围属性

• startValue - 范围起始值
• endValue - 范围结束值
• color - 范围颜色
• startWidth - 起始宽度
• endWidth - 结束宽度
• gradient - 范围渐变
• rangeOffset - 与轴的偏移量
• sizeUnit - 逻辑像素或因子
• label - 范围文本标签

指针属性（通用）

• value - 指针值
• enableDragging - 启用指针拖动
• enableAnimation - 启用指针动画
• animationDuration - 动画时长
• animationType - 动画曲线类型
• onValueChangeStart - 拖动开始回调
• onValueChanging - 拖动进度回调
• onValueChanged - 值变更回调
• onValueChangeEnd - 拖动结束回调

常见用例

1. 进度指示器 - 使用 LinearBarPointer 或 RangePointer 跟踪进度
2. 速度表仪表盘 - 使用带有 NeedlePointer 和范围的 RadialGauge
3. 温度显示 - 使用垂直 LinearGauge 或半圆形 RadialGauge
4. 电量指示器 - 使用带有镜像效果和范围的 LinearGauge
5. 音量/亮度控制 - 使用可拖动的 LinearShapePointer
6. KPI 仪表盘 - 使用多个带有注释的 RadialGauge
7. 评分显示 - 使用带有半圆形和 RangePointer 的 RadialGauge
8. 燃油表 - 使用带有指针和彩色范围的 RadialGauge
9. 加载指示器 - 使用动画 LinearBarPointer 或 RangePointer
10. 滑块替代方案 - 使用带有可拖动指针的交互式 LinearGauge