chinese-lunar-date Hướng dẫn sử dụng

Phiên bản：1.0.0 | Cập nhật cuối：2025-06 Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼). MIT License.

Mục lục

• 1. Tổng quan
• 2. Cài đặt và nhập
• 3. Khái niệm cốt lõi
• 4. Tạo ngày
• 5. Đọc thuộc tính
• 6. Chuyển đổi ngày
• 7. Tính toán ngày
• 8. Định dạng
• 9. Can Chi
• 10. Con giáp
• 11. 24 tiết khí
• 12. Lễ hội truyền thống
• 13. Đa lịch
• 14. Đa ngôn ngữ / Đa khu vực
• 15. API cấp thấp
• 16. Số Trung Hoa
• 17. Tham chiếu kiểu
• 18. Câu hỏi thường gặp（FAQ）
• 19. Kiến trúc và nguyên tắc thiết kế
• 20. Nhật ký cập nhật

1. Tổng quan

chinese-lunar-date là thư viện âm lịch độ chính xác cao dựa trên thuật toán thiên văn.

Định dạng xuất： ESM / CJS / IIFE, IIFE nén chỉ ~47 KB（gzip ~16 KB）.

2. Cài đặt và nhập

2.1 Cài đặt

npm install chinese-lunar-date

2.2 ESM

import { ChineseDate, formatGanZhi, PATTERNS } from 'chinese-lunar-date'

2.3 CJS

const { ChineseDate, formatGanZhi, PATTERNS } = require('chinese-lunar-date')

2.4 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'))

  const lunar = ChineseDate.gregorianToLunar(ChineseDate.CHINESE_CONFIG, 2024, 6, 21)
</script>

2.5 TypeScript

Thư viện được viết bằng TypeScript gốc, đi kèm định nghĩa kiểu đầy đủ.

import type { LunarDateValue, GanZhiPair, LocaleCode } from 'chinese-lunar-date'

3. Khái niệm cốt lõi

3.1 Chu kỳ lục thập giáp tử（cycle / year）

• cycle — Số thứ tự chu kỳ（bắt đầu từ 1）, cho biết chu kỳ 60 năm thứ mấy
• year — Số năm trong chu kỳ（1-60）, tương ứng trực tiếp với can chi

gregorianYear = epochYear + (cycle - 1) * 60 + (year - 1)

3.2 Đối tượng giá trị bất biến

Tất cả instance ngày đềubất biến. Mọi thao tác sửa đổi đều trả về instance mới.

3.3 Cấu hình lịch và khác biệt khu vực

3.4 Mã ngôn ngữ và khu vực

4. Tạo ngày

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 })
const d1 = ChineseDate.fromISO('2024-06-21')
const date4 = ChineseDate.fromTimestamp(Date.now())
const date5 = ChineseDate.fromJDE(2460482.5)

5. Đọc thuộc tính

5.1 Thuộc tính ngày âm lịch

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

5.2 Thuộc tính Can Chi

date.yearGanZhi      // "甲辰"
date.monthGanZhi     // "庚午"
date.dayGanZhi       // "甲寅"
date.ganZhiInfo      // { year: {gan:0,zhi:4}, month: {gan:6,zhi:6}, day: {gan:0,zhi:2} }

Chỉ số Can Chi：

• gan（Thiên Can）：0=甲, 1=乙, 2=丙, 3=丁, 4=戊, 5=己, 6=庚, 7=辛, 8=壬, 9=癸
• zhi（Địa Chi）：0=子, 1=丑, 2=寅, 3=卯, 4=辰, 5=巳, 6=午, 7=未, 8=申, 9=酉, 10=戌, 11=亥

5.3 Thuộc tính con giáp

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

date.getZodiac('vi-VN')  // "Thìn"
date.getZodiac('ko-KR')  // "용"
date.getZodiac('ja-JP')  // "辰"

5.4 Thuộc tính dương lịch và thứ

