当前位置：首页 > news >正文

Calendar.js 农历公历互转库使用指南

news 2026/5/12 5:07:17

Calendar.js 农历公历互转库使用指南

【免费下载链接】calendar.js中国农历（阴阳历）和西元阳历即公历互转JavaScript库项目地址: https://gitcode.com/gh_mirrors/ca/calendar.js

为什么选择 Calendar.js？

在开发中国传统节日应用、农历生日提醒或农业日程管理系统时，我们常常需要在公历和农历之间进行精确转换。Calendar.js 作为一款轻量级 JavaScript 库，提供了 1900-3000 年间的公历农历互转功能，支持节气计算、生肖属相、干支纪年等传统文化元素，是开发中国特色日期应用的理想选择。

💡核心优势：无需后端支持，纯前端实现高精度历法转换；体积小巧（约 20KB），无外部依赖；API 简洁易用，适合各类 Web 应用集成。

快速上手：从安装到首次转换

准备工作

首先，通过 Git 克隆项目到本地：

git clone https://gitcode.com/gh_mirrors/ca/calendar.js cd calendar.js

项目结构采用模块化设计，核心代码位于src/目录，包含常量定义和转换逻辑：

src/ ├── constant/ # 历法常量定义 │ ├── ChineseEra.js # 天干地支数据 │ ├── Lunar.js # 农历基础数据 │ └── ... └── index.js # 核心转换逻辑

基础转换示例

公历转农历：将 1987 年 11 月 1 日转换为农历日期

import calendar from './src/index.js'; const result = calendar.solar2lunar(1987, 11, 1); console.log(result);

返回结果包含丰富信息：

