syncfusion-react-circular-gauge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Circular Gauge

实现Syncfusion React Circular Gauge

When to Use This Skill

何时使用此技能

Use the Circular Gauge component when you need to:

Display measurements on a circular scale (speedometers, temperature gauges, fuel indicators)
Monitor KPIs and metrics in dashboards (business metrics, sensor readings)
Visualize progress or percentages in a circular format
Show real-time data with animated pointer updates
Create responsive data visualizations with multiple pointers and ranges
Print or export gauge visualizations for reports

The Circular Gauge is ideal for applications requiring visual representation of values on a circular scale with customizable appearance, animations, and interactivity.

当你需要以下场景时，使用Circular Gauge组件：

在圆形刻度上展示测量数据（速度表、温度表、燃油指示器）
在仪表盘中监控KPI和指标（业务指标、传感器读数）
以圆形格式可视化进度或百分比
通过动画指针更新展示实时数据
创建带有多指针和多范围的响应式数据可视化
打印或导出仪表盘可视化内容用于报告

Circular Gauge非常适合需要在圆形刻度上可视化数值，且具备可自定义外观、动画和交互性的应用场景。

Component Overview

组件概述

Syncfusion React Circular Gauge (

@syncfusion/ej2-react-circulargauge

) is a data visualization component that displays values on a circular scale. It consists of:

Axes - The circular scale tracks with customizable angles, direction, and styling
Pointers - Value indicators in three types: Needle (default), RangeBar, or Marker
Ranges - Colored segments representing value ranges (e.g., 0-25%, 25-50%)
Annotations - Text or image overlays for labels and callouts
Legend - Optional legend displaying range meanings
Export - Print, PDF, PNG, or SVG export capabilities

Syncfusion React Circular Gauge（

@syncfusion/ej2-react-circulargauge

）是一款数据可视化组件，用于在圆形刻度上展示数值。它包含以下部分：

轴 - 可自定义角度、方向和样式的圆形刻度轨道
指针 - 三种类型的数值指示器：指针（默认）、范围条或标记
范围 - 代表数值区间的彩色分段（例如0-25%、25-50%）
注释 - 用于标签和标注的文本或图像覆盖层
图例 - 可选的图例，展示各范围的含义
导出 - 支持打印以及导出为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
```
@syncfusion/ej2-react-circulargauge
```
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

📄 阅读： references/getting-started.md

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

Gauge Structure: Axes, Pointers & Ranges

仪表盘结构：轴、指针与范围

📄 Read: references/axes-pointers-ranges.md

Configure axes (angles, direction, styling)
Add and customize pointers (Needle, RangeBar, Marker types)
Define ranges with colors and labels
Multiple axes and pointers
When to read: Building the core gauge structure and data visualization

📄 阅读： references/axes-pointers-ranges.md

配置轴（角度、方向、样式）
添加并自定义指针（指针、范围条、标记类型）
定义带有颜色和标签的范围
多轴与多指针
阅读时机： 构建仪表盘核心结构和数据可视化时

Visual Appearance & Dimensions

视觉外观与尺寸

📄 Read: references/appearance-dimensions.md

Add titles and customize styling
Position gauge (centerX, centerY)
Set dimensions (width, height, margin)
Apply backgrounds, borders, color schemes
Responsive design
When to read: Customizing gauge look, sizing, and layout

📄 阅读： references/appearance-dimensions.md

添加标题并自定义样式
定位仪表盘（centerX、centerY）
设置尺寸（宽度、高度、边距）
应用背景、边框、配色方案
响应式设计
阅读时机： 自定义仪表盘外观、尺寸和布局时

Annotations & Legend

注释与图例

📄 Read: references/annotations-legend.md

Add text annotations
Add image annotations
Position annotations
Display and customize legend
Handle legend interactions
When to read: Adding labels, callouts, or explanatory elements

📄 阅读： references/annotations-legend.md

添加文本注释
添加图像注释
定位注释
显示并自定义图例
处理图例交互
阅读时机： 添加标签、标注或说明元素时

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Animation effects and timing
User interaction (events, tooltips)
Print and export to PDF/PNG/SVG
Real-time data binding
Multiple gauge instances
When to read: Adding interactions, animations, or export functionality

📄 阅读： references/advanced-features.md

