046b254a创建于 2025年10月21日历史提交

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 插件：

引入插件

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

import calendar from "@/uni_modules/nutpi-calendar";

调用 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}`);
  },
};

版权信息

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

坚果派uni-app X插件

nutpi-idcard：用于解析身份证号码，提取其中的关键信息，如地区、出生日期、性别等。支持中国居民身份证、港澳台居民居住证以及外国人永久居留身份证的插件。插件地址：https://ext.dcloud.net.cn/plugin?id=23728，仓库地址：https://gitcode.com/nutpi/uni-idcard。
nutpi-chinese-number-format：一个功能强大的中文数字格式化 UTS 插件，支持数字与中文之间的双向转换，适用于 uni-app 和 uni-app x 项目。插件地址：https://ext.dcloud.net.cn/plugin?id=23776，仓库地址：https://gitcode.com/nutpi/uni-chinese-number-format/。
nutpi-utils：支持鸿蒙的拨打电话，发短信、退出应用、电量获取等功能。插件地址：https://ext.dcloud.net.cn/plugin?id=22525，仓库地址：https://gitcode.com/nutpi/uni-utils。
calendar中国传统日历：nutpi-calendar 是一个功能强大的 UTS 插件，用于处理公历和农历之间的转换，获取节日信息、节气、生肖、干支纪年等中国传统日历相关功能。插件地址：https://ext.dcloud.net.cn/plugin?id=23786，仓库地址：https://gitcode.com/nutpi/uni-calendar。

nutpi-calendar中国传统日历相关功能插件（适配鸿蒙）

特性

API 文档

使用案例

版权信息

相关链接

坚果派uni-app X插件