syncfusion-aspnetcore-circulargauge

实现 Syncfusion Circular Gauge

• 何时使用此技能
• 组件概览
• 文档与导航指南
  • Circular Gauge 入门
  • 配置仪表轴
  • 使用指针
  • 添加和自定义范围
  • 注释和自定义内容
  • 仪表外观与样式
  • 用户交互
  • 国际化与本地化
  • 导出和打印功能
  • 无障碍功能与 WCAG 合规性
  • 大小与尺寸
• 快速入门示例
  • Pages/_ViewImports.cshtml
  • Pages/Shared/_Layout.cshtml
  • Pages/Index.cshtml.cs
  • Pages/Index.cshtml
• 常见模式
  • 模式 1：包含多个仪表的仪表板
  • 模式 2：支持拖动的交互式仪表
  • 模式 3：包含范围和警报的仪表
  • 模式 4：本地化仪表
• 关键属性和配置
• 常见用例
• 后续步骤
• 综合错误与后续参考

何时使用此技能

在用户需要以下功能时使用此技能：

• 在 ASP.NET Core Razor Pages 应用程序中创建或实现 Syncfusion Circular Gauge 组件。
• 在圆形刻度上显示数值。
• 配置仪表轴、指针和范围。
• 使用组件属性自定义仪表外观。
• 添加工具提示、指针拖放和事件处理程序等交互功能。
• 在需要导出和打印模块时导出或打印仪表内容。
• 支持国际化区域设置和从右向左渲染。
• 实现无障碍仪表可视化。
• 使用一个或多个 Circular Gauge 组件构建仪表板式数据可视化。

组件概览

Circular Gauge 是一种数据可视化组件，用于在圆形刻度上显示数值。它适用于仪表板、状态指示器、监控屏幕和 KPI 可视化。

所有仪表元素均使用 SVG 渲染，因此该组件可缩放，并适用于响应式布局。

主要功能包括：

• 多种指针，例如指针、标记和范围条指针。
• 多个轴，每个轴都可独立设置最小值、最大值、半径、刻度、标签、范围和指针。
• 可自定义范围，用于对数值区间进行分类。
• 注释，用于在仪表内部放置自定义文本或可视内容。
• 工具提示显示和指针拖动等用户交互。
• 启用所需的导出或打印设置后，支持导出和打印。
• 支持国际化的本地化数字显示。
• 支持从右向左渲染。
• 通过正确的组件渲染和辅助描述提供无障碍功能支持。

文档与导航指南

Circular Gauge 入门

当你需要在 ASP.NET Core Razor Pages 应用程序中首次设置 Circular Gauge 时，请阅读本主题。

涵盖内容：

• 安装最新的 Syncfusion.EJ2.AspNet.Core NuGet 包。
• 配置 _ViewImports.cshtml。
• 在 _Layout.cshtml 中添加 Syncfusion 脚本引用。
• 注册 Syncfusion 脚本管理器。
• 在 Index.cshtml 中创建第一个 Circular Gauge。
• 从 Index.cshtml.cs 传递仪表值。

配置仪表轴

需要配置仪表刻度时，请阅读本主题。

涵盖内容：

• 轴的最小值和最大值。
• 起始角度和结束角度。
• 以百分比或像素值设置轴半径。
• 轴方向。
• 主刻度和次刻度。
• 标签的位置和格式。
• 在单个 Circular Gauge 中配置多个轴。

使用指针

需要在仪表上显示数值时，请阅读本主题。

涵盖内容：

• 配置指针。
• 配置标记指针。
• 配置范围条指针。
• 在同一轴上配置多个指针。
• 指针半径和指针宽度。
• 指针动画。
• 指针拖动行为。

添加和自定义范围

需要将仪表直观地划分为有意义的区域时，请阅读本主题。

涵盖内容：

• 创建一个或多个范围。
• 设置范围的起始值和结束值。
• 自定义范围颜色。
• 设置范围半径。
• 设置范围的起始宽度和结束宽度。
• 创建警告、危险和成功区域。
• 根据需要支持交互式拖动范围。

注释和自定义内容

需要在仪表内部或周围放置其他内容时，请阅读本主题。

涵盖内容：

• 添加文本注释。
• 使用角度和半径定位注释。
• 在仪表中心显示动态数值。
• 放置自定义 HTML 内容。
• 创建仪表板标签和数值指示器。

仪表外观和样式

需要使用 Circular Gauge 属性修改视觉外观时，请阅读本主题。

涵盖内容：

• 仪表标题。
• 标题样式。
• 仪表背景。
• 边框设置。
• 使用 centerX 和 centerY 设置中心位置。
• 宽度和高度。
• 边距配置。
• 半圆形和四分之一圆形仪表布局。