动画效果与计时
用户交互（事件、工具提示）
打印与导出为PDF/PNG/SVG
实时数据绑定
多仪表盘实例
阅读时机： 添加交互、动画或导出功能时

API Reference

API参考

📄 Read: references/api-reference.md

Component props, events, methods, and child directive reference
Quick lookup for commonly used props, methods and event args
When to read: When you need exact API names, types or method signatures

📄 阅读： references/api-reference.md

组件属性、事件、方法和子指令参考
常用属性、方法和事件参数的快速查询
阅读时机： 需要准确的API名称、类型或方法签名时

Accessibility & Internationalization

无障碍访问与国际化

📄 Read: references/accessibility-i18n.md

WCAG 2.1 compliance and ARIA support
Screen reader compatibility
Keyboard navigation
RTL language support
Localization and culture settings
When to read: Making gauges accessible or supporting multiple languages

📄 阅读： references/accessibility-i18n.md

WCAG 2.1合规性与ARIA支持
屏幕阅读器兼容性
键盘导航
RTL语言支持
本地化与文化设置
阅读时机： 让仪表盘具备无障碍访问性或支持多语言时

Common Patterns & Use Cases

常见模式与用例

📄 Read: references/common-patterns.md

Speedometer pattern
Progress/percentage gauge pattern
Temperature/sensor monitoring
Multi-pointer dashboards
Real-time updates with animations
Performance tips and troubleshooting
When to read: Looking for common implementations or solving issues

📄 阅读： references/common-patterns.md

速度表模式
进度/百分比仪表盘模式
温度/传感器监控
多指针仪表盘
带动画的实时更新
性能提示与故障排除
阅读时机： 寻找常见实现方案或解决问题时

Quick Start Example

快速入门示例

Here's a minimal working example to get started:

tsx

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

export function App() {
  return (
    <div style={{ height: '500px' }}>
      <CircularGaugeComponent 
        title="Speedometer"
        centerX="50%"
        centerY="50%"
      >
        <AxesDirective>
          <AxisDirective 
            startAngle={270} 
            endAngle={90}
            minimum={0}
            maximum={100}
          >
            <RangesDirective>
              <RangeDirective start={0} end={30} color='#1E7145' />
              <RangeDirective start={30} end={60} color='#F7D900' />
              <RangeDirective start={60} end={100} color='#C1192B' />
            </RangesDirective>
            
            <PointersDirective>
              <PointerDirective 
                value={65} 
                type='Needle'
                radius='70%'
              />
            </PointersDirective>
          </AxisDirective>
        </AxesDirective>
      </CircularGaugeComponent>
    </div>
  );
}

Install the package first:

bash

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

以下是一个最简可用示例，帮助你快速上手：

tsx

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

export function App() {
  return (
    <div style={{ height: '500px' }}>
      <CircularGaugeComponent 
        title="Speedometer"
        centerX="50%"
        centerY="50%"
      >
        <AxesDirective>
          <AxisDirective 
            startAngle={270} 
            endAngle={90}
            minimum={0}
            maximum={100}
          >
            <RangesDirective>
              <RangeDirective start={0} end={30} color='#1E7145' />
              <RangeDirective start={30} end={60} color='#F7D900' />
              <RangeDirective start={60} end={100} color='#C1192B' />
            </RangesDirective>
            
            <PointersDirective>
              <PointerDirective 
                value={65} 
                type='Needle'
                radius='70%'
              />
            </PointersDirective>
          </AxisDirective>
        </AxesDirective>
      </CircularGaugeComponent>
    </div>
  );
}

先安装包：

bash

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

Common Patterns

常见模式

Pattern 1: Simple Progress Indicator

模式1：简单进度指示器

tsx

<CircularGaugeComponent>
  <AxesDirective>
    <AxisDirective minimum={0} maximum={100}>
      <RangesDirective>
        <RangeDirective start={0} end={50} color='#E8E8E8' />
        <RangeDirective start={50} end={100} color='#4CAF50' />
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={75} type='RangeBar' />
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</CircularGaugeComponent>

tsx

<CircularGaugeComponent>
  <AxesDirective>
    <AxisDirective minimum={0} maximum={100}>
      <RangesDirective>
        <RangeDirective start={0} end={50} color='#E8E8E8' />
        <RangeDirective start={50} end={100} color='#4CAF50' />
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={75} type='RangeBar' />
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</CircularGaugeComponent>

