syncfusion-flutter-calendar-datepicker

Syncfusion Flutter Calendar & Date Range Picker

このスキルでは、日付とカレンダー機能に関連する Syncfusion Flutter コンポーネント、SfCalendar（イベントカレンダー）と SfDateRangePicker（日付範囲ピッカー）を取り上げます。多くの外観や設定機能を共有していますが、主な用途はそれぞれ異なります。

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

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

• 予定、スケジュール管理、時間管理に対応したイベントカレンダーを実装する
• フォーム、フィルター、予約インターフェースに日付選択を追加する
• カレンダービュー（月、週、日、年、年代、タイムライン、スケジュール）を表示する
• レポート、分析、フィルタリングのための日付範囲選択を処理する
• 繰り返しイベントやタイムゾーンに対応した予定／予約システムを作成する
• ドラッグ＆ドロップ、サイズ変更、リソースビューに対応したスケジュール管理インターフェースを構築する
• さまざまな表示モードや制限を設定して日付を移動できるようにする
• ビルダー、テーマ、スタイルを使ってカレンダーの外観をカスタマイズする
• 複数の日付選択モード（単一、複数、範囲、複数範囲）に対応する
• RTL サポートとアクセシビリティに対応したカレンダーのローカライズを統合する

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

次の場合は SfCalendar（イベントカレンダー）を使用します。

• 予定／イベントを表示して管理する必要がある
• アプリにスケジュール機能（予約、会議、タスク）が必要である
• イベント管理にタイムラインビューやスケジュールビューが必要である
• 時間ベースのビュー（時間枠を含む日、週、稼働週）が重要である
• 繰り返しイベント、タイムゾーン、リソース割り当てが必要である
• ドラッグ＆ドロップや予定のサイズ変更が必要である
• 会議スケジューラー、予約管理、タスク管理、イベント計画用のカレンダーを構築する

次の場合は SfDateRangePicker（日付範囲ピッカー）を使用します。

• 予定管理を伴わない日付選択が必要である
• 主な目的がフォーム／フィルター用の日付または日付範囲の選択である
• 柔軟な選択モード（単一、複数、範囲、複数範囲）が必要である
• 予約の開始日／終了日、レポート期間などを入力するためのシンプルな日付入力が必要である
• 日付選択ダイアログにアクションボタン（確定／キャンセル）が必要である
• 日付フィルター、予約日、レポートの日付範囲、フォームの日付入力用の UI を構築する

主な違いのまとめ：

機能	SfCalendar	SfDateRangePicker
主な用途	イベントのスケジュール管理と表示	日付選択
予定／イベント	✅ 完全対応	❌ 非対応
表示タイプ	9 種類（日、週、タイムラインなど）	4 種類（月、年、年代、世紀）
選択モード	単一の日付／時間枠	単一、複数、範囲、複数範囲
時間枠	✅ はい（時刻あり）	❌ 日付のみ
アクションボタン	❌ なし	✅ 確定／キャンセルボタン
繰り返しイベント	✅ はい	❌ いいえ
タイムゾーン	✅ はい	❌ いいえ
リソースビュー	✅ はい	❌ いいえ
ドラッグ＆ドロップ	✅ はい	❌ いいえ

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

はじめに

📄 読む: references/getting-started.md

• 2 つのコンポーネントのインストールとパッケージのセットアップ
• SfCalendar の基本的な実装
• SfDateRangePicker の基本的な実装
• パッケージの依存関係とインポート
• 簡単な比較と最初のサンプル

コンポーネントの概要

📄 カレンダー: references/calendar-overview.md

• SfCalendar ウィジェットの概要と機能
• Calendar と Date Range Picker の使い分け
• 9 種類のカレンダービューの説明
• カレンダー固有の機能
• 基本的なカレンダー設定

📄 日付範囲ピッカー: references/datepicker-overview.md

• SfDateRangePicker ウィジェットの概要と機能
• Date Range Picker と Calendar の使い分け
• 4 種類のピッカービューの説明
• 日付ピッカー固有の機能
• マルチピッカービュー（横並び）

