syncfusion-react-linear-gauge

Syncfusion React Linear Gauge の実装

このスキルを使用する場面

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

• 測定値を表示する：線形／水平スケール上に表示する場合（温度計、体温計、燃料計など）
• リアルタイムデータを監視する：ポインターをアニメーション付きで更新する場合（センサーの測定値、システムメトリクスなど）
• 進捗や割合を表示する：線形形式で表示する場合
• ダッシュボードを作成する：KPI を表示する複数のゲージを配置する場合
• 範囲を視覚化する：異なる色で範囲を表示する場合（例：安全、警告、危険の領域）
• レスポンシブなデータ可視化を構築する：外観とインタラクティブ機能をカスタマイズする場合
• ゲージの可視化を印刷またはエクスポートする：レポートやドキュメントに使用する場合

Linear Gauge は、軸、ポインター、範囲、インタラクティブ機能をカスタマイズしながら、水平／線形スケール上の値を視覚的に表現する必要があるアプリケーションに最適です。

---

コンポーネントの概要

Syncfusion React Linear Gauge（@syncfusion/ej2-react-lineargauge）は、線形スケール上に値を表示するデータ可視化コンポーネントです。次の要素で構成されています。

• 軸 - 範囲、目盛り、ラベル、スタイルをカスタマイズできる線形スケール
• ポインター - 値を示すインジケーター。棒（デフォルト）とマーカー（図形）の 2 種類があります
• 範囲 - 値の範囲を表す色付きの領域（例：低温、温暖、高温）
• 注釈 - ラベルや吹き出し用のテキストまたは画像のオーバーレイ
• 目盛りとラベル - 書式をカスタマイズできるスケールの目印
• エクスポート - 印刷、PDF、PNG、SVG へのエクスポート機能

---

ドキュメントとナビゲーションガイド

実装する内容に応じて、該当するリファレンスを選んでください。

はじめにとセットアップ

📄 参照: references/getting-started.md

• @syncfusion/ej2-react-lineargauge パッケージをインストールする
• Vite または Create React App でセットアップする
• 基本的なコンポーネントを初期化する
• 最小構成の動作例
• CSS のインポートとテーマ
• 参照する場面： 初回のセットアップ時、または新しいプロジェクトへの導入時

ゲージの構造：軸、目盛り、ラベル

📄 参照: references/axis-ticks-labels.md

• 軸を設定する（最小値、最大値の範囲）
• 軸線をカスタマイズする（高さ、幅、色）
• 主目盛りと補助目盛りを設定する
• ラベルの書式とカスタマイズ
• ラベルの単位と書式を設定する
• 複数の軸を設定する
• 参照する場面： ゲージの基本構造とスケールを構築するとき

ポインターの種類と設定

📄 参照: references/pointers.md

• 棒ポインターの種類（デフォルト、塗りつぶしスタイル）
• マーカーポインターの種類（Circle、Rectangle、Triangle、Diamond、Image、Text）
• ポインターの値を設定、更新する
• ポインターの外観をカスタマイズする（幅、色、半径）
• 同じ軸に複数のポインターを配置する
• ドラッグ＆ドロップ操作
• パフォーマンスを最適化する
• 参照する場面： 値を示すインジケーターやインタラクティブ機能を追加するとき

範囲と注釈

📄 参照: references/ranges-annotations.md

• 開始値と終了値を指定して範囲を作成する
• 範囲のスタイルを設定する（色、グラデーション効果）
• 範囲のラベルと位置
• 吹き出しやラベル用のテキスト注釈
• 画像注釈
• 位置と配置
• 参照する場面： 値の領域を強調したり、説明要素を追加したりするとき

外観とカスタマイズ

📄 参照: references/appearance-customization.md

• タイトルを追加する
• ゲージの寸法を設定する（幅、高さ、余白）
• 背景と境界線をカスタマイズする
• テーマと配色を適用する
• レスポンシブデザインのパターン
• CSS クラスをカスタマイズする
• RTL 言語のサポート
• 参照する場面： ゲージの外観をスタイリング、カスタマイズするとき

高度な機能

📄 参照： references/advanced-features.md

• アニメーション効果とタイミング
• イベント処理（valueChange、print、export）
• ツールチップとホバー効果
• PDF／PNG／SVG への印刷とエクスポート
• リアルタイムのデータバインディングと更新
• 複数の機能の組み合わせ
• パフォーマンスに関するヒントと最適化
• 参照するタイミング： インタラクション、アニメーション、またはエクスポート機能を追加するとき

