syncfusion-react-circular-gauge

Syncfusion React Circular Gauge の実装

このスキルを使用するタイミング

次のような場合は、Circular Gauge コンポーネントを使用してください。

• 円形の目盛りで測定値を表示する（速度計、温度計、燃料計など）
• ダッシュボードで KPI や指標を監視する（ビジネス指標、センサーの読み取り値など）
• 進捗状況や割合を円形で可視化する
• ポインターをアニメーションで更新し、リアルタイムデータを表示する
• 複数のポインターや範囲を使って、レスポンシブなデータ可視化を作成する
• レポート用にゲージの可視化を印刷またはエクスポートする

Circular Gauge は、カスタマイズ可能な外観、アニメーション、インタラクティブ機能を備えた円形の目盛りで値を視覚的に表現する必要があるアプリケーションに最適です。

---

コンポーネントの概要

Syncfusion React Circular Gauge（@syncfusion/ej2-react-circulargauge）は、円形の目盛りで値を表示するデータ可視化コンポーネントです。次の要素で構成されます。

• 軸 - カスタマイズ可能な角度、方向、スタイルを備えた円形の目盛り
• ポインター - 針（デフォルト）、RangeBar、マーカーの 3 種類の値インジケーター
• 範囲 - 値の範囲を表す色付きのセグメント（例：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

• 軸を設定する（角度、方向、スタイル）
• ポインターを追加してカスタマイズする（針、RangeBar、マーカーの各タイプ）
• 色やラベルを指定して範囲を定義する
• 複数の軸とポインターを設定する
• 参照するタイミング： ゲージの基本構造とデータ可視化を構築するとき

外観と寸法

📄 参照先： 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

• コンポーネントの props、イベント、メソッド、子ディレクティブのリファレンス
• よく使う props、メソッド、イベント引数をすばやく確認
• 参照するタイミング： 正確な 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} />

---

主な設定プロパティ

Prop	Type	Purpose
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. Getting Started から始めて、最初のゲージを設定します
2. Axes、Pointers & Ranges のリファレンスを使って構造を構築します
3. スタイリングのリファレンスを使って外観をカスタマイズします
4. Advanced Features のリファレンスを使ってインタラクションを追加します
5. Accessibility のリファレンスを使ってアクセシビリティをテストします
6. 実装のアイデアを得るために共通パターンを参照します

詳細や高度なシナリオについては、上記にリンクされている各リファレンスファイルを参照してください。