ビューの種類とナビゲーション

📄 参照： references/views.md

• 月ビュー（両方のコンポーネント）
• 年、10年、世紀ビュー（Date Range Picker）
• 日、週、稼働週ビュー（Calendar）
• スケジュールビュー（Calendar）
• タイムラインビュー：日、週、稼働週、月（Calendar）
• 月の予定一覧ビュー（Calendar）
• ビューの切り替えとナビゲーション
• 週番号の表示
• 週の開始日の設定

📄 参照： references/date-navigations.md

• 前後へのナビゲーション
• プログラムによる日付ナビゲーション
• 初期表示日の設定
• ナビゲーション矢印
• ビューモード切り替えコントロール
• 最小／最大日付の制限
• ブラックアウト日（無効な日付）

Calendar 固有の機能

📄 参照： references/appointments.md

• Calendar の予定（イベント／スケジュール設定）
• 予定クラスとプロパティ
• CalendarDataSource の設定とマッピング
• カスタム予定オブジェクト
• 終日予定
• 繰り返し予定とルール
• 予定の表示モード
• 予定のタイムゾーンサポート
• 予定のカスタマイズ

Date Range Picker 固有の機能

📄 参照： references/selections.md

• 選択モード（単一、複数、範囲、複数範囲、拡張可能）
• 単一の日付選択
• 複数の日付選択
• 範囲選択（開始日と終了日）
• 複数範囲選択（複数の範囲）
• プログラムによる選択
• 選択変更コールバック
• 初期選択日
• 選択範囲の装飾とスタイル設定

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

📄 参照： references/customization.md

• 外観のカスタマイズ
• セルのスタイルと色
• ヘッダーのカスタマイズ
• 今日のハイライト色
• セルの枠線色と背景色
• 選択範囲の装飾
• テーマとの統合
• 特別な時間帯（Calendar）
• 月セルの外観

📄 参照： references/builders.md

• カスタムセルビルダー
• 月セルビルダー
• 年セルビルダー
• 予定ビルダー（Calendar）
• 時間帯ビルダー（Calendar）
• リソースヘッダービルダー（Calendar）
• ビルダーパターンと例

イベント処理

📄 参照： references/callbacks.md

• onSelectionChanged（両方のコンポーネント）
• onViewChanged（両方のコンポーネント）
• onTap と onLongPress（Calendar）
• onSubmit と onCancel（Date Range Picker）
• Calendar 固有のコールバック（予定とのインタラクション）
• コールバック引数の型
• イベント処理パターン

ローカライズとアクセシビリティ

📄 参照： references/localization.md

• 国際化サポート
• ロケールの設定
• 日付形式のカスタマイズ
• ヘッダーとセルの形式
• グローバル化の例
• 右から左（RTL）へのサポート

📄 参照： references/accessibility.md

• スクリーンリーダーのサポート
• セマンティックラベル
• キーボードナビゲーション
• WCAG 準拠
• フォーカスインジケーター
• アクセシブルな日付選択

高度な機能

📄 参照： references/advanced-features.md

• タイムゾーン（Calendar）
• リソースビュー（Calendar）
• ドラッグ＆ドロップ（Calendar）
• 予定のサイズ変更（Calendar）
• 予定の追加読み込み（Calendar）
• ヒジュラ暦のサポート（Date Range Picker）
• 日付の制限と制約（Date Range Picker）
• アクションボタン（Date Range Picker）
• 現在時刻インジケーター（Calendar）

クイックスタートの例

予定付きの基本的なカレンダー

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_calendar/calendar.dart';

