syncfusion-flutter-sliders

Syncfusion Flutter スライダーコントロール

このスキルでは、値の選択と範囲の操作に関連する Syncfusion Flutter の 3 つのコンポーネント、SfSlider（単一値）、SfRangeSlider（2 つのつまみを持つ範囲）、SfRangeSelector（チャートなどの子コンテンツを含む範囲セレクター）をまとめています。これらのコンポーネントには、見た目や設定に関する多くの共通点がありますが、それぞれ異なる役割と統合パターンがあります。

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

次のような場合にこのスキルを使用します。

• コンパクトな UI で単一の数値または日付を選択する場合（SfSlider を使用）。
• 2 つのつまみで開始点と終了点の範囲を選択する場合（SfRangeSlider を使用）。
• 別のウィジェットを連動させる範囲を選択する（チャートのズームや選択など）、または子コンテンツを表示する場合（SfRangeSelector を使用）。
• スライダーコントロール全体で、トラック、目盛り、ラベル、つまみ、ツールチップの外観をカスタマイズする場合。
• 選択やズームのために、スライダーの範囲をチャートと連携させる場合。
• スライダーコントロールで RTL、アクセシビリティ、キーボード操作に対応する場合。

適切なコンポーネントの選び方

次の場合は SfSlider を使用します。

• 単一値を選択する UI（音量、進捗率、タイムラインのスクラバー）が必要な場合。
• シンプルさと小さな画面領域が求められる場合。

次の場合は SfRangeSlider を使用します。

• 2 つのつまみを使って、数値または日付の範囲をユーザーに選択してもらう場合。
• つまみの動作を制御するドラッグモード（onThumb、betweenThumbs、both）が必要な場合。

次の場合は SfRangeSelector を使用します。

• 子ウィジェット（一般的にはチャート）を含む、または制御する範囲コントロールが必要な場合。
• プログラムによる更新やチャートとの統合に RangeController が必要な場合。

主な違いの概要：

機能	SfSlider	SfRangeSlider	SfRangeSelector
主な用途	単一値	2 つのつまみを持つ範囲	子ウィジェットを含む範囲（チャート）
値の型	value	values (SfRangeValues)	initialValues / controller
子コンテンツ	❌	❌	✅（任意のウィジェット。多くの場合はチャート）
コントローラーのサポート	❌	❌	✅ (RangeController)
ドラッグモード	—	✅ (dragMode)	✅ (dragMode)
更新の遅延	❌	❌	✅ (enableDeferredUpdate)

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

はじめに

📄 参照： references/getting-started.md

• 3 つのスライダーコントロールすべてのインストールとパッケージの設定
• SfSlider の基本的な実装（水平および垂直）
• SfRangeSlider の基本的な実装
• チャートと連携する SfRangeSelector の基本的な実装
• パッケージの依存関係とインポート
• すぐに試せる比較と最初の例
• 数値および日付ベースのスライダーの例

コンポーネントの概要

📄 スライダー： references/slider-overview.md

• SfSlider ウィジェットの概要と機能
• 単一値スライダーと範囲コントロールの使い分け
• 数値と日付の値のサポート
• 水平および垂直の向き
• スライダー固有の機能
• スライダーの基本設定

📄 範囲スライダー： references/range-slider-overview.md

• SfRangeSlider ウィジェットの概要と機能
• Range Slider と Range Selector の使い分け
• 開始値と終了値を扱う SfRangeValues クラス
• ドラッグモードの概要
• アクティブ領域と非アクティブ領域のトラック
• 範囲スライダー固有の例

📄 範囲セレクター： references/range-selector-overview.md

• SfRangeSelector ウィジェットの概要と機能
• チャートとの連携に Range Selector を使用する場面
• 子ウィジェットのサポート（チャート、グラフ、カスタムコンテンツ）
• RangeController の概要
• initialValues と controller の違い
• 更新を遅延させるパターン
• チャートとの連携パターン

値の設定

📄 参照： references/values-and-intervals.md

• 最小値と最大値の設定
• 各ウィジェットの値の型（double、DateTime）
• 間隔の設定とステップ値
• カスタム書式を使用した数値範囲
• 日付および DateTime の範囲
• DateIntervalType の設定
• NumberFormat と DateFormat の使用方法
• 値の制約と検証

ビジュアルのカスタマイズ

📄 参照： references/track-and-shapes.md

