# 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.
>
> 🌐 Phiên bản ngôn ngữ：简体中文 · 繁體中文(台) · 繁體中文(港) · 日本語 · 한국어 · **Tiếng Việt**

---

## Mục lục

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

| Khả năng | Mô tả |
|----------|-------|
| **Dương lịch ↔ Âm lịch** | Độ chính xác cấp thiên văn dựa trên lý thuyết hành tinh VSOP87 |
| **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, 6 ngôn ngữ |
| **Lễ hội truyền thống** | 13 lễ hội tích hợp, lọc tự động theo khu vực |
| **Định dạng** | 5 định dạng tích hợp + chuỗi mẫu tùy chỉnh（17 Token） |
| **Đa lịch** | 4 biến thể âm lịch Trung/Nhật/Hàn/Việt |
| **Đa 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 |

**Đị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

```bash
npm install chinese-lunar-date
```

### 2.2 ESM

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

### 2.3 CJS

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

### 2.4 Trình duyệt IIFE

```html
<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 đủ.

```ts
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

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

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

Tất cả instance ngày đều**bấ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

| Lịch | Múi giờ | Kỷ nguyên | Hằng số cấu hình |
|------|---------|-----------|------------------|
| Trung Quốc | UTC+8 | 2636 TCN | `CHINESE_CONFIG` |
| Nhật Bản | UTC+9 | 2636 TCN | `JAPANESE_CONFIG` |
| Hàn Quốc | UTC+8:30 / UTC+9 | 2333 TCN（Đàn Quân） | `KOREAN_CONFIG` |
| Việt Nam | UTC+7 / UTC+8 | 2636 TCN | `VIETNAMESE_CONFIG` |

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

| Mã | Ngôn ngữ | Mô tả |
|----|----------|-------|
| `zh-CN` | Giản thể Trung Văn | Trung Quốc đại lục |
| `zh-TW` | Phồn thể Trung Văn | Đài Loan |
| `zh-HK` | Phồn thể Trung Văn | Hồng Kông |
| `ja-JP` | 日本語 | Nhật Bản |
| `ko-KR` | 한국어 | Hàn Quốc |
| `vi-VN` | Tiếng Việt | Việt Nam |

---

## 4. Tạo ngày

```ts
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

```ts
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

```ts
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

```ts
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ứ

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

---

## 6. Chuyển đổi ngày

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

| Token | Xuất | Ví dụ |
|-------|------|-------|
| `{CY}` | Số chu kỳ | `78` |
| `{Y}` | Số năm trong chu kỳ | `34` |
| `{Ygz}` | Can chi năm | `甲辰` |
| `{Z}` | Con giáp | `Thìn` |
| `{M}` | Số tháng | `5` |
| `{Mname}` | Tên tháng | `tháng năm` |
| `{L}` | Đánh dấu nhuận | `nhuận` |
| `{D}` | Số ngày | `6` |
| `{Dname}` | Tên ngày | `mùng sáu` |

#### Dương lịch

| Token | Xuất | Ví dụ |
|-------|------|-------|
| `{GY}` | Năm dương lịch | `2024` |
| `{GM}` | Tháng dương lịch | `6` |
| `{GD}` | Ngày dương lịch | `21` |

#### Thứ

| Token | Xuất | Ví dụ |
|-------|------|-------|
| `{W}` | Số thứ (0-6) | `5` |
| `{Wname}` | Tên thứ đầy đủ | `Thứ Sáu` |
| `{Wshort}` | Tên thứ viết tắt | `T6` |

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

```ts
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

```ts
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

```ts
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í

```ts
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ố | Tên | Số | Tên | Số | Tên | Số | Tên |
|----|-----|----|-----|----|-----|----|-----|
| 1 | Lập xuân | 7 | Lập hạ | 13 | Lập thu | 19 | Lập đông |
| 2 | Vũ thủy | 8 | Tiểu mãn | 14 | Xử thử | 20 | Tiểu tuyết |
| 3 | Kinh trập | 9 | Mang chủng | 15 | Bạch lộ | 21 | Đại tuyết |
| 4 | Xuân phân | 10 | Hạ chí | 16 | Thu phân | 22 | Đông chí |
| 5 | Thanh minh | 11 | Tiểu thử | 17 | Hàn lộ | 23 | Tiểu hàn |
| 6 | Cốc vũ | 12 | Đại thử | 18 | Sương giáng | 24 | Đại hàn |

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

### 11.2 Tên tiết khí

```ts
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í

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

### 11.4 Tiết khí cả năm

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

---

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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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？

```html
<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）