CalendarView Flutter API #

中文 | English

本文档只描述发布到 pub 的日历 SDK API。示例页面和具体业务样式仅保留在仓库 demo 中，不属于发布包内容。

支持作者 #

如果这个库对你有帮助，可以请作者喝杯咖啡。

支付宝	微信

界面截图 #

导入 #

import 'package:calendarview_flutter/calendarview_flutter.dart';

最小使用 #

final controller = CalendarController(focusedDay: DateTime.now());

CalendarView(
  controller: controller,
  pageOrientation: CalendarPageOrientation.horizontal,
  onDaySelected: (day) {
    controller.selectDay(day);
  },
)

CalendarController #

构造参数：

状态读取：

配置方法：

跳转与选择：

选择模式 #

单选：

controller
  ..setSelectionMode(CalendarSelectionMode.single)
  ..selectDay(DateTime(2026, 7, 14));

范围选择：

controller
  ..setSelectionMode(CalendarSelectionMode.range)
  ..setRangeSelectionLimits(minRange: 2, maxRange: 14);

CalendarView(
  controller: controller,
  pageOrientation: CalendarPageOrientation.horizontal,
  onDaySelected: (day) => controller.selectDay(day),
  onRangeSelected: (range) {
    final start = range.start;
    final end = range.end;
  },
  onSelectOutOfRange: (day, violation) {},
)

多选：

controller
  ..setSelectionMode(CalendarSelectionMode.multi)
  ..setMaxMultiSelectSize(5);

CalendarView(
  controller: controller,
  pageOrientation: CalendarPageOrientation.horizontal,
  onDaySelected: (day) => controller.selectDay(day),
  onMultiSelected: (day, selectedSize, maxSize) {},
  onMultiSelectOutOfSize: (day, maxSize) {},
)

CalendarView #

核心月/周日历视图。

CalendarInteractiveController #

控制可展开、折叠、全屏的日历布局。

状态：

方法：

CalendarInteractiveView #

日历 + 内容列表联动视图。

CalendarMonthYearController #

控制年视图浮层。

CalendarMonthYearView #

在 CalendarInteractiveView 之上增加年视图。

CalendarMonthListView #

按月份连续滚动的列表视图。

CalendarYearModeStyle #

年视图样式配置。

内置值：CalendarYearModeStyle.dark、CalendarYearModeStyle.vertical。

CalendarYearModeLayout #

为自定义页面增加年视图覆盖层。

CalendarComponentBuilder #

日历样式扩展协议。库层只提供协议，不内置 demo 样式。

需要实现：

可覆盖：

示例：

class MyCalendarBuilder extends CalendarComponentBuilder {
  const MyCalendarBuilder();

  @override
  List<String> orderedWeekLabels(int firstWeekday) {
    return calendarOrderedWeekLabels(
      const ['日', '一', '二', '三', '四', '五', '六'],
      firstWeekday,
    );
  }

  @override
  Widget buildWeekBarCell(BuildContext context, CalendarWeekBarCellData data) {
    return Text(data.label);
  }

  @override
  Widget buildDayCell(BuildContext context, CalendarDayCellData data) {
    return Center(child: Text('${data.date.day}'));
  }
}

辅助 API：

数据模型与回调 #

年概览弹层 #

await showYearOverviewSheet(
  context,
  year: 2026,
  onMonthSelected: (month) {
    controller.jumpToMonth(month);
  },
);

致谢 #

感谢 huanghaibin-dev/CalendarView 作者提供 Android 版本源码参考。

再次感谢支持 #

如果这个库节省了你的开发时间，欢迎支持作者持续维护。

支付宝	微信