农历日期 - ChineseDate

介绍

ChineseDate 类用于表示农历日期，提供了获取农历月、农历日、天干地支、生肖、传统节日等方法。它可以通过公历日期或直接使用农历日期来构建 ChineseDate 对象，方便处理与农历相关的各种需求。

1. 构建 ChineseDate 对象

ChineseDate 对象的构建可以通过两种方式：使用农历日期构建或使用公历日期构建。

1.1 使用农历日期构建

// 通过农历日期构建 ChineseDate 对象
// 参数：年份（1992），月份（12 表示农历腊月），日期（14 表示农历十四日）
ChineseDate chineseDate = new ChineseDate(1992, 12, 14);

• ChineseDate(int lunarYear, int lunarMonth, int lunarDay)：通过农历年份、农历月份和农历日期构建 ChineseDate 对象。

1.2 使用公历日期构建

// 通过公历日期构建 ChineseDate 对象
// 参数：公历日期（例如 "1993-01-06"）
ChineseDate chineseDate = new ChineseDate(DateUtil.parseDate("1993-01-06"));

• ChineseDate(Date date)：通过公历 Date 对象构建 ChineseDate 对象。

实际开发中： 这两种构建方式可以根据实际需求选择合适的方式。通常在处理用户输入的农历日期或需要显示农历日期时，会用到这些构建方法。

2. 基本使用

构建 ChineseDate 对象后，可以使用其提供的多种方法获取农历日期的详细信息，如农历月、农历日、天干地支、生肖等。

// 创建 ChineseDate 对象，使用公历日期构建
ChineseDate date = new ChineseDate(DateUtil.parseDate("2020-01-25"));

// 获取农历月（数字表示，从1开始，1表示正月）
int chineseMonth = date.getChineseMonth(); 
// 输出：1

// 获取农历月名称（字符串表示，如正月、二月）
String chineseMonthName = date.getChineseMonthName(); 
// 输出：正月

// 获取农历日（如初一、初二）
String chineseDay = date.getChineseDay(); 
// 输出：初一

// 获取天干地支（如庚子）
String cyclical = date.getCyclical(); 
// 输出：庚子

// 获取生肖（如鼠、牛）
String chineseZodiac = date.getChineseZodiac(); 
// 输出：鼠

// 获取传统节日（部分支持，多个节日以逗号分隔）
String festivals = date.getFestivals(); 
// 输出：春节

// 获取完整的农历日期描述（如庚子鼠年 正月初一）
String fullDate = date.toString(); 
// 输出：庚子鼠年 正月初一

• getChineseMonth()：返回农历月，数字表示，从1开始（1表示正月）。
• getChineseMonthName()：返回农历月名称，字符串表示，如正月、二月等。
• getChineseDay()：返回农历日，字符串表示，如初一、初二等。
• getCyclical()：返回当前年份的天干地支，如庚子、甲申等。
• getChineseZodiac()：返回生肖名称，如鼠、牛等。
• getFestivals()：返回传统节日名称，部分节日支持，多个节日以逗号分隔。
• toString()：返回完整的农历日期描述，包括年份的天干地支、生肖、月份和日期。

实际开发中： 获取这些农历信息通常用于节日提醒、农历生日管理、传统节日祝福等功能模块。

3. 获取天干地支

从 Hutool 5.4.1 版本开始，ChineseDate 支持获取更详细的天干地支信息，包括年、月、日的天干地支。

// 创建 ChineseDate 对象，使用公历日期构建
ChineseDate chineseDate = new ChineseDate(DateUtil.parseDate("2020-08-28"));

// 获取年、月、日的天干地支组合，结果：庚子年甲申月癸卯日
String cyclicalYMD = chineseDate.getCyclicalYMD(); 
// 输出：庚子年甲申月癸卯日

• getCyclicalYMD()：返回年、月、日的天干地支组合，如庚子年甲申月癸卯日。

实际开发中： 天干地支的计算可以用于传统文化相关应用，如择吉日、运势分析等。

---

总结

Hutool 的 ChineseDate 类在农历日期的操作上非常方便，尤其适用于需要处理中国传统历法相关的业务场景。无论是获取农历信息、节日查询，还是天干地支的运算，ChineseDate 都提供了简洁易用的 API，大大简化了开发工作。