• アクティブおよび非アクティブなトラックの色
• トラックの高さと太さのカスタマイズ
• トラックの角と形状
• カスタムトラックのスタイル設定パターン
• RangeSelector の領域の色
• 3 つすべてのウィジェットにおけるトラックの外観

📄 参照： references/ticks-and-dividers.md

• 目盛りの有効化と設定
• 主目盛りの設定
• 補助目盛りと間隔
• 区切り線の設定
• 目盛りと区切り線のスタイル設定
• 3 つすべてのウィジェットの完全な例

📄 参照： references/labels-and-formatting.md

• ラベルの表示と配置
• 数値の NumberFormat（通貨、パーセンテージ、簡略形式）
• 日付の DateFormat（さまざまなパターン）
• labelFormatterCallback によるラベルのカスタム書式設定
• ラベルテキストのスタイル設定
• ラベルのオフセットと配置
• 端のラベルの表示設定

📄 参照： references/thumbs-tooltips-overlay.md

• サムのサイズ、色、カスタマイズ
• サムのアイコンとカスタムウィジェット
• サムのストローク（境界線）の設定
• オーバーレイ（リップル）の設定
• ツールチップの有効化と設定
• ツールチップの形状（長方形、パドル型）
• ツールチップテキストの書式設定
• ツールチップを常に表示するオプション

高度な機能

📄 参照： references/drag-modes.md

• ドラッグモードの機能（RangeSlider と RangeSelector のみ）
• SliderDragMode.onThumb の説明
• SliderDragMode.betweenThumbs の説明
• SliderDragMode.both の説明
• 適切なドラッグモードの選択
• 各モードのユースケースと例

📄 参照： references/range-controller.md

• RangeController の概要（RangeSelector のみ）
• RangeController を使用する場面
• コントローラーの作成と破棄
• パフォーマンス向上のための更新の遅延
• プログラムによる範囲の更新
• 範囲の変更の監視
• コントローラーを使ったチャート連携
• コントローラーと initialValues の比較
• 高度なパターン（適用ボタン、セレクターの同期）

イベント処理

📄 参照： references/callbacks-and-events.md

• onChanged コールバック（継続的な更新）
• onChangeStart コールバック（操作の開始）
• onChangeEnd コールバック（操作の完了）
• ライフサイクル全体の例
• コールバック内での検証と制約
• 非同期処理とデバウンス
• イベント処理パターン
• コールバック使用のベストプラクティス

アクセシビリティと状態

📄 参照： references/accessibility-and-states.md

• アクセシビリティの概要と重要性
• スクリーンリーダー向けのセマンティックラベル
• 有効状態と無効状態
• キーボードナビゲーションのサポート
• スクリーンリーダーのサポート（VoiceOver、TalkBack）
• 右から左へ記述する言語（RTL）のサポート
• WCAG 準拠のガイドライン
• 色のコントラストに関する考慮事項
• タッチターゲットのサイズ
• アクセシビリティ機能のテスト

クイックスタートの例

SfSlider — 基本的な単一値スライダー

double _value = 40.0;

SfSlider(
  min: 0.0,
  max: 100.0,
  value: _value,
  interval: 20,
  showLabels: true,
  onChanged: (dynamic newValue) {
    setState(() { _value = newValue; });
  },
)

SfRangeSlider — 基本的な範囲選択

SfRangeValues _values = const SfRangeValues(40.0, 60.0);

SfRangeSlider(
  min: 0.0,
  max: 100.0,
  values: _values,
  interval: 20,
  showLabels: true,
  onChanged: (SfRangeValues newValues) {
    setState(() { _values = newValues; });
  },
)

SfRangeSelector — チャートの子ウィジェットとコントローラーを使った範囲選択

final SfRangeValues _initial = SfRangeValues(0.3, 0.7);
RangeController _controller = RangeController(start: 0.3, end: 0.7);

SfRangeSelector(
  min: 0,
  max: 1,
  initialValues: _initial,
  controller: _controller,
  child: SizedBox(height: 130, child: SfCartesianChart(...)),
)

よく使われるパターン

パターン 1：用途に応じたウィジェットの選択

• 単一値 → SfSlider
• 範囲選択 → SfRangeSlider
• チャート／子ウィジェットを制御する範囲選択 → SfRangeSelector

パターン 2：制御ありと制御なし

