chinese-lunar-date 使用手冊

版本：1.0.0 | 最後更新：2025-06 Copyright (c) 2025 北京鋒通科技有限公司 (郭玉峰, 吳瓊). MIT License.

目錄

• 1. 概述
• 2. 安裝與引入
• 3. 核心概念
• 4. 建立日期
• 5. 讀取屬性
• 6. 日期轉換
• 7. 日期運算
• 8. 格式化
• 9. 天干地支
• 10. 生肖
• 11. 24 節氣
• 12. 傳統節日
• 13. 多曆法
• 14. 多語言 / 多地區
• 15. 低階 API
• 16. 中文數字
• 17. 型別參考
• 18. 常見問題（FAQ）
• 19. 架構與設計原則
• 20. 更新日誌

1. 概述

chinese-lunar-date 是一個基於天文算法的高精度農曆曆法庫，提供以下核心能力：

輸出格式： ESM / CJS / IIFE，IIFE 壓縮後僅 ~47 KB（gzip ~16 KB）。

2. 安裝與引入

2.1 安裝

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 瀏覽器 IIFE 引入

<script src="dist/chinese-lunar-date.iife.js"></script>
<script>
  const date = ChineseDate.ChineseDate.fromGregorian(2024, 6, 21)
  console.log(date.formatFull('zh-HK'))  // "甲辰龍年 五月初六"
</script>

2.5 TypeScript 支援

本函式庫使用原生 TypeScript 編寫，自帶完整型別定義。

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

3. 核心概念

3.1 六十甲子週期（cycle / year）

• cycle — 週期序號（1 起始），表示當前是第幾個 60 年週期
• year — 週期內年序（1-60），直接對應干支

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

3.2 不可變值物件

所有日期實例都是不可變的。任何修改操作都會回傳新實例。

3.3 曆法配置與地區差異

3.4 語言與地區代碼

4. 建立日期

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. 讀取屬性

5.1 農曆日期屬性

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

5.2 天干地支屬性

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

5.3 生肖屬性

date.zodiac          // "龍"
date.zodiacEmoji     // "🐉"
date.zodiacIndex     // 4
date.getZodiac('zh-HK')  // "龍"

5.4 公曆與星期屬性

date.weekday         // 5
date.weekdayName     // "星期五"
date.gregorianYearCn // "二〇二四"

6. 日期轉換

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. 日期運算

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 或 30

8. 格式化

8.1 內建格式方法

date.formatFull('zh-HK')   // "甲辰龍年 五月初六"
date.formatGanZhi()        // "甲辰年 庚午月 甲寅日"
date.formatCompact()       // "78/34/5/0/6"
date.formatISO()           // "78-34-5-0-6"

8.2 自訂模式

date.format('{Ygz}{Z}年 {Mname}{Dname}', 'zh-HK')   // "甲辰龍年 五月初六"
date.format('{GY}年{GM}月{GD}日', 'zh-HK')           // "2024年6月21日"

8.3 預設格式常量 PATTERNS

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

date.format(PATTERNS.LUNAR_FULL)               // "甲辰龍年 九月初九"
date.format(PATTERNS.GREGORIAN_CN_FULL)        // "二〇二五年十月十一日"

8.4 格式化 Token 完整參考

農曆相關

公曆相關

星期相關

8.5 解析

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. 天干地支

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

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

10. 生肖

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

zodiac(value, 'zh-HK')  // "雞"
zodiacEmoji(value)       // "🐔"
zodiacFromGregorianYear(2024, 'zh-HK')  // "龍"
zodiacList('zh-HK')  // ["鼠", "牛", "虎", "兔", "龍", "蛇", "馬", "羊", "猴", "雞", "狗", "豬"]

11. 24 節氣

ChineseDate.solarTerm(5, 2024)   // 清明
ChineseDate.qingming(2024)       // 同上

solarTermName(3, 'zh-HK')       // "驚蟄"
solarTermNames('zh-HK')         // ["立春", "雨水", "驚蟄", ...]

date.getSolarTermName('zh-HK')  // "清明" 或 null
ChineseDate.solarTermsInYear(2024, 'zh-HK')

12. 傳統節日

12.1 取得節日日期

ChineseDate.festivalDate('spring', 2024)       // 農曆新年
ChineseDate.festivalDate('mid-autumn', 2024)   // 中秋節

12.2 查詢某日的節日

date.getFestivals('zh-HK')  // [{ name: "農曆新年", key: "spring", ... }]

12.3 全年節日

ChineseDate.festivalsInYear(2024, 'zh-HK')
// [{ name: "農曆新年", key: "spring", date: {...} }, ...]

12.4 內建節日一覽

13. 多曆法

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

注意：由於時區差異，同一公曆日期在不同曆法中可能對應不同的農曆日期。

14. 多語言 / 多地區

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

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

const loc = getLocale('zh-HK')
loc.zodiac        // ["鼠", "牛", "虎", "兔", "龍", "蛇", "馬", "羊", "猴", "雞", "狗", "豬"]
loc.solarTerms    // ["立春", "雨水", "驚蟄", ...]

繁體中文地區差異

15. 低階 API

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

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

16. 中文數字

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

toChineseYear(2025, 'upper')  // "二〇二五"
toChineseNumber(21, 'upper')  // "二十一"
getWeekdayName(6, 'zh-HK')    // "星期六"

17. 型別參考

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. 常見問題（FAQ）

Q: `cycle` 和 `year` 有什麼區別？

cycle 標識第幾個 60 年週期，year 標識週期內的第幾年（1-60）。大多數場景下，直接使用 date.gregorianYear 即可。

Q: 為什麼同一公曆日期，`ChineseDate` 和 `JapaneseDate` 的農曆日期不同？

這是因為時區差異。

Q: IIFE 格式如何使用？

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

意見回饋與合作

如果您在使用過程中遇到問題，或有功能建議、商務合作等需求，歡迎透過電子郵件聯繫我們：

📧 gyfinjava@163.com

19. 架構與設計原則

• 不可變值物件 — 實例建立後不可修改
• 純函式核心 — 底層算法全部為純函式
• 配置驅動 — 不同曆法透過 CalendarConfig 區分
• 快取最佳化 — 天文計算結果自動快取
• TypeScript 優先 — 原生 TypeScript，完整型別定義

20. 更新日誌

1.0.0

• 初始發布
• 支援中國 / 日本 / 韓國 / 越南四種農曆變體
• 6 種語言 / 地區支援
• IIFE 壓縮後 ~47 KB（gzip ~16 KB）