Tài liệu LichTa

Hướng dẫn cài đặt và sử dụng thư viện LichTa trong dự án của bạn.

1. Cài đặt

Thư viện sử dụng cấu trúc Monorepo — mỗi package là một gói npm riêng biệt dưới scope @lichta/*. Cài package nào tùy vào nhu cầu, @lichta/core luôn được cài kèm tự động khi bạn cài bất kỳ package nào khác.

1.1. Module lõi (bắt buộc)

Đây là package duy nhất bắt buộc phải có — chứa toàn bộ logic tính toán, không phụ thuộc framework nào.

npm install @lichta/core
yarn add @lichta/core
pnpm add @lichta/core
bun add @lichta/core

1.2. Binding cho framework UI (tùy chọn)

Nếu bạn muốn dùng sẵn component Calendar/Formatter thay vì tự dựng UI, cài thêm package tương ứng với framework đang dùng:

# React
npm install @lichta/react

# Vue
npm install @lichta/vue

# Svelte 5 (re-export toàn bộ @lichta/core, không cần cài core riêng)
npm install @lichta/svelte

1.3. Adapter cho calendar library bên thứ 3 (tùy chọn)

Nếu bạn đang dùng FullCalendar, EventCalendar hoặc React Big Calendar và muốn tiêm (inject) ngày âm lịch vào lịch có sẵn:

npm install @lichta/full-calendar
npm install @lichta/event-calendar
npm install @lichta/react-big-calendar

2. Sử dụng cơ bản

Import LichTa từ module core để thực hiện các phép tính chuyển đổi ngày tháng cơ bản.

import { LichTa } from '@lichta/core';

// 1. Dương lịch sang Âm lịch
const lunar = LichTa.toLunar(10, 2, 2024);
console.log(lunar);
// -> { day: 1, month: 1, year: 2024, isLeap: false, yearCanChi: 'Giáp Thìn' }

// 2. Âm lịch sang Dương lịch (isLeap = true nếu là tháng nhuận)
const solar = LichTa.toSolar(1, 1, 2024, false);
console.log(solar);
// -> { day: 10, month: 2, year: 2024 }

// 3. Tùy chỉnh múi giờ (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 nằm ngoài phạm vi hợp lệ (năm 1800–2199, tháng 1–12, ngày 1–31) — nên bọc trong try/catch khi nhận input từ người dùng.

3. Can Chi & Phong Thủy

Ngoài chuyển đổi ngày tháng, @lichta/core còn tính Can Chi, Ngũ Hành (Mệnh) và Giờ Hoàng Đạo.

import { LichTa, getYearDetails, getDayCanChi, getMonthCanChi, getHourCanChi, getAuspiciousHours } from '@lichta/core';

// Can Chi + Mệnh theo năm
getYearDetails(2024);
// -> { can: 'Giáp', chi: 'Thìn', menh: 'Thủy', fullString: 'Giáp Thìn - Mệnh Thủy' }

// Can Chi ngày / tháng / giờ (cần Julian Day Number — lunar.jd)
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)

// 6 giờ Hoàng Đạo trong ngày
getAuspiciousHours(lunar.jd); // ['Tý', 'Mão', 'Thìn', 'Ngọ', 'Dậu', 'Tuất']

4. Format & Hiển thị

Các hàm tiện ích để hiển thị ngày âm lịch theo kiểu truyền thống Việt Nam, hoặc theo pattern tùy chỉnh.

import { 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 DC'); // 'Ngày Giáp Thìn'

Token	Mô tả	Ví dụ
`dd` / `d`	Ngày (2 chữ số / không)	01, 15
`MM` / `M`	Tháng (2 chữ số / không)	01, 12
`yyyy` / `yy`	Năm (4 chữ số / 2 chữ số)	2024, 24
`CC` / `MC` / `DC`	Can Chi năm / tháng / ngày	Giáp Thìn
`L`	"Nhuận" nếu là tháng nhuận	Nhuận

5. Components & Frameworks

Mỗi package @lichta/react, @lichta/vue, @lichta/svelte export sẵn 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';

<Calendar
  theme="glass"
  locale="vi"
  onSelect={(date, lunar) => console.log(date, lunar)}
  renderDay={(cell) => ...}
/>

Vue

Vue phát sự kiện chọn ngày qua @select (chưa hỗ trợ prop render tùy chỉnh như React/Svelte).

Svelte 5

@lichta/svelte re-export toàn bộ API của @lichta/core luôn, không cần cài @lichta/core riêng.

Prop	Kiểu	Mô tả
`month` / `year`	`number`	Tháng/năm hiển thị ban đầu
`showLunar`	`boolean`	Hiện ngày âm lịch dưới ngày dương (mặc định `true`)
`locale`	`'vi' \| 'en' \| 'ja' \| 'ko'`	Ngôn ngữ nhãn thứ trong tuần
`theme`	`'classic' \| 'glass'`	Giao diện lịch

Xem demo trực tiếp từng framework ở trang chủ, mục "🎮 Dùng thử demo trực tiếp".

6. Tích hợp Calendar bên thứ 3

Các package @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' }));

pluginOptions	Mặc định	Mô tả
`showLeapMonth`	`true`	Hiện chữ "(Nhuận)" cho tháng nhuận
`showTooltip`	`true`	Hiện Can Chi khi hover
`monthOnFirstDayOnly`	`false`	Chỉ hiện số tháng âm vào mùng 1
`color` / `className`	`'#888'`	Tùy chỉnh màu chữ / class CSS
`render`	—	Hàm render HTML/React node tùy chỉnh, nhận vào `LunarDate`

Lưu ý: @lichta/event-calendar dùng runtime Svelte 4 nội bộ — không tương thích trực tiếp trong ứng dụng Svelte 5 (chỉ dùng ngoài Svelte 5 hoặc Vanilla JS).

7. Tài liệu API

Đây là tài liệu hướng dẫn sử dụng ở mức tổng quan. Để tra cứu đầy đủ chữ ký hàm, kiểu dữ liệu, và toàn bộ hàm tiện ích khác của @lichta/core, xem trang tham chiếu API chi tiết.

Xem tài liệu API đầy đủ