Làm lịch âm, lễ hội và nhắc giỗ cho ứng dụng bằng TypeScript, Python

Lịch âm, ngày giỗ và lễ hội cho app hay website chỉ cần hai gói: @nhatnguyet/am-lich và @nhatnguyet/le-hoi (bản Python là nhatnguyet). Lịch tính theo giờ Việt Nam, đối chiếu điểm sóc với NASA và 24 tiết khí với IMCCE từ 1900 tới 2100; lễ hội lấy từ bộ dữ liệu mở 206 lễ, ba thứ tiếng.
Các bước
- Cài gói (TypeScript hoặc Python).
- Đổi ngày dương sang âm:
solarToLunar(ngay, thang, nam). - Tính ngày giỗ: lấy ngày âm của ngày mất, rồi
lunarToSolar(ngayAm, thangAm, nam, false)cho từng năm. - Liệt kê lễ trong năm:
leHoiTrongNam(nam); lễ rơi vào một ngày:leHoiTheoNgay(ngay, thang, nam). - Cần lịch Trung Quốc, Hàn Quốc thì truyền múi giờ ở
MUI_GIO_LICH.
npm i @nhatnguyet/am-lich @nhatnguyet/le-hoi
pip install nhatnguyetMã TypeScript và kết quả
import { solarToLunar, lunarToSolar, yearCanChi, MUI_GIO_LICH } from "@nhatnguyet/am-lich";
import { leHoiTrongNam, leHoiTheoNgay, DANH_SACH_LE_HOI } from "@nhatnguyet/le-hoi";
// Bước 2: ngày âm của một ngày dương
const am = solarToLunar(19, 11, 2026);
console.log(`19/11/2026 là ngày ${am.day}/${am.month} năm ${yearCanChi(am.year).label}`);
// Bước 3: ngày giỗ theo ngày âm của ngày mất
const mat = solarToLunar(12, 4, 2019);
console.log(`Ngày mất 12/4/2019 là ${mat.day}/${mat.month} âm lịch`);
for (const nam of [2027, 2028, 2029]) {
const { duong } = lunarToSolar(mat.day, mat.month, nam, false);
console.log(`Giỗ năm ${nam}: ${duong.day}/${duong.month}/${duong.year}`);
}
// Bước 4: lễ hội trong năm, xếp theo ngày
const ten = Object.fromEntries(DANH_SACH_LE_HOI.map((l) => [l.id, l.ten]));
const le2027 = leHoiTrongNam(2027).sort((a, b) => a.ngay.localeCompare(b.ngay));
console.log(`Năm 2027 có ${le2027.length} lễ ngày cố định, bốn lễ đầu:`);
for (const l of le2027.slice(0, 4)) console.log(" ", l.ngay, ten[l.id]);
console.log("Ngày 6/2/2027:", leHoiTheoNgay(6, 2, 2027).map((l) => l.ten).join(", "));
// Bước 5: Tết theo lịch Việt Nam, Trung Quốc, Hàn Quốc
for (const nuoc of ["vietNam", "trungQuoc", "hanQuoc"]) {
const t = lunarToSolar(1, 1, 1985, false, MUI_GIO_LICH[nuoc]).duong;
console.log(`Tết 1985, lịch ${nuoc}: ${t.day}/${t.month}/${t.year}`);
}19/11/2026 là ngày 11/10 năm Bính Ngọ
Ngày mất 12/4/2019 là 8/3 âm lịch
Giỗ năm 2027: 14/4/2027
Giỗ năm 2028: 2/4/2028
Giỗ năm 2029: 21/4/2029
Năm 2027 có 164 lễ ngày cố định, bốn lễ đầu:
2027-01-01 Tết Dương Lịch
2027-02-03 Ngày thành lập Đảng Cộng sản Việt Nam
2027-02-06 Tết Nguyên Đán
2027-02-09 Hội Xuân chùa Keo
Ngày 6/2/2027: Tết Nguyên Đán
Tết 1985, lịch vietNam: 21/1/1985
Tết 1985, lịch trungQuoc: 20/2/1985
Tết 1985, lịch hanQuoc: 20/2/1985
Người mất ngày 12/4/2019 là mùng 8 tháng 3 âm lịch, nên giỗ rơi vào 14/4/2027, 2/4/2028, 21/4/2029. Năm 2027 có 164 lễ tính được ngày; các lễ còn lại do ban tổ chức công bố từng năm, xem cột lich_cong_bo.
Cùng việc ấy bằng Python
Tên hàm giống bản TypeScript, viết kiểu snake_case; kết quả là dict cùng khoá.
from nhatnguyet import am_lich, le_hoi
am = am_lich.solar_to_lunar(19, 11, 2026)
print(f"19/11/2026 là ngày {am['day']}/{am['month']} năm {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"Giỗ năm {nam}: {duong['day']}/{duong['month']}/{duong['year']}")
ten = {l["id"]: l["ten"] 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"], ten[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"Tết 1985, lịch {nuoc}: {tet['day']}/{tet['month']}/{tet['year']}")19/11/2026 là ngày 11/10 năm Bính Ngọ
Giỗ năm 2027: 14/4/2027
Giỗ năm 2028: 2/4/2028
Giỗ năm 2029: 21/4/2029
2027-01-01 Tết Dương Lịch
2027-02-03 Ngày thành lập Đảng Cộng sản Việt Nam
Tết 1985, lịch viet_nam: 21/1/1985
Tết 1985, lịch trung_quoc: 20/2/1985
Tết 1985, lịch han_quoc: 20/2/1985
Tết 1985, lịch nhat_ban: 20/2/1985
Dựng lịch tháng có ngày âm và lễ
Lặp các ngày trong tháng, gọi solarToLunar cho số nhỏ dưới mỗi ô và leHoiTheoNgay để tô ô có lễ. Hình dưới là tháng 2/2027 dựng đúng cách ấy: Tết Nguyên Đán rơi vào thứ Bảy 6/2.

Xuất lịch .ics
festivalsIcs(2027) của @nhatnguyet/le-hoi (Python: festivals_ics(2027) trong nhatnguyet.en) trả một tệp iCalendar (RFC 5545), mỗi lễ một sự kiện cả ngày, kèm nơi tổ chức khi có; nhập thẳng vào Google Calendar, Apple Calendar hay Outlook. Dòng lệnh: npx @nhatnguyet/cli festivals 2027 --ics > le-hoi-2027.ics.
Những chỗ cần biết
- Giỗ người mất trong tháng nhuận: theo nếp thường gặp, nhiều nhà làm giỗ vào tháng chính cùng số; hàm trên truyền
falselà theo nếp ấy. - Ngày 30 của tháng thiếu: tháng âm chỉ có 29 ngày thì
lunarToSolartrả ngày mùng 1 tháng sau. Muốn biết tháng ấy đủ hay thiếu, đổi ngược bằngsolarToLunarrồi so. - Lễ âm lịch đặt vào tháng chính, không tháng nhuận; năm không có ngày ấy thì lễ không có trong danh sách năm đó.
- Lịch Trung Quốc, Hàn Quốc dùng cùng quy tắc, chỉ khác giờ địa phương. Năm 1985 Tết Việt Nam là 21/1, Tết Trung Quốc và Hàn Quốc là 20/2.
Ghi nguồn
Mã theo giấy phép MIT. Bộ lễ hội theo CC BY 4.0: anh chị phát hành lại thì ghi "Dữ liệu: Nhật Nguyệt (nhatnguyet.org)". Kho mã ở trang mã nguồn mở, bộ dữ liệu ở trang dữ liệu mở.