Pattern 2: Multi-Pointer Dashboard

模式2：多指针仪表盘

Use multiple pointers on the same axis to compare values:

tsx

<PointersDirective>
  <PointerDirective value={45} type='Needle' />
  <PointerDirective value={60} type='Marker' />
</PointersDirective>

在同一轴上使用多个指针来比较数值：

tsx

<PointersDirective>
  <PointerDirective value={45} type='Needle' />
  <PointerDirective value={60} type='Marker' />
</PointersDirective>

Pattern 3: Real-Time Updates

模式3：实时更新

tsx

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

// Update pointer value on interval
useEffect(() => {
  const timer = setInterval(() => {
    setValue(prev => (prev + Math.random() * 10) % 100);
  }, 1000);
  return () => clearInterval(timer);
}, []);

// Bind value to pointer
<PointerDirective value={value} />

tsx

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

// 定时更新指针数值
useEffect(() => {
  const timer = setInterval(() => {
    setValue(prev => (prev + Math.random() * 10) % 100);
  }, 1000);
  return () => clearInterval(timer);
}, []);

// 将数值绑定到指针
<PointerDirective value={value} />

Key Configuration Props

关键配置属性

Prop	Type	Purpose
`title`	string	Gauge title displayed at top
`centerX` / `centerY`	string	Position (% or px)
`startAngle` / `endAngle`	number	Axis sweep degrees (0-360)
`minimum` / `maximum`	number	Axis scale range
`value` (pointer)	number	Current pointer value
`type` (pointer)	'Needle' \| 'RangeBar' \| 'Marker'	Pointer visualization type
`radius` (pointer)	string	Pointer length (% or px)
`color`	string	Element color (hex, rgb, name)
`direction`	'ClockWise' \| 'AntiClockWise'	Axis direction
`animationDuration`	number	Animation time in milliseconds

For the complete API listing (all component props, events, methods and child directives) see: references/api-reference.md

属性	类型	用途
`title`	string	显示在顶部的仪表盘标题
`centerX` / `centerY`	string	位置（百分比或像素）
`startAngle` / `endAngle`	number	轴的扫过角度（0-360）
`minimum` / `maximum`	number	轴的刻度范围
`value` （指针）	number	当前指针数值
`type` （指针）	'Needle' \| 'RangeBar' \| 'Marker'	指针可视化类型
`radius` （指针）	string	指针长度（百分比或像素）
`color`	string	元素颜色（十六进制、RGB、颜色名称）
`direction`	'ClockWise' \| 'AntiClockWise'	轴的方向
`animationDuration`	number	动画时长（毫秒）

完整的API列表（所有组件属性、事件、方法和子指令）请查看：references/api-reference.md

Common Use Cases

常见用例

Speedometer/Speed Monitor - Display vehicle speed with colored ranges
Temperature Gauge - Monitor temperature with hot/cold indicators
Performance KPI - Show system metrics or business KPIs
Fuel/Battery Level - Visualize resource consumption
Network Traffic - Display bandwidth usage in real-time
Sports/Gaming Scores - Show player stats or game progress
Industrial Monitoring - Sensor data visualization
Percentage/Progress - Alternative circular progress visualization

速度表/速度监控 - 用彩色范围展示车辆速度
温度表 - 监控温度并显示冷热指示器
性能KPI - 展示系统指标或业务KPI
燃油/电池电量 - 可视化资源消耗情况
网络流量 - 实时展示带宽使用情况
体育/游戏得分 - 展示玩家统计数据或游戏进度
工业监控 - 传感器数据可视化
百分比/进度 - 圆形进度条的替代可视化方案

Next Steps

下一步

Start with Getting Started to set up your first gauge
Build structure using Axes, Pointers & Ranges reference
Customize appearance with styling reference
Add interactions with Advanced Features reference
Test accessibility using Accessibility reference
Reference common patterns for implementation ideas

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

从入门指南开始，搭建你的第一个仪表盘
使用轴、指针与范围参考文档构建结构
使用样式参考文档自定义外观
使用高级功能参考文档添加交互
使用无障碍访问参考文档测试无障碍性
参考常见模式获取实现思路

如需更多细节或高级场景，请查阅上面链接的具体参考文件。