syncfusion-flutter-calendar-datepicker

Syncfusion Flutter 日历和日期范围选择器

本技能涵盖两个用于日期和日历功能的相关 Syncfusion Flutter 组件：SfCalendar（事件日历）和 SfDateRangePicker（日期范围选择器）。虽然它们在视觉和配置功能方面有许多共同点，但主要用途各不相同。

何时使用此技能

在以下情况下使用此技能：

• 实现事件日历，支持约会、日程安排和时间管理
• 添加日期选择功能，用于表单、筛选器或预订界面
• 显示日历视图（月、周、日、年、十年、时间线、日程）
• 处理日期范围选择，用于报告、分析或筛选
• 创建约会/预订系统，支持重复事件和时区
• 构建日程安排界面，支持拖放、调整大小和资源视图
• 启用日期导航，支持多种视图模式和限制
• 自定义日历外观，使用构建器、主题和样式
• 支持多种日期选择模式（单选、多选、范围、多范围）
• 集成日历本地化，支持 RTL 和无障碍功能

选择合适的组件

在以下情况下使用 SfCalendar（事件日历）：

• 需要显示和管理约会/事件
• 应用需要日程安排功能（预订、会议、任务）
• 需要用于事件管理的时间线视图或日程视图
• 基于时间的视图很重要（按时间段显示的日、周、工作周）
• 需要重复事件、时区或资源分配
• 需要拖放或调整约会大小
• 为以下场景构建日历：会议安排器、约会簿、任务管理器、活动规划器

在以下情况下使用 SfDateRangePicker（日期范围选择器）：

• 需要日期选择，而无需管理约会
• 主要目的是为表单/筛选器选择日期或日期范围
• 需要灵活的选择模式（单选、多选、范围、多范围）
• 需要为预订开始/结束日期、报告周期等简化日期输入
• 希望在日期选择对话框中使用操作按钮（确认/取消）
• 为以下界面构建 UI：日期筛选器、预订日期、报告日期范围、表单日期输入

主要区别汇总：

功能	SfCalendar	SfDateRangePicker
主要用途	事件日程安排与显示	日期选择
约会/事件	✅ 完全支持	❌ 不支持
视图类型	9 种视图（日、周、时间线等）	4 种视图（月、年、十年、世纪）
选择模式	单个日期/时间段	单选、多选、范围、多范围
时间段	✅ 支持（含时间）	❌ 仅日期
操作按钮	❌ 无	✅ 确认/取消按钮
重复事件	✅ 支持	❌ 不支持
时区	✅ 支持	❌ 不支持
资源视图	✅ 支持	❌ 不支持
拖放	✅ 支持	❌ 不支持

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 两个组件的安装和软件包设置
• SfCalendar 基本实现
• SfDateRangePicker 基本实现
• 软件包依赖项和导入
• 快速比较和首批示例

组件概览

📄 日历： references/calendar-overview.md

• SfCalendar 组件概览和功能
• 何时使用 Calendar，何时使用 Date Range Picker
• 九种日历视图类型说明
• 日历专属功能
• 日历基本配置

📄 日期范围选择器： references/datepicker-overview.md

• SfDateRangePicker 组件概览和功能
• 何时使用 Date Range Picker，何时使用 Calendar
• 四种选择器视图类型说明
• 日期选择器专属功能
• 多选择器视图（并排显示）

视图类型和导航

📄 阅读： references/views.md

• 月视图（两个组件）
• 年、十年、世纪视图（日期范围选择器）
• 日、周、工作周视图（日历）
• 日程视图（日历）
• 时间轴视图：日、周、工作周、月（日历）
• 月日程视图（日历）
• 视图切换和导航
• 周数显示
• 配置每周的第一天

📄 阅读： references/date-navigations.md

• 向前和向后导航
• 以编程方式导航日期
• 配置初始显示日期
• 导航箭头
• 视图模式切换控件
• 最小/最大日期限制
• 禁用日期（不可选日期）

日历专属功能

📄 阅读： references/appointments.md

• 日历约会（事件/日程安排）
• 约会类和属性
• 设置和映射 CalendarDataSource
• 自定义约会对象
• 全天约会
• 重复约会和规则
• 约会显示模式
• 约会的时区支持
• 自定义约会

日期范围选择器专属功能

📄 阅读： references/selections.md

• 选择模式（单选、多选、范围、多范围、可扩展）
• 选择单个日期
• 选择多个日期
• 范围选择（开始日期和结束日期）
• 多范围选择（多个范围）
• 以编程方式选择
• 选择变更回调
• 初始选中日期
• 选择装饰和样式

自定义和样式

📄 阅读： references/customization.md

• 自定义视觉外观
• 单元格样式和颜色
• 自定义页眉
• 今日高亮颜色
• 单元格边框颜色和背景
• 选择装饰
• 主题集成
• 特殊时间区域（日历）
• 月视图单元格外观

📄 阅读： references/builders.md

• 自定义单元格构建器
• 月视图单元格构建器
• 年视图单元格构建器
• 约会构建器（日历）
• 时间区域构建器（日历）
• 资源页眉构建器（日历）
• 构建器模式和示例

事件处理

📄 阅读： references/callbacks.md

• onSelectionChanged（两个组件）
• onViewChanged（两个组件）
• onTap 和 onLongPress（日历）
• onSubmit 和 onCancel（日期范围选择器）
• 日历专属回调（约会交互）
• 回调参数类型
• 事件处理模式

本地化和无障碍功能

📄 阅读： references/localization.md

• 国际化支持
• 区域设置配置
• 自定义日期格式
• 页眉和单元格格式
• 全球化示例
• 从右向左（RTL）支持

📄 阅读： references/accessibility.md

• 屏幕阅读器支持
• 语义标签
• 键盘导航
• 符合 WCAG 标准
• 焦点指示器
• 无障碍日期选择

高级功能

📄 阅读： references/advanced-features.md

• 时区（日历）
• 资源视图（日历）
• 拖放（日历）
• 调整约会大小（日历）
• 加载更多约会（日历）
• 回历支持（日期范围选择器）
• 日期限制和约束（日期范围选择器）
• 操作按钮（日期范围选择器）
• 当前时间指示器（日历）

快速入门示例

带约会的基本日历

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 - 日历视图类型（day、week、month、schedule、timeline 等）
• dataSource - 包含预约的 CalendarDataSource
• initialDisplayDate - 初始显示的日期
• initialSelectedDate - 初始选中的日期/时间
• monthViewSettings - 月视图配置
• timeSlotViewSettings - 日/周视图配置
• scheduleViewSettings - 日程视图配置
• todayHighlightColor - 今天日期的颜色
• selectionDecoration - 选择样式
• onTap - 点击单元格时的回调
• onLongPress - 长按时的回调
• onViewChanged - 视图变化时的回调
• onSelectionChanged - 选择变化时的回调
• showNavigationArrow - 显示前进/后退箭头
• showCurrentTimeIndicator - 显示当前时间线
• allowViewNavigation - 允许在视图间切换
• firstDayOfWeek - 每周的第一天（1-7）
• blackoutDates - 禁用的日期
• minDate / maxDate - 日期范围限制

SfDateRangePicker 核心属性

• view - 选择器视图类型（month、year、decade、century）
• selectionMode - 选择模式（single、multiple、range、multiRange、extendableRange）
• 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