syncfusion-react-linear-gauge
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion React Linear Gauge
实现Syncfusion React Linear Gauge
When to Use This Skill
何时使用此技能
Use the Linear Gauge component when you need to:
- Display measurements on a linear/horizontal scale (temperature gauges, thermometers, fuel indicators)
- Monitor real-time data with animated pointer updates (sensor readings, system metrics)
- Show progress or percentages in a linear format
- Create dashboards with multiple gauges displaying KPIs
- Visualize ranges with different colors (e.g., safe, warning, critical zones)
- Build responsive data visualizations with customizable appearance and interactivity
- Print or export gauge visualizations for reports and documentation
The Linear Gauge is ideal for applications requiring visual representation of values on a horizontal/linear scale with customizable axes, pointers, ranges, and interactive features.
当你需要以下功能时,使用Linear Gauge组件:
- 显示测量值:在线性/水平刻度上展示(温度仪表、温度计、燃油指示器)
- 监控实时数据:通过指针动画更新展示(传感器读数、系统指标)
- 展示进度或百分比:以线性格式呈现
- 创建仪表盘:使用多个仪表展示KPI
- 可视化范围:用不同颜色区分(如安全区、警告区、危险区)
- 构建响应式数据可视化:支持自定义外观和交互性
- 打印或导出仪表可视化结果:用于报告和文档
Linear Gauge非常适合需要在线性/水平刻度上可视化数值,且支持自定义轴、指针、范围及交互功能的应用场景。
Component Overview
组件概述
Syncfusion React Linear Gauge () is a data visualization component that displays values on a linear scale. It consists of:
@syncfusion/ej2-react-lineargauge- Axes - The linear scale with customizable range, ticks, labels, and styling
- Pointers - Value indicators in two types: Bar (default) or Marker (shapes)
- Ranges - Colored segments representing value ranges (e.g., cold, warm, hot)
- Annotations - Text or image overlays for labels and callouts
- Ticks & Labels - Scale markers with customizable formatting
- Export - Print, PDF, PNG, or SVG export capabilities
Syncfusion React Linear Gauge()是一款数据可视化组件,用于在线性刻度上显示数值。它包含以下部分:
@syncfusion/ej2-react-lineargauge- Axes(轴):线性刻度,支持自定义范围、刻度线、标签和样式
- Pointers(指针):数值指示器,有两种类型:Bar(默认)或Marker(形状类)
- Ranges(范围):彩色分段,代表不同数值范围(如低温、中温、高温)
- Annotations(注释):文本或图片覆盖层,用于标签和标注
- Ticks & Labels(刻度线与标签):刻度标记,支持自定义格式化
- Export(导出):支持打印、导出为PDF、PNG或SVG格式
Documentation and Navigation Guide
文档与导航指南
Choose the reference based on what you need to implement:
根据你要实现的功能选择对应的参考文档:
Getting Started & Setup
快速入门与设置
📄 Read: references/getting-started.md
- Install package
@syncfusion/ej2-react-lineargauge - Setup in Vite or Create React App
- Basic component initialization
- Minimal working example
- CSS imports and themes
- When to read: First time setup or new project integration
📄 阅读: references/getting-started.md
- 安装包
@syncfusion/ej2-react-lineargauge - 在Vite或Create React App中配置
- 基础组件初始化
- 最简运行示例
- CSS导入与主题设置
- 阅读时机: 首次搭建或集成到新项目时
Gauge Structure: Axes, Ticks & Labels
仪表结构:轴、刻度线与标签
📄 Read: references/axis-ticks-labels.md
- Configure axes (minimum, maximum range)
- Customize axis line (height, width, color)
- Configure major and minor ticks
- Format and customize labels
- Set label units and formatting
- Multiple axes configuration
- When to read: Building the core gauge structure and scale
📄 阅读: references/axis-ticks-labels.md
- 配置轴(最小值、最大值范围)
- 自定义轴线(高度、宽度、颜色)
- 配置主刻度线和次刻度线
- 格式化和自定义标签
- 设置标签单位与格式
- 多轴配置
- 阅读时机: 构建仪表核心结构和刻度时
Pointer Types & Configuration
指针类型与配置
📄 Read: references/pointers.md
- Bar pointer type (default, fill styles)
- Marker pointer types (Circle, Rectangle, Triangle, Diamond, Image, Text)
- Setting and updating pointer values
- Customize pointer appearance (width, color, radius)
- Multiple pointers on same axis
- Drag-drop interactions
- Performance optimization
- When to read: Adding value indicators and interactive features
📄 阅读: references/pointers.md
- Bar指针类型(默认,填充样式)
- Marker指针类型(圆形、矩形、三角形、菱形、图片、文本)
- 设置与更新指针数值
- 自定义指针外观(宽度、颜色、半径)
- 单轴多指针配置
- 拖拽交互
- 性能优化
- 阅读时机: 添加数值指示器和交互功能时
Ranges & Annotations
范围与注释
📄 Read: references/ranges-annotations.md
- Creating ranges with start/end values
- Range styling (colors, gradient effects)
- Range labels and positions
- Text annotations for callouts and labels
- Image annotations
- Positioning and alignment
- When to read: Highlighting value zones or adding descriptive elements
📄 阅读: references/ranges-annotations.md
- 创建带起始/结束值的范围
- 范围样式(颜色、渐变效果)
- 范围标签与位置
- 用于标注和标签的文本注释
- 图片注释
- 定位与对齐
- 阅读时机: 高亮数值区间或添加描述元素时
Visual Appearance & Customization
视觉外观与自定义
📄 Read: references/appearance-customization.md
- Add titles
- Set gauge dimensions (width, height, margin)
- Customize background and borders
- Apply themes and color schemes
- Responsive design patterns
- CSS class customization
- RTL language support
- When to read: Styling and customizing gauge appearance
📄 阅读: references/appearance-customization.md
- 添加标题
- 设置仪表尺寸(宽度、高度、边距)
- 自定义背景与边框
- 应用主题与配色方案
- 响应式设计模式
- CSS类自定义
- RTL语言支持
- 阅读时机: 样式调整与仪表外观自定义时
Advanced Features
高级功能
📄 Read: references/advanced-features.md
- Animation effects and timing
- Event handling (valueChange, print, export)
- Tooltips and hover effects
- Print and export to PDF/PNG/SVG
- Real-time data binding and updates
- Combining multiple features
- Performance tips and optimization
- When to read: Adding interactions, animations, or export functionality
📄 阅读: references/advanced-features.md
- 动画效果与时长设置
- 事件处理(valueChange、print、export)
- 提示框与悬停效果
- 打印与导出为PDF/PNG/SVG
- 实时数据绑定与更新
- 多功能组合使用
- 性能技巧与优化
- 阅读时机: 添加交互、动画或导出功能时
Quick Start Example
快速入门示例
Here's a minimal working example to get started:
tsx
import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective,
PointersDirective, PointerDirective, RangesDirective, RangeDirective }
from '@syncfusion/ej2-react-lineargauge';
import '@syncfusion/ej2-lineargauge/styles/material.css';
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>
);
}Install the package first:
bash
npm install @syncfusion/ej2-react-lineargauge --save以下是一个最简运行示例:
tsx
import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective,
PointersDirective, PointerDirective, RangesDirective, RangeDirective }
from '@syncfusion/ej2-react-lineargauge';
import '@syncfusion/ej2-lineargauge/styles/material.css';
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>
);
}先安装依赖包:
bash
npm install @syncfusion/ej2-react-lineargauge --saveCommon Patterns
常见模式
Pattern 1: Simple Temperature Gauge
模式1:简易温度仪表
tsx
<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>tsx
<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>Pattern 2: Progress/Percentage Indicator
模式2:进度/百分比指示器
tsx
<PointersDirective>
<PointerDirective
value={75}
type='Marker'
markerType='Rectangle'
width={20}
color='#007AFF'
/>
</PointersDirective>tsx
<PointersDirective>
<PointerDirective
value={75}
type='Marker'
markerType='Rectangle'
width={20}
color='#007AFF'
/>
</PointersDirective>Pattern 3: Real-Time Updates
模式3:实时更新
tsx
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} />tsx
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 Reference
LinearGaugeComponent API参考
Verified Props (Based on Official Syncfusion Documentation)
已验证属性(基于Syncfusion官方文档)
| Prop | Type | Purpose | Example |
|---|---|---|---|
| string | Gauge title text | |
| "Horizontal" | "Vertical" | Layout orientation (default: Vertical) | |
| string | Gauge width | |
| string | Gauge height | |
| Prop | Type | 用途 | 示例 |
|---|---|---|---|
| string | 仪表标题文本 | |
| "Horizontal" | "Vertical" | 布局方向(默认:Vertical) | |
| string | 仪表宽度 | |
| string | 仪表高度 | |
AxisDirective API Reference
AxisDirective API参考
Verified Props for AxisDirective
AxisDirective已验证属性
| Prop | Type | Purpose | Example |
|---|---|---|---|
| number | Start value of the axis range | |
| number | End value of the axis range | |
| object | Label customization (use | |
| Prop | Type | 用途 | 示例 |
|---|---|---|---|
| number | 轴范围起始值 | |
| number | 轴范围结束值 | |
| object | 标签自定义(使用 | |
labelStyle Format Options
labelStyle格式选项
- - Shows value as-is
{ format: '{value}' } - - Adds °C suffix
{ format: '{value}°C' } - - Adds $ prefix and K suffix
{ format: '${value}K' } - - Adds % suffix
{ format: '{value}%' }
⚠️ NOT SUPPORTED:
- ❌ - Not a valid property
majorTicksInterval - ❌ - Not a valid property
minorTicksInterval - ❌ - Not a valid property (use axis-level styling instead)
axisLineStyle
- - 按原始值显示
{ format: '{value}' } - - 添加°C后缀
{ format: '{value}°C' } - - 添加$前缀和K后缀
{ format: '${value}K' } - - 添加%后缀
{ format: '{value}%' }
⚠️ 不支持:
- ❌ - 无效属性
majorTicksInterval - ❌ - 无效属性
minorTicksInterval - ❌ - 无效属性(改用轴级样式设置)
axisLineStyle
PointerDirective API Reference
PointerDirective API参考
Verified Props for PointerDirective
PointerDirective已验证属性
| Prop | Type | Purpose | Example |
|---|---|---|---|
| number | The value to display | |
| string | Pointer color (hex or named) | |
| "Bar" | "Marker" | Pointer shape type (default: Bar) | |
| "Circle" | "Rectangle" | "Triangle" | "Diamond" | "Image" | "Text" | Shape for marker pointers | |
| number | Pointer width in pixels | |
| Prop | Type | 用途 | 示例 |
|---|---|---|---|
| number | 要显示的数值 | |
| string | 指针颜色(十六进制或命名色) | |
| "Bar" | "Marker" | 指针形状类型(默认:Bar) | |
| "Circle" | "Rectangle" | "Triangle" | "Diamond" | "Image" | "Text" | Marker指针的形状 | |
| number | 指针宽度(像素) | |
Pointer Type Examples
指针类型示例
Bar Pointer (Default)
tsx
<PointerDirective value={140} color='blue' width={8} />Marker Pointer
tsx
<PointerDirective
value={75}
type='Marker'
markerType='Rectangle'
width={15}
color='#1976D2'
/>Bar指针(默认)
tsx
<PointerDirective value={140} color='blue' width={8} />Marker指针
tsx
<PointerDirective
value={75}
type='Marker'
markerType='Rectangle'
width={15}
color='#1976D2'
/>RangeDirective API Reference
RangeDirective API参考
Verified Props for RangeDirective
RangeDirective已验证属性
| Prop | Type | Purpose | Example |
|---|---|---|---|
| number | Start value of the range | |
| number | End value of the range | |
| string | Range background color | |
| number | Width of start edge | |
| number | Width of end edge | |
| Prop | Type | 用途 | 示例 |
|---|---|---|---|
| number | 范围起始值 | |
| number | 范围结束值 | |
| string | 范围背景色 | |
| number | 范围起始端宽度 | |
| number | 范围结束端宽度 | |
Example with Width
带宽度设置的示例
tsx
<RangeDirective start={0} end={80} color='#4CAF50' startWidth={15} endWidth={15} />tsx
<RangeDirective start={0} end={80} color='#4CAF50' startWidth={15} endWidth={15} />Working Code Examples
可运行代码示例
Example 1: Temperature Gauge (Verified)
示例1:温度仪表(已验证)
tsx
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>
);
}tsx
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>
);
}Example 2: Progress Indicator (Verified)
示例2:进度指示器(已验证)
tsx
<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>tsx
<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>Example 3: Multi-Pointer Gauge (Verified)
示例3:多指针仪表(已验证)
tsx
<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>tsx
<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 Methods & Events
LinearGaugeComponent方法与事件
Use the following methods/events when you need interactivity like animation lifecycle, tooltips, drag, export, and print:
Methods
destroy()export(type, fileName, orientation?, allowDownload?)print(id?)setAnnotationValue(annotationIndex, content, axisValue?)setPointerValue(axisIndex, pointerIndex, value)
Events
- ,
load,loadedresized - (pointer value changes)
valueChange - ,
dragStart,dragMovedragEnd beforePrinttooltipRenderanimationComplete- ,
annotationRenderaxisLabelRender - ,
gaugeMouseDown,gaugeMouseMove,gaugeMouseUpgaugeMouseLeave
当需要动画生命周期、提示框、拖拽、导出、打印等交互功能时,使用以下方法和事件:
方法
destroy()export(type, fileName, orientation?, allowDownload?)print(id?)setAnnotationValue(annotationIndex, content, axisValue?)setPointerValue(axisIndex, pointerIndex, value)
事件
- ,
load,loadedresized - (指针数值变化时)
valueChange - ,
dragStart,dragMovedragEnd beforePrinttooltipRenderanimationComplete- ,
annotationRenderaxisLabelRender - ,
gaugeMouseDown,gaugeMouseMove,gaugeMouseUpgaugeMouseLeave
Common Use Cases
常见使用场景
- Temperature Monitoring - Real-time temperature with hot/cold indicators
- Sensor Data Visualization - Display sensor readings (pressure, humidity, etc.)
- Performance Metrics - Show system performance, CPU usage, memory
- Progress Indicators - Visualize task completion or download progress
- Fuel/Battery Level - Monitor resource consumption
- Speed/RPM Gauges - Display rotation speeds or velocities
- Network Traffic - Show bandwidth usage in real-time
- Quality/Score Indicators - Display ratings or quality metrics
- 温度监控:实时显示温度,区分冷热区间
- 传感器数据可视化:展示传感器读数(压力、湿度等)
- 性能指标:展示系统性能、CPU使用率、内存情况
- 进度指示器:可视化任务完成度或下载进度
- 燃油/电量显示:监控资源消耗
- 速度/RPM仪表:展示转速或速度
- 网络流量:实时显示带宽使用情况
- 质量/评分指示器:展示评级或质量指标
Next Steps
下一步
- Start with Getting Started to install and setup your first gauge
- Build structure using Axes, Ticks & Labels reference
- Add pointers using Pointer Types & Configuration reference
- Highlight zones with Ranges & Annotations reference
- Customize appearance with Visual Appearance reference
- Add interactions with Advanced Features reference
- Test accessibility using Accessibility reference
For more details or advanced scenarios, consult the specific reference files linked above.
- 从快速入门开始:安装并搭建你的第一个仪表
- 构建结构:参考Axes、Ticks & Labels文档
- 添加指针:参考Pointer Types & Configuration文档
- 高亮区间:参考Ranges & Annotations文档
- 自定义外观:参考Visual Appearance文档
- 添加交互:参考Advanced Features文档
- 测试可访问性:参考Accessibility文档
如需更多细节或高级场景,请查阅上述链接的具体参考文件。