更新记录

1.0.0（2025-06-07） 下载此版本

[1.0.0] - 2025-06-07

平台兼容性

uni-app(4.65)

uni-app x(4.65)

nutpi-calendar

nutpi-calendar 是一个功能强大的 UTS 插件，用于处理公历和农历之间的转换，获取节日信息、节气、生肖、干支纪年等中国传统日历相关功能。它旨在为 uni-app 开发者提供一个简单易用且高效的日历解决方案，尤其适用于需要深度集成中国农历功能的应用。

特性

• 公历转农历：轻松将公历日期转换为详细的农历信息，包括农历年份、月份、日期、是否闰月、生肖、天干地支等。
• 农历转公历：支持将农历日期反向转换为公历日期。
• 节日信息：内置公历节日和农历传统节日数据，方便获取指定日期的节日名称。
• 节气计算：准确计算二十四节气。
• 自定义节日：支持添加或修改节日信息。
• 高性能：基于 UTS 实现，保证在 App 端的原生性能。

API 文档

插件导出一个名为 calendar 的对象，包含以下主要方法：

• solar2lunar(year: number, month: number, day: number): LunarDateInfo

  • 描述：将公历日期转换为农历日期信息。
  • 参数：
  • year: 公历年份 (例如: 2024)
  • month: 公历月份 (1-12)
  • day: 公历日期 (1-31)
  • 返回值 LunarDateInfo 对象，包含：
  • lunarYear: number - 农历年份
  • lunarMonth: number - 农历月份
  • lunarDay: number - 农历日期
  • isLeap: boolean - 是否闰月
  • lunarYearChn: string - 农历年份中文 (例如: "甲辰")
  • lunarMonthChn: string - 农历月份中文 (例如: "正月")
  • lunarDayChn: string - 农历日期中文 (例如: "初一")
  • animal: string - 生肖 (例如: "龙")
  • astro: string - 星座
  • gzYear: string - 干支年 (例如: "甲辰")
  • gzMonth: string - 干支月
  • gzDay: string - 干支日
  • solarTerm: string - 当日节气，若无则为空字符串
  • festival: string - 公历节日，若无则为空字符串
  • lunarFestival: string - 农历节日，若无则为空字符串

• lunar2solar(lunarYear: number, lunarMonth: number, lunarDay: number, isLeapMonth: boolean = false): SolarDateInfo

  • 描述：将农历日期转换为公历日期信息。
  • 参数：
  • lunarYear: 农历年份
  • lunarMonth: 农历月份
  • lunarDay: 农历日期
  • isLeapMonth: boolean (可选, 默认为 false) - 是否为闰月
  • 返回值 SolarDateInfo 对象，包含：
  • year: number - 公历年份
  • month: number - 公历月份
  • day: number - 公历日期
  • weekday: number - 星期几 (0 为周日，1 为周一，以此类推)
  • weekdayChn: string - 星期几中文

• getFestival(year: number, month: number, day: number): string

  • 描述：获取指定公历日期的公历节日名称。
  • 参数：同 solar2lunar
  • 返回值：节日名称字符串，若无则为空字符串。

• getLunarFestival(lunarYear: number, lunarMonth: number, lunarDay: number): string

  • 描述：获取指定农历日期的农历节日名称。
  • 参数：同 lunar2solar (无需 isLeapMonth)
  • 返回值：节日名称字符串，若无则为空字符串。

• setFestival(month: number, day: number, festivalName: string): void

  • 描述：设置或覆盖公历节日。
  • 参数：
  • month: 公历月份
  • day: 公历日期
  • festivalName: 节日名称。如果传入空字符串，则表示删除该节日。

• setLunarFestival(lunarMonth: number, lunarDay: number, festivalName: string): void

  • 描述：设置或覆盖农历节日。
  • 参数：
  • lunarMonth: 农历月份
  • lunarDay: 农历日期
  • festivalName: 节日名称。如果传入空字符串，则表示删除该节日。

• getTerm(year: number, month: number, day: number): string

  • 描述：获取指定公历日期的节气名称 (此方法实际通过 solar2lunar 的返回值的 solarTerm 属性获取)。

• toGanZhiYear(year: number): string

  • 描述：获取指定公历年份的干支纪年。

• getAnimal(year: number): string

  • 描述：获取指定公历年份的生肖。

使用案例

以下是如何在您的 uni-app x 项目中使用 nutpi-calendar 插件：

1. 引入插件

   在您的 .uvue 或 .uts 文件中引入插件：

   import calendar from "@/uni_modules/nutpi-calendar/utssdk/index.uts";

2. 调用 API

   // 在页面的 script 部分
   export default {
     onLoad() {
       // 公历转农历
       const today = new Date();
       const lunarDate = calendar.solar2lunar(
         today.getFullYear(),
         today.getMonth() + 1,
         today.getDate()
       );
       console.log(
         `今天是农历：${lunarDate.lunarYearChn}年 ${lunarDate.lunarMonthChn}${lunarDate.lunarDayChn}`
       );
       console.log(`生肖：${lunarDate.animal}`);
       if (lunarDate.solarTerm) {
         console.log(`节气：${lunarDate.solarTerm}`);
       }
       if (lunarDate.festival) {
         console.log(`公历节日：${lunarDate.festival}`);
       }
       if (lunarDate.lunarFestival) {
         console.log(`农历节日：${lunarDate.lunarFestival}`);
       }
   
       // 农历转公历 (例如：查询2024年正月初一的公历日期)
       const solarDate = calendar.lunar2solar(2024, 1, 1);
       console.log(
         `2024年正月初一的公历日期是：${solarDate.year}-${solarDate.month}-${solarDate.day}`
       );
   
       // 获取指定日期的节日
       const christmas = calendar.getFestival(today.getFullYear(), 12, 25);
       console.log(`12月25日是：${christmas}`);
   
       const springFestival = calendar.getLunarFestival(2025, 1, 1); // 查询2025年春节
       console.log(`2025年农历正月初一是：${springFestival}`);
   
       // 设置自定义节日
       calendar.setFestival(10, 24, "程序员节");
       const programmersDay = calendar.getFestival(
         today.getFullYear(),
         10,
         24
       );
       console.log(`10月24日是：${programmersDay}`);
     },
   };

版权信息

• 作者：坚果派 0
• 公众号：nutpi
• 电话：
• 官网：https://www.nutpi.net/ 0

相关链接

• UTS 语法
• UTS API 插件
• Hello UTS