chinese-lunar-date

Thư viện âm lịch độ chính xác cao — Can Chi · Con giáp · Tiết khí · Lễ hội · Định dạng · Đa ngôn ngữ

Tính toán âm lịch dựa trên thuật toán thiên văn. Hỗ trợ 4 biến thể âm lịch Trung Quốc/Nhật Bản/Hàn Quốc/Việt Nam và 6 ngôn ngữ: giản thể Trung Văn/phồn thể Trung Văn (Đài Loan/Hồng Kông)/日本語/한국어/Tiếng Việt.

Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼). MIT License.

import { ChineseDate } from 'chinese-lunar-date'

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.yearGanZhi    // "甲辰"
date.zodiac        // "Thìn"
date.zodiacEmoji   // "🐉"
date.formatFull()  // "Giáp Thìn năm Thìn tháng năm mùng sáu"

Điểm độc đáo của dự án

• Mô-đun thiên văn nhẹ tự phát triển — Dựa trên dữ liệu cắt giảm lý thuyết hành tinh VSOP87 (ngưỡng 1e-7, chỉ giữ 220/2564 hạng), thay thế thư viện astronomia cồng kềnh. Kích thước IIFE giảm từ ~350 KB xuống ~47 KB (gzip ~16 KB), không mất độ chính xác
• Kiến trúc thống nhất 4 loại lịch — 4 biến thể âm lịch Trung/Nhật/Hàn/Việt được điều khiển bằng cấu hình CalendarConfig. Cùng một thuật toán thích ứng các kỷ nguyên và lịch sử múi giờ khác nhau
• Đối tượng giá trị bất biến + Hàm thuần túy kép — API cấp cao (ChineseDate v.v.) là đối tượng giá trị bất biến, thuật toán cấp thấp đều là hàm thuần túy. Hai chế độ có thể sử dụng độc lập
• Phân biệt khu vực Trung Văn phồn thể — zh-TW và zh-HK không chỉ khác chữ mà còn khác tên lễ hội (ví dụ: 「春節/農曆新年」). Không phải chuyển đổi giản phồn đơn thuần

Tại sao chọn chinese-lunar-date?

Tính năng

• Độ chính xác cấp thiên văn — Mô-đun thiên văn nhẹ tự phát triển dựa trên lý thuyết hành tinh VSOP87
• Đối tượng giá trị bất biến — Instance sau khi tạo không thể sửa đổi, with() / addDays() trả về instance mới
• Can Chi — Trụ năm, trụ tháng, trụ ngày, chuyển đổi giữa số thứ tự lục thập giáp tử và chuỗi
• Con giáp — Tên 12 con giáp đa ngôn ngữ + Emoji
• 24 tiết khí — Tính tiết khí chính xác đến ngày, phân biệt trung khí và tiết khí
• Lễ hội truyền thống — 13 lễ hội tích hợp, lọc tự động theo khu vực
• Đa ngôn ngữ / Đa khu vực — zh-CN / zh-TW / zh-HK / ja-JP / ko-KR / vi-VN
• Định dạng — 5 định dạng tích hợp + chuỗi mẫu tùy chỉnh
• Đa lịch — 4 cấu hình lịch Trung / Nhật / Hàn / Việt (khác kỷ nguyên, khác lịch sử múi giờ)
• TypeScript ưu tiên — Định nghĩa kiểu đầy đủ, xuất ESM / CJS / IIFE
• Nhẹ — IIFE nén chỉ ~47 KB (gzip ~16 KB)

Cài đặt

npm install chinese-lunar-date

Bắt đầu nhanh

Tạo ngày

import { ChineseDate } from 'chinese-lunar-date'

const date = ChineseDate.fromGregorian(2024, 6, 21)
const date2 = ChineseDate.fromDate(new Date(2024, 5, 21))
const today = ChineseDate.today()
const date3 = ChineseDate.fromValue({ cycle: 78, year: 34, month: 5, leap: false, day: 6 })

Đọc thuộc tính

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.cycle           // 78
date.year            // 34
date.month           // 5
date.leap            // false
date.day             // 6
date.gregorianYear   // 2024

date.yearGanZhi      // "甲辰"
date.monthGanZhi     // "庚午"
date.dayGanZhi       // "甲寅"

date.zodiac          // "Thìn"
date.zodiacEmoji     // "🐉"
date.zodiacIndex     // 4

Định dạng

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.formatFull('vi-VN')   // "Giáp Thìn năm Thìn tháng năm mùng sáu"
date.formatGanZhi()        // "甲辰年 庚午月 甲寅日"
date.formatCompact()       // "78/34/5/0/6"
date.format('{Ygz}{Z} năm {Mname}{Dname}', 'vi-VN')

Tính toán ngày

const date = ChineseDate.fromGregorian(2024, 6, 21)

const tomorrow = date.addDays(1)
const yesterday = date.addDays(-1)
const firstDay = date.with({ day: 1 })
tomorrow.isAfter(date)     // true

Chuyển đổi

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.toGregorian()  // { year: 2024, month: 6, day: 21 }
date.toDate()       // Date object
date.toJSON()       // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }

Đa lịch

import { ChineseDate, JapaneseDate, KoreanDate, VietnameseDate } from 'chinese-lunar-date'

const cn = ChineseDate.fromGregorian(2024, 6, 21)    // UTC+8
const jp = JapaneseDate.fromGregorian(2024, 6, 21)   // UTC+9
const kr = KoreanDate.fromGregorian(2024, 6, 21)     // UTC+8:30/9
const vn = VietnameseDate.fromGregorian(2024, 6, 21) // UTC+7/8

Lưu ý: Do chênh lệch múi giờ, cùng một ngày dương lịch có thể tương ứng với ngày âm lịch khác nhau trong các lịch khác nhau.

24 tiết khí

import { ChineseDate, solarTermName } from 'chinese-lunar-date'

ChineseDate.solarTerm(5, 2024)   // Thanh minh
solarTermName(3, 'vi-VN')       // "Kinh trập"

const date = ChineseDate.fromGregorian(2024, 4, 4)
date.getSolarTermName('vi-VN')  // "Thanh minh"

Lễ hội truyền thống

import { ChineseDate } from 'chinese-lunar-date'

ChineseDate.festivalDate('spring', 2024)      // Tết Nguyên đán
ChineseDate.festivalsInYear(2024, 'vi-VN')

Đa ngôn ngữ / Đa khu vực

import { getLocale, availableLocales } from 'chinese-lunar-date'

const loc = getLocale('vi-VN')
loc.zodiac        // ["Tý", "Sửu", "Dần", "Mão", "Thìn", "Tỵ", "Ngọ", "Mùi", "Thân", "Dậu", "Tuất", "Hợi"]
loc.solarTerms    // ["Lập xuân", "Vũ thủy", "Kinh trập", ...]

Token định dạng

Danh sách Token đầy đủ vui lòng xemHướng dẫn sử dụng.

Trình duyệt (IIFE)

<script src="dist/chinese-lunar-date.iife.js"></script>
<script>
  const date = ChineseDate.ChineseDate.fromGregorian(2024, 6, 21)
  console.log(date.formatFull('vi-VN'))
</script>

Build

npm install chinese-lunar-date
npm run build        # Biên dịch ESM + CJS + IIFE
npm run build:types  # Tạo khai báo kiểu .d.ts
npm run test         # Chạy test

Phản hồi và Hợp tác

Nếu bạn gặp vấn đề khi sử dụng, hoặc có đề xuất tính năng, nhu cầu hợp tác kinh doanh, vui lòng liên hệ qua email：

📧 gyfinjava@163.com

License

MIT License

Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼)