CrazyTaro/freeCalendar

a useful calendar which you can custom its styles or drawing-action easily. (完整的日历功能,丰富的属性设置及回调处理;高度可控的UI设计及绘制,可在不修改任何源代码的基础上直接对大量的UI进行调整和修改.)

Download

Step 1. Add the JitPack repository to your build file

Add it in your root settings.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add it in your settings.gradle.kts at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add to pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.CrazyTaro:freeCalendar:0.8.0'
	}

	dependencies {
		implementation("com.github.CrazyTaro:freeCalendar:0.8.0")
	}

	<dependency>
	    <groupId>com.github.CrazyTaro</groupId>
	    <artifactId>freeCalendar</artifactId>
	    <version>0.8.0</version>
	</dependency>


                            
    libraryDependencies += "com.github.CrazyTaro" % "freeCalendar" % "0.8.0"


                            
    :dependencies [[com.github.CrazyTaro/freeCalendar "0.8.0"]]

Readme

[TOC]

1. calendar

a useful calendar which you can custom its styles or actions easily.

2. 概述

日历控件并不是会很常用到,但是在项目中用到的话很多时候是更倾向于UI自定义程度会比较高或者带有自己应用的特点. github上已经存在很多很不错的日历控件.但是绝大多数的特点是该日历特有的并且UI的修改与控制也会很麻烦. 基于这个原因,所以就写了这个日历控件库希望本身功能比较完整的情况下同时也能提供比较方便容易的自定义UI的功能

3. 版本更新内容

4. 功能特点

丰富的xml属性设置可以满足大部分的需要并且能直接在xml中预览出效果
大量的自定义绘制方法可直接控制日历的UI显示
自定义UI绘制采用接口回调的方式不需要继承任何View直接重写相关的方法即可

5. TODO

[ ] 优化绘制的方式和逻辑(长期工作)
[ ] 调整"假期/加班"图标绘制方式
[ ] 分离并独立农历/公历节日计算
[ ] 提供一些日期相关的工具方法或接口

6. 使用方式

6.1. step1:在项目级别的`build.gradle`文件下声明仓库

allprojects {
	repositories {
		...
		maven { url 'https://www.jitpack.io' }
	}
}

6.2. step2:引用需要的版本

6.3. step3:在xml中使用

<com.taro.calendar.lib.CalendarView
        android:id="@+id/cv_calendar"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

6.4. step4:自定义UI控制

6.4.1. 颜色样式配置

大部分的颜色可以在xml中直接设置,也可以在代码中进行设置;所有的颜色配置都在ColorSetting的类中.

view.getColorSetting()
        .setBackgroundColor(ColorSetting.DEFAULT_COLOR_BLUE)
        .setDateBackgroundColor(Color.parseColor("#ff9900"));

也可以new ColorSetting()并配置后再设置给calendarView

6.4.2. 假期/加班图标设置

由于默认UI是不处理并显示任何图标的,假期及加班图标的设置需要重写部分绘制UI.

@Override
public void updateDayCellAfterNewSetting(@NonNull DayCell cell, @NonNull Lunar lunarDate) {
    //农历日期类计算当前日期是需要休假的
    //现在正在调整节日的计算及处理,后面可能就不再是进行类似的判断
    //之后根据调整后的节日计算再判断当前日期是否需要休假,这部分将会考虑被独立出来处理
    if (lunarDate.isHoliday()) {
        //必须对日期对象中相关的特殊日期标识进行设置才有效
        //需要显示底部图标时也需要设置相关的标识
        //MASK_DATE_HOLIDAY,假期标识
        //MASK_DATE_WORK,加班标识
        //MASK_DATE_BOTTOM_DRAWABLE,显示底部图标标识
        cell.setSpecialDate(DayCell.MASK_DATE_HOLIDAY, true);
    }
}

设置了显示假期图标或者加班图标后,还可以设置假期或加班图标的标识;该图标的类型是TipDrawable,通过调用对应的方法即可设置相关样式.包括背景色/文本等;获取默认的假期/加班图标可调用calendarView的方法getWorkTipDrawable/getFestivalDrawable;

