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 コンポーネントを作成または実装する。
• 円形の目盛りで数値を表示する。
• ゲージの軸、ポインター、範囲を設定する。
• コンポーネントのプロパティを使ってゲージの外観をカスタマイズする。
• ツールチップ、ポインターのドラッグアンドドロップ、イベントハンドラーなどのインタラクティブ機能を追加する。
• エクスポートおよび印刷モジュールが必要な場合に、ゲージのコンテンツをエクスポートまたは印刷する。
• 国際ロケールと右から左への描画をサポートする。
• アクセシブルなゲージの視覚化を実装する。
• 1 つ以上の 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 からのゲージ値の受け渡し。

ゲージ軸の設定

ゲージの目盛りを設定する必要がある場合は、このトピックをお読みください。

対象となる項目：

• 軸の最小値と最大値。
• 開始角度と終了角度。
• パーセント値またはピクセル値による軸の半径。
• 軸の方向。
• 主目盛りと副目盛り。
• ラベルの位置と書式設定。
• 1 つの Circular Gauge に複数の軸を配置する方法。

ポインターの操作

ゲージに値を表示する必要がある場合は、このトピックをお読みください。

対象となる項目：

• 針ポインターの設定。
• マーカーポインターの設定。
• レンジバーポインターの設定。
• 同じ軸上に複数のポインターを配置する方法。
• ポインターの半径と幅。
• ポインターのアニメーション。
• ポインターのドラッグ動作。

範囲の追加とカスタマイズ

ゲージを意味のある領域に視覚的に分割する必要がある場合は、このトピックをお読みください。

対象となる項目：

• 1 つ以上の範囲の作成。
• 範囲の開始値と終了値の設定。
• 範囲の色のカスタマイズ。
• 範囲の半径の設定。
• 範囲の開始幅と終了幅の設定。
• 警告、危険、成功の領域の作成。
• 必要に応じて、範囲のインタラクティブなドラッグをサポートする方法。

注釈とカスタムコンテンツ

ゲージの内側または周囲に追加コンテンツを配置する必要がある場合は、このトピックをお読みください。

対象となる項目：

• テキスト注釈の追加。
• 角度と半径を使用した注釈の配置。
• ゲージ中央への動的な値の表示。
• カスタム HTML コンテンツの配置。
• ダッシュボードのラベルと値インジケーターの作成。

ゲージの外観とスタイル設定

Circular Gauge のプロパティを使用して外観を変更する必要がある場合は、このトピックをお読みください。

対象となる項目：

• ゲージのタイトル。
• タイトルのスタイル。
• ゲージの背景。
• 境界線の設定。
• centerX と centerY を使用した中央位置。
• 幅と高さ。
• 余白の設定。
• 半円形および四分円形のゲージレイアウト。

ユーザー操作

ゲージをインタラクティブにする必要がある場合は、このトピックをお読みください。

対象となる項目：

• ツールチップの有効化。
• ツールチップの内容のカスタマイズ。
• ポインターのドラッグの有効化。
• ドラッグ開始、ドラッグ中、ドラッグ終了イベントの処理。
• インタラクティブな値の更新。
• マウスイベントの処理。

国際化とローカライズ

カルチャ固有のゲージコンテンツを表示する必要がある場合は、このトピックをお読みください。

対象となる項目：

• ロケールに基づく数値の書式設定。
• 桁区切り記号。
• ラベルの書式設定による通貨またはパーセントの書式設定。
• 右から左への描画。
• ロケール固有のダッシュボードラベル。

エクスポートと印刷機能

Circular Gauge をエクスポートまたは印刷する必要がある場合は、このトピックをお読みください。

対象となる項目：

• 印刷サポートの有効化。
• 画像エクスポートの有効化。
• PDF エクスポートの有効化。
• ゲージのコンテンツを画像形式でエクスポートする方法。
• ゲージのコンテンツを PDF でエクスポートする方法。
• ブラウザーからゲージを印刷する方法。

アクセシビリティと WCAG 準拠

支援技術で Circular Gauge を使いやすくする必要がある場合は、このトピックをお読みください。

対象となる項目：

• 支援技術向けの説明テキスト。
• キーボードフォーカスの動作。
• タブインデックスの設定。
• 色のコントラストに関する考慮事項。
• 意味のあるタイトルとラベル。
• 重要な値を色だけで伝えることの回避。

サイズと寸法

ゲージの描画サイズを制御する必要がある場合は、このトピックをお読みください。

対象となる項目：

• ピクセル単位での幅の設定。
• パーセント単位での幅の設定。
• ピクセル単位での高さの設定。
• レスポンシブなコンテナーの動作。
• ゲージ領域を基準とした軸の半径。
• 小さいコンテナーでのクリッピングの防止。

クイックスタートの例

次のクイックスタートでは、完全な 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	読み上げ支援用の説明テキストを指定します。	"Speed gauge showing current speed"

一般的なユースケース

1. KPI やビジネス指標を表示するパフォーマンスダッシュボード。
2. 温度、圧力、速度、負荷の値をリアルタイムで監視する画面。
3. 完了率や目標達成状況を追跡する進捗インジケーター。
4. CPU、メモリ、ディスク、ネットワークの使用状況を表示するリソース使用率ビュー。
5. 速度、RPM、スループットを表示するスピードメーター形式の表示。
6. 評価、コンプライアンスレベル、満足度スコアを表示する品質スコアダッシュボード。
7. 色分けされた範囲で安全、警告、危険の各ゾーンを示すアラートベースの監視。
8. ユーザーがポインターをドラッグして数値を選択するインタラクティブな入力シナリオ。

次のステップ

• 新しい Circular Gauge ページを作成するときは、クイックスタートの例を使用します。
• スケールの動作を設定するときは、軸のトピックを使用します。
• 値の表示方法を制御するときは、ポインターのトピックを使用します。
• 安全、警告、危険のゾーンを表示するときは、範囲のトピックを使用します。
• ポインターのドラッグやツールチップの動作を有効にするときは、インタラクションのトピックを使用します。
• 複数のカルチャや右から左への表示に対応するときは、ローカライズのトピックを使用します。
• エクスポートと印刷のトピックは、それらの機能が必要な場合にのみ使用します。
• 値とページデータは Index.cshtml.cs で管理します。
• Circular Gauge のマークアップは Index.cshtml で管理します。
• Syncfusion のスクリプト参照と <ejs-scripts> の登録は _Layout.cshtml で管理します。