Dayjs Plugin Lunar

!NPM License

dayjs-plugin-lunar 是一个基于 Day.js 的扩展插件，用于方便地处理和转换农历时间。它依赖 tyme4ts 作为底层时间计算库。

安装

``bash
npm install dayjs dayjs-plugin-lunar
`

如果你的 npm 版本低于 7，则需要额外安装 tyme4ts：

`bash
npm install tyme4ts
`

快速开始

$3

`ts
import dayjs from "dayjs";
import { PluginLunar } from "dayjs-plugin-lunar";

// 注册插件
dayjs.extend(PluginLunar);

dayjs("2024-12-19 12:00:00").format("LMLDLhLK"); // 冬月十九午正初刻

// 转换为农历时辰
dayjs("2024-12-19 12:00:00").toLunarHour().getName(); // 午时

// 转换为农历日期
dayjs("2024-12-19 12:00:00").toLunarDay().getName(); // 十九

// 转换为农历月份
dayjs("2024-12-19 12:00:00").toLunarMonth().getName(); // 冬月

// 通过农历构造日期
dayjs.lunar(2025, 1, 1).format("YYYY-MM-DD"); // 2025-01-29
`

$3

tyme4ts 将农历的 冬月 和 腊月 表述为 十一月 和 十二月，dayjs-plugin-lunar 希望更遵循传统命名，对此进行了修改。若需显示 tyme4ts 的原始表述，可将 traditional 设置为 false。

`ts
dayjs.extend(PluginLunar, { traditional: false });

// 转换为农历月份（使用 tyme4ts 原始表述）
dayjs.lunar(2024, 11, 1).toLunarMonth().getName(); // 十一月
`

更多用法参看测试用例

API 参考

$3

基于 dayjs 原始 format 方法拓展，新增农历格式化模板

#### 扩展的 format 模版

| 模板 | 输出 | 详情 |
| ---- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| LY | 甲子 乙丑 ... 癸亥 | 干支纪年 |
| LZ | 鼠 牛 ... 猪 | 生肖 |
| LM | 正月 二月 ... 腊月 | 农历月份 |
| LD | 初一 初二 ... 三十 | 农历日期 |
| LH | 子时 丑时 ... 亥时 | 农历时辰 |
| Lh | 子 丑 ... 亥 | 农历时辰（简写） |
| LK | 初初刻 初一刻 ... 正三刻 | 农历刻数（采用九十六刻制#%E4%B9%9D%E5%8D%81%E5%85%AD%E5%88%BB%E5%88%B6>)） |

#### 示例

`javascript
dayjs("2024-12-19 12:00:00").format("LYLZ年LMLDLhLK"); // 甲辰龙年冬月十九午正初刻
`

$3

基于 dayjs 原始 add / subtract 方法拓展，新增农历单位加减

| 单位 | 详情 |
| --------------- | -------- |
| lunar-year | 农历年 |
| lunar-month | 农历月 |
| lunar-day | 农历日 |
| lunar-dual-hour | 农历时辰 |

#### 示例

`javascript
dayjs("2024-12-20 12:20:00")
.add(1, "lunar-dual-hour")
.format("YYYY-MM-DD HH:mm:ss"); // 2024-12-20 14:20:00
`

$3

农历单位类型

* 'dual-hour': 时辰（2小时）
* 'day': 日
* 'month': 月
* 'year': 年

Type: ("dual-hour" | "day" | "month" | "year")

$3

使用农历时间创建 Dayjs 对象

#### 参数

* lunarYear [number][1] 该农历年大部分日期所在的公历年，支持 -1 至 9999 年
* lunarMonth [number][1]? 农历月，1 到 12，闰月为负数（如：-4 表示闰四月）
* lunarDay [number][1]? 农历日，1 到 30
* lunarHour [number][1]? 时，0 到 23
* lunarMinute [number][1]? 分，0 到 59
* lunarSecond [number][1]? 秒，0 到 59

#### 示例

`javascript
dayjs.lunar(2025, 1, 1).format('YYYY-MM-DD') // 2025-01-29
`

`javascript
dayjs.lunar(2023, -4, 15) // 创建农历2023年闰四月十五的日期
`

Returns Dayjs

$3

转换为农历的时辰

#### 示例

`javascript
dayjs('2024-12-19 12:00:00').toLunarHour().getName(); // 午时
`

Returns LunarHour tyme4ts 中的 LunarHour 类

$3

转换为农历的日期

#### 示例

`javascript
dayjs('2025-01-29').toLunarDay().getName(); // 初一
`

Returns LunarDay tyme4ts 中的 LunarDay 类

$3

转换为农历的月份

#### 示例

`javascript
dayjs('2025-01-29').toLunarMonth().getName(); // 正月
`

Returns LunarMonth tyme4ts 中的 LunarMonth 类

$3

转换为农历的季节

#### 示例

`javascript
dayjs('2025-01-29').toLunarSeason().getName(); // 孟春
`

Returns LunarSeason tyme4ts 中的 LunarSeason 类

$3

转换为农历的年份

#### 示例

`javascript
dayjs('2025-01-01').toLunarYear().getYear(); // 2024
`

Returns LunarYear tyme4ts 中的 LunarYear 类

$3

添加农历时间

#### 参数

* value [number][1] 要添加的数量，可为负数
* unit [LunarUnit][2] 单位，支持 'dual-hour'(时辰)、'day'(日)、'month'(月)、'year'(年)

#### 示例

`javascript
dayjs('2024-12-20 12:00:00').addLunar(1, 'dual-hour').toLunarHour().getName(); // 未时
`

`javascript
dayjs('2025-01-29').addLunar(1, 'month').format('YYYY-MM-DD'); // 2025-02-28
`

Returns Dayjs

$3

减去农历时间，与 addLunar 相反

#### 参数

* value [number][1] 要减去的数量，可为负数
* unit [LunarUnit][2] 单位，支持 'dual-hour'(时辰)、'day'(日)、'month'(月)、'year'(年)

#### 示例

`javascript
dayjs('2024-12-20 12:00:00').subtractLunar(1, 'dual-hour').toLunarHour().getName(); // 巳时
`

`javascript
dayjs('2025-01-29').subtractLunar(1, 'month').format('YYYY-MM-DD'); // 2024-12-31
``

Returns Dayjs

[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

[2]: #lunarunit

License

MIT