前言

lunisolar.js是一個專業(yè)的Javascript農歷工具庫。支持各類農歷信息查詢，如天干地支、五行納音、神煞宜忌、建除十二神、八字十神、四柱神煞、胎神占方、每日吉時、每日吉神方等。使用Typescript編寫，主體代碼壓縮后只有11.5KB左右。簡單易上手。

昔見不同版本日歷（包括紙質日歷和各類日歷軟件），其所示宜忌有所不同，更有相矛盾者，不知如何取用，故疑其推算依據(jù)是否誤，本著宏揚傳統(tǒng)文化之精神，查閱各資料文案，以制此庫。

現(xiàn)所用的中國傳統(tǒng)歷法，我們常稱為農歷，農歷是陰陽合歷，即包含了陰歷和陽歷，所以此庫取lunar+solar，命名為lunisolar。

農歷中，通過月相圓缺紀月，此屬于陰歷范疇，本庫會以一個Lunar對象記錄轉換好的陰歷數(shù)據(jù)。 而公歷與陰歷的轉換規(guī)律性不大，使用壽星天文歷open in new window的計算方式又過于復雜也影響代碼體積，故本庫的核心采用查表法進行轉換，其數(shù)據(jù)來自香港天文臺【公歷與農歷日期對照表open in new window】。其可查詢年份范圍為[1901,2100]。數(shù)據(jù)抓取和壓縮的代碼見倉庫 lunar-crawleropen in new window，此處不作詳細介紹。

屬于陽歷范疇的內容比較多，有二十四節(jié)氣、天干地支等，傳統(tǒng)很多術數(shù)多以陽歷排盤，如八字、奇門遁甲...（也有少數(shù)以陰歷排盤的，如紫微斗數(shù)）。其中二十四節(jié)氣是陽歷中十分重要的部分，其影響天干地支的換歲和換月。

過去，年和歲是兩個不同的概念。

年 是指陰歷正月初一到下一個正月初一的一個周期。

歲 是指太陽連續(xù)兩次通過春分點的時間間隔，古人一般用‘冬至點’來觀測，現(xiàn)代稱作回歸年（tropical year），也叫 太陽年（solar year）。一個周期結束而開始下一個周期，稱為換歲。

1回歸年 = 365.2421990741日 = 365天5小時48分46秒

我們常說的二十四節(jié)氣，其實分為節(jié)和氣，共十二節(jié)和十二氣，節(jié)和氣交替出現(xiàn)。天干地支紀月是以節(jié)換月的。

實際上，節(jié)氣是某一個時刻，而這個時刻并不是固定在某天的某個時辰。但由于數(shù)據(jù)源只精確到日，所以本庫的交節(jié)（更換八字月柱），也是以日為準。

我們知道天干地支是基于二十四節(jié)氣來定的。對于一些術數(shù)，如八字命理，通常以立春換歲，即到了立春，便更換下一個天干地支紀年，例如今年為甲子年，則到下一個立春，則換成乙丑年。

但是，并不是所有術數(shù)都是以立春換歲，例如中醫(yī)的五運六氣，則以大寒日換歲。 而奇門遁甲則以冬至換歲，中氣換月。

lunisolar是為術數(shù)服務的， 所以lunisolar默認使用立春換歲, 當然你也可以自定義換歲的節(jié)氣。

生肖：生肖與十二地支是對應的，所以實際上生肖也是按節(jié)氣更換，所以生肖默認也是按立春更換。

另外，根據(jù) 中國大陸國家標準：編號GB/T 33661-2017 『農歷的編算和頒行』規(guī)定,

“干支紀年的循環(huán)參考時間：對應于北京時間公歷1984年2月2日0時起到1985年2月19日24時截止的農歷年為甲子年。”

如按此標準的話，應該正月初一換歲，即生肖在正月初一更換。 這樣的好處是方便大眾記憶與使用，但與傳統(tǒng)術數(shù)的計算方式有所沖突，對術數(shù)并無任何指導意義。 由于大部分術數(shù)系統(tǒng)并不以正月初一換歲，所以lunisolar默認并不跟隨此標準進行換歲（雖然可以通過配置設置成與國標一致，但不建議）。

子時是每一天的開始，子時對應的時間為 [23:00, 01:00), 為了方便一天的時辰吉兇計算，所以lunisolar會在23:00進行換日。

Tips

子時作為一天的第一個時辰，究竟是以子時正中（0:00）換日，還是以23：00作為換日？這種爭論從古時一直便有，八字也因此有 “區(qū)分早晚子時” 和 “不區(qū)分早晚子時” 的兩派。lunisolar的八字工具暫時會以23:00換日，日后會考慮在新版本的八字增強插件中增加區(qū)分此兩派的設置選項。

moment.jsopen in new window 和 dayjsopen in new window 是兩個比較出名的時間工具庫，為了符合大家的使用習慣，lunisolar針對公歷的部分作將會盡量向dayjs看齊，并參考了其代碼設計。針對公歷部分，盡管lunisolar也有類似dayjs的方法，但并不會cover其所有功能，如果你僅僅是對公歷進行作，推薦使用dayjs。lunisolar重點在于農歷部分，例如Lunisolar的format方法和diff方法包含dayjs這兩個方法的功能并與之保持一致，同時加入了對農歷的處理，具體功能及使用請繼續(xù)閱讀文檔。

lunisloar采用面向對象開發(fā)，下圖可以幫助了解各個對象關系。