chinese-lunar-date

高精度農曆曆法庫 — 干支 · 生肖 · 節氣 · 節日 · 格式化 · 多語言

基於天文算法的農曆計算，支援中國、日本、韓國、越南四種農曆變體，以及簡體中文、繁體中文（臺灣/香港）、日本語、한국어、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        // "龍"
date.zodiacEmoji   // "🐉"
date.formatFull()  // "甲辰龍年 五月初六"

本專案獨創

• 自研輕量天文模組 — 基於 VSOP87 行星理論截斷資料（1e-7 閾值，僅保留 220/2564 項），替代笨重的 astronomia 函式庫，IIFE 體積從 ~350 KB 降至 ~47 KB（gzip ~16 KB），精度無損
• 四種曆法統一架構 — 中/日/韓/越四種農曆變體透過 CalendarConfig 配置驅動，同一套演算法適配不同紀元和時區歷史，而非四套獨立實作
• 不可變值物件 + 純函式雙模式 — 高層 API（ChineseDate 等）為不可變值物件，底層演算法全部為純函式，兩種模式可獨立使用
• 繁體中文地區差異化 — zh-TW 與 zh-HK 不僅用字不同，節日名稱也有區分（如「春節/農曆新年」），非簡單繁簡映射

為什麼選擇 chinese-lunar-date？

特性

• 天文級精度 — 基於 VSOP87 行星理論，自研輕量天文模組替代笨重的第三方函式庫
• 不可變值物件 — 所有實例建立後不可修改，with() / addDays() 回傳新實例
• 天干地支 — 年柱、月柱、日柱，六十甲子序號與字串互轉
• 生肖 — 12 生肖多語言名稱 + Emoji
• 24 節氣 — 精確到天的節氣計算，區分中氣與節氣
• 傳統節日 — 13 個內建節日，按地區自動篩選
• 多語言 / 多地區 — zh-CN / zh-TW / zh-HK / ja-JP / ko-KR / vi-VN
• 格式化 — 內建 5 種格式 + 自訂模式字串
• 多曆法 — 中 / 日 / 韓 / 越四種曆法配置（不同紀元、不同時區歷史）
• TypeScript 優先 — 完整型別定義，編譯輸出 ESM / CJS / IIFE
• 輕量 — IIFE 壓縮後僅 ~47 KB（gzip ~16 KB）

安裝

npm install chinese-lunar-date

快速開始

建立日期

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 })

讀取屬性

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          // "龍"
date.zodiacEmoji     // "🐉"
date.zodiacIndex     // 4

格式化

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

date.formatFull('zh-HK')   // "甲辰龍年 五月初六"
date.formatGanZhi()        // "甲辰年 庚午月 甲寅日"
date.formatCompact()       // "78/34/5/0/6"
date.format('{Ygz}{Z}年 {Mname}{Dname}', 'zh-HK')  // "甲辰龍年 五月初六"

日期運算

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

轉換

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 }

多曆法

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

24 節氣

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

ChineseDate.solarTerm(5, 2024)   // 清明
solarTermName(3, 'zh-HK')       // "驚蟄"

const date = ChineseDate.fromGregorian(2024, 4, 4)
date.getSolarTermName('zh-HK')  // "清明"

傳統節日

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

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

const date = ChineseDate.fromGregorian(2024, 2, 10)
date.getFestivals('zh-HK')  // [{ name: "農曆新年", key: "spring", ... }]

內建節日列表

多語言 / 多地區

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

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

格式化 Token

完整 Token 列表請參閱使用手冊。

意見回饋與合作

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

📧 gyfinjava@163.com

License

MIT License

Copyright (c) 2025 北京鋒通科技有限公司 (郭玉峰, 吳瓊)