syncfusion-react-linear-gauge（syncfusion React Linear gauge 前端）

Implementing 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.

Component Overview

Syncfusion React Linear Gauge (@syncfusion/ej2-react-lineargauge) is a data visualization component that displays values on a linear scale. It consists of:

• 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

Documentation and Navigation Guide

Choose the reference based on what you need to implement:

Getting Started & Setup

📄 Read: references/getting-started.md

• Install @syncfusion/ej2-react-lineargauge package
• 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

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

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

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

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

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

Quick Start Example

Here's a minimal working example to get started:

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:

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

Common Patterns

Pattern 1: Simple Temperature Gauge

<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

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

Pattern 3: Real-Time Updates

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

Verified Props (Based on Official Syncfusion Documentation)

AxisDirective API Reference

Verified Props for AxisDirective

labelStyle Format Options

• {format: '{value}'} - Shows value as-is
• {format: '{value}°C'} - Adds °C suffix
• {format: '${value}K'} - Adds $ prefix and K suffix
• {format: '{value}%'} - Adds % suffix

⚠️ NOT SUPPORTED:

• ❌ majorTicksInterval - Not a valid property
• ❌ minorTicksInterval - Not a valid property
• ❌ axisLineStyle - Not a valid property (use axis-level styling instead)

PointerDirective API Reference

Verified Props for PointerDirective

Pointer Type Examples

Bar Pointer (Default)

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

Marker Pointer

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

RangeDirective API Reference

Verified Props for RangeDirective

Example with Width

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

Working Code Examples

Example 1: Temperature Gauge (Verified)

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)

<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)

<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

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, loaded, resized
• valueChange (pointer value changes)
• dragStart, dragMove, dragEnd
• beforePrint
• tooltipRender
• animationComplete
• annotationRender, axisLabelRender
• gaugeMouseDown, gaugeMouseMove, gaugeMouseUp, gaugeMouseLeave

Common Use Cases

1. Temperature Monitoring - Real-time temperature with hot/cold indicators
2. Sensor Data Visualization - Display sensor readings (pressure, humidity, etc.)
3. Performance Metrics - Show system performance, CPU usage, memory
4. Progress Indicators - Visualize task completion or download progress
5. Fuel/Battery Level - Monitor resource consumption
6. Speed/RPM Gauges - Display rotation speeds or velocities
7. Network Traffic - Show bandwidth usage in real-time
8. Quality/Score Indicators - Display ratings or quality metrics

Next Steps

1. Start with Getting Started to install and setup your first gauge
2. Build structure using Axes, Ticks & Labels reference
3. Add pointers using Pointer Types & Configuration reference
4. Highlight zones with Ranges & Annotations reference
5. Customize appearance with Visual Appearance reference
6. Add interactions with Advanced Features reference
7. Test accessibility using Accessibility reference

For more details or advanced scenarios, consult the specific reference files linked above.