• SfSlider と SfRangeSlider は通常、value／values と onChanged を通じて親の状態によって制御します。
• SfRangeSelector は、プログラムによる更新やチャート連携のために RangeController を使って制御できます。

主要なプロパティ

SfSliderの主なプロパティ

• min - 最小値（doubleまたはDateTime）
• max - 最大値（doubleまたはDateTime）
• value - スライダーの現在値
• interval - 分割間の間隔
• stepSize - 離散値のステップ間隔
• onChanged - 値が変化したときのコールバック
• onChangeStart - ドラッグ開始時のコールバック
• onChangeEnd - ドラッグ終了時のコールバック
• showLabels - 間隔ごとのラベルを表示
• showTicks - 目盛りを表示
• showDividers - 区切り線を表示
• enableTooltip - 操作時のツールチップを有効化
• activeColor - アクティブなトラックの色
• inactiveColor - 非アクティブなトラックの色
• numberFormat - 数値用のNumberFormat
• dateFormat - DateTime値用のDateFormat
• dateIntervalType - 日付の間隔の種類（年、月、日など）
• labelFormatterCallback - ラベルのカスタム書式設定
• tooltipTextFormatterCallback - ツールチップのカスタム書式設定
• semanticFormatterCallback - アクセシビリティラベルの書式設定

SfRangeSliderの主なプロパティ

• min - 最小値（doubleまたはDateTime）
• max - 最大値（doubleまたはDateTime）
• values - 範囲の現在値（開始値と終了値を持つSfRangeValues）
• interval - 分割間の間隔
• stepSize - 離散値のステップ間隔
• onChanged - 値が変化したときのコールバック
• onChangeStart - ドラッグ開始時のコールバック
• onChangeEnd - ドラッグ終了時のコールバック
• dragMode - ドラッグ操作モード（onDragStart、onThumb、betweenThumbs、both）
• showLabels - 間隔ごとのラベルを表示
• showTicks - 目盛りを表示
• showDividers - 区切り線を表示
• enableTooltip - 操作時のツールチップを有効化
• activeColor - アクティブなトラックの色（つまみの間）
• inactiveColor - 非アクティブなトラックの色
• numberFormat - 数値用のNumberFormat
• dateFormat - DateTime値用のDateFormat
• dateIntervalType - 日付の間隔の種類
• labelFormatterCallback - ラベルのカスタム書式設定
• tooltipTextFormatterCallback - ツールチップのカスタム書式設定
• semanticFormatterCallback - アクセシビリティラベルの書式設定

SfRangeSelectorの主なプロパティ

• min - 最小値（doubleまたはDateTime）
• max - 最大値（doubleまたはDateTime）
• initialValues - 初期範囲値（SfRangeValues）
• controller - プログラムによる制御用のRangeController
• interval - 分割間の間隔
• stepSize - 離散値のステップ間隔
• onChanged - 値が変化したときのコールバック（controllerを使用する場合は省略可能）
• onChangeStart - ドラッグ開始時のコールバック
• onChangeEnd - ドラッグ終了時のコールバック
• dragMode - ドラッグ操作モード（onDragStart、onThumb、betweenThumbs、both）
• enableDeferredUpdate - パフォーマンス向上のため、更新の遅延を有効化
• deferredUpdateDelay - 更新を遅延させる時間
• showLabels - 間隔ごとのラベルを表示
• showTicks - 目盛りを表示
• showDividers - 区切り線を表示
• enableTooltip - 操作時のツールチップを有効化
• activeColor - アクティブなトラックの色（つまみの間）
• inactiveColor - 非アクティブなトラックの色
• child - 子ウィジェット（通常はチャート）
• numberFormat - 数値用のNumberFormat
• dateFormat - DateTime値用のDateFormat
• dateIntervalType - 日付の間隔の種類
• labelFormatterCallback - ラベルのカスタム書式設定
• tooltipTextFormatterCallback - ツールチップのカスタム書式設定
• semanticFormatterCallback - アクセシビリティラベルの書式設定
• enableIntervalSelection - 間隔による選択を有効化
• showDivisors - 領域の区切り線を表示

一般的なユースケース

1. 音量または明るさの調整 — SfSlider
2. 日付範囲フィルター — SfRangeSlider
3. チャートのズーム／セグメント選択 — SfRangeSelector + チャートとの連携
4. 分析ダッシュボード用の時間範囲ピッカー — SfRangeSelector
5. 商品リストの両端指定価格範囲フィルター — SfRangeSlider