更新记录

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

[1.0.0] - 2025-06-07

平台兼容性

uni-app(4.65)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ √ √ √ √ √ √ √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 快应用-华为 快应用-联盟
√ √ √ √ √ √ √ √ √ √ √

uni-app x(4.65)

Chrome Safari Android iOS 鸿蒙 微信小程序
√ √ √ √ √ √

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

版权信息

相关链接

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

无

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

许可协议

MIT License

Copyright (c) 2025 nutpi

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

评论列表 撰写评论 向官方投诉

暂无用户评论。