Lunar JavaScript 农历工具库使用指南

2026-02-06 04:07:45作者：郜逊炳

lunar-javascript

项目地址：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            # 浏览器端演示页面

二、快速上手指南

环境准备

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

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

安装依赖
项目依赖通过 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 文档请参考项目内置的说明文件，或通过以下方式获取更多信息：

官方文档：API 参考
源码示例：测试用例

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

lunar-javascript

项目地址：https://gitcode.com/gh_mirrors/lu/lunar-javascript

登录后查看全文

Lunar JavaScript 农历工具库使用指南

一、项目结构解析

核心文件说明

目录结构概览

二、快速上手指南

环境准备

基础使用示例

1. Node.js 环境

2. 浏览器环境

三、核心功能详解

1. 公历与农历互转

2. 节气与传统节日查询

四、测试与调试

运行单元测试

浏览器端演示

五、常见问题

1. 时区问题处理

2. 兼容性说明

六、API 文档

热门内容推荐

最新内容推荐

项目优选

Lunar JavaScript 农历工具库使用指南

一、项目结构解析

核心文件说明

目录结构概览

二、快速上手指南

环境准备

基础使用示例

1. Node.js 环境

2. 浏览器环境

三、核心功能详解

1. 公历与农历互转

2. 节气与传统节日查询

四、测试与调试

运行单元测试

浏览器端演示

五、常见问题

1. 时区问题处理

2. 兼容性说明

六、API 文档

相关内容推荐

热门内容推荐

最新内容推荐

项目优选