|
|
|
|
|
## 主要Api文档
|
|
|
|
|
|
- [主要Api文档](#%e4%b8%bb%e8%a6%81api%e6%96%87%e6%a1%a3)
|
|
|
- [配置日历的UI](#%e9%85%8d%e7%bd%ae%e6%97%a5%e5%8e%86%e7%9a%84ui)
|
|
|
- [参数说明](#%e5%8f%82%e6%95%b0%e8%af%b4%e6%98%8e)
|
|
|
- [配置Controller](#%e9%85%8d%e7%bd%aecontroller)
|
|
|
- [通用参数说明](#%e9%80%9a%e7%94%a8%e5%8f%82%e6%95%b0%e8%af%b4%e6%98%8e)
|
|
|
- [给controller添加事件监听](#%e7%bb%99controller%e6%b7%bb%e5%8a%a0%e4%ba%8b%e4%bb%b6%e7%9b%91%e5%90%ac)
|
|
|
- [利用controller来控制日历的切换，支持配置动画](#%e5%88%a9%e7%94%a8controller%e6%9d%a5%e6%8e%a7%e5%88%b6%e6%97%a5%e5%8e%86%e7%9a%84%e5%88%87%e6%8d%a2%e6%94%af%e6%8c%81%e9%85%8d%e7%bd%ae%e5%8a%a8%e7%94%bb)
|
|
|
- [利用controller来获取当前日历的状态和数据](#%e5%88%a9%e7%94%a8controller%e6%9d%a5%e8%8e%b7%e5%8f%96%e5%bd%93%e5%89%8d%e6%97%a5%e5%8e%86%e7%9a%84%e7%8a%b6%e6%80%81%e5%92%8c%e6%95%b0%e6%8d%ae)
|
|
|
- [如何自定义UI](#%e5%a6%82%e4%bd%95%e8%87%aa%e5%ae%9a%e4%b9%89ui)
|
|
|
- [自定义WeekBar](#%e8%87%aa%e5%ae%9a%e4%b9%89weekbar)
|
|
|
- [自定义日历Item：](#%e8%87%aa%e5%ae%9a%e4%b9%89%e6%97%a5%e5%8e%86item)
|
|
|
- [根据实际场景，自定义额外的数据extraData](#%e6%a0%b9%e6%8d%ae%e5%ae%9e%e9%99%85%e5%9c%ba%e6%99%af%e8%87%aa%e5%ae%9a%e4%b9%89%e9%a2%9d%e5%a4%96%e7%9a%84%e6%95%b0%e6%8d%aeextradata)
|
|
|
- [实现进度条样式的日历](#%e5%ae%9e%e7%8e%b0%e8%bf%9b%e5%ba%a6%e6%9d%a1%e6%a0%b7%e5%bc%8f%e7%9a%84%e6%97%a5%e5%8e%86)
|
|
|
- [实现自定义各种标记的日历](#%e5%ae%9e%e7%8e%b0%e8%87%aa%e5%ae%9a%e4%b9%89%e5%90%84%e7%a7%8d%e6%a0%87%e8%ae%b0%e7%9a%84%e6%97%a5%e5%8e%86)
|
|
|
- [手动修改自定义的数据](#%e6%89%8b%e5%8a%a8%e4%bf%ae%e6%94%b9%e8%87%aa%e5%ae%9a%e4%b9%89%e7%9a%84%e6%95%b0%e6%8d%ae)
|
|
|
- [DateModel实体类](#datemodel%e5%ae%9e%e4%bd%93%e7%b1%bb)
|
|
|
|
|
|
### 配置日历的UI
|
|
|
|
|
|
日历UI相关的配置是在CalendarViewWidget的构造函数里面进行配置就行了。
|
|
|
```
|
|
|
CalendarViewWidget(
|
|
|
{Key key,
|
|
|
this.dayWidgetBuilder = defaultCustomDayWidget,
|
|
|
this.weekBarItemWidgetBuilder = defaultWeekBarWidget,
|
|
|
@required this.calendarController,
|
|
|
this.boxDecoration,
|
|
|
this.padding = EdgeInsets.zero,
|
|
|
this.margin = EdgeInsets.zero,
|
|
|
this.verticalSpacing = 10,
|
|
|
this.itemSize})
|
|
|
: super(key: key);
|
|
|
```
|
|
|
#### 参数说明
|
|
|
|
|
|
| 属性 | 含义 | 默认值 |
|
|
|
| :----------------------: | :------------------------: | :--------------------------------------: |
|
|
|
| weekBarItemWidgetBuilder | 创建顶部的weekbar | 默认样式 |
|
|
|
| dayWidgetBuilder | 创建日历item | 默认样式 |
|
|
|
| verticalSpacing | 日历item之间的竖直方向间距 | 默认10 |
|
|
|
| boxDecoration | 整体的背景设置 | 默认为空 |
|
|
|
| itemSize | 每个item的边长 | 手机默认是屏幕宽度/7，网页默认屏幕高度/7 |
|
|
|
| padding | 日历的padding | 默认为EdgeInsets.zero |
|
|
|
| margin | 日历的padding | 默认为EdgeInsets.zero |
|
|
|
|
|
|
|
|
|
|
|
|
### 配置Controller
|
|
|
两个作用：
|
|
|
一个是显示日历所需要的相关数据，是在controller里面进行配置的。
|
|
|
一个是可以利用controller添加事件监听，使用controller进行操作日历
|
|
|
|
|
|
|
|
|
```
|
|
|
//构造函数
|
|
|
CalendarController(
|
|
|
{int selectMode = CalendarConstants.MODE_SINGLE_SELECT,
|
|
|
int showMode = CalendarConstants.MODE_SHOW_ONLY_MONTH,
|
|
|
int minYear = 1971,
|
|
|
int maxYear = 2055,
|
|
|
int minYearMonth = 1,
|
|
|
int maxYearMonth = 12,
|
|
|
int nowYear,
|
|
|
int nowMonth,
|
|
|
int minSelectYear = 1971,
|
|
|
int minSelectMonth = 1,
|
|
|
int minSelectDay = 1,
|
|
|
int maxSelectYear = 2055,
|
|
|
int maxSelectMonth = 12,
|
|
|
int maxSelectDay = 30,
|
|
|
Set<DateTime> selectedDateTimeList = EMPTY_SET,
|
|
|
DateModel selectDateModel,
|
|
|
int maxMultiSelectCount = 9999,
|
|
|
Map<DateModel, Object> extraDataMap = EMPTY_MAP})
|
|
|
```
|
|
|
|
|
|
#### 通用参数说明
|
|
|
|
|
|
| 属性 | 含义 | 默认值 |
|
|
|
| :-----------------: | :-----------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|
|
|
| selectMode | 选择模式,表示单选或者多选 | 默认是单选<br>static const int MODE_SINGLE_SELECT = 1;<br>static const int MODE_MULTI_SELECT = 2; |
|
|
|
| showMode | 展示模式 | 默认是只展示月视图<br>static const int MODE_SHOW_ONLY_MONTH=1;//仅支持月视图<br>static const int MODE_SHOW_ONLY_WEEK=2;//仅支持星期视图<br>static const int MODE_SHOW_WEEK_AND_MONTH=3;//支持两种视图，先显示周视图<br>static const int MODE_SHOW_MONTH_AND_WEEK=4;//支持两种视图，先显示月视图 |
|
|
|
| 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<DateModel> selectedDateList = new Set() |
|
|
|
| selectDateModel | 当前选择项,用于单选 | 默认为空 |
|
|
|
| maxMultiSelectCount | 多选，最多选多少个 | hhh |
|
|
|
| extraDataMap | 自定义额外的数据 | 默认为空Map，Map<DateTime, Object> extraDataMap = new Map() |
|
|
|
|
|
|
|
|
|
#### 给controller添加事件监听
|
|
|
|
|
|
| 方法 | 含义 | 默认值 |
|
|
|
| :-----------------------------------------------------------------------: | :--------------------: | :----: |
|
|
|
| void addMonthChangeListener(OnMonthChange listener) | 月份切换事件 |
|
|
|
| void addOnCalendarSelectListener(OnCalendarSelect listener) | 点击选择事件 |
|
|
|
| void addOnMultiSelectOutOfRangeListener(OnMultiSelectOutOfRange listener) | 多选超出指定范围 |
|
|
|
| void addOnMultiSelectOutOfSizeListener(OnMultiSelectOutOfSize listener) | 多选超出限制个数 |
|
|
|
| void addExpandChangeListener(ValueChanged<bool> expandChange) | 监听日历的展开收缩状态 |
|
|
|
|
|
|
#### 利用controller来控制日历的切换，支持配置动画
|
|
|
|
|
|
| 方法 | 含义 | 默认值 |
|
|
|
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------: | :----: |
|
|
|
| Future<bool> previousPage() | 滑动到上一个页面，会自动根据当前的展开状态，滑动到上一个月或者上一个星期。如果已经在第一个页面，没有上一个页面，就会返回false，其他情况返回true |
|
|
|
| Future<bool> 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() | 切换展开状态 |
|
|
|
| void changeExtraData(Map<DateModel, Object> newMap) | 修改自定义的额外数据并刷新日历 |
|
|
|
|
|
|
|
|
|
#### 利用controller来获取当前日历的状态和数据
|
|
|
|
|
|
| 方法 | 含义 | 默认值 |
|
|
|
| :-------------------------------------: | :--------------------: | :----: |
|
|
|
| DateTime getCurrentMonth() | 获取当前的月份 |
|
|
|
| Set<DateModel> getMultiSelectCalendar() | 获取被选中的日期,多选 |
|
|
|
| DateModel getSingleSelectCalendar() | 获取被选中的日期，单选 |
|
|
|
|
|
|
|
|
|
|
|
|
### 如何自定义UI
|
|
|
|
|
|
包括自定义WeekBar、自定义日历Item，默认使用的都是DefaultXXXWidget。
|
|
|
|
|
|
只要继承对应的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,
|
|
|
),
|
|
|
);
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
第二种做法，你也可以直接重写build方法，进行更加的自定义绘制。
|
|
|
|
|
|
```
|
|
|
class CustomStyleWeekBarItem extends BaseWeekBar {
|
|
|
List<String> weekList = ["mo", "tu", "we", "th", "fr", "sa", "su"];
|
|
|
|
|
|
//可以直接重写build方法，weekbar底部添加下划线
|
|
|
@override
|
|
|
Widget build(BuildContext context) {
|
|
|
List<Widget> children = List();
|
|
|
|
|
|
var items = getWeekDayWidget();
|
|
|
children.add(Row(
|
|
|
children: items,
|
|
|
));
|
|
|
children.add(Divider(
|
|
|
color: Colors.grey,
|
|
|
));
|
|
|
return Column(
|
|
|
children: children,
|
|
|
);
|
|
|
}
|
|
|
|
|
|
@override
|
|
|
Widget getWeekBarItem(int index) {
|
|
|
return new Container(
|
|
|
margin: EdgeInsets.only(top: 10, bottom: 10),
|
|
|
child: new Center(
|
|
|
child: new Text(
|
|
|
weekList[index],
|
|
|
style:
|
|
|
TextStyle(fontWeight: FontWeight.w700, color: Color(0xffC5BCDC)),
|
|
|
),
|
|
|
),
|
|
|
);
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
|
|
|
#### 自定义日历Item：
|
|
|
提供两种方法，一种是利用组合widget的方式来创建，一种是利用Canvas来自定义绘制Item。最后只需要在CalendarController的构造参数中进行配置就可以了。
|
|
|
* 利用组合widget的方式来创建：继承BaseCombineDayWidget，重写getNormalWidget(DateModel dateModel)
|
|
|
和getSelectedWidget(DateModel dateModel)就可以了，返回对应的widget就行。
|
|
|
```
|
|
|
class DefaultCombineDayWidget extends BaseCombineDayWidget {
|
|
|
DefaultCombineDayWidget(DateModel dateModel) : super(dateModel);
|
|
|
|
|
|
@override
|
|
|
Widget getNormalWidget(DateModel dateModel) {
|
|
|
//实现默认状态下的UI
|
|
|
}
|
|
|
|
|
|
@override
|
|
|
Widget getSelectedWidget(DateModel dateModel) {
|
|
|
//绘制被选中的UI
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
|
|
|
* 利用Canvas来自定义绘制，继承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);
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 根据实际场景，自定义额外的数据extraData
|
|
|
|
|
|
#### 实现进度条样式的日历
|
|
|
|
|
|
我们可以自定义每个item的进度条数据，保存到map中，最后赋值给controller的extraDataMap。
|
|
|
```
|
|
|
//外部处理每个dateModel所对应的进度
|
|
|
Map<DateModel, int> 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;
|
|
|
```
|
|
|
|
|
|
#### 实现自定义各种标记的日历
|
|
|
```
|
|
|
//外部处理每个dateModel所对应的标记
|
|
|
Map<DateModel, String> 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;
|
|
|
```
|
|
|
|
|
|
#### 手动修改自定义的数据
|
|
|
当自定义的数据发生变化的时候，可以使用controller的changeExtraData(Map<DateModel, Object> newMap)方法，
|
|
|
日历会自动刷新，根据新的额外数据进行绘制。
|
|
|
```
|
|
|
//可以动态修改extraDataMap
|
|
|
void changeExtraData(Map<DateModel, Object> newMap) {
|
|
|
this.calendarConfiguration.extraDataMap = newMap;
|
|
|
this.calendarProvider.generation.value++;
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### DateModel实体类
|
|
|
日历所用的日期的实体类DateModel，有下面这些属性。可以在自定义绘制DayWidget的时候，根据相应的属性，进行判断后，绘制相应的UI。
|
|
|
|
|
|
| 属性 | 含义 | 类型 | 默认值 |
|
|
|
| :---------------: | :---------------------------------------------------: | :----: | :------: |
|
|
|
| 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 | 默认为空 |
|
|
|
| isCurrentMonth | 是否是当前月份 | bool |
|
|
|
|
|
|
|
|
|
| 方法 | 含义 |
|
|
|
| :---------------------------------------: | :-------------------------------------------------------: |
|
|
|
| DateTime getDateTime() | 将DateModel转化成DateTime |
|
|
|
| DateModel fromDateTime(DateTime dateTime) | 根据DateTime创建对应的model，并初始化农历和传统节日等信息 |
|
|
|
| bool operator ==(Object other) | 重写==方法，可以判断两个dateModel是否是同一天 | |
