syncfusion-flutter-gauges

Syncfusion Flutter ゲージ

このスキルでは、データの可視化や測定値の表示に使用する、関連性の高い 2 つの Syncfusion Flutter コンポーネント、SfLinearGauge（線形ゲージ）と SfRadialGauge（放射状ゲージ）を扱います。多くの表示機能や設定機能を共有していますが、それぞれ用途が異なり、視覚的な表現方法も異なります。

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

次のような場合に、このスキルを使用してください。

• 線形または放射状のスケールでデータを表示し、測定値を視覚的に表現する
• カスタムスタイルやアニメーションを適用した進捗インジケーターを作成する
• KPI、メトリクス、パフォーマンス指標を使ったダッシュボードの可視化を構築する
• 測定値表示を実装する（速度計、温度計、圧力計など）
• ドラッグ可能なポインターや値の変更に対応するインタラクティブなゲージを追加する
• 線形または円形のスケールに範囲やしきい値を可視化する
• 音量、明るさ、評価の入力に使うカスタムゲージコントロールを作成する
• 最新の Flutter アプリケーションにアナログ形式のインジケーターを表示する
• ゲージ表示を使ってバッテリー、信号、ステータスのインジケーターを構築する
• 色、グラデーション、アニメーション、スタイルを使ってゲージの外観をカスタマイズする

適切なコンポーネントの選択

SfLinearGauge（線形ゲージ）を使用する場合：

• 水平方向または垂直方向の測定値表示が必要な場合
• データを線形スケール（バー形式）で表すのが最適な場合
• 進捗やレベルのインジケーターにバー ポインターを使用したい場合
• 向きの柔軟な変更（簡単に 90° 回転できること）が重要な場合
• 対称的な表示にミラー効果が必要な場合
• 次のようなものを構築する場合：進捗バー、スライダー、バッテリーインジケーター、音量コントロール、水平ダッシュボード

SfRadialGauge（放射状ゲージ）を使用する場合：

• 円形または弧形の表示が必要な場合
• 可視化に針ポインター（従来型のゲージスタイル）が必要な場合
• 360 度または半円の表示を行いたい場合
• ウィジェットを使った注釈をゲージ上に配置する必要がある場合
• ゲージ上部にタイトルの表示が必要な場合
• 画像へのエクスポート機能が必要な場合
• 次のようなものを構築する場合：速度計、RPM メーター、温度ゲージ、コンパス表示、時計盤、円形の進捗表示

主な違いのまとめ：

機能	SfLinearGauge	SfRadialGauge
主な形状	線形（水平方向／垂直方向）	円形／弧形
向き	水平、垂直	円形（360°）
バー ポインター	✅ はい	❌ いいえ
針ポインター	❌ いいえ	✅ はい
範囲ポインター	❌ いいえ	✅ はい
マーカー ポインター	✅ 形状とウィジェット	✅ 形状とウィジェット
ミラー効果	✅ はい	❌ いいえ
注釈	❌ いいえ	✅ はい
タイトルのサポート	❌ いいえ	✅ はい
画像へのエクスポート	❌ いいえ	✅ はい
複数の軸	❌ 制限あり	✅ はい
軸の角度	該当なし	✅ 設定可能

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

はじめに

📄 参照先： references/getting-started.md

• 両コンポーネントのインストールとパッケージのセットアップ
• SfLinearGauge の基本的な実装
• SfRadialGauge の基本的な実装
• パッケージの依存関係とインポート
• 簡単な比較と最初の例

コンポーネントの概要

📄 線形ゲージ： references/linear-gauge-overview.md

• SfLinearGauge ウィジェットの概要と機能
• 線形ゲージと放射状ゲージの使い分け
• 向きのオプション（水平方向／垂直方向）
• 線形ゲージ固有の機能
• 線形ゲージの基本的な設定

📄 放射状ゲージ： references/radial-gauge-overview.md

• SfRadialGauge ウィジェットの概要と機能
• 放射状ゲージと線形ゲージの使い分け
• 円形および弧形の設定
• 放射状ゲージ固有の機能
• タイトルと複数軸のサポート
• 放射状ゲージの基本的な設定

軸とスケール

📄 参照： references/axes.md

• 両方のゲージの軸をカスタマイズする
• リニア軸（トラック、太さ、色）
• ラジアル軸（円弧、角度、半径）
• 最小値と最大値
• 軸の間隔とスケール
• 軸線のスタイルとグラデーション
• ラベルと目盛りの位置
• 軸の方向を反転する
• カスタムスケールとレンダラー
• 複数の軸（ラジアル）

ポインター

📄 参照： references/pointers.md

• ポインターの種類の概要
• 形状／マーカーポインター（両方のゲージ）
• ウィジェットポインター（両方のゲージ）
• バーポインター（リニアゲージのみ）
• 針ポインター（ラジアルゲージのみ）
• 範囲ポインター（ラジアルゲージのみ）
• 複数のポインターの設定
• ポインターの位置とスタイル
• ポインターの比較と選択ガイド

