syncfusion-angular-circular-gauge

实现 Syncfusion Angular Circular Gauge

目录

• 何时使用此技能
• 组件概述
• 文档与导航指南
• 快速入门示例
• 常见模式
• 关键概念

何时使用此技能

在以下情况下，请使用 Circular Gauge 技能：

• 显示径向指标： 温度、RPM、速度、压力或性能指标
• 构建仪表板： KPI 仪表板、监控系统、实时数据可视化
• 创建速度计： 在一定范围内直观表示连续值
• 显示进度或状态： 多步骤流程、完成百分比、状态指标
• 实现交互式仪表： 可拖动指针、范围指示器、用户控制的值
• 自定义仪表外观： 多种样式、主题、动画和布局选项

组件概述

Syncfusion 的 Circular Gauge 组件是一种灵活且功能丰富的控件，用于显示径向数据可视化。主要功能包括：

功能	描述
坐标轴	可自定义的圆形坐标轴，可配置起始/结束角度、标签、刻度和范围
指针	三种指针类型：指针（带帽和尾部）、范围条（基于填充）、标记（形状或图像）
范围	用于突出显示数值区间的彩色区域，支持渐变
注释	在仪表的特定位置放置文本、形状或图像
动画	仪表元素在加载和值变化时播放平滑动画
用户交互	可拖动指针、工具提示、单击事件和动态值更新
响应式设计	可根据容器大小调整，并提供灵活的尺寸选项
多个坐标轴	支持同时使用多个坐标轴，每个坐标轴具有独立的范围和指针

文档与导航指南

选择符合当前需求的参考文档：

-### API 参考 📄 阅读： references/api-reference.md

入门指南

📄 阅读： references/getting-started.md

• 安装和包设置（Ivy 和 ngcc 版本）
• 模块注册和服务提供程序
• 基本仪表实现
• 设置指针值
• 快速集成示例

何时阅读： 首次设置、安装问题、基本仪表渲染

坐标轴配置

📄 阅读： references/axes-configuration.md

• 坐标轴自定义（线条样式、背景、颜色）
• 角度和方向（顺时针/逆时针、起始/结束角度）
• 坐标轴半径（基于像素和百分比的尺寸设置）
• 刻度配置（主/次刻度、位置、偏移、样式）
• 标签（字体、位置、格式、角度旋转、智能标签处理）
• 最小值/最大值范围
• 单个仪表上的多个坐标轴

何时阅读： 配置仪表布局、调整刻度/标签外观、定位元素

指针与类型

📄 阅读： references/pointers-and-types.md

• 指针类型概述（指针、范围条、标记）
• 指针（半径、帽的自定义、尾部长度、宽度变化）
• 范围条指针（条形指示器、圆角）
• 标记指针（形状：圆形、矩形、三角形、菱形；自定义图像）
• 指针拖动（全局启用/禁用、单个指针配置）
• 单个坐标轴上的多个指针
• 指针动画（启用、时长、计时）
• 渐变颜色（线性和径向渐变）

何时阅读： 选择指针类型、自定义指针外观、添加用户交互

范围和样式

📄 阅读： references/ranges-and-styling.md

• 范围基础（起始/结束值、着色区域）
• 范围自定义（颜色、厚度、半径）
• 在单个坐标轴上设置多个范围
• 使用圆角半径提升视觉效果
• 范围定位（坐标轴内侧/外侧）
• 范围拖动功能
• 渐变支持（线性和径向）
• 将范围颜色应用于刻度和标签

适合阅读的场景： 添加着色区域、创建分层可视化、设置区域样式

外观和动画

📄 阅读： references/appearance-and-animation.md

• 仪表标题（文本、字体样式、位置）
• 仪表定位（以像素或百分比表示的 centerX、centerY）
• 背景和边框自定义
• 边距和间距配置
• 仪表尺寸（响应式尺寸、固定尺寸）
• 动画（适用于所有元素的全局 animationDuration、指针专属动画）
• 半圆形/四分之一圆形仪表的半径计算
• 创建非圆形仪表布局

适合阅读的场景： 设置仪表容器样式、启用动画、创建主题化显示

注释和交互

📄 阅读： references/annotations-and-interaction.md

• 注释（自定义 HTML/元素，通过半径和角度定位）
• 子仪表（嵌套在注释中的仪表）
• 工具提示（悬停信息、自定义工具提示内容）
• 用户交互事件（指针拖动、值更改、仪表交互）
• 打印和导出功能
• 国际化和本地化
• 无障碍功能（符合 WCAG、键盘导航）

