syncfusion-react-linear-gauge

实现 Syncfusion React Linear Gauge

何时使用此技能

在以下情况下使用 Linear Gauge 组件：

• 在直线／水平刻度上显示测量值（温度计、温度计、燃油指示器）
• 监控实时数据，并通过动画更新指针（传感器读数、系统指标）
• 以线性格式显示进度或百分比
• 创建仪表板，通过多个仪表显示 KPI
• 使用不同颜色显示范围（例如安全、警告、严重区域）
• 构建外观和交互性均可自定义的响应式数据可视化
• 打印或导出仪表可视化内容，用于报告和文档

Linear Gauge 非常适合需要在水平／线性刻度上直观呈现数值，并可自定义坐标轴、指针、范围和交互功能的应用。

---

组件概述

Syncfusion React Linear Gauge（@syncfusion/ej2-react-lineargauge）是一个在直线刻度上显示数值的数据可视化组件。它包含：

• 坐标轴 - 具有可自定义范围、刻度线、标签和样式的线性刻度
• 指针 - 两种类型的数值指示器：条形（默认）或标记（形状）
• 范围 - 表示数值范围的彩色区段（例如冷、暖、热）
• 注释 - 用于标签和标注的文本或图像叠加层
• 刻度线和标签 - 支持自定义格式的刻度标记
• 导出 - 支持打印、导出为 PDF、PNG 或 SVG

---

文档与导航指南

根据要实现的内容选择参考文档：

入门与设置

📄 阅读： references/getting-started.md

• 安装 @syncfusion/ej2-react-lineargauge 包
• 在 Vite 或 Create React App 中进行设置
• 初始化基础组件
• 最简可运行示例
• CSS 导入和主题
• 何时阅读： 首次设置或集成到新项目时

仪表结构：坐标轴、刻度线和标签

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

• 配置坐标轴（最小值、最大值范围）
• 自定义坐标轴线（高度、宽度、颜色）
• 配置主刻度线和次刻度线
• 设置标签格式并自定义标签
• 设置标签单位和格式
• 配置多个坐标轴
• 何时阅读： 构建仪表的核心结构和刻度时

指针类型与配置

📄 阅读： references/pointers.md

• 条形指针类型（默认、填充样式）
• 标记指针类型（圆形、矩形、三角形、菱形、图像、文本）
• 设置和更新指针值
• 自定义指针外观（宽度、颜色、半径）
• 在同一坐标轴上使用多个指针
• 拖放交互
• 性能优化
• 何时阅读： 添加数值指示器和交互功能时

范围与注释

📄 阅读： references/ranges-annotations.md

• 使用起始值／结束值创建范围
• 设置范围样式（颜色、渐变效果）
• 设置范围标签及其位置
• 为标注和标签添加文本注释
• 图像注释
• 设置位置和对齐方式
• 何时阅读： 突出显示数值区域或添加描述性元素时

外观与自定义

📄 阅读： references/appearance-customization.md

• 添加标题
• 设置仪表尺寸（宽度、高度、边距）
• 自定义背景和边框
• 应用主题和配色方案
• 响应式设计模式
• 自定义 CSS 类
• RTL 语言支持
• 何时阅读： 设置仪表样式和自定义仪表外观时

高级功能

📄 阅读： references/advanced-features.md

• 动画效果和时序
• 事件处理（valueChange、print、export）
• 工具提示和悬停效果
• 打印并导出为 PDF/PNG/SVG
• 实时数据绑定和更新
• 组合使用多项功能
• 性能提示和优化
• 何时阅读： 添加交互、动画或导出功能时

快速入门示例

以下是一个可供入门的最小可运行示例：

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective, RangesDirective, RangeDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <div style={{ height: '400px', width: '100%' }}>
      <LinearGaugeComponent 
        title="Temperature Monitor"
        orientation="Horizontal"
      >
        <AxesDirective>
          <AxisDirective 
            minimum={0}
            maximum={100}
            labelStyle={{ format: '{value}°C' }}
          >
            <RangesDirective>
              <RangeDirective start={0} end={30} color='#1E90FF' />
              <RangeDirective start={30} end={70} color='#FFA500' />
              <RangeDirective start={70} end={100} color='#FF4500' />
            </RangesDirective>
            
            <PointersDirective>
              <PointerDirective value={55} />
            </PointersDirective>
          </AxisDirective>
        </AxesDirective>
      </LinearGaugeComponent>
    </div>
  );
}

请先安装软件包：

npm install @syncfusion/ej2-react-lineargauge --save

---

常见模式

模式 1：简单温度计

<LinearGaugeComponent title="Temperature">
  <AxesDirective>
    <AxisDirective minimum={-40} maximum={50} labelStyle={{ format: '{value}°C' }}>
      <RangesDirective>
        <RangeDirective start={-40} end={0} color='#4CAF50' />
        <RangeDirective start={0} end={25} color='#8BC34A' />
        <RangeDirective start={25} end={50} color='#FF5722' />
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={20} />
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</LinearGaugeComponent>

模式 2：进度/百分比指示器

<PointersDirective>
  <PointerDirective 
    value={75} 
    type='Marker'
    markerType='Rectangle'
    width={20}
    color='#007AFF'
  />
</PointersDirective>

模式 3：实时更新

const [value, setValue] = useState(50);

useEffect(() => {
  const timer = setInterval(() => {
    setValue(prev => (prev + (Math.random() - 0.5) * 10) % 100);
  }, 1000);
  return () => clearInterval(timer);
}, []);

<PointerDirective value={value} />

---

LinearGaugeComponent API 参考

已验证的属性（基于 Syncfusion 官方文档）