クイックスタートの例

開始するための最小限の動作例を紹介します。

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective, RangesDirective, RangeDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <div style={{ height: '400px', width: '100%' }}>
      <LinearGaugeComponent 
        title="Temperature Monitor"
        orientation="Horizontal"
      >
        <AxesDirective>
          <AxisDirective 
            minimum={0}
            maximum={100}
            labelStyle={{ format: '{value}°C' }}
          >
            <RangesDirective>
              <RangeDirective start={0} end={30} color='#1E90FF' />
              <RangeDirective start={30} end={70} color='#FFA500' />
              <RangeDirective start={70} end={100} color='#FF4500' />
            </RangesDirective>
            
            <PointersDirective>
              <PointerDirective value={55} />
            </PointersDirective>
          </AxisDirective>
        </AxesDirective>
      </LinearGaugeComponent>
    </div>
  );
}

まずパッケージをインストールします。

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

---

よく使われるパターン

パターン 1：シンプルな温度ゲージ

<LinearGaugeComponent title="Temperature">
  <AxesDirective>
    <AxisDirective minimum={-40} maximum={50} labelStyle={{ format: '{value}°C' }}>
      <RangesDirective>
        <RangeDirective start={-40} end={0} color='#4CAF50' />
        <RangeDirective start={0} end={25} color='#8BC34A' />
        <RangeDirective start={25} end={50} color='#FF5722' />
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={20} />
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</LinearGaugeComponent>

パターン 2：進捗／パーセンテージ表示

<PointersDirective>
  <PointerDirective 
    value={75} 
    type='Marker'
    markerType='Rectangle'
    width={20}
    color='#007AFF'
  />
</PointersDirective>

パターン 3：リアルタイム更新

const [value, setValue] = useState(50);

useEffect(() => {
  const timer = setInterval(() => {
    setValue(prev => (prev + (Math.random() - 0.5) * 10) % 100);
  }, 1000);
  return () => clearInterval(timer);
}, []);

<PointerDirective value={value} />

---

LinearGaugeComponent API リファレンス

検証済みのプロパティ（Syncfusion の公式ドキュメントに基づく）

プロパティ	型	目的	例
title	string	ゲージのタイトルテキスト	title="Temperature"
orientation	"Horizontal" | "Vertical"	レイアウトの向き（デフォルト：Vertical）	orientation="Horizontal"
width	string	ゲージの幅	width="100%" または width="400px"
height	string	ゲージの高さ	height="300px"

---

AxisDirective API リファレンス

AxisDirective の検証済みプロパティ

プロパティ	型	目的	例
minimum	number	軸の範囲の開始値	minimum={0}
maximum	number	軸の範囲の終了値	maximum={200}
labelStyle	object	ラベルのカスタマイズ（format プロパティを使用）	labelStyle={{ format: '{value}°C' }}

labelStyle の書式設定オプション

• { format: '{value}' } - 値をそのまま表示します
• { format: '{value}°C' } - °C の接尾辞を追加します
• { format: '${value}K' } - $ の接頭辞と K の接尾辞を追加します
• { format: '{value}%' } - % の接尾辞を追加します

⚠️ サポートされていません：

• ❌ majorTicksInterval - 有効なプロパティではありません
• ❌ minorTicksInterval - 有効なプロパティではありません
• ❌ axisLineStyle - 有効なプロパティではありません（代わりに軸レベルのスタイル設定を使用してください）

---

PointerDirective API リファレンス

PointerDirective の検証済みプロパティ

プロパティ	型	目的	例
value	number	表示する値	value={140}
color	string	ポインターの色（16 進数または名前）	color='green' または color='#1976D2'
type	"Bar" | "Marker"	ポインターの形状タイプ（デフォルト：Bar）	type="Marker"
markerType	"Circle" | "Rectangle" | "Triangle" | "Diamond" | "Image" | "Text"	マーカーポインターの形状	markerType="Rectangle"
width	number	ポインターの幅（ピクセル単位）	width={8}

ポインタータイプの例

バー型ポインター（デフォルト）

<PointerDirective value={140} color='blue' width={8} />

マーカー型ポインター

<PointerDirective 
  value={75} 
  type='Marker'
  markerType='Rectangle'
  width={15}
  color='#1976D2'
/>

---

RangeDirective API リファレンス

RangeDirective の検証済みプロパティ