用户交互

需要使仪表具有交互性时，请阅读本主题。

涵盖内容：

• 启用工具提示。
• 自定义工具提示内容。
• 启用指针拖动。
• 处理拖动开始、拖动移动和拖动结束事件。
• 通过交互更新数值。
• 处理鼠标事件。

国际化和本地化

需要显示特定区域文化的仪表内容时，请阅读本主题。

涵盖内容：

• 基于区域设置的数字格式。
• 分组分隔符。
• 通过标签格式设置货币或百分比格式。
• 从右到左渲染。
• 特定区域设置的仪表板标签。

导出和打印功能

需要导出或打印 Circular Gauge 时，请阅读本主题。

涵盖内容：

• 启用打印支持。
• 启用图像导出。
• 启用 PDF 导出。
• 将仪表内容导出为图像格式。
• 将仪表内容导出为 PDF。
• 在浏览器中打印仪表。

无障碍功能和 WCAG 合规性

需要让辅助技术更易于使用 Circular Gauge 时，请阅读本主题。

涵盖内容：

• 为辅助技术提供描述文本。
• 键盘焦点行为。
• Tab 索引配置。
• 颜色对比度注意事项。
• 有意义的标题和标签。
• 避免仅通过颜色传达关键数值。

尺寸和维度

需要控制仪表的渲染尺寸时，请阅读本主题。

涵盖内容：

• 以像素设置宽度。
• 以百分比设置宽度。
• 以像素设置高度。
• 响应式容器行为。
• 相对于仪表区域设置轴半径。
• 防止在较小容器中发生裁剪。

快速入门示例

以下快速入门示例采用完整的 ASP.NET Core Razor Pages 结构。

本示例特意不包含：

• Syncfusion 样式表链接。
• 自定义样式块。
• Syncfusion 许可证注册内容。
• _ViewImports.cshtml 中的 @namespace 指令。
• Index.cshtml 中完全限定的模型声明。

在 NuGet 包和 CDN 脚本引用中始终使用相同的最新软件包版本。

安装 NuGet 包：

Install-Package Syncfusion.EJ2.AspNet.Core -Version 33.2.7

或者使用 .NET CLI 安装：

dotnet add package Syncfusion.EJ2.AspNet.Core --version 33.2.7

Pages/_ViewImports.cshtml

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, Syncfusion.EJ2

Pages/Shared/_Layout.cshtml

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <title>@ViewData["Title"] - Circular Gauge Demo</title>

    
    <script src="https://cdn.syncfusion.com/ej2/33.2.7/dist/ej2.min.js"></script>
</head>
<body>
    <header>
        <nav>
            <a asp-area="" asp-page="/Index">Circular Gauge Demo</a>
        </nav>
    </header>

    <main role="main">
        @RenderBody()
    </main>

    
    <ejs-scripts></ejs-scripts>

    @await RenderSectionAsync("Scripts", required: false)
</body>
</html>

Pages/Index.cshtml.cs

using Microsoft.AspNetCore.Mvc.RazorPages;

namespace CircularGaugeGettingStarted.Pages
{
    public class IndexModel : PageModel
    {
        public string GaugeTitle { get; set; } = "Speed";

        public double MinimumValue { get; set; } = 0;

        public double MaximumValue { get; set; } = 120;

        public double PointerValue { get; set; } = 70;

        public double SafeRangeStart { get; set; } = 0;

        public double SafeRangeEnd { get; set; } = 50;

        public double WarningRangeStart { get; set; } = 50;

        public double WarningRangeEnd { get; set; } = 80;

        public double DangerRangeStart { get; set; } = 80;

        public double DangerRangeEnd { get; set; } = 120;

        public void OnGet()
        {
        }
    }
}

Pages/Index.cshtml

@page
@model CircularGaugeGettingStarted.Pages.IndexModel

@{
    ViewData["Title"] = "Circular Gauge";
}

<h1>ASP.NET Core Circular Gauge</h1>
<p>Basic Circular Gauge with axis, pointer, and ranges.</p>