view.getFestivalDrawable()
        //设置图标文本
        .setText("啊")
        //设置文本颜色
        .setTextColor(Color.WHITE)
        //设置图标背景色
        .setBackgroundColor(Color.BLACK);

6.4.3. 完全自定义UI

继承BaseCalendarDrawHelper,对需要修改或者控制的UI进行重写即可.

其中BaseCalendarDrawHelper是一个默认实现了所有绘制接口的类,默认的控件CalendarView的绘制操作即使用此类的实例.该类是实现了IDrawCallback的绘制接口.

直接实现IDrawCallback也是一样的,但一次需要实现的接口有点多,推荐还是继承BaseCalendarDrawHelper进行并重写相关方法即可;

public class BaseCalendarDrawHelper implements IDrawCallback {
    //实现对应的方法...
}

在回调的方法中,实际上需要使用的样式已经设置在paint中,如果不需要改动样式直接就可以绘制自己需要的UI

public class BaseCalendarDrawHelper implements IDrawCallback {
    @Override
    public void drawWeekTitleBackground(Canvas canvas, @NonNull RectF drawArea, Paint paint) {
        canvas.drawRect(drawArea, paint);
    }

    @Override
    public void drawSelectedDayBackground(Canvas canvas, @NonNull RectF recommendRectf, @Nullable Drawable drawable, boolean isToday, Paint paint) {
        if (drawable != null) {
            //存在drawable使用背景drawable绘制
            drawable.setBounds((int) recommendRectf.left, (int) recommendRectf.top,
                    (int) recommendRectf.right, (int) recommendRectf.bottom);
            drawable.draw(canvas);
        } else {
            //否则绘制圆形背景
            canvas.drawArc(recommendRectf, 0, 360, false, paint);
        }
    }

    @Override
    public void drawDateText(Canvas canvas, boolean isToday, boolean isSelected, int color, float textSize, float x, float y, @NonNull String date, Paint paint) {
        canvas.drawText(date, x, y, paint);
    }

    //其它绘制方法...
}

以上给出了几个默认绘制方法的实现,可见看到实际上只需要调用canvas默认对应的方法就可以进行绘制了(图形或者是文字等);

当需要自己调整绘制的UI时,则可以使用方法提供的参数自行调整.如上默认提供的推荐区域为正方形,但是可以将UI绘制为圆形.具体视需求而定.

重要提示:BaseCalendarDrawHelper中基本每个方法都实现了相关的绘制逻辑,不需要默认的UI绘制方式则重写时注意不要调用super方法,以上示例为BaseCalendarDrawHelper的实现,具体每个方法的默认实现请查看该类的源码.

更多接口方法及说明请查看以下内容

7. 效果图

默认效果(带农历日期/节日/日期不居中/显示次要月份)

文本居中(仔细看主要的元素都集中在下半部分,可能会感觉有点挤)

无农历日期

不显示次要月份

简洁文本居中(日期显示居中,会显得清楚端正)

自定义周末标题

显示假期/加班图标

滑动效果

丰富的可设置属性

8. 接口及属性参考

8.1. xml属性及意义

8.1.1. 节日(包含农历/公历节日及节气)属性

节日相关的属性值类型都相同,仅列出第一个

8.1.2. 日历(设置或样式)属性

日历相关的属性值类型都相同,仅列出第一个

关于部分属性说明可能有点模糊的下面特别说明一下.

次要月份指非当前月份的上个月份和下个月份
- 如当前月份为5月,则次要月份为4,6月;
- 当前月份为6月时,则次要月份为5,7月；即效果图中灰色部分月份
次要颜色是指用于次要月份的主要文本颜色
次要月份的节日/周末颜色默认跟随次要颜色,对应属性设置为false时则使用设置的节日/周末颜色
- 若设置周末颜色为红色,次要颜色为灰色,当calendarMinorWeekendColor为false时,则次要月份的周末颜色为红色,否则为灰色
优先显示节日属性只有该节日允许显示时才有效
当所有优先显示属性都设置(或者同时设置了多个时),实际的显示顺序永远如下:
- 农历节日->公历节日->节气,当其中某个优先属性没有设置时,则忽略该节日;
- 若设置农历节日优先,但当天不存在农历节日,同时存在公历节日及节气时,则优先显示公历节日;