{ "lYear": 1987, // 农历年份 "lMonth": 9, // 农历月份 "lDay": 10, // 农历日期 "IMonthCn": "九月", // 农历月份中文 "IDayCn": "初十", // 农历日期中文 "Animal": "兔", // 生肖 "gzYear": "丁卯", // 干支年份 // ... 更多属性 }

农历转公历：将 1987 年农历九月初十转换为公历日期

const result = calendar.lunar2solar(1987, 9, 10); console.log(result.cYear, result.cMonth, result.cDay); // 1987 11 1

🔍注意：农历月份参数需注意是否为闰月，若需转换闰月日期，需传入第四个参数true，如lunar2solar(2020, 4, 1, true)表示 2020 年闰四月初一。

功能模块详解

1. 核心转换功能

Calendar.js 提供两个核心方法实现历法互转，构成了整个库的基础功能：

公历转农历：solar2lunar(y, m, d)

功能价值：将现代国际通用历法转换为中国传统农历
操作方法：传入公历年月日（数字类型）
实际应用：传统节日提醒、农历生日计算

// 获取今天的农历信息 const today = new Date(); const lunarToday = calendar.solar2lunar( today.getFullYear(), today.getMonth() + 1, today.getDate() ); console.log(`今天是农历${lunarToday.IMonthCn}${lunarToday.IDayCn}`);

农历转公历：lunar2solar(y, m, d, isLeapMonth)

功能价值：将传统农历日期转换为现代公历日期
操作方法：传入农历年月日，闰月需指定第四个参数为true
实际应用：传统节日假期安排、历史事件日期转换

// 计算2024年农历新年（正月初一）的公历日期 const springFestival = calendar.lunar2solar(2024, 1, 1); console.log(`2024年春节是公历${springFestival.cMonth}月${springFestival.cDay}日`);

2. 传统文化元素支持

除基础转换外，库中还集成了丰富的中国传统文化元素：

生肖属相

通过getAnimal(year)方法获取指定年份的生肖：

console.log(calendar.getAnimal(1990)); // 马

干支纪年

自动在转换结果中包含干支信息：

const result = calendar.solar2lunar(2023, 1, 1); console.log(result.gzYear); // 壬寅 console.log(result.gzMonth); // 壬子月 console.log(result.gzDay); // 辛巳日

二十四节气

转换结果中包含节气信息，可用于农业应用开发：

const result = calendar.solar2lunar(2023, 3, 6); console.log(result.Term); // 惊蛰

3. 节日管理功能

库内置了常用的公历和农历节日数据，并支持自定义扩展：

获取节日信息

转换结果中自动包含节日信息：

const result = calendar.solar2lunar(2023, 1, 1); console.log(result.festival); // 元旦

自定义节日

通过setFestival()和setLunarFestival()方法扩展节日数据：

// 添加自定义公历节日 calendar.setFestival({ ...calendar.getFestival(), // 保留原有节日 "12-25": { title: "圣诞节" } }); // 添加自定义农历节日 calendar.setLunarFestival({ ...calendar.getLunarFestival(), // 保留原有节日 "9-9": { title: "重阳节" } });

高级应用场景

场景一：传统节日提醒系统

构建一个能够提醒中国传统节日的应用，结合 Calendar.js 实现核心功能：

function getUpcomingFestivals(days = 7) { const festivals = []; const today = new Date(); for (let i = 0; i < days; i++) { const date = new Date(today); date.setDate(today.getDate() + i); const lunarInfo = calendar.solar2lunar( date.getFullYear(), date.getMonth() + 1, date.getDate() ); if (lunarInfo.festival || lunarInfo.lunarFestival) { festivals.push({ date: `${date.getMonth() + 1}月${date.getDate()}日`, solarFestival: lunarInfo.festival, lunarFestival: lunarInfo.lunarFestival }); } } return festivals; } // 获取未来7天的节日 console.log(getUpcomingFestivals(7));

场景二：农历生日提醒

实现基于农历的生日提醒功能，不受公历日期变化影响：

function getLunarBirthday提醒(month, day) { const today = new Date(); const currentYear = today.getFullYear(); // 计算今年的农历生日对应的公历日期 const birthdayThisYear = calendar.lunar2solar(currentYear, month, day); // 如果今年生日已过，则计算明年的 if (birthdayThisYear.cMonth < today.getMonth() + 1 || (birthdayThisYear.cMonth === today.getMonth() + 1 && birthdayThisYear.cDay < today.getDate())) { return calendar.lunar2solar(currentYear + 1, month, day); } return birthdayThisYear; } // 提醒农历九月初十的生日 const nextBirthday = getLunarBirthday提醒(9, 10); console.log(`下一个生日是${nextBirthday.cYear}年${nextBirthday.cMonth}月${nextBirthday.cDay}日`);

场景三：节气农时指导

结合二十四节气为农业生产提供指导：

function getCurrentSolarTerm() { const today = new Date(); const solarInfo = calendar.solar2lunar( today.getFullYear(), today.getMonth() + 1, today.getDate() ); if (solarInfo.isTerm) { return `今天是${solarInfo.Term}，${getSolarTermAdvice(solarInfo.Term)}`; } else { // 查找当前节气 const terms = calendar.solarTerm; for (let i = 0; i < 24; i++) { const termDate = calendar.getTerm(today.getFullYear(), i + 1); if (termDate === today.getDate()) { return `今天是${terms[i]}，${getSolarTermAdvice(terms[i])}`; } } return "当前无节气"; } } function getSolarTermAdvice(term) { const adviceMap = { "立春": "春耕开始，注意防寒保暖", "清明": "踏青祭祖，注意森林防火", "立夏": "农作物进入生长旺季", // ... 其他节气建议 }; return adviceMap[term] || "根据当地农时安排生产活动"; } console.log(getCurrentSolarTerm());

常见问题与解决方案

日期范围限制

问题：转换结果返回 -1 或异常值
解决方案：库仅支持 1900 年 1 月 31 日至 3000 年 12 月 31 日之间的日期转换。超出此范围的日期需要额外处理。

function safeSolar2lunar(y, m, d) { if (y < 1900 || y > 3000) { throw new Error("日期超出支持范围（1900-3000）"); } return calendar.solar2lunar(y, m, d); }

闰月处理

问题：农历闰月转换错误
解决方案：转换闰月日期时必须指定第四个参数为true

// 正确：转换2020年闰四月初一 const correct = calendar.lunar2solar(2020, 4, 1, true); // 错误：未指定闰月参数 const wrong = calendar.lunar2solar(2020, 4, 1);

性能优化

问题：大量日期转换时性能下降
解决方案：对于需要批量处理的场景，建议缓存已转换的日期结果

const dateCache = new Map(); function cachedSolar2lunar(y, m, d) { const key = `${y}-${m}-${d}`; if (dateCache.has(key)) { return dateCache.get(key); } const result = calendar.solar2lunar(y, m, d); dateCache.set(key, result); return result; }

项目扩展可能性

Calendar.js 作为基础历法转换库，可通过多种方式扩展其功能：

1. 多语言支持

当前库仅支持中文显示，可扩展为多语言版本：

// 示例：添加英文支持 const i18n = { en: { months: ['January', 'February', ...], days: ['1st', '2nd', ...], animals: ['Rat', 'Ox', ...] }, // 其他语言... }; // 创建多语言版转换方法 function solar2lunarI18n(y, m, d, lang = 'zh') { const result = calendar.solar2lunar(y, m, d); return { ...result, IMonthCn: i18n[lang].months[result.lMonth - 1], IDayCn: i18n[lang].days[result.lDay - 1], Animal: i18n[lang].animals[result.Animal] }; }