date.weekday           // 5
date.weekdayName       // "Thứ Sáu"（vi-VN）
date.weekdayShort      // "T6"
date.gregorianYearCn   // "二〇二四"

6. Chuyển đổi ngày

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

7. Tính toán ngày

const tomorrow = date.addDays(1)
const yesterday = date.addDays(-1)
const nextMonth = date.addMonths(1)
const lastYear = date.addYears(-1)
const firstDay = date.with({ day: 1 })

a.equals(b)      // false
a.isAfter(b)     // true
a.diffDays(b)    // 3
date.daysInMonth()  // 29 hoặc 30

8. Định dạng

8.1 Phương thức định dạng tích hợp

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.formatISO()           // "78-34-5-0-6"

8.2 Mẫu tùy chỉnh

date.format('{Ygz}{Z} năm {Mname}{Dname}', 'vi-VN')
date.format('{GY} năm {GM} tháng {GD} ngày', 'vi-VN')

8.3 Hằng số định dạng预设 PATTERNS

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

date.format(PATTERNS.LUNAR_FULL)
date.format(PATTERNS.GREGORIAN_ISO)  // "2025-10-11"

8.4 Tham chiếu Token định dạng đầy đủ

Âm lịch

Dương lịch

Thứ

8.5 Phân tích cú pháp

import { parseCompact, parseISO, parseGregorian } from 'chinese-lunar-date'

parseCompact('78/34/5/0/6')    // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
parseISO('78-34-5-0-6')        // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
parseGregorian('2025-10-11')   // { year: 2025, month: 10, day: 11 }

9. Can Chi

import { yearGanZhi, formatGanZhi, parseGanZhi, allGanZhi, ganZhiToCycleIndex } from 'chinese-lunar-date'

yearGanZhi(value)   // { gan: 3, zhi: 9 }  → Đinh Dậu
formatGanZhi({ gan: 3, zhi: 9 })  // "丁酉"
parseGanZhi('甲子')  // { gan: 0, zhi: 0 }
allGanZhi()  // ["甲子", "乙丑", ..., "癸亥"]

10. Con giáp

import { zodiac, zodiacEmoji, zodiacFromGregorianYear, zodiacList } from 'chinese-lunar-date'

zodiac(value, 'vi-VN')  // "Dậu"
zodiacEmoji(value)       // "🐔"
zodiacFromGregorianYear(2024, 'vi-VN')  // "Thìn"
zodiacList('vi-VN')  // ["Tý", "Sửu", "Dần", "Mão", "Thìn", "Tỵ", "Ngọ", "Mùi", "Thân", "Dậu", "Tuất", "Hợi"]

11. 24 tiết khí

11.1 Lấy ngày tiết khí

ChineseDate.solarTerm(1, 2024)   // Lập xuân
ChineseDate.solarTerm(5, 2024)   // Thanh minh
ChineseDate.qingming(2024)       // Tương tự

Bảng đối chiếu số tiết khí：

Số lẻ làtiết khí（tiết）, số chẵn làtrung khí（khí）.

11.2 Tên tiết khí

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

solarTermName(3, 'vi-VN')  // "Kinh trập"
solarTermNames('vi-VN')    // ["Lập xuân", "Vũ thủy", "Kinh trập", ...]

11.3 Kiểm tra ngày có phải tiết khí

date.getSolarTermName('vi-VN')  // "Thanh minh" hoặc null

11.4 Tiết khí cả năm

ChineseDate.solarTermsInYear(2024, 'vi-VN')
// [{ index: 1, name: "Lập xuân", date: {...}, jde: ... }, ...]

12. Lễ hội truyền thống

ChineseDate.festivalDate('spring', 2024)       // Tết Nguyên đán
ChineseDate.festivalDate('mid-autumn', 2024)   // Tết Trung thu

date.getFestivals('vi-VN')
ChineseDate.festivalsInYear(2024, 'vi-VN')