适合阅读的场景： 添加自定义内容、处理用户交互、实现无障碍仪表

快速入门示例

带单个指针的基本圆形仪表：

import { CircularGaugeModule } from '@syncfusion/ej2-angular-circulargauge';
import { GaugeTooltipService } from '@syncfusion/ej2-angular-circulargauge';
import { Component, ViewEncapsulation } from '@angular/core';

@Component({
  imports: [CircularGaugeModule],
  providers: [GaugeTooltipService],
  standalone: true,
  selector: 'app-gauge',
  template: `
    <ejs-circulargauge id='gauge-container' [title]='title'>
      <e-axes>
        <e-axis [startAngle]='200' [endAngle]='160' [minimum]='0' [maximum]='100'>
          <e-pointers>
            <e-pointer [value]='75' type='Needle'></e-pointer>
          </e-pointers>
        </e-axis>
      </e-axes>
    </ejs-circulargauge>
  `,
  encapsulation: ViewEncapsulation.None
})
export class AppComponent {
  title = 'Speed Gauge';
}

步骤：

1. 安装包：npm install @syncfusion/ej2-angular-circulargauge
2. 在组件中导入 CircularGaugeModule
3. 按需添加服务（GaugeTooltipService 等）
4. 使用坐标轴和指针配置 ejs-circulargauge
5. 设置指针的 value 和 type

常见模式

模式 1：速度计显示

创建一个速度计仪表，并通过范围标示速度区域（安全、警告、危险）：

// Basic structure:
<ejs-circulargauge>
  <e-axes>
    <e-axis [minimum]='0' [maximum]='200'>
      
      
      
      <e-ranges>
        <e-range [start]='0' [end]='80' color='green'></e-range>
        <e-range [start]='80' [end]='150' color='orange'></e-range>
        <e-range [start]='150' [end]='200' color='red'></e-range>
      </e-ranges>
      <e-pointers>
        <e-pointer [value]='speedValue' type='Needle'></e-pointer>
      </e-pointers>
    </e-axis>
  </e-axes>
</ejs-cirulargauge>

参考： ranges-and-styling.md（多个范围）、pointers-and-types.md（指针）

模式 2：使用多个坐标轴显示多个指标

同时显示多个相关指标（内侧和外侧坐标轴）：

// Configure multiple axes:
<e-axes>
  <e-axis [radius]='60%'></e-axis>
  <e-axis [radius]='40%'></e-axis>
</e-axes>

参考： axes-configuration.md（多个坐标轴部分）

模式 3：带可拖动指针的交互式仪表

允许用户通过拖动指针调整值：

// Enable dragging globally or per-pointer:
<ejs-circulargauge [enablePointerDrag]='true'>
  
  <e-pointer [enableDrag]='true'></e-pointer>
</ejs-circulargauge>

参考： pointers-and-types.md（拖动指针部分）

模式 4：仪表加载动画

在仪表加载时添加平滑的入场动画：

// Enable animation for all elements:
<ejs-circulargauge [animationDuration]='2000'>
  
</ejs-circulargauge>

参考： appearance-and-animation.md（动画部分）

核心概念

角度和方向

圆形仪表沿圆形平面旋转。可以通过以下属性控制可见弧线：

• startAngle： 弧线起始角度（默认值：200°）
• endAngle： 弧线结束角度（默认值：160°）
• direction： ClockWise 或 AntiClockWise

这样可以创建完整圆形（0-360°）或部分仪表（半圆、四分之一圆）。

半径和尺寸

仪表支持灵活的尺寸设置：

• 基于像素： 固定尺寸（例如，500px）
• 基于百分比： 相对于容器的尺寸（例如，80%）

可以分别为坐标轴、范围、指针和注释设置半径。

指针与范围

• 指针： 显示特定值（如速度计指针）
• 范围： 显示区域或区间（如用颜色编码的区域）

可结合使用以创建丰富的可视化效果（例如，指针显示当前速度，范围显示安全/警告区域）。

动画

动画会影响：

1. 坐标轴线条渲染（沿指定方向）
2. 刻度和标签
3. 范围
4. 指针（可单独控制）
5. 注释

将 animationDuration 设置为毫秒数（0 = 禁用）。

多个指针和轴

支持 n+ 个指针和轴：

• 多个指针： 显示不同指标（湿度 + 温度）
• 多个轴： 信息层（内环 / 外环）

每个轴都有独立的范围、指针和样式。

---

准备好开始实现了吗？ 请先阅读 getting-started.md 了解安装方法，然后根据需要查看特定功能的参考文档。