# time.lunar 库模块帮助文档

<details>  <summary>必读</summary>  <p>

## 农历格式化语法

time.lunar 对象兼容 time 对象的格式化语法。
并格外支持 %L 前缀的农历格式化语法，示例：

~~~aardio
tostring(time.lunar(),"%Ly年(生肖:%LY)%Lm%Ld %LH时")
~~~

格式化参数为 `tostring(timeLunarObject,format,language)`   

省略 format 参数则使用的默认输出格式为 `%Ly年%Lm%Ld`。 
省略 language 参数则默认为 `chs` 。  

time.lunar 对象的使用 `%y-%m-%d` 会输出公历日期（数值格式），
而使用 `%Lyyyy-%Lmm-%Ldd` 会输出农历日期（数值格式）。
格式串 `%Ly年%Lm%Ld` 则会输出中文农历日期。

可选使用 time.lunar 对象的 format 属性自定义默认的输出格式串。
format 也可以作为 `timeLunarObject.format(format,language)` 格式（ownerCall 格式）的方法调用，所有参数可选。

## 关于农历节气

aardio 标准库 time.lunar 提供农历月历（阴历）相关接口，
而标准库 time.sun 则提供农历二十四节气（太阳历）接口。

> 获取农历节气请使用 `time.sun.getSolarTerm(year, nameOrLongitude)` 函数。

农历（阴阳合历）
├── 阴历部分（月亮历） 
│   ├── 朔望月：根据月相确定月份（初一=朔日）
│   ├── 大小月：大月30天，小月29天
│   └── 闰月：协调阴历年与回归年的差异
│
└── 阳历部分（太阳历）
    ├── 二十四节气：根据太阳黄经位置确定
    ├── 节气定月：以中气定月份归属
    └── 指导农事：反映季节变化

</p></details>