13. Đ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.

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

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

availableLocales()  // ["zh-CN", "zh-TW", "zh-HK", "ja-JP", "ko-KR", "vi-VN"]

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", ...]

15. API cấp thấp

import {
  gregorianToLunar, lunarToGregorian,
  CHINESE_CONFIG, JAPANESE_CONFIG, KOREAN_CONFIG, VIETNAMESE_CONFIG
} from 'chinese-lunar-date'

const lunar = gregorianToLunar(VIETNAMESE_CONFIG, 2024, 6, 21)
const greg = lunarToGregorian(VIETNAMESE_CONFIG, lunar)

16. Số Trung Hoa

import { toChineseYear, toChineseNumber, getWeekdayName } from 'chinese-lunar-date'

toChineseYear(2025, 'upper')  // "二〇二五"
toChineseNumber(21, 'upper')  // "二十一"
getWeekdayName(6, 'vi-VN')    // "Thứ Bảy"

17. Tham chiếu kiểu

interface LunarDateValue {
  cycle: number
  year: number
  month: number
  leap: boolean
  day: number
}

interface GregorianDate {
  year: number
  month: number
  day: number
}

type CalendarType = 'chinese' | 'korean' | 'japanese' | 'vietnamese'

interface GanZhiPair {
  gan: number
  zhi: number
}

type LocaleCode = 'zh-CN' | 'zh-TW' | 'zh-HK' | 'ja-JP' | 'ko-KR' | 'vi-VN'

18. Câu hỏi thường gặp（FAQ）

Q: Khác biệt giữa `cycle` và `year` là gì？

cycle cho biết chu kỳ 60 năm thứ mấy, year cho biết năm thứ mấy trong chu kỳ（1-60）. Hầu hết trường hợp, chỉ cần dùng date.gregorianYear.

Q: Tại sao cùng ngày dương lịch mà `ChineseDate` và `JapaneseDate` cho kết quả âm lịch khác？

Do chênh lệch múi giờ. Khi trăng mới xảy ra gần nửa đêm UTC+8, Nhật Bản（UTC+9）có thể đã sang ngày hôm sau.

Q: Tại sao `cycle` của lịch Hàn Quốc khác Trung Quốc？

Lịch Hàn Quốc dùng kỷ nguyên Đàn Quân（2333 TCN）, muộn hơn kỷ nguyên Trung Quốc 297 năm. Nhưng gregorianYear giống nhau.

Q: Cách dùng định dạng IIFE？

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

Q: Độ chính xác thế nào？

Thư viện sử dụng thuật toán thiên văn dựa trên lý thuyết hành tinh VSOP87, chính xác tương đương lịch biểu do đài thiên văn công bố（sai số ở cấp giây）.

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

19. Kiến trúc và nguyên tắc thiết kế

• Đối tượng giá trị bất biến — Instance sau khi tạo không thể sửa đổi
• Hàm thuần túy cốt lõi — Thuật toán cấp thấp đều là hàm thuần túy
• Cấu hình điều khiển — Lịch khác nhau phân biệt qua CalendarConfig
• Tối ưu bộ nhớ đệm — Kết quả tính toán thiên văn tự động lưu đệm
• TypeScript ưu tiên — TypeScript gốc, định nghĩa kiểu đầy đủ

20. Nhật ký cập nhật

1.0.0

• Phát hành lần đầu
• Hỗ trợ 4 biến thể âm lịch Trung/Nhật/Hàn/Việt
• 6 ngôn ngữ / khu vực
• Can Chi（trụ năm tháng ngày）
• Con giáp（đa ngôn ngữ + Emoji）
• Tính 24 tiết khí
• 13 lễ hội truyền thống
• Định dạng（5 tích hợp + mẫu tùy chỉnh）
• Mô-đun thiên văn nhẹ tự phát triển（dữ liệu VSOP87 cắt giảm）
• IIFE nén ~47 KB（gzip ~16 KB）