Dayjs Plugin Lunar

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

安装

npm install dayjs dayjs-plugin-lunar

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

npm install tyme4ts

快速开始

基础使用

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

自定义配置

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

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

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

更多用法参看测试用例

API 参考

format

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

扩展的 format 模版

示例

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

add / subtract

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

示例

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

LunarUnit

农历单位类型

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

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

lunar

使用农历时间创建 Dayjs 对象

参数

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

示例

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

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

Returns Dayjs

toLunarHour

转换为农历的时辰

示例

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

Returns LunarHour tyme4ts 中的 LunarHour 类

toLunarDay

转换为农历的日期

示例

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

Returns LunarDay tyme4ts 中的 LunarDay 类

toLunarMonth

转换为农历的月份

示例

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

Returns LunarMonth tyme4ts 中的 LunarMonth 类

toLunarSeason

转换为农历的季节

示例

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

Returns LunarSeason tyme4ts 中的 LunarSeason 类

toLunarYear

转换为农历的年份

示例

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

Returns LunarYear tyme4ts 中的 LunarYear 类

addLunar

添加农历时间

参数

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

示例

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

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

Returns Dayjs

subtractLunar

减去农历时间，与 addLunar 相反

参数

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

示例

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

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

Returns Dayjs

License

MIT