用 TypeScript、Python 为应用加入农历、节庆和忌日提醒

为应用或网站做农历、忌日和节庆,只需两个包:@nhatnguyet/am-lich 与 @nhatnguyet/le-hoi(Python 包名为 nhatnguyet)。历法按越南时间推算,1900 至 2100 年的朔与 NASA、二十四节气与 IMCCE 对照;节庆来自三种语言的 206 个越南节庆开放数据集。
步骤
- 安装包(TypeScript 或 Python)。
- 公历转农历:
solarToLunar(ngay, thang, nam)。 - 计算忌日:取去世日的农历,再对每一年调用
lunarToSolar(ngayAm, thangAm, nam, false)。 - 列出全年节庆用
leHoiTrongNam(nam),某一天的节庆用leHoiTheoNgay(ngay, thang, nam)。 - 需要中国或韩国农历时,从
MUI_GIO_LICH传入时区。
npm i @nhatnguyet/am-lich @nhatnguyet/le-hoi
pip install nhatnguyetTypeScript 代码与输出
import { solarToLunar, lunarToSolar, yearCanChi, MUI_GIO_LICH } from "@nhatnguyet/am-lich";
import { leHoiTrongNam, leHoiTheoNgay, DANH_SACH_LE_HOI } from "@nhatnguyet/le-hoi";
// 第 2 步:公历日期对应的农历
const am = solarToLunar(19, 11, 2026);
console.log(`2026/11/19 是农历 ${am.month} 月 ${am.day} 日,${yearCanChi(am.year).label} 年`);
// 第 3 步:按去世日的农历算忌日
const mat = solarToLunar(12, 4, 2019);
console.log(`2019/4/12 去世,农历 ${mat.month} 月 ${mat.day} 日`);
for (const nam of [2027, 2028, 2029]) {
const { duong } = lunarToSolar(mat.day, mat.month, nam, false);
console.log(`${nam} 年忌日:${duong.year}/${duong.month}/${duong.day}`);
}
// 第 4 步:全年节庆,按日期排序
const ming = Object.fromEntries(DANH_SACH_LE_HOI.map((l) => [l.id, l.ten_zh]));
const jie = leHoiTrongNam(2027).sort((a, b) => a.ngay.localeCompare(b.ngay));
console.log(`2027 年有 ${jie.length} 个固定日期的节庆,前四个:`);
for (const l of jie.slice(0, 4)) console.log(" ", l.ngay, ming[l.id]);
console.log("2027/2/6:", leHoiTheoNgay(6, 2, 2027).map((l) => l.ten_zh).join("、"));
// 第 5 步:按越南、中国、韩国历法的春节
for (const nuoc of ["vietNam", "trungQuoc", "hanQuoc"]) {
const t = lunarToSolar(1, 1, 1985, false, MUI_GIO_LICH[nuoc]).duong;
console.log(`1985 年春节,${nuoc}:${t.year}/${t.month}/${t.day}`);
}2026/11/19 是农历 10 月 11 日,Bính Ngọ 年
2019/4/12 去世,农历 3 月 8 日
2027 年忌日:2027/4/14
2028 年忌日:2028/4/2
2029 年忌日:2029/4/21
2027 年有 164 个固定日期的节庆,前四个:
2027-01-01 元旦
2027-02-03 越南共产党成立日
2027-02-06 越南春节
2027-02-09 Keo 寺春季庙会
2027/2/6: 越南春节
1985 年春节,vietNam:1985/1/21
1985 年春节,trungQuoc:1985/2/20
1985 年春节,hanQuoc:1985/2/20
2019 年 4 月 12 日去世,即农历三月初八,所以忌日落在 2027/4/14、2028/4/2、2029/4/21。2027 年有 164 个节庆可算出日期;其余由主办方逐年公布,见 lich_cong_bo 列。
用 Python 做同样的事
函数名与 TypeScript 相同,改用 snake_case;结果是键名相同的 dict。
from nhatnguyet import am_lich, le_hoi
am = am_lich.solar_to_lunar(19, 11, 2026)
print(f"2026/11/19 是农历 {am['month']} 月 {am['day']} 日,{am_lich.year_can_chi(am['year'])['label']} 年")
mat = am_lich.solar_to_lunar(12, 4, 2019)
for nam in (2027, 2028, 2029):
duong, _ = am_lich.lunar_to_solar(mat["day"], mat["month"], nam, False)
print(f"{nam} 年忌日:{duong['year']}/{duong['month']}/{duong['day']}")
ming = {l["id"]: l["ten_zh"] for l in le_hoi.danh_sach_le_hoi()}
for l in sorted(le_hoi.le_hoi_trong_nam(2027), key=lambda l: l["ngay"])[:2]:
print(l["ngay"], ming[l["id"]])
for nuoc, mui in am_lich.MUI_GIO_LICH.items():
tet, _ = am_lich.lunar_to_solar(1, 1, 1985, False, mui)
print(f"1985 年春节,{nuoc}:{tet['year']}/{tet['month']}/{tet['day']}")2026/11/19 是农历 10 月 11 日,Bính Ngọ 年
2027 年忌日:2027/4/14
2028 年忌日:2028/4/2
2029 年忌日:2029/4/21
2027-01-01 元旦
2027-02-03 越南共产党成立日
1985 年春节,viet_nam:1985/1/21
1985 年春节,trung_quoc:1985/2/20
1985 年春节,han_quoc:1985/2/20
1985 年春节,nhat_ban:1985/2/20
做一个带农历和节庆的月历
逐日循环,用 solarToLunar 得到格子里的小字农历,用 leHoiTheoNgay 标出有节庆的日子。下图就是这样做出的 2027 年 2 月:越南春节在 2 月 6 日星期六。

导出 .ics 日历
@nhatnguyet/le-hoi 的 festivalsIcs(2027)(Python:nhatnguyet.en 中的 festivals_ics(2027))返回 iCalendar(RFC 5545)文件,每个节庆一个全天事件,已知举办地时附上地点;可直接导入 Google 日历、Apple 日历或 Outlook。命令行:npx @nhatnguyet/cli festivals 2027 --ics > festivals-2027.ics。
需要注意的地方
- 闰月去世者的忌日:按常见习俗,许多人家在同号的正月份做忌日;上面传入
false即按此习俗。 - 小月的三十日:农历月只有 29 天时,
lunarToSolar返回下月初一。想知道该月大小,可用solarToLunar反算比较。 - 农历节庆放在正月份,不放闰月;某年没有该日,节庆就不在当年列表中。
- 中国、韩国农历规则相同,只是地方时不同。1985 年越南春节在 1 月 21 日,中国和韩国在 2 月 20 日。
注明出处
代码采用 MIT 许可。节庆数据集采用 CC BY 4.0:再发布时注明“数据:Nhat Nguyet (nhatnguyet.org)”。代码库见开源页面,数据集见开放数据页。



