Ozakboy.TaiwanKit.Ganzhi.NET — 農曆/節氣/干支轉換套件

Ozakboy.TaiwanKit 系列套件之一——曆法轉換的 .NET 函式庫，也是系列中技術最複雜的一個。

相關連結

• 📦 NuGet：https://www.nuget.org/packages/Ozakboy.TaiwanKit.Ganzhi.NET/
• 💻 GitHub：https://github.com/ozakboy/Ozakboy.TaiwanKit.Ganzhi.NET
• 🌐 介紹網站：https://ganzhi.ozakboy.life

dotnet add package Ozakboy.TaiwanKit.Ganzhi.NET

專案背景

農曆與節氣的計算對正確性要求極高——轉換錯一天就是嚴重 bug，而節氣的月干支歸屬更要精確到「分」。本套件以微軟 BCL 的農曆核心搭配自建的天文級節氣表，把國曆↔農曆、二十四節氣、干支四柱、生肖與農曆節日整合成一致的 API，涵蓋 1901~2100 兩百年。

主要功能

國曆 ↔ 農曆互轉

閏月以 IsLeapMonth 明確表示（避開 BCL 閏月序號位移的坑），不存在的日期以 TryToSolar 優雅拒絕，並提供 GetLeapMonth 查詢。

二十四節氣（精確到分）

交接時刻為台灣時間 UTC+8，精確到分。

干支四柱與生肖

年柱界線可選立春精確時刻（命理慣例，預設）或正月初一（民俗慣例）；月柱依節氣精確時刻切換（五虎遁），日柱以兩個獨立公認錨點互證，時柱含 23:00 晚子時規則。

農曆節日

除夕、春節、元宵、端午、七夕、中元、中秋、重陽、臘八與冬至；正確處理臘八一年兩次或零次的特例。

技術架構

• 節氣表天文計算：以全精度 VSOP87D 星曆 + IAU1980 章動主項 + Espenak-Meeus ΔT 離線計算 200 年 × 24 節氣，捨入到分
• 多來源驗證：與 USNO 二分二至時刻（2000 年 4/4 全中）、紫金山天文台來源（2025 年 3/3 全中）、2026 年全 24 節氣多來源交叉（24/24）比對
• 農曆核心：包裝微軟 BCL ChineseLunisolarCalendar，免自建曆法資料的正確性風險
• 多框架：netstandard2.0 / netstandard2.1 / net8.0 / net9.0 / net10.0，零執行期依賴
• 品質保證：96 項 xUnit 測試（含閏月、節氣交接日、四柱邊界、roundtrip 全區間抽樣）
• 雙語文件：README 與線上文件皆中英雙語，介紹網站以 Nuxt 4 靜態產生、部署於 GitHub Pages