範囲

📄 参照： references/ranges.md

• 範囲の可視化の概念
• リニアゲージへの範囲の追加
• ラジアルゲージへの範囲の追加
• 範囲の色とグラデーション
• 範囲の位置と太さ
• 複数の範囲の設定
• 範囲のユースケースとパターン

カスタマイズとスタイル設定

📄 参照： references/customization.md

• 両方のゲージの外観
• 色（単色とグラデーション）
• 太さとサイズ
• 境界線のカスタマイズ
• 角と縁のスタイル
• 背景色と画像
• テーマとの統合
• ラベルと目盛りのスタイル設定

アニメーション

📄 参照： references/animation.md

• 両方のゲージでのアニメーションのサポート
• ポインターのアニメーション
• 軸と範囲のアニメーション
• アニメーションの時間とイージング
• enableAnimation プロパティ
• アニメーションのコールバック
• 読み込みアニメーション

インタラクション

📄 参照： references/interaction.md

• 両方のゲージでのポインターのドラッグ
• enableDragging プロパティ
• 値変更イベント
• onValueChangeStart、onValueChanging、onValueChanged、onValueChangeEnd
• タッチとジェスチャーのサポート
• インタラクティブな値の更新
• ドラッグ範囲の制限

アクセシビリティ

📄 参照： references/accessibility.md

• スクリーンリーダーのサポート
• ゲージのセマンティックラベル
• WCAG への準拠
• キーボードナビゲーション
• リニアゲージのアクセシビリティ
• ラジアルゲージのアクセシビリティ
• ベストプラクティス

高度な機能

📄 参照： references/advanced-features.md

• ミラーゲージ（リニアゲージ）
• ウィジェットを使った注釈（ラジアルゲージ）
• 画像へのエクスポート（ラジアルゲージ）
• 背景画像（ラジアルゲージ）
• カスタムラベルの書式設定
• カスタムレンダラーとビルダー
• 特殊な設定
• エッジケースとトラブルシューティング

クイックスタートの例

詳細なセットアップ手順については、はじめにを参照してください。

基本的なリニアゲージ

import 'package:syncfusion_flutter_gauges/gauges.dart';

SfLinearGauge(
  minimum: 0,
  maximum: 100,
  barPointers: [LinearBarPointer(value: 60)],
  markerPointers: [LinearShapePointer(value: 60)],
)

基本的なラジアルゲージ

import 'package:syncfusion_flutter_gauges/gauges.dart';

SfRadialGauge(
  axes: [
    RadialAxis(
      minimum: 0,
      maximum: 150,
      pointers: [NeedlePointer(value: 90)],
    ),
  ],
)

インタラクティブなゲージ（ドラッグ可能）

double _value = 50.0;

// Linear with dragging
SfLinearGauge(
  markerPointers: [
    LinearShapePointer(
      value: _value,
      enableDragging: true,
      onChanged: (v) => setState(() => _value = v),
    ),
  ],
)

// Radial with dragging
SfRadialGauge(
  axes: [
    RadialAxis(
      pointers: [
        NeedlePointer(
          value: _value,
          enableDragging: true,
          onValueChanged: (v) => setState(() => _value = v),
        ),
      ],
    ),
  ],
)

よく使われるパターン

複数範囲のステータスインジケーター：

ranges: [
  LinearGaugeRange(startValue: 0, endValue: 30, color: Colors.red),
  LinearGaugeRange(startValue: 30, endValue: 70, color: Colors.yellow),
  LinearGaugeRange(startValue: 70, endValue: 100, color: Colors.green),
]

グラデーションのスタイル設定：

axisTrackStyle: LinearAxisTrackStyle(
  gradient: LinearGradient(colors: [Colors.blue, Colors.purple]),
)

垂直方向：

SfLinearGauge(
  orientation: LinearGaugeOrientation.vertical,
  barPointers: [LinearBarPointer(value: 75)],
)

カスタム角度（半円）：

RadialAxis(startAngle: 180, endAngle: 0)

ミラー効果：

SfLinearGauge(isMirrored: true)

主なプロパティ

SfLinearGauge の主なプロパティ

• minimum - 軸の最小値（デフォルト：0）
• maximum - 軸の最大値（デフォルト：100）
• interval - 軸ラベルの間隔
• orientation - 水平方向または垂直方向
• isMirrored - ゲージ要素を反転します
• isAxisInversed - 軸の方向を反転します
• axisTrackStyle - 軸トラックのスタイル（色、太さ、グラデーション、枠線）
• axisTrackExtent - 軸トラックを両端に延長します
• showAxisTrack - 軸トラックを表示／非表示にします
• showLabels - 軸ラベルを表示／非表示にします
• showTicks - 目盛りを表示／非表示にします
• labelPosition - ラベルの内側または外側への配置
• tickPosition - 目盛りの内側または外側への配置
• labelOffset - 目盛りとラベルの間隔
• labelFormatterCallback - カスタムラベルの書式設定
• ranges - 色付きセグメント用の LinearGaugeRange のリスト
• markerPointers - 形状またはウィジェットのポインターのリスト
• barPointers - バー型ポインター（進捗スタイル）のリスト
• animationDuration - アニメーションの時間（ミリ秒）
• onGenerateLabels - カスタムラベル生成コールバック
• valueToFactorCallback - カスタムスケール変換