属性	类型	用途	示例
title	string	仪表标题文本	title="Temperature"
orientation	"Horizontal" | "Vertical"	布局方向（默认：Vertical）	orientation="Horizontal"
width	string	仪表宽度	width="100%" 或 width="400px"
height	string	仪表高度	height="300px"

---

AxisDirective API 参考

AxisDirective 的已验证属性

属性	类型	用途	示例
minimum	number	轴范围的起始值	minimum={0}
maximum	number	轴范围的结束值	maximum={200}
labelStyle	object	标签自定义（使用 format 属性）	labelStyle={{ format: '{value}°C' }}

labelStyle 格式选项

• { format: '{value}' } - 按原样显示值
• { format: '{value}°C' } - 添加 °C 后缀
• { format: '${value}K' } - 添加 $ 前缀和 K 后缀
• { format: '{value}%' } - 添加 % 后缀

⚠️ 不支持：

• ❌ majorTicksInterval - 不是有效属性
• ❌ minorTicksInterval - 不是有效属性
• ❌ axisLineStyle - 不是有效属性（请改用轴级样式设置）

---

PointerDirective API 参考

PointerDirective 的已验证属性

属性	类型	用途	示例
value	number	要显示的值	value={140}
color	string	指针颜色（十六进制或命名颜色）	color='green' 或 color='#1976D2'
type	"Bar" | "Marker"	指针形状类型（默认：Bar）	type="Marker"
markerType	"Circle" | "Rectangle" | "Triangle" | "Diamond" | "Image" | "Text"	标记指针的形状	markerType="Rectangle"
width	number	指针宽度（像素）	width={8}

指针类型示例

条形指针（默认）

<PointerDirective value={140} color='blue' width={8} />

标记指针

<PointerDirective 
  value={75} 
  type='Marker'
  markerType='Rectangle'
  width={15}
  color='#1976D2'
/>

---

RangeDirective API 参考

RangeDirective 的已验证属性

属性	类型	用途	示例
start	number	范围的起始值	start={0}
end	number	范围的结束值	end={80}
color	string	范围背景色	color='#4CAF50'
startWidth	number	起始边缘的宽度	startWidth={15}
endWidth	number	结束边缘的宽度	endWidth={15}

宽度示例

<RangeDirective start={0} end={80} color='#4CAF50' startWidth={15} endWidth={15} />

---

可运行代码示例

示例 1：温度计（已验证）

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective, RangesDirective, RangeDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={200} labelStyle={{ format: '{value}°C' }}>
          <PointersDirective>
            <PointerDirective value={140} color='green'></PointerDirective>
          </PointersDirective>
          <RangesDirective>
            <RangeDirective start={0} end={80} startWidth={15} endWidth={15}></RangeDirective>
            <RangeDirective start={80} end={120} startWidth={15} endWidth={15}></RangeDirective>
            <RangeDirective start={120} end={140} startWidth={15} endWidth={15}></RangeDirective>
            <RangeDirective start={140} end={200} startWidth={15} endWidth={15}></RangeDirective>
          </RangesDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

示例 2：进度指示器（已验证）

<LinearGaugeComponent title="Project Status">
  <AxesDirective>
    <AxisDirective minimum={0} maximum={100} labelStyle={{ format: '{value}%' }}>
      <RangesDirective>
        <RangeDirective start={0} end={30} color='#EF5350' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={30} end={70} color='#FFCA28' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={70} end={100} color='#66BB6A' startWidth={15} endWidth={15}></RangeDirective>
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={75} color='#1976D2' width={8}></PointerDirective>
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</LinearGaugeComponent>

示例 3：多指针仪表（已验证）

<LinearGaugeComponent>
  <AxesDirective>
    <AxisDirective minimum={0} maximum={1000} labelStyle={{ format: '${value}K' }}>
      <RangesDirective>
        <RangeDirective start={0} end={400} color='#E53935' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={400} end={700} color='#FB8C00' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={700} end={1000} color='#43A047' startWidth={15} endWidth={15}></RangeDirective>
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={650} color='#1976D2' width={6}></PointerDirective>
        <PointerDirective value={850} type='Marker' markerType='Circle' width={10} color='#FF6F00'></PointerDirective>
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</LinearGaugeComponent>

---

LinearGaugeComponent 方法和事件

需要动画生命周期、工具提示、拖动、导出和打印等交互功能时，请使用以下方法和事件：

方法

• destroy()
• export(type, fileName, orientation?, allowDownload?)
• print(id?)
• setAnnotationValue(annotationIndex, content, axisValue?)
• setPointerValue(axisIndex, pointerIndex, value)

事件

• load、loaded、resized
• valueChange（指针值变化）
• dragStart、dragMove、dragEnd
• beforePrint
• tooltipRender
• animationComplete
• annotationRender、axisLabelRender
• gaugeMouseDown、gaugeMouseMove、gaugeMouseUp、gaugeMouseLeave

---

常见用例

1. 温度监控 - 实时显示温度和冷热指示器
2. 传感器数据可视化 - 显示传感器读数（压力、湿度等）
3. 性能指标 - 显示系统性能、CPU 使用率和内存使用情况
4. 进度指示器 - 可视化任务完成情况或下载进度
5. 燃油/电池电量 - 监控资源消耗
6. 速度/RPM 仪表 - 显示转速或速度
7. 网络流量 - 实时显示带宽使用情况
8. 质量/评分指示器 - 显示评级或质量指标

---

后续步骤

1. 从入门指南开始，安装并设置你的第一个仪表
2. 使用轴、刻度和标签参考来构建结构
3. 使用指针类型和配置参考来添加指针
4. 使用范围和注释参考来突出显示区域
5. 使用视觉外观参考来自定义外观
6. 使用高级功能参考来添加交互
7. 使用无障碍功能参考来测试无障碍访问

如需更多详情或高级场景，请参阅上文链接的相应参考文件。