[使用范例](https://www.aardio.com/zh-cn/doc/example/Languages/dotNet/Advanced/lunar.html)

## time 成员列表 <a id="time" href="#time">&#x23;</a>

### time.lunar() <a id="time.lunar" href="#time.lunar">&#x23;</a>
[返回对象:TimeLunarObject](#TimeLunarObject)

### time.lunar(dateTime,...) <a id="time.lunar" href="#time.lunar">&#x23;</a>
解析指定公历时间并返回对应的农历时间对象。  
- 参数 @dateTime 可使用 time 对象、.NET DateTime 对象或日期字符串指定公历时间。  
如果参数 @dateTime 不是 time 对象或 .NET DateTime 对象则将所有参数传给 time 构造函数以创建 time 对象。  
指定字符串时可兼容 `%H:%M:%S`,`%H:%M`,`%H` 格式的时间部分（可自右向左省略秒、分、时）。  

此函数失败返回 null。

### time.lunar(year,month,day,isLeap) <a id="time.lunar" href="#time.lunar">&#x23;</a>
直接指定农历日期并返回农历时间对象。  

- 参数 @year 指定农历年份（数值）。  
- 参数 @month 指定农历月份（1-12）。  
- 参数 @day 指定农历日（1-30）。  
- 参数 @isLeap 可选指定是否为闰月，默认为 false。

## time.lunar 成员列表 <a id="time.lunar" href="#time.lunar">&#x23;</a>

农历月历支持库。  
相关库 time.sun （农历节气，太阳历）。  
 time.julianDay （儒略日）

创建农历时间对象。  
返回对象可作为 tostring 函数的参数转为农历日期完整格式，  
传入 tonumber 可转为 Unix 时间戳（单位秒）。  

Windows7(.NET 2.0) 开始自带此组件

### time.lunar.is() <a id="time.lunar.is" href="#time.lunar.is">&#x23;</a>
检测参数 @1 是否 time.lunar 对象。

### time.lunar.toSolar <a id="time.lunar.toSolar" href="#time.lunar.toSolar">&#x23;</a>
将农历日期转换为公历日期。

### time.lunar.toSolar() <a id="time.lunar.toSolar" href="#time.lunar.toSolar">&#x23;</a>
[返回对象:timeObject](https://www.aardio.com/zh-cn/doc/library-reference/time/_.html#timeObject)

### time.lunar.toSolar(dateString) <a id="time.lunar.toSolar" href="#time.lunar.toSolar">&#x23;</a>
参数 @dateString 可指定 `2026-01-30` 格式的短日期字符串（农历日期）。  
短日期之后也可以指定 `%H:%M:%S`,`%H:%M`,`%H` 格式的时间部分（可自右向左省略秒、分、小时）。

### time.lunar.toSolar(dateTime) <a id="time.lunar.toSolar" href="#time.lunar.toSolar">&#x23;</a>
参数可指定任何包含 year,month,day 字段的表对象。  
忽略参数 @dateTime 存储的实际时间并提取 year,month,day 字段作为参数（视为农历日期）

### time.lunar.toSolar(year,month,day,isLeap) <a id="time.lunar.toSolar" href="#time.lunar.toSolar">&#x23;</a>
- 参数 @year 指定农历年份（数值）。  
- 参数 @month 指定农历月份（1-12）。  
- 参数 @day 指定农历日（1-30）。  
- 参数 @isLeap 可选指定是否为闰月，默认为 false。  

成功返回 time 对象，失败返回 null 及错误信息。

## TimeLunarObject 成员列表 <a id="TimeLunarObject" href="#TimeLunarObject">&#x23;</a>

### TimeLunarObject.addDays() <a id="TimeLunarObject.addDays" href="#TimeLunarObject.addDays">&#x23;</a>
添加参数 @1 指定的天数（可为正值或负值）。  
此函数不会修改当前对象，而是返回新的 time.lunar 对象。

[返回对象:TimeLunarObject](#TimeLunarObject)

### TimeLunarObject.addMonths() <a id="TimeLunarObject.addMonths" href="#TimeLunarObject.addMonths">&#x23;</a>
添加参数 @1 指定的月份数（可为正值或负值）。  
此函数不会修改当前对象，而是返回新的 time.lunar 对象。

[返回对象:TimeLunarObject](#TimeLunarObject)

### TimeLunarObject.addYears() <a id="TimeLunarObject.addYears" href="#TimeLunarObject.addYears">&#x23;</a>
添加参数 @1 指定的年份数（可为正值或负值）。  
此函数不会修改当前对象，而是返回新的 time.lunar 对象。

[返回对象:TimeLunarObject](#TimeLunarObject)

### TimeLunarObject.dateTime <a id="TimeLunarObject.dateTime" href="#TimeLunarObject.dateTime">&#x23;</a>
System.DateTime 对象

### TimeLunarObject.day <a id="TimeLunarObject.day" href="#TimeLunarObject.day">&#x23;</a>
农历日

### TimeLunarObject.dayName <a id="TimeLunarObject.dayName" href="#TimeLunarObject.dayName">&#x23;</a>
农历日中文名称，例如 "初一"

### TimeLunarObject.diffDays(lunarOrTime) <a id="TimeLunarObject.diffDays" href="#TimeLunarObject.diffDays">&#x23;</a>
用当前对象指定参数 @lunarOrTime   
指定的 time.lunar 对象或 time 对象。  
返回相差的天数。

### TimeLunarObject.format <a id="TimeLunarObject.format" href="#TimeLunarObject.format">&#x23;</a>
可选指定默认的输出格式串。  
支持 time 对象的所有格式化语法，额外支持 `%L` 前缀的农历格式码。  

可使用 tostring 将 time.lunar 对象（作为第一个参数）转换为字符串。  
可选用 tostring 的第 2 个参数指定 format 参数（不改变对象的 format 属性）。  
如果未指定 format 参数则此 format 属性为第 2 个参数的默认值。  

如果在 time.lunar 的第 2 个构造参数里指定了时间格式串，  
则该格式串仅用于解析输入的时间字符串，与这里控制输出的 format 属性无关。  

format 也可以作为方法调用（ownerCall 格式，参数 1 可选指定格式串）。

### TimeLunarObject.getDayOfWeek() <a id="TimeLunarObject.getDayOfWeek" href="#TimeLunarObject.getDayOfWeek">&#x23;</a>
返回星期（数值）。  
0 表示周日，1~6 对应周一到周六。  
也可以在格式化串中用 `%a` 或 `%A`输出星期的文本格式。

### TimeLunarObject.getDayOfYear() <a id="TimeLunarObject.getDayOfYear" href="#TimeLunarObject.getDayOfYear">&#x23;</a>
返当前农历时间是当前农历年的第几天

### TimeLunarObject.getDaysInMonth() <a id="TimeLunarObject.getDaysInMonth" href="#TimeLunarObject.getDaysInMonth">&#x23;</a>
返回当前农历月份的总天数

### TimeLunarObject.getDaysInYear() <a id="TimeLunarObject.getDaysInYear" href="#TimeLunarObject.getDaysInYear">&#x23;</a>
返回当前农历年份的总天数

### TimeLunarObject.getMonthsInYear() <a id="TimeLunarObject.getMonthsInYear" href="#TimeLunarObject.getMonthsInYear">&#x23;</a>
返回当前农历年的月份总数

### TimeLunarObject.hour <a id="TimeLunarObject.hour" href="#TimeLunarObject.hour">&#x23;</a>
小时

### TimeLunarObject.hourFullName <a id="TimeLunarObject.hourFullName" href="#TimeLunarObject.hourFullName">&#x23;</a>
农历时辰完整名称，例如 "子时"

### TimeLunarObject.hourName <a id="TimeLunarObject.hourName" href="#TimeLunarObject.hourName">&#x23;</a>
农历时辰名称，例如 "子"

### TimeLunarObject.isLeapMonth <a id="TimeLunarObject.isLeapMonth" href="#TimeLunarObject.isLeapMonth">&#x23;</a>
是否为闰月

### TimeLunarObject.isLeapMonth() <a id="TimeLunarObject.isLeapMonth" href="#TimeLunarObject.isLeapMonth">&#x23;</a>
当前农历时间所在月份是否闰月。

### TimeLunarObject.isLeapYear() <a id="TimeLunarObject.isLeapYear" href="#TimeLunarObject.isLeapYear">&#x23;</a>
当前农历时间所在年份是否闰年

### TimeLunarObject.month <a id="TimeLunarObject.month" href="#TimeLunarObject.month">&#x23;</a>
农历月

### TimeLunarObject.monthFullName <a id="TimeLunarObject.monthFullName" href="#TimeLunarObject.monthFullName">&#x23;</a>
农历月完整中文名称，例如 "正月" 或 "闰五月"

### TimeLunarObject.monthName <a id="TimeLunarObject.monthName" href="#TimeLunarObject.monthName">&#x23;</a>
农历月中文名称，例如 "正"

### TimeLunarObject.solarDay <a id="TimeLunarObject.solarDay" href="#TimeLunarObject.solarDay">&#x23;</a>
公历日

### TimeLunarObject.solarMonth <a id="TimeLunarObject.solarMonth" href="#TimeLunarObject.solarMonth">&#x23;</a>
公历月份

### TimeLunarObject.solarYear <a id="TimeLunarObject.solarYear" href="#TimeLunarObject.solarYear">&#x23;</a>
公历年份

### TimeLunarObject.timestamp <a id="TimeLunarObject.timestamp" href="#TimeLunarObject.timestamp">&#x23;</a>
原始时间戳（秒）

### TimeLunarObject.toSolar() <a id="TimeLunarObject.toSolar" href="#TimeLunarObject.toSolar">&#x23;</a>
返回公历时间（time 对象）  

[返回对象:timeObject](https://www.aardio.com/zh-cn/doc/library-reference/time/_.html#timeObject)

### TimeLunarObject.year <a id="TimeLunarObject.year" href="#TimeLunarObject.year">&#x23;</a>
农历年

### TimeLunarObject.yearName <a id="TimeLunarObject.yearName" href="#TimeLunarObject.yearName">&#x23;</a>
干支年名称，例如 "甲辰"

### TimeLunarObject.zodiac <a id="TimeLunarObject.zodiac" href="#TimeLunarObject.zodiac">&#x23;</a>
生肖名称，例如 "龙"