SfRadialGauge の主なプロパティ

• title - ゲージの見出し用の GaugeTitle
• backgroundColor - ゲージの背景色
• axes - RadialAxis のリスト（複数に対応）
• enableLoadingAnimation - 読み込みアニメーションを表示します
• animationDuration - アニメーションの時間（ミリ秒）

RadialAxis の主なプロパティ

• minimum - 軸の最小値（デフォルト：0）
• maximum - 軸の最大値（デフォルト：100）
• interval - ラベルの間隔
• startAngle - 軸の開始角度（デフォルト：270）
• endAngle - 軸の終了角度（デフォルト：270）
• radiusFactor - 半径のサイズ係数（0～1）
• centerX - 水平方向の中心位置（0～1）
• centerY - 垂直方向の中心位置（0～1）
• isInversed - 軸の方向を反転します
• canScaleToFit - 角度に基づいて軸を配置します
• canRotateLabels - 角度に基づいてラベルを回転します
• showFirstLabel - 最初のラベルを表示／非表示にします
• showLastLabel - 最後のラベルを表示／非表示にします
• maximumLabels - 論理ピクセル 100 個あたりの最大ラベル数
• axisLineStyle - 軸線用の AxisLineStyle
• showAxisLine - 軸線を表示／非表示にします
• showLabels - ラベルを表示／非表示にします
• showTicks - 目盛りを表示／非表示にします
• axisLabelStyle - ラベル用の GaugeTextStyle
• labelFormat - ラベルの書式文字列（接頭辞／接尾辞）
• numberFormat - グローバリゼーション用の NumberFormat
• labelsPosition - 内側または外側への配置
• ticksPosition - 内側または外側への配置
• majorTickStyle - MajorTickStyle のカスタマイズ
• minorTickStyle - MinorTickStyle のカスタマイズ
• minorTicksPerInterval - 区間ごとの補助目盛り数
• tickOffset - 軸からの距離
• labelOffset - 目盛りからの距離
• offsetUnit - 論理ピクセルまたは係数
• backgroundImage - 軸の背景用の AssetImage
• ranges - GaugeRange のリスト
• pointers - GaugePointer のリスト
• annotations - GaugeAnnotation のリスト
• onLabelCreated - ラベル作成コールバック
• onAxisTapped - 軸タップ時のコールバック
• onCreateAxisRenderer - カスタムレンダラーのコールバック

LinearGauge の範囲プロパティ

• startValue - 範囲の開始値
• endValue - 範囲の終了値
• color - 範囲の色
• startWidth - 開始時の幅
• endWidth - 終了時の幅
• position - 内側、外側、または交差
• rangeShapeType - 平面または曲線の形状

RadialGauge の範囲プロパティ

• startValue - 範囲の開始値
• endValue - 範囲の終了値
• color - 範囲の色
• startWidth - 開始時の幅
• endWidth - 終了時の幅
• gradient - 範囲のグラデーション
• rangeOffset - 軸からのオフセット
• sizeUnit - 論理ピクセルまたは係数
• label - 範囲のテキストラベル

ポインターのプロパティ（共通）

• value - ポインターの値
• enableDragging - ポインターのドラッグを有効にします
• enableAnimation - ポインターのアニメーションを有効にします
• animationDuration - アニメーションの継続時間
• animationType - アニメーションのカーブタイプ
• onValueChangeStart - ドラッグ開始時のコールバック
• onValueChanging - ドラッグ中の進行状況コールバック
• onValueChanged - 値変更時のコールバック
• onValueChangeEnd - ドラッグ終了時のコールバック

一般的なユースケース

1. 進捗インジケーター - 進捗の追跡には LinearBarPointer または RangePointer を使用します
2. スピードメーターのダッシュボード - NeedlePointer と範囲を備えた RadialGauge を使用します
3. 温度表示 - 縦型の LinearGauge または半円形の RadialGauge を使用します
4. バッテリーインジケーター - ミラー効果と範囲を備えた LinearGauge を使用します
5. 音量／輝度のコントロール - ドラッグ可能な LinearShapePointer を使用します
6. KPI ダッシュボード - 注釈を備えた複数の RadialGauge を使用します
7. 評価表示 - 半円形で RangePointer を備えた RadialGauge を使用します
8. 燃料計 - 針とカラー範囲を備えた RadialGauge を使用します
9. ローディングインジケーター - アニメーション付きの LinearBarPointer または RangePointer を使用します
10. スライダーの代替 - ドラッグ可能なポインターを備えたインタラクティブな LinearGauge を使用します