syncfusion-react-circular-gauge

实现 Syncfusion React Circular Gauge

何时使用此技能

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

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

Circular Gauge 非常适合需要在圆形刻度上直观呈现数值，并支持自定义外观、动画和交互性的应用。

---

组件概览

Syncfusion React Circular Gauge（@syncfusion/ej2-react-circulargauge）是一款用于在圆形刻度上显示数值的数据可视化组件。它由以下部分组成：

• 坐标轴 - 带有可自定义角度、方向和样式的圆形刻度轨道
• 指针 - 三种类型的数值指示器：Needle（默认）、RangeBar 或 Marker
• 范围 - 表示数值区间的彩色片段（例如，0-25%、25-50%）
• 注释 - 用于标签和标注的文本或图像叠加层
• 图例 - 可选图例，用于显示范围含义
• 导出 - 支持打印，以及导出为 PDF、PNG 或 SVG

---

文档与导航指南

根据需要实现的功能选择参考文档：

开始使用与设置

📄 阅读： references/getting-started.md

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

仪表结构：坐标轴、指针和范围

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

• 配置坐标轴（角度、方向、样式）
• 添加和自定义指针（Needle、RangeBar、Marker 类型）
• 定义范围及其颜色和标签
• 多个坐标轴和指针
• 何时阅读： 构建仪表核心结构和数据可视化时

视觉外观与尺寸

📄 阅读： references/appearance-dimensions.md

• 添加标题并自定义样式
• 设置仪表位置（centerX、centerY）
• 设置尺寸（width、height、margin）
• 应用背景、边框和配色方案
• 响应式设计
• 何时阅读： 自定义仪表外观、大小和布局时

注释与图例

📄 阅读： references/annotations-legend.md

• 添加文本注释
• 添加图像注释
• 设置注释位置
• 显示和自定义图例
• 处理图例交互
• 何时阅读： 添加标签、标注或说明性元素时

高级功能

📄 阅读： references/advanced-features.md

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

API 参考

📄 阅读： references/api-reference.md

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

无障碍与国际化

📄 阅读： references/accessibility-i18n.md

• 符合 WCAG 2.1 标准并支持 ARIA
• 兼容屏幕阅读器
• 键盘导航
• RTL 语言支持
• 本地化和区域设置
• 何时阅读： 提升仪表的无障碍性或支持多种语言时

常见模式和用例

📄 阅读： references/common-patterns.md

• 速度计模式
• 进度／百分比仪表模式
• 温度／传感器监控
• 多指针仪表板
• 带动画的实时更新
• 性能提示和故障排查
• 何时阅读： 查找常见实现方式或解决问题时

---

快速入门示例

以下是一个最简可运行示例，帮助你快速开始：

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

请先安装软件包：

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

---

常见模式

模式 1：简单进度指示器

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

模式 2：多指针仪表板

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

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

模式 3：实时更新

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} />

---

关键配置属性

属性	类型	用途
title	string	显示在顶部的仪表标题
centerX / centerY	string	位置（% 或 px）
startAngle / endAngle	number	坐标轴扫过的角度（0-360）
minimum / maximum	number	坐标轴刻度范围
value (pointer)	number	当前指针数值
type (pointer)	'Needle' | 'RangeBar' | 'Marker'	指针可视化类型
radius (pointer)	string	指针长度（% 或 px）
color	string	元素颜色（hex、rgb、名称）
direction	'ClockWise' | 'AntiClockWise'	坐标轴方向
animationDuration	number	动画时长（毫秒）

---

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

常见用例

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

---

后续步骤

1. 从入门指南开始，设置你的第一个仪表
2. 使用坐标轴、指针和范围参考来构建结构
3. 参照样式指南自定义外观
4. 参照高级功能指南添加交互
5. 使用无障碍指南测试无障碍性
6. 参考常见模式，获取实现思路

如需更多详情或了解高级场景，请查阅上文链接的具体参考文件。