8.1.3. 颜色相关属性

8.1.4. 其它样式相关属性

部分属性说明如下:

1.节日及加班drawable是针对国内常见的节日及加班调休的机制,可以在日历中显示出当天是否节日或者是否需要加班;该属性不可用是因为该drawable的类型必须是TipDrawable;当需要完全自定义该图标的UI时,可在drawHelper中自行处理

2.滑动触发比率是指在该界面滑动的距离相对于view的宽(横向)高(垂直)长度的比率,当超过该比率时,则触发月份的切换,否则松开将回来当前月份(即界面不变);

该属性在界面大小变动比较大时会比较实用,默认为0.3f;当日历填充屏幕时,由于屏幕高度比较高,0.3f的高度比率可能用户手指滑动不太方便,可以调整该比率小一点更适合滑动;

8.2. 行为操作回调接口方法

在对日历进行一些操作时,会有相应的方法进行回调处理;

|方法名称|返回值|说明| |--|--|--| |onSelectedDayChanged|-|当选中日期改变时该方法会回调(不管只有日期还是全部)| |onResetToToday|-|当日期被重置为今天时回调|

8.3. 绘制接口方法及功能

UI的绘制是通过IDrawCallback接口进行回调的.即使是默认可直接使用的CalendarView也是通过默认的BaseCalendarDrawHelper进行绘制UI;

当然在样式不需要改变很多的情况下,绝大部分的逻辑与判断已经处理好了并且仅仅只需要调用canvas对应的绘制方法进行绘制即可.

绘制接口有点多,做好心理准备哦

8.3.1. 接口方法及参数说明

8.3.2. 部分重点方法说明

有部分方法在BaseCalendarDrawHelper中并没有实现具体代码,但是实际上是有很重要的预备作用的.下面重点说一下这几个方法.具体可直接查看源码.

createDayCell-创建日期对象方法

创建日期对象,日期对象必定是DayCell类型,但是这里是允许自定义创建对象的.所以当实际需要处理的日期对象数据包含了其它自定义的数据类型时,可以继承自DayCell进行返回;日期对象数据是会缓存起来复用的,请尽量不要在子类中引用Activity等临时性比较强的对象,防止内在泄漏

updateDayCellAfterNewSetting-更新了dayCell数据后的回调

由于DayCell会被复用,所以当切换月份或者其它任何被复用的情况下,dayCell都会被重新赋值,赋值后此方法会回调;可在此方法中进行一些判断或者逻辑处理,或者给自定义的dayCell添加一些相关的属性或者设置

beforeCellDraw-绘制某个日期之前的回调

此回调首先提供了大量绘制该cell时使用的参数(在绘制过程都是不变的,除非手动去修改设置);如绘制的区域,颜色配置,日期字体大小;之后在其它绘制回调中不再提供这些不变的配置参数,所以如果需要时可以在此处缓存下来.此处所有参数仅在此次日期绘制时不变,绘制新的日期时参数可能会变动;

其中参数drawArea需要特别说明一下,这里是指该日期所占的绘制区域,是个矩形,是个矩形,是个矩形!,并且每个日期的绘制区域是相连在一起的(本质日历就是一个表格类型),当需要把绘制UI成特别形状时必须在此绘制区域内并且需要自行调整.

最后,在此方法中可以进行一些最初的绘制操作.但该部分的所有绘制结果都会被后续绘制重叠的内容覆盖.(即绘制在最底层)

afterCellDraw-绘制某个日期之后的回调

此回调与beforeCellDraw非常相似,但是仅有一个目的,做绘制后工作的处理或者是自行调整UI绘制,此部分的绘制操作会覆盖原有的所有绘制内容.

接口及参数详情说明

9. 其它

农历日期计算的源码来自网络,如果有任何不当的地方,侵删.

10. github地址

https://github.com/CrazyTaro/freeCalendar

喜欢或者有用的话欢迎给个star~谢谢支持~