Thư viện chuyển đổi Dương lịch ↔ Âm lịch Việt Nam cho JavaScript/TypeScript.
Thuần TypeScript, 0 dependency ở phần lõi, strongly-typed đầy đủ, hỗ trợ sẵn component cho React/Vue/Svelte 5 và adapter tiêm ngày âm lịch vào FullCalendar/EventCalendar/React Big Calendar.
- 🔄 Chuyển đổi Solar ↔ Lunar chính xác — thuật toán Hồ Ngọc Đức (phạm vi năm 1800–2199)
- 🐉 Can Chi — tính Can Chi cho năm, tháng, ngày, giờ
- 🔮 Ngũ Hành & Mệnh — tính mệnh theo năm sinh
- ⏰ Giờ Hoàng Đạo — 6 giờ tốt trong ngày
- 🎨 Format linh hoạt — hiển thị ngày âm lịch truyền thống hoặc theo pattern tùy chỉnh
- 🌐 i18n — hỗ trợ Việt–Anh–Nhật–Hàn (vi, en, ja, ko)
- 📅 Component sẵn dùng —
Calendar/Formattercho React, Vue, Svelte 5 - 🔌 Plugin tích hợp — FullCalendar, EventCalendar, React Big Calendar
- 📦 Modular — cài đúng phần cần dùng,
@lichta/corekhông phụ thuộc framework nào
| Package | Mô tả |
|---|---|
@lichta/core |
Thuật toán lõi Solar↔Lunar, Can Chi, Ngũ Hành, format — thuần TypeScript, 0 dependency |
@lichta/react |
Component Calendar cho React |
@lichta/vue |
Component Calendar cho Vue 3 |
@lichta/svelte |
Component Calendar/Formatter cho Svelte 5 (re-export toàn bộ @lichta/core) |
@lichta/full-calendar |
Adapter tiêm ngày âm lịch vào FullCalendar |
@lichta/event-calendar |
Adapter tiêm ngày âm lịch vào EventCalendar |
@lichta/react-big-calendar |
Adapter tiêm ngày âm lịch vào React Big Calendar |
@lichta/core được cài kèm tự động khi bạn cài bất kỳ package nào ở trên — không cần cài riêng.
pnpm add @lichta/core
# hoặc: npm install @lichta/core / yarn add @lichta/core / bun add @lichta/coreDùng React/Vue/Svelte? Cài thêm package binding tương ứng (@lichta/react, @lichta/vue, @lichta/svelte) — xem bảng packages ở trên.
import { LichTa } from '@lichta/core';
// Dương lịch → Âm lịch
const lunar = LichTa.toLunar(10, 2, 2024);
// → { day: 1, month: 1, year: 2024, isLeap: false, jd: 2460351,
// dayCanChi: 'Giáp Thìn', monthCanChi: 'Bính Dần', yearCanChi: 'Giáp Thìn' }
// Âm lịch → Dương lịch (isLeap bắt buộc truyền đúng nếu là tháng nhuận)
const solar = LichTa.toSolar(1, 1, 2024, false);
// → { day: 10, month: 2, year: 2024 }
// Múi giờ tùy chỉnh (mặc định GMT+7 Việt Nam)
const lunarGmt8 = LichTa.toLunar(10, 2, 2024, 8);toLunar/toSolar throw RangeError nếu ngày/tháng/năm ngoài phạm vi hợp lệ (năm 1800–2199) — nên bọc trong try/catch khi nhận input từ người dùng.
import { LichTa, getYearDetails, getDayCanChi, getMonthCanChi, getHourCanChi, getAuspiciousHours } from '@lichta/core';
getYearDetails(2024);
// → { can: 'Giáp', chi: 'Thìn', menh: 'Thủy', fullString: 'Giáp Thìn - Mệnh Thủy' }
const lunar = LichTa.toLunar(10, 2, 2024);
getDayCanChi(lunar.jd); // 'Giáp Thìn'
getMonthCanChi(lunar.month, lunar.year); // 'Bính Dần'
getHourCanChi(8, lunar.jd); // giờ Thìn (7h-9h)
getAuspiciousHours(lunar.jd); // 6 giờ Hoàng Đạo trong ngàyimport { formatTraditional, formatLunarDate, getMonthName, getDayName } from '@lichta/core';
formatTraditional(lunar); // 'Mùng Một tháng Giêng năm Giáp Thìn'
formatLunarDate(lunar, 'dd/MM/yyyy'); // '01/01/2024'
formatLunarDate(lunar, 'Ngày d tháng M năm CC'); // 'Ngày 1 tháng 1 năm Giáp Thìn'
getMonthName(1); // 'Giêng'
getDayName(15); // 'Rằm'Format tokens: dd/d (ngày), MM/M (tháng), yyyy/yy (năm), CC/MC/DC (Can Chi năm/tháng/ngày), L ("Nhuận" nếu là tháng nhuận).
Hỗ trợ 4 ngôn ngữ cho tên Can Chi, Ngũ Hành, con giáp, tên tháng, thứ trong tuần: vi, en, ja, ko.
import { t, getZodiacAnimal } from '@lichta/core';
t('en').fiveElements; // ['Metal', 'Wood', 'Water', 'Fire', 'Earth']
t('ja').weekDays; // ['日', '月', '火', '水', '木', '金', '土']
getZodiacAnimal(0, 'vi'); // 'Chuột'Mỗi package binding export component Calendar (lịch tháng có ngày âm lịch) đóng gói trên @lichta/core.
React
import { Calendar } from '@lichta/react';
import '@lichta/core/styles/calendar-base.css';
<Calendar theme="glass" locale="vi" onSelect={(date, lunar) => console.log(date, lunar)} />Vue
<Calendar theme="glass" locale="vi" @select="onSelect" />Svelte 5
<Calendar theme="glass" locale="vi" onSelect={(date, lunar) => console.log(date, lunar)} />Chi tiết props, custom render, theming: xem README của từng package (@lichta/react, @lichta/vue, @lichta/svelte).
@lichta/full-calendar, @lichta/event-calendar, @lichta/react-big-calendar export một hàm duy nhất injectLunarDates(options, pluginOptions?) — bọc cấu hình gốc của calendar library và tiêm ngày âm lịch vào từng ô ngày.
import { Calendar } from '@fullcalendar/core';
import dayGridPlugin from '@fullcalendar/daygrid';
import { injectLunarDates } from '@lichta/full-calendar';
const calendar = new Calendar(el, injectLunarDates({
plugins: [dayGridPlugin],
initialView: 'dayGridMonth'
}, { showLeapMonth: true, color: '#81b29a' }));Chi tiết từng adapter: xem README của @lichta/full-calendar, @lichta/event-calendar, @lichta/react-big-calendar.
- Tài liệu đầy đủ — cài đặt, sử dụng, components, tích hợp
- API Reference — chữ ký hàm, kiểu dữ liệu, ví dụ đã chạy thật
- Về LichTa — nguồn gốc thuật toán, hệ sinh thái package
- Demo trực tiếp — thử tương tác từng framework/integration
LichTa sử dụng thuật toán chuyển đổi âm lịch của Hồ Ngọc Đức (Đại học Leipzig), dựa trên các công thức thiên văn trong "Astronomical Algorithms" của Jean Meeus (1998) — chuẩn de facto cho lịch âm Việt Nam trong lập trình.
- Julian Day Number — hệ tọa độ ngày liên tục cho tính toán thiên văn
- Điểm Sóc (New Moon) — xác định mùng 1 âm lịch
- Trung Khí (Solar Terms) — xác định tháng và tháng nhuận
Phạm vi hỗ trợ: 1800 – 2199 | Múi giờ mặc định: GMT+7 (Việt Nam)
Repo này chỉ chứa bản build công khai (dist/) và đóng vai trò issue tracker — mã nguồn được giữ private nên không nhận PR sửa code trực tiếp tại đây. Bạn có thể báo lỗi, đề xuất tính năng, hoặc tham gia thảo luận.
- Hồ Ngọc Đức — thuật toán gốc (informatik.uni-leipzig.de)
- Jean Meeus — Astronomical Algorithms (1998)
- Zeforc Labs — phát triển và duy trì