class MyCalendar extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('My Calendar')),
      body: SfCalendar(
        view: CalendarView.month,
        dataSource: MeetingDataSource(_getDataSource()),
        monthViewSettings: MonthViewSettings(
          appointmentDisplayMode: MonthAppointmentDisplayMode.appointment
        ),
      ),
    );
  }

  List<Meeting> _getDataSource() {
    final List<Meeting> meetings = <Meeting>[];
    final DateTime today = DateTime.now();
    final DateTime startTime = DateTime(today.year, today.month, today.day, 9, 0, 0);
    final DateTime endTime = startTime.add(Duration(hours: 2));
    
    meetings.add(Meeting(
      'Conference',
      startTime,
      endTime,
      Color(0xFF0F8644),
      false
    ));
    
    return meetings;
  }
}

class MeetingDataSource extends CalendarDataSource {
  MeetingDataSource(List<Meeting> source) {
    appointments = source;
  }

  @override
  DateTime getStartTime(int index) => appointments![index].from;
  
  @override
  DateTime getEndTime(int index) => appointments![index].to;
  
  @override
  String getSubject(int index) => appointments![index].eventName;
  
  @override
  Color getColor(int index) => appointments![index].background;
  
  @override
  bool isAllDay(int index) => appointments![index].isAllDay;
}

class Meeting {
  Meeting(this.eventName, this.from, this.to, this.background, this.isAllDay);
  
  String eventName;
  DateTime from;
  DateTime to;
  Color background;
  bool isAllDay;
}

基本的な日付範囲ピッカー

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_datepicker/datepicker.dart';

class MyDatePicker extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Select Date Range')),
      body: SfDateRangePicker(
        view: DateRangePickerView.month,
        selectionMode: DateRangePickerSelectionMode.range,
        onSelectionChanged: _onSelectionChanged,
        showActionButtons: true,
      ),
    );
  }

  void _onSelectionChanged(DateRangePickerSelectionChangedArgs args) {
    if (args.value is PickerDateRange) {
      final DateTime startDate = args.value.startDate;
      final DateTime? endDate = args.value.endDate;
      print('Selected range: $startDate to $endDate');
    }
  }
}

複数選択が可能な日付ピッカー

SfDateRangePicker(
  view: DateRangePickerView.month,
  selectionMode: DateRangePickerSelectionMode.multiple,
  initialSelectedDates: [
    DateTime.now(),
    DateTime.now().add(Duration(days: 2)),
    DateTime.now().add(Duration(days: 5)),
  ],
  onSelectionChanged: (DateRangePickerSelectionChangedArgs args) {
    final List<DateTime> selectedDates = args.value;
    print('Selected ${selectedDates.length} dates');
  },
)

よくあるパターン

パターン 1：異なるビューを備えたカレンダー

// Switch between day, week, month, and schedule views
CalendarView _calendarView = CalendarView.month;

SfCalendar(
  view: _calendarView,
  dataSource: MeetingDataSource(_appointments),
  onViewChanged: (ViewChangedDetails details) {
    // Handle view changes
  },
)

// Toggle view with buttons
void _changeView(CalendarView view) {
  setState(() {
    _calendarView = view;
  });
}

パターン 2：レポート用の日付範囲フィルター

// Common pattern for selecting date ranges in analytics/reports
PickerDateRange? _selectedRange;

SfDateRangePicker(
  selectionMode: DateRangePickerSelectionMode.range,
  onSelectionChanged: (DateRangePickerSelectionChangedArgs args) {
    setState(() {
      _selectedRange = args.value;
    });
  },
  showActionButtons: true,
  onSubmit: (Object? value) {
    if (_selectedRange != null) {
      _loadReportData(_selectedRange!.startDate, _selectedRange!.endDate);
    }
    Navigator.pop(context);
  },
)

パターン 3：カスタマイズされたセルの外観

// Custom styling for both components
SfCalendar(
  view: CalendarView.month,
  todayHighlightColor: Colors.blue,
  cellBorderColor: Colors.grey[300],
  backgroundColor: Colors.white,
  selectionDecoration: BoxDecoration(
    color: Colors.transparent,
    border: Border.all(color: Colors.blue, width: 2),
    borderRadius: BorderRadius.circular(4),
  ),
)