<ejs-circulargauge id="speedGauge"
                    title="@Model.GaugeTitle"
                    width="100%"
                    height="450px">
    <e-circulargauge-axes>
        <e-circulargauge-axis startAngle="240"
                              endAngle="120"
                              minimum="@Model.MinimumValue"
                              maximum="@Model.MaximumValue"
                              radius="90%">
            <e-circulargauge-ranges>
                <e-circulargauge-range start="@Model.SafeRangeStart"
                                       end="@Model.SafeRangeEnd"
                                       color="#30B32D"
                                       radius="80%">
                </e-circulargauge-range>
                <e-circulargauge-range start="@Model.WarningRangeStart"
                                       end="@Model.WarningRangeEnd"
                                       color="#FFDD00"
                                       radius="80%">
                </e-circulargauge-range>
                <e-circulargauge-range start="@Model.DangerRangeStart"
                                       end="@Model.DangerRangeEnd"
                                       color="#F03E3E"
                                       radius="80%">
                </e-circulargauge-range>
            </e-circulargauge-ranges>
            <e-circulargauge-pointers>
                <e-circulargauge-pointer value="@Model.PointerValue">
                </e-circulargauge-pointer>
            </e-circulargauge-pointers>
        </e-circulargauge-axis>
    </e-circulargauge-axes>
</ejs-circulargauge>

常见模式

模式 1：包含多个仪表的仪表板

当仪表板需要显示速度、温度、压力、评分或利用率等多个指标时，请使用此模式。

实现方法：

• 为每个指标创建单独的 <ejs-circulargauge> 实例。
• 为每个仪表使用唯一的 id 值。
• 在 Index.cshtml.cs 中存储数值。
• 从页面模型绑定每个仪表的标题和指针值。
• 保持仪表尺寸一致，以便仪表板布局整洁。

示例模型值：

using Microsoft.AspNetCore.Mvc.RazorPages;

namespace CircularGaugeGettingStarted.Pages
{
    public class IndexModel : PageModel
    {
        public double SpeedValue { get; set; } = 70;

        public double TemperatureValue { get; set; } = 45;

        public double PressureValue { get; set; } = 90;

        public void OnGet()
        {
        }
    }
}

示例 Index.cshtml 结构：

@page
@model CircularGaugeGettingStarted.Pages.IndexModel

@{
    ViewData["Title"] = "Gauge Dashboard";
}

<h1>Gauge Dashboard</h1>

<ejs-circulargauge id="speedGauge" title="Speed" width="100%" height="300px">
    <e-circulargauge-axes>
        <e-circulargauge-axis minimum="0" maximum="120">
            <e-circulargauge-pointers>
                <e-circulargauge-pointer value="@Model.SpeedValue">
                </e-circulargauge-pointer>
            </e-circulargauge-pointers>
        </e-circulargauge-axis>
    </e-circulargauge-axes>
</ejs-circulargauge>

<ejs-circulargauge id="temperatureGauge" title="Temperature" width="100%" height="300px">
    <e-circulargauge-axes>
        <e-circulargauge-axis minimum="0" maximum="100">
            <e-circulargauge-pointers>
                <e-circulargauge-pointer value="@Model.TemperatureValue">
                </e-circulargauge-pointer>
            </e-circulargauge-pointers>
        </e-circulargauge-axis>
    </e-circulargauge-axes>
</ejs-circulargauge>

<ejs-circulargauge id="pressureGauge" title="Pressure" width="100%" height="300px">
    <e-circulargauge-axes>
        <e-circulargauge-axis minimum="0" maximum="150">
            <e-circulargauge-pointers>
                <e-circulargauge-pointer value="@Model.PressureValue">
                </e-circulargauge-pointer>
            </e-circulargauge-pointers>
        </e-circulargauge-axis>
    </e-circulargauge-axes>
</ejs-circulargauge>

模式 2：支持拖动的交互式仪表

当用户需要通过拖动指针直接更改仪表值时，请使用此模式。

实现方法：

• 在 Circular Gauge 上设置 enablePointerDrag="true"。
• 需要跟踪值变化时，使用指针拖动事件。
• 如果需要持久化存储，只在拖动完成后更新服务器。
• 除非需要实时更新，否则避免在拖动过程中持续保存数值。

示例：

@page
@model CircularGaugeGettingStarted.Pages.IndexModel

@{
    ViewData["Title"] = "Interactive Gauge";
}

<h1>Interactive Circular Gauge</h1>
<p>Drag the pointer to change the value.</p>


<ejs-circulargauge id="interactiveGauge"
                    title="Interactive Speed"
                    width="100%"
                    height="450px"
                    enablePointerDrag="true">
    <e-circulargauge-axes>
        <e-circulargauge-axis minimum="0"
                              maximum="120"
                              startAngle="240"
                              endAngle="120">
            <e-circulargauge-pointers>
                <e-circulargauge-pointer value="@Model.SpeedValue">
                </e-circulargauge-pointer>
            </e-circulargauge-pointers>
        </e-circulargauge-axis>
    </e-circulargauge-axes>
</ejs-circulargauge>

模式 3：包含范围和警报的仪表

当仪表需要显示安全、警告和危险区域时，请使用此模式。

建议的范围设计：

• 绿色范围表示正常值。
• 黄色范围表示警告值。
• 红色范围表示危险值。