プロパティ	型	目的	例
start	number	範囲の開始値	start={0}
end	number	範囲の終了値	end={80}
color	string	範囲の背景色	color='#4CAF50'
startWidth	number	開始端の幅	startWidth={15}
endWidth	number	終了端の幅	endWidth={15}

幅を指定する例

<RangeDirective start={0} end={80} color='#4CAF50' startWidth={15} endWidth={15} />

---

動作するコード例

例 1：温度ゲージ（検証済み）

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective, RangesDirective, RangeDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={200} labelStyle={{ format: '{value}°C' }}>
          <PointersDirective>
            <PointerDirective value={140} color='green'></PointerDirective>
          </PointersDirective>
          <RangesDirective>
            <RangeDirective start={0} end={80} startWidth={15} endWidth={15}></RangeDirective>
            <RangeDirective start={80} end={120} startWidth={15} endWidth={15}></RangeDirective>
            <RangeDirective start={120} end={140} startWidth={15} endWidth={15}></RangeDirective>
            <RangeDirective start={140} end={200} startWidth={15} endWidth={15}></RangeDirective>
          </RangesDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

例 2：進捗インジケーター（検証済み）

<LinearGaugeComponent title="Project Status">
  <AxesDirective>
    <AxisDirective minimum={0} maximum={100} labelStyle={{ format: '{value}%' }}>
      <RangesDirective>
        <RangeDirective start={0} end={30} color='#EF5350' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={30} end={70} color='#FFCA28' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={70} end={100} color='#66BB6A' startWidth={15} endWidth={15}></RangeDirective>
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={75} color='#1976D2' width={8}></PointerDirective>
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</LinearGaugeComponent>

例 3：複数ポインターのゲージ（検証済み）

<LinearGaugeComponent>
  <AxesDirective>
    <AxisDirective minimum={0} maximum={1000} labelStyle={{ format: '${value}K' }}>
      <RangesDirective>
        <RangeDirective start={0} end={400} color='#E53935' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={400} end={700} color='#FB8C00' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={700} end={1000} color='#43A047' startWidth={15} endWidth={15}></RangeDirective>
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={650} color='#1976D2' width={6}></PointerDirective>
        <PointerDirective value={850} type='Marker' markerType='Circle' width={10} color='#FF6F00'></PointerDirective>
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</LinearGaugeComponent>

---

LinearGaugeComponent のメソッドとイベント

アニメーションのライフサイクル、ツールチップ、ドラッグ、エクスポート、印刷などのインタラクティブ機能が必要な場合は、次のメソッドとイベントを使用します。

メソッド

• destroy()
• export(type, fileName, orientation?, allowDownload?)
• print(id?)
• setAnnotationValue(annotationIndex, content, axisValue?)
• setPointerValue(axisIndex, pointerIndex, value)

イベント

• load、loaded、resized
• valueChange（ポインターの値が変更されたとき）
• dragStart、dragMove、dragEnd
• beforePrint
• tooltipRender
• animationComplete
• annotationRender、axisLabelRender
• gaugeMouseDown、gaugeMouseMove、gaugeMouseUp、gaugeMouseLeave

---

一般的なユースケース

1. 温度モニタリング - 高温・低温のインジケーターを使って温度をリアルタイムに表示
2. センサーデータの可視化 - センサーの測定値（圧力、湿度など）を表示
3. パフォーマンス指標 - システムのパフォーマンス、CPU 使用率、メモリ使用量を表示
4. 進捗インジケーター - タスクの完了状況やダウンロードの進捗状況を可視化
5. 燃料／バッテリー残量 - リソースの消費量をモニタリング
6. 速度／RPM ゲージ - 回転速度や速度を表示
7. ネットワークトラフィック - 帯域幅の使用量をリアルタイムに表示
8. 品質／スコアインジケーター - 評価や品質指標を表示

---

次のステップ

1. 「Getting Started」から始める：最初のゲージをインストールしてセットアップします
2. 構造を構築する：「Axes, Ticks & Labels」リファレンスを使用します
3. ポインターを追加する：「Pointer Types & Configuration」リファレンスを使用します
4. ゾーンを強調表示する：「Ranges & Annotations」リファレンスを使用します
5. 外観をカスタマイズする：「Visual Appearance」リファレンスを使用します
6. インタラクションを追加する：「Advanced Features」リファレンスを使用します
7. アクセシビリティをテストする：「Accessibility」リファレンスを使用します

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