From c223b3ba78a69c8487de6fc0fd11e08aa94f8b71 Mon Sep 17 00:00:00 2001 From: LXD312569496 <450468291@qq.com> Date: Thu, 31 Oct 2019 17:57:22 +0800 Subject: [PATCH] =?UTF-8?q?readme=E6=96=87=E6=A1=A3=E4=BF=AE=E6=94=B9?= =?UTF-8?q?=EF=BC=8C=E5=A2=9E=E5=8A=A0=E8=8B=B1=E6=96=87=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 17 ++- README.md | 329 +++++++++------------------------------------------ README_en.md | 113 ++++++++++++++++++ 3 files changed, 182 insertions(+), 277 deletions(-) create mode 100644 README_en.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 38d5db9..8ff01c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,14 +1,21 @@ -## [1.0.0] - 2019/9/22 -* 重构日历的代码 +### 近期修改 + + +### [2.0.0] - 2019/11/01 +* 日历支持padding和margin属性，item的大小计算修改 +* 实现日历整体自适应高度 +* controller提供changeExtraDataMap的方法，可以随时动态的修改自定义数据extraDataMap +* 支持显示月视图和周视图的情况，优先显示周视图，MODE_SHOW_WEEK_AND_MONTH +* 支持verticalSpacing和itemSize属性 +### [1.0.0] - 2019/10/10 +* 重构日历的代码,进行性能优化 * 创建configuration类，将配置的信息放到这里 * 引入provider状态管理,避免深层嵌套传递信息 * 实现周视图，并实现周视图和月视图之间的联动 * DateModel增加isCurrentMonth，用于绘制月视图可以屏蔽一些非当前月份的日子，前面几天或者后面几天的isCurrentMonth是为false的。 +### [0.0.1] - 2019/5/19. -## [0.0.1] - 2019/5/19. - -## 主要功能 * 支持公历，农历，节气，传统节日，常用节假日 * 日期范围设置，默认支持的最大日期范围为1971.01-2055.12 * 禁用日期范围设置，比如想实现某范围的日期内可以点击，范围外的日期置灰 diff --git a/README.md b/README.md index e62c030..020a83d 100644 --- a/README.md +++ b/README.md @@ -3,25 +3,20 @@ Flutter上的一个日历控件，可以定制成自己想要的样子。 -## 介绍 -之前写了一个Flutter日历的开源库，最近增加了一些功能，并且对代码进行了一下重构。（之前的代码写得真的是****，没搞状态框架，还各种嵌套代码） +### Language: [English](https://github.com/fluttercandies/flutter_custom_calendar/blob/master/README_en.md)|中文简体 -## 示例 +* 概述 +* 在线Demo +* 效果图 +* 快速使用 +* 2.0版本 +* 注意事项 +* 主要Api文档 -日历支持web预览：[点击此处进入预览](https://lxd312569496.github.io/flutter_custom_calendar/#/) - - - - - - - - +### 概述 - -## 主要功能 * 支持公历，农历，节气，传统节日，常用节假日 * 日期范围设置，默认支持的最大日期范围为1971.01-2055.12 * 禁用日期范围设置，比如想实现某范围的日期内可以点击，范围外的日期置灰 @@ -30,296 +25,86 @@ Flutter上的一个日历控件，可以定制成自己想要的样子。 * 自定义日历Item，支持组合widget的方式和利用canvas绘制的方式 * 自定义顶部的WeekBar * 根据实际场景，可以给Item添加自定义的额外数据，实现各种额外的功能。比如实现进度条风格的日历，实现日历的各种标记 -* 支持周视图的展示 -* 支持月份视图和星期视图的展示与切换联动 +* 支持周视图的展示,支持月份视图和星期视图的展示与切换联动 -## 近期修改 -### [1.0.0] - 2019/10/10 -* 重构日历的代码,进行性能优化 -* 创建configuration类，将配置的信息放到这里 -* 引入provider状态管理,避免深层嵌套传递信息 -* 实现周视图，并实现周视图和月视图之间的联动 -* DateModel增加isCurrentMonth，用于绘制月视图可以屏蔽一些非当前月份的日子，前面几天或者后面几天的isCurrentMonth是为false的。 +### 在线Demo -### [0.0.1] - 2019/5/19. +日历支持web预览：[点击此处进入预览](https://lxd312569496.github.io/flutter_custom_calendar/#/) + + +### 效果图 + + + + + + + + + -* 支持公历，农历，节气，传统节日，常用节假日 -* 日期范围设置，默认支持的最大日期范围为1971.01-2055.12 -* 禁用日期范围设置，比如想实现某范围的日期内可以点击，范围外的日期置灰 -* 支持单选、多选模式，提供多选超过限制个数的回调和多选超过指定范围的回调。 -* 跳转到指定日期，默认支持动画切换 -* 自定义日历Item，支持组合widget的方式和利用canvas绘制的方式 -* 自定义顶部的WeekBar -* 可以给Item添加自定义的额外数据，实现各种额外的功能。比如实现进度条风格的日历 ## 使用 -在pubspec.yaml添加依赖: +1.在pubspec.yaml文件里面添加依赖: ``` flutter_custom_calendar: git: url: https://github.com/LXD312569496/flutter_custom_calendar.git ``` -引入flutter_custom_calendar,就可以使用CalendarViewWidget，配置CalendarController就可以了。 + +2.导入flutter_custom_calendar库 ``` import 'package:flutter_custom_calendar/flutter_custom_calendar.dart'; - -CalendarViewWidget({@required this.calendarController, this.boxDecoration}); ``` -* boxDecoration用来配置整体的背景 -* 利用CalendarController来配置一些数据，并且可以通过CalendarController进行一些操作或者事件监听，比如滚动到下一个月，获取当前被选中的Item等等。 - -## 配置CalendarController - -下面是CalendarController中一些支持自定义配置的属性。不配置的话，会有对应的默认值。（配置现在都是在controller这里进行配置的，内部会将配置的数据抽成Configuration类） - -配置的含义主要包括了3个方面的配置。 -* 一个是显示日历所需要的相关数据， -* 一个是显示日历的自定义UI的相关配置， -* 一个是对日历的监听事件进行配置。 - +3.创建CalendarViewWidget对象，配置CalendarController ``` - //构造函数 - CalendarController( - {int selectMode = Constants.MODE_SINGLE_SELECT, - int showMode = Constants.MODE_SHOW_ONLY_MONTH, - bool expandStatus = true, - DayWidgetBuilder dayWidgetBuilder = defaultCustomDayWidget, - WeekBarItemWidgetBuilder weekBarItemWidgetBuilder = defaultWeekBarWidget, - int minYear = 1971, - int maxYear = 2055, - int minYearMonth = 1, - int maxYearMonth = 12, - int nowYear = -1, - int nowMonth = -1, - int minSelectYear = 1971, - int minSelectMonth = 1, - int minSelectDay = 1, - int maxSelectYear = 2055, - int maxSelectMonth = 12, - int maxSelectDay = 30, - Set selectedDateTimeList = EMPTY_SET, - DateModel selectDateModel, - int maxMultiSelectCount = 9999, - double verticalSpacing = 10, - bool enableExpand = true, - Map extraDataMap = EMPTY_MAP}) - +CalendarController controller= new CalendarController( + minYear: 2018, + minYearMonth: 1, + maxYear: 2020, + maxYearMonth: 12, + showMode: CalendarConstants.MODE_SHOW_MONTH_AND_WEEK); +CalendarViewWidget calendar= CalendarViewWidget( + calendarController: controller, + ), ``` -### 数据方面的配置 - -属性 | 含义 | 默认值 -:-: | :-: | :-: -selectMode | 选择模式,表示单选或者多选 | 默认是单选
static const int MODE_SINGLE_SELECT = 1;
static const int MODE_MULTI_SELECT = 2; -showMode|展示模式| 默认是只展示月视图
static const int MODE_SHOW_ONLY_MONTH=1;//仅支持月视图
static const int MODE_SHOW_ONLY_WEEK=2;//仅支持星期视图
static const int MODE_SHOW_WEEK_AND_MONTH=3;//支持月和星期视图切换 -minYear | 日历显示的最小年份| 1971 -maxYear | 日历显示的最大年份| 2055 -minYearMonth | 日历显示的最小年份的月份| 1 -maxYearMonth | 日历显示的最大年份的月份| 12 -nowYear | 日历显示的当前的年份| -1 -nowMonth | 日历显示的当前的月份| -1 -minSelectYear | 可以选择的最小年份| 1971 -minSelectMonth | 可以选择的最小年份的月份| 1 -minSelectDay | 可以选择的最小月份的日子| 1 -maxSelectYear | 可以选择的最大年份| 2055 -maxSelectMonth | 可以选择的最大年份的月份| 12 -maxSelectDay | 可以选择的最大月份的日子| 30，注意：不能超过对应月份的总天数 -selectedDateList | 被选中的日期,用于多选| 默认为空Set, Set selectedDateList = new Set() -selectDateModel | 当前选择项,用于单选| 默认为空 -maxMultiSelectCount | 多选，最多选多少个| hhh -extraDataMap | 自定义额外的数据| 默认为空Map，Map extraDataMap = new Map() - - -### UI绘制相关的配置 - -属性 | 含义 | 默认值 -:-: | :-: | :-: -weekBarItemWidgetBuilder | 创建顶部的weekbar | 默认样式 -dayWidgetBuilder | 创建日历item | 默认样式 -verticalSpacing|日历item之间的竖直方向间距|默认10 -boxDecoration |整体的背景设置| -itemSize| 每个item的边长|默认是屏幕宽度/7| - - -### 事件监听的配置 - -方法 | 含义 | 默认值 -:-: | :-: | :-: -void addMonthChangeListener(OnMonthChange listener) | 月份切换事件 | -void addOnCalendarSelectListener(OnCalendarSelect listener) | 点击选择事件 | -void addOnMultiSelectOutOfRangeListener(OnMultiSelectOutOfRange listener) | 多选超出指定范围 | -void addOnMultiSelectOutOfSizeListener(OnMultiSelectOutOfSize listener) | 多选超出限制个数 | -void addExpandChangeListener(ValueChanged expandChange)|监听日历的展开收缩状态| - -## 利用controller来控制日历的切换，支持配置动画 - -方法 | 含义 | 默认值 -:-: | :-: | :-: -Future previousPage()|滑动到上一个页面，会自动根据当前的展开状态，滑动到上一个月或者上一个星期。如果已经在第一个页面，没有上一个页面，就会返回false，其他情况返回true| -Future nextPage()|滑动到下一个页面，会自动根据当前的展开状态，滑动到下一个月或者下一个星期。如果已经在最后一个页面，没有下一个页面，就会返回false，其他情况返回true| -void moveToCalendar(int year, int month, int day, {bool needAnimation = false,Duration duration = const Duration(milliseconds: 500),Curve curve = Curves.ease}) | 到指定日期 | -void moveToNextYear()|切换到下一年| -void moveToPreviousYear()|切换到上一年| -void moveToNextMonth()|切换到下一个月份| -void moveToPreviousMonth()|切换到上一个月份| -void toggleExpandStatus()|切换展开状态| - - -## 利用controller来获取日历的一些数据信息 - -方法 | 含义 | 默认值 -:-: | :-: | :-: -DateTime getCurrentMonth()|获取当前的月份| -Set getMultiSelectCalendar()|获取被选中的日期,多选| -DateModel getSingleSelectCalendar()|获取被选中的日期，单选| - - -## 如何自定义UI - -包括自定义WeekBar、自定义日历Item，默认使用的都是DefaultXXXWidget。 +* boxDecoration用来配置整体的背景 +* 利用CalendarController来配置一些数据，并且可以通过CalendarController进行一些操作或者事件监听，比如滚动到下一个月，获取当前被选中的Item等等。 -只要继承对应的Base类，实现相应的方法，然后只需要在配置Controller的时候，实现相应的Builder方法就可以了。 -``` -//支持自定义绘制 -DayWidgetBuilder dayWidgetBuilder; //创建日历item -WeekBarItemWidgetBuilder weekBarItemWidgetBuilder; //创建顶部的weekbar -``` -### 自定义WeekBar -继承BaseWeekBar，重写getWeekBarItem(index)方法就可以。随便你怎么实现，只需要返回一个Widget就可以了。 -``` -class DefaultWeekBar extends BaseWeekBar { - const DefaultWeekBar({Key key}) : super(key: key); - @override - Widget getWeekBarItem(int index) { - /** - * 自定义Widget - */ - return new Container( - height: 40, - alignment: Alignment.center, - child: new Text( - Constants.WEEK_LIST[index], - style: topWeekTextStyle, - ), - ); - } -} -``` -### 自定义日历Item： -提供两种方法，一种是利用组合widget的方式来创建，一种是利用Canvas来自定义绘制Item。最后只需要在CalendarController的构造参数中进行配置就可以了。 -* 继承BaseCombineDayWidget，重写getNormalWidget(DateModel dateModel) -和getSelectedWidget(DateModel dateModel)就可以了，返回对应的widget就行。 +4.操作日历 ``` -class DefaultCombineDayWidget extends BaseCombineDayWidget { - DefaultCombineDayWidget(DateModel dateModel) : super(dateModel); - - @override - Widget getNormalWidget(DateModel dateModel) { - //实现默认状态下的UI - } - - @override - Widget getSelectedWidget(DateModel dateModel) { - //绘制被选中的UI - } -} +controller.toggleExpandStatus();//月视图和周视图的切换 ``` - -* 继承BaseCustomDayWidget，重写drawNormal和drawSelected的两个方法就可以了，利用canvas自己绘制Item。 - ``` -class DefaultCustomDayWidget extends BaseCustomDayWidget { - DefaultCustomDayWidget(DateModel dateModel) : super(dateModel); - @override - void drawNormal(DateModel dateModel, Canvas canvas, Size size) { - //实现默认状态下的UI - defaultDrawNormal(dateModel, canvas, size); - } - @override - void drawSelected(DateModel dateModel, Canvas canvas, Size size) { - //绘制被选中的UI - defaultDrawSelected(dateModel, canvas, size); - } -} +controller.previousPage();//操作日历切换到上一页 ``` -### 根据实际场景，自定义额外的数据extraData - -#### 自定义每个item的进度条数据 - ``` - //外部处理每个dateModel所对应的进度 - Map progressMap = { - DateModel.fromDateTime(temp.add(Duration(days: 1))): 0, - DateModel.fromDateTime(temp.add(Duration(days: 2))): 20, - DateModel.fromDateTime(temp.add(Duration(days: 3))): 40, - DateModel.fromDateTime(temp.add(Duration(days: 4))): 60, - DateModel.fromDateTime(temp.add(Duration(days: 5))): 80, - DateModel.fromDateTime(temp.add(Duration(days: 6))): 100, - }; - //创建CalendarController对象的时候，将extraDataMap赋值就行了 - new CalendarController( - extraDataMap: progressMap) - //绘制DayWidget的时候，可以直接从dateModel的extraData对象中拿到想要的数据 - int progress = dateModel.extraData; +controller.nextPage();//操作日历切换到下一页 ``` -#### 自定义各种标记 -``` - //外部处理每个dateModel所对应的标记 - Map customExtraData = { - DateModel.fromDateTime(DateTime.now().add(Duration(days: -1))): "假", - DateModel.fromDateTime(DateTime.now().add(Duration(days: -2))): "游", - DateModel.fromDateTime(DateTime.now().add(Duration(days: -3))): "事", - DateModel.fromDateTime(DateTime.now().add(Duration(days: -4))): "班", - DateModel.fromDateTime(DateTime.now().add(Duration(days: -5))): "假", - DateModel.fromDateTime(DateTime.now().add(Duration(days: -6))): "游", - DateModel.fromDateTime(DateTime.now().add(Duration(days: 2))): "游", - DateModel.fromDateTime(DateTime.now().add(Duration(days: 3))): "事", - DateModel.fromDateTime(DateTime.now().add(Duration(days: 4))): "班", - DateModel.fromDateTime(DateTime.now().add(Duration(days: 5))): "假", - DateModel.fromDateTime(DateTime.now().add(Duration(days: 6))): "游", - DateModel.fromDateTime(DateTime.now().add(Duration(days: 7))): "事", - DateModel.fromDateTime(DateTime.now().add(Duration(days: 8))): "班", - }; - //创建CalendarController对象的时候，将extraDataMap赋值就行了 - new CalendarController( - extraDataMap: customExtraData) - //绘制DayWidget的时候，可以直接从dateModel的extraData对象中拿到想要的数据 - String data = dateModel.extraData; -``` +## 2.0版本 +主要改动： +* UI配置相关的参数，移动到CalendarView的构造方法里面（旧版本是在controller里面配置） +* 日历支持padding和margin属性，item的大小计算修改 +* 实现日历整体自适应高度 +* controller提供changeExtraDataMap的方法，可以随时动态的修改自定义数据extraDataMap +* 支持显示月视图和周视图的情况，优先显示周视图，MODE_SHOW_WEEK_AND_MONTH +* 支持verticalSpacing和itemSize属性 +## 注意事项 -## DateModel实体类 -日历所用的日期的实体类DateModel，有下面这些属性。可以在自定义绘制DayWidget的时候，根据相应的属性，进行判断后，绘制相应的UI。 +* 如果使用2.0之前的版本，则需要将UI配置相关的参数，移动到CalendarView的构造方法里面（旧版本是在controller里面配置） +* 暂时没有发现其他问题，如果有其他问题，可以跟我说一下。 +* 如果你用这个库做了日历，可以将展示结果分享给我，我贴到文档上进行展示 -属性|含义|类型|默认值 -:-: | :-: | :-: |:-: -year|年份|int| -month|月份|int| -day|日期|int|默认为1 -lunarYear|农历年份|int| -lunarMonth|农历月份|int| -lunarDay|农历日期|int| -lunarString|农历字符串|String| -solarTerm|24节气|String| -gregorianFestival|gregorianFestival|String| -traditionFestival|传统农历节日|String| -isCurrentDay|是否是今天|bool|false -isLeapYear|是否是闰年|bool|false -isWeekend|是否是周末|bool|false -isInRange|是否在范围内,比如可以实现在某个范围外，设置置灰的功能|bool|false -isSelected|是否被选中，用来实现一些标记或者选择功能|bool|false -extraData|自定义的额外数据|Object|默认为空 +## 主要API文档 +[API Documentation](https://github.com/fluttercandies/flutter_custom_calendar/blob/master/API.md) -方法|含义| -:-: | :-: | -DateTime getDateTime()|将DateModel转化成DateTime -DateModel fromDateTime(DateTime dateTime)|根据DateTime创建对应的model，并初始化农历和传统节日等信息 -bool operator ==(Object other)|重写==方法，可以判断两个dateModel是否是同一天 \ No newline at end of file diff --git a/README_en.md b/README_en.md new file mode 100644 index 0000000..638ddf0 --- /dev/null +++ b/README_en.md @@ -0,0 +1,113 @@ + +## FlutterCalendarWidget + +Flutter上的一个日历控件，可以定制成自己想要的样子。 +A calendar widget in flutter,you can design what you want to show! + + +### Language: 中文简体|[English](https://lxd312569496.github.io/flutter_custom_calendar/) + +* Overview +* Online Demo +* Example +* Getting Started +* 2.0 version +* matters needing attention +* API Documentation + + + +### Overview + +* Support the Gregorian calendar, lunar calendar, solar terms, traditional festivals and common holidays +* Date range setting, the maximum date range supported by default is 1971.01-2055.12 +* Disable date range settings. For example, you can click within a range of dates and gray the dates outside the range +* Support single selection and multiple selection modes, and provide multiple selection of callbacks exceeding the limit and multiple selection of callbacks exceeding the specified range. +* Jump to the specified date. Animation switching is supported by default +* Custom Calendar items, support the way of combining widgets and drawing with canvas +* Customize the weekbar at the top +* According to the actual scene, you can add custom additional data to the item to realize various additional functions. For example, to realize the calendar of progress bar style and various marks of calendar +* Support weekly view display, monthly view and weekly view display and switching linkage + +### Online Demo + +Calendar supports web Preview：[Click here for preview](https://lxd312569496.github.io/flutter_custom_calendar/#/) + + +### Example + + + + + + + + + + + +## Getting Started + +1.add dependencies into you project pubspec.yaml file: +``` +flutter_custom_calendar: + git: + url: https://github.com/LXD312569496/flutter_custom_calendar.git +``` + +2.import flutter_custom_calendar lib +``` +import 'package:flutter_custom_calendar/flutter_custom_calendar.dart'; +``` + +3.create CalendarViewWidget object，profile CalendarController +``` +CalendarController controller= new CalendarController( + minYear: 2018, + minYearMonth: 1, + maxYear: 2020, + maxYearMonth: 12, + showMode: CalendarConstants.MODE_SHOW_MONTH_AND_WEEK); +CalendarViewWidget calendar= CalendarViewWidget( + calendarController: controller, + ), +``` + +4.operate controller +``` +controller.toggleExpandStatus();//Switch between month view and week view +``` + +``` +controller.previousPage();//Action calendar switch to previous page +``` + +``` +controller.nextPage();//Action calendar switch to next page + +``` + + +## 2.0 version +Major changes： +* The UI configuration related parameters are moved to the calendar view construction method (the old version is configured in the controller) +* Calendar supports padding and margin attributes, and item size calculation and modification. +* Realize the overall adaptive height of calendar +* The controller provides the method of changing extradatamap, which can dynamically modify the customized data extradatamap at any time. +* It supports the display of monthly view and weekly view, with weekly view as the priority, and mode "show" week "and" month " +* Supports verticalspacing and itemsize properties + + +## matters needing attention + +* If you use the version before 2.0, you need to move the UI configuration related parameters to the calendar view construction method (the old version is configured in the controller). +* I haven't found any other problems for the time being. If you have any, please let me know. +* If you use this library to make a calendar, you can share the display results with me, and I will paste them on the document for display. + + + +## API Documentation + +[API Documentation](https://github.com/fluttercandies/flutter_custom_calendar/blob/master/API.md) + +