首页
/ Lunar JavaScript 农历工具库使用指南

Lunar JavaScript 农历工具库使用指南

2026-02-06 04:07:45作者：郜逊炳
lunar-javascript
日历、公历(阳历)、农历(阴历、老黄历)、佛历、道历，支持节假日、星座、儒略日、干支、生肖、节气、节日、彭祖百忌、每日宜忌、吉神宜趋凶煞宜忌、吉神(喜神/福神/财神/阳贵神/阴贵神)方位、胎神方位、冲煞、纳音、星宿、八字、五行、十神、建除十二值星、青龙名堂等十二神、黄道黑道日及吉凶等。lunar is a calendar library for Solar and Chinese Lunar.
项目地址：https://gitcode.com/gh_mirrors/lu/lunar-javascript

Lunar JavaScript 是一款轻量级的农历工具库，提供公历与农历互转、节气查询、传统节日计算等功能，无第三方依赖，易于集成到各类 JavaScript 项目中。本文将详细介绍项目结构、核心功能及使用方法，帮助开发者快速上手。

一、项目结构解析

核心文件说明

项目采用简洁的文件组织方式，主要包含以下关键部分：

  • package.json：项目元数据配置文件，定义了项目名称、版本、依赖及脚本命令，通过 npm install 即可完成环境搭建。

  • index.js：库的主入口文件，整合了所有核心功能模块并对外暴露 API，开发者可通过 require('lunar-javascript') 直接调用。

  • lunar.js：核心算法实现文件，包含农历转换、节气计算、干支五行等底层逻辑，是整个工具库的功能核心。

  • 测试目录（__tests__）：存放 Jest 测试脚本，覆盖了 Solar（公历）、Lunar（农历）、JieQi（节气）等 20+ 功能模块的单元测试，确保代码稳定性。

目录结构概览

lunar-javascript/
├── __tests__/           # 单元测试脚本
├── index.js             # 主入口文件
├── lunar.js             # 核心算法实现
├── package.json         # 项目配置
├── README.md            # 项目说明文档
└── demo.html            # 浏览器端演示页面

二、快速上手指南

环境准备

  1. 克隆项目
    从代码仓库获取项目源码：

    git clone https://gitcode.com/gh_mirrors/lu/lunar-javascript
cd lunar-javascript

  2. 安装依赖
    项目依赖通过 npm 管理，执行以下命令完成安装：

    npm install

基础使用示例

1. Node.js 环境

创建测试文件 test.js，引入工具库并调用核心方法：

const { Solar } = require('./index.js');

// 创建公历日期对象（1986年5月29日）
const solar = Solar.fromYmd(1986, 5, 29);

// 输出公历完整信息
console.log(solar.toFullString()); 
// 输出：1986-05-29 00:00:00 星期四 双子座

// 转换为农历并输出详细信息
console.log(solar.getLunar().toFullString());
// 输出：一九八六年四月廿一 丙寅(虎)年 癸巳(蛇)月 癸酉(鸡)日 ...

执行测试脚本：

node test.js

2. 浏览器环境

直接在 HTML 中引入 lunar.js，通过浏览器控制台查看结果：

<!DOCTYPE html>
<html>
  <body>
    <script src="lunar.js"></script>
    <script>
      const solar = Lunar.Solar.fromYmd(2023, 10, 1);
      console.log('农历日期：', solar.getLunar().getMonth() + '月' + solar.getLunar().getDay() + '日');
    </script>
  </body>
</html>

将上述代码保存为 demo.html，用浏览器打开即可在控制台看到转换结果。

三、核心功能详解

1. 公历与农历互转

  • 公历转农历
    通过 Solar 类创建公历日期，调用 getLunar() 方法获取农历对象：

    const { Solar } = require('./index.js');
const solar = Solar.fromYmd(2023, 10, 1);
const lunar = solar.getLunar();
console.log(lunar.toFullString()); 
// 输出：二零二三年八月十七 癸卯(兔)年 辛酉(鸡)月 癸巳(蛇)日 ...

  • 农历转公历
    使用 Lunar 类直接构建农历日期，再转换为公历：

    const { Lunar } = require('./index.js');
const lunar = Lunar.fromYmd(2023, 8, 17);
const solar = lunar.getSolar();
console.log(solar.toFullString()); 
// 输出：2023-09-30 00:00:00 星期六 天秤座