SfDateRangePicker(
  todayHighlightColor: Colors.green,
  selectionColor: Colors.blue,
  rangeSelectionColor: Colors.blue.withOpacity(0.3),
  startRangeSelectionColor: Colors.blue,
  endRangeSelectionColor: Colors.blue,
)

パターン 4：日付選択の制限

// Disable past dates and weekends
SfDateRangePicker(
  minDate: DateTime.now(),
  maxDate: DateTime.now().add(Duration(days: 365)),
  selectableDayPredicate: (DateTime date) {
    // Disable weekends
    return date.weekday != DateTime.saturday && 
           date.weekday != DateTime.sunday;
  },
)

主要なプロパティ

SfCalendar の主なプロパティ

• view - カレンダーの表示タイプ（日、週、月、スケジュール、タイムラインなど）
• dataSource - 予定を含む CalendarDataSource
• initialDisplayDate - 初期表示する日付
• initialSelectedDate - 初期選択する日付／時刻
• monthViewSettings - 月表示の設定
• timeSlotViewSettings - 日／週表示の設定
• scheduleViewSettings - スケジュール表示の設定
• todayHighlightColor - 今日の日付の色
• selectionDecoration - 選択時のスタイル
• onTap - セルがタップされたときのコールバック
• onLongPress - 長押し時のコールバック
• onViewChanged - 表示が切り替わったときのコールバック
• onSelectionChanged - 選択が変更されたときのコールバック
• showNavigationArrow - 前後に移動する矢印を表示
• showCurrentTimeIndicator - 現在時刻の線を表示
• allowViewNavigation - 表示の切り替えを許可
• firstDayOfWeek - 週の開始曜日（1～7）
• blackoutDates - 選択不可にする日付
• minDate / maxDate - 日付範囲の制限

SfDateRangePicker の主なプロパティ

• view - ピッカーの表示タイプ（月、年、10年、世紀）
• selectionMode - 選択モード（単一、複数、範囲、複数範囲、拡張可能な範囲）
• initialSelectedDate - 初期選択する日付
• initialSelectedDates - 初期選択する日付（複数選択モード）
• initialSelectedRange - 初期選択する範囲
• initialSelectedRanges - 初期選択する範囲（複数範囲モード）
• initialDisplayDate - 初期表示する日付
• monthViewSettings - 月表示の設定
• yearViewSettings - 年表示の設定
• todayHighlightColor - 今日の日付の色
• selectionColor - 選択色
• rangeSelectionColor - 範囲選択の色
• startRangeSelectionColor - 開始日の色
• endRangeSelectionColor - 終了日の色
• onSelectionChanged - 選択が変更されたときのコールバック
• onViewChanged - 表示が切り替わったときのコールバック
• onSubmit - 確認ボタンが押されたときのコールバック
• onCancel - キャンセルボタンが押されたときのコールバック
• showActionButtons - 確認／キャンセルボタンを表示
• showTodayButton - 今日ボタンを表示
• allowViewNavigation - 表示の切り替えを許可
• enablePastDates - 過去の日付の選択を有効化
• minDate / maxDate - 日付範囲の制限
• selectableDayPredicate - カスタム日付検証
• monthCellStyle - 月セルのスタイル
• yearCellStyle - 年セルのスタイル

一般的なユースケース

1. 会議スケジューラー - SfCalendar のスケジュール表示を使用
2. イベント管理 - SfCalendar の月表示、繰り返しイベント、ドラッグ＆ドロップを使用
3. 予約システム - SfDateRangePicker の範囲選択と日付制限を使用
4. 日付フィルター - レポートで範囲／複数範囲を選択するために SfDateRangePicker を使用
5. タスク管理 - SfCalendar のスケジュール表示と終日予定を使用
6. 休暇プランナー - SfDateRangePicker の複数選択と選択不可日を使用
7. リソーススケジューラー - SfCalendar のリソース表示とタイムラインを使用
8. シンプルな日付入力 - SfDateRangePicker の単一選択モードを使用