示例：

@page
@model CircularGaugeGettingStarted.Pages.IndexModel

@{
    ViewData["Title"] = "Gauge with Ranges";
}

<h1>Gauge with Ranges</h1>

<ejs-circulargauge id="rangeGauge"
                    title="System Load"
                    width="100%"
                    height="450px">
    <e-circulargauge-axes>
        <e-circulargauge-axis minimum="0"
                              maximum="120"
                              startAngle="240"
                              endAngle="120">
            <e-circulargauge-ranges>
                <e-circulargauge-range start="0"
                                       end="50"
                                       color="#30B32D"
                                       radius="80%">
                </e-circulargauge-range>
                <e-circulargauge-range start="50"
                                       end="80"
                                       color="#FFDD00"
                                       radius="80%">
                </e-circulargauge-range>
                <e-circulargauge-range start="80"
                                       end="120"
                                       color="#F03E3E"
                                       radius="80%">
                </e-circulargauge-range>
            </e-circulargauge-ranges>
            <e-circulargauge-pointers>
                <e-circulargauge-pointer value="@Model.SpeedValue">
                </e-circulargauge-pointer>
            </e-circulargauge-pointers>
        </e-circulargauge-axis>
    </e-circulargauge-axes>
</ejs-circulargauge>

模式 4：本地化仪表

当仪表需要支持特定区域设置的文本方向或数字显示时，请使用此模式。

实现方法：

• 配置了本地化资源时，使用 locale 应用特定区域设置的格式。
• 使用 enableRtl="true" 启用从右到左的呈现。
• 使用服务器端模型中的描述性标题文本。
• 如果应用支持多种语言，避免将面向用户的标签硬编码。

示例：

@page
@model CircularGaugeGettingStarted.Pages.IndexModel

@{
    ViewData["Title"] = "Localized Gauge";
}

<h1>Localized Circular Gauge</h1>

<ejs-circulargauge id="localizedGauge"
                    title="@Model.GaugeTitle"
                    width="100%"
                    height="450px"
                    locale="en-US"
                    enableRtl="false"
                    useGroupingSeparator="true">
    <e-circulargauge-axes>
        <e-circulargauge-axis minimum="0"
                              maximum="100000"
                              startAngle="240"
                              endAngle="120">
            <e-circulargauge-pointers>
                <e-circulargauge-pointer value="65000">
                </e-circulargauge-pointer>
            </e-circulargauge-pointers>
        </e-circulargauge-axis>
    </e-circulargauge-axes>
</ejs-circulargauge>

关键属性和配置

属性	用途	常见值
title	设置仪表标题文本。	"Speed"、"Temperature"、"System Load"
centerX	设置仪表的水平中心位置。	"50%"、"100px"
centerY	设置仪表的垂直中心位置。	"50%"、"100px"
width	设置仪表宽度。	"400px"、"100%"
height	设置仪表高度。	"450px"、"100%"
background	设置仪表背景颜色。	"transparent"、"#f5f5f5"、"white"
enablePointerDrag	启用指针拖动。	true、false
enableRtl	启用从右到左的呈现。	true、false
useGroupingSeparator	为数字标签启用分组分隔符。	true、false
allowPrint	启用打印支持。	true、false
allowImageExport	启用图像导出支持。	true、false
allowPdfExport	启用 PDF 导出支持。	true、false
description	提供辅助说明文本。	"显示当前速度的速度仪表"

常见用例

1. 用于展示 KPI 和业务指标的性能仪表板。
2. 用于实时监控温度、压力、速度或负载值的界面。
3. 用于显示完成百分比或跟踪目标的进度指示器。
4. 用于查看 CPU、内存、磁盘或网络使用情况的资源利用率视图。
5. 用于显示速度、RPM 或吞吐量的速度计式界面。
6. 用于展示评级、合规水平或满意度评分的质量评分仪表板。
7. 使用彩色范围标示安全、警告和危险区域的警报监控。
8. 用户通过拖动指针选择数值的交互式输入场景。

后续步骤

• 创建新的圆形仪表盘页面时，使用 Quick Start 示例。
• 配置刻度行为时，使用轴主题。
• 控制数值的显示方式时，使用指针主题。
• 显示安全、警告和危险区域时，使用范围主题。
• 启用指针拖动或工具提示行为时，使用交互主题。
• 支持多种区域设置或从右向左显示时，使用本地化主题。
• 仅在需要这些功能时，使用导出和打印主题。
• 让 Index.cshtml.cs 负责数值和页面数据。
• 让 Index.cshtml 负责圆形仪表盘标记。
• 让 _Layout.cshtml 负责 Syncfusion 脚本引用和 <ejs-scripts> 注册。