2. 节气与传统节日查询

  • 节气查询
    通过公历日期获取当日节气：

    const solar = Solar.fromYmd(2023, 6, 21);
console.log(solar.getJieQi()); // 输出：夏至

  • 节日查询
    支持传统农历节日和公历节日查询：

    const lunar = Lunar.fromYmd(2023, 1, 1);
console.log(lunar.getFestivals()); // 输出：春节

四、测试与调试

运行单元测试

项目使用 Jest 框架编写测试用例，执行以下命令运行全部测试：

npm test

测试结果将显示各模块的通过率，确保核心功能正常工作。

浏览器端演示

项目提供 demo.html 演示页面，可直接在浏览器中打开查看交互效果。页面包含日期转换、节气查询等功能的可视化展示，便于快速验证库的使用效果。

五、常见问题

1. 时区问题处理

工具库默认使用本地时区计算日期，若需指定时区，可通过 Solar.fromYmdHms() 方法的 timeZone 参数设置，例如：

const solar = Solar.fromYmdHms(2023, 1, 1, 0, 0, 0, 8); // 指定东八区

2. 兼容性说明

  • 支持 Node.js v10+ 及现代浏览器（Chrome、Firefox、Edge 等）。
  • 如需在 IE 等旧浏览器中使用，需自行添加 ES6+ 语法转换（如 Babel）。

六、API 文档

完整的 API 文档请参考项目内置的说明文件，或通过以下方式获取更多信息：

通过本文的介绍，相信你已对 Lunar JavaScript 工具库有了基本了解。无论是构建日历应用、传统命理工具，还是需要处理农历相关业务，这款轻量级库都能提供可靠的支持。如需进一步扩展功能，可参考源码中的算法实现，或提交 Issue 参与项目贡献。

lunar-javascript
日历、公历(阳历)、农历(阴历、老黄历)、佛历、道历，支持节假日、星座、儒略日、干支、生肖、节气、节日、彭祖百忌、每日宜忌、吉神宜趋凶煞宜忌、吉神(喜神/福神/财神/阳贵神/阴贵神)方位、胎神方位、冲煞、纳音、星宿、八字、五行、十神、建除十二值星、青龙名堂等十二神、黄道黑道日及吉凶等。lunar is a calendar library for Solar and Chinese Lunar.
项目地址：https://gitcode.com/gh_mirrors/lu/lunar-javascript
登录后查看全文

相关内容推荐

1 解锁传统文化工具：零基础掌握Lunar JavaScript农历算法2 3分钟掌握Lunar JavaScript：超强农历工具库使用秘籍3 探索农历计算的奥秘：Lunar JavaScript实战指南4 零基础掌握 Lunar JavaScript：农历与传统文化计算实用指南5 7个步骤掌握lunar-javascript：从农历转换到传统文化API应用6 JavaScript农历工具库零基础入门实战指南7 Lunar JavaScript 终极完全指南：掌握农历转换与传统文化计算8 掌握Lunar JavaScript农历工具库：从入门到精通的完全指南9 终极指南：如何用lunar打造专业级农历日历应用10 如何用Lunar JavaScript轻松搞定农历公历转换？完整实用指南 🚀
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

AcFunDown视频下载工具完全指南还在为数字笔记抓狂？这款开源神器让手写批注效率提升300%Windows笔记本电池健康管理全指南：从根源解决电池损耗问题gmx_MMPBSA分子间相互作用索引错误的深度诊断与解决Axure RP 11 本地化方案：Mac中文界面优化与原型设计工具汉化全指南如何高效获取教育资源？这款工具让教材下载效率提升80%视频元数据深度编辑：专业技巧与案例网盘直链下载技术解析与应用指南如何用DeepSeek-R1推理模型提升复杂任务解决能力：完整指南5个突破瓶颈技巧：硬件优化工具让你的电脑性能提升30%

项目优选

收起
docsdocs
暂无描述
Markdown
827
5.48 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
494
515
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
783
1.57 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
800
1.14 K
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
970
2.28 K
kernelkernel
deepin linux kernel
C
32
16
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
480
312
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.01 K
766
cannbot-skillscannbot-skills
CANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。
Markdown
1.26 K
808
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
647
284