imported>InstantNull 来自 2023年7月30日 (日) 00:46

2023-07-30T00:46:14Z

新页面

{{high-use|91898}}
本模块为其他模块提供日期相关的函数。目前支持[[公历]]和[[儒略曆]]的日期，有效范围从公元前999年至公元9999年。使用的日期都应当是[[前公历|公历前推的]]，也就是说所有的时间都是唯一且确定的。

日期，包含可选的时间，可以用多种格式指定，并且可以通过多种格式进行显示转换，例如：1 April 2016 或 April 1, 2016。一个日期的属性包括它的儒略日期和公历序列日期，以及星期几和一年中的第几天。

日期是可比的（例如，<code>date1 <= date2</code>），并且可以相加或相减（例如，<code>date + '3 months'</code>）。两个日期之间的差异可以通过 <code>date1 - date2</code> 来确定。这些操作适用于公历和儒略历日期，但如果两个日期混用不同的历法，<code>date1 - date2</code> 将为空。

该模块提供以下内容：

{| class="wikitable"
! 模块导出 !! 描述
|-
| <code>_current</code> || 包含当前年月日时分秒的表（table）
|-
| <code>_Date</code> || 返回包含指定日期的表（table）的函数
|-
| <code>_days_in_month</code> || 返回某个月的天数的函数
|}

== 格式化输出 ==
日期可以以文字形式输出：
<syntaxhighlight lang="lua">
local Date = require('Module:Date')._Date
local text = Date(2016, 7, 1):text() -- 输出 '1 July 2016'
local text = Date(2016, 7, 1):text('%-d %B') -- 输出 '1 July'
local text = Date('1 July 2016'):text('mdy') -- 输出 'July 1, 2016'
</syntaxhighlight>

模块提供了下列格式代码简写：
{| class="wikitable"
! 代码 !! 结果
|-
| hm || hour:minute, 包含"am"或"pm" or variant, if specified (14:30 or 2:30 pm or variant)
|-
| hms || hour:minute:second (14:30:45)
|-
| ymd || year-month-day (2016-07-01)
|-
| mdy || month day, year (July 1, 2016)
|-
| dmy || day month year (1 July 2016)
|}

以下格式化代码（类似于C语言的 [[time.h#时间日期数据的格式化函数|strftime]]）可用于格式化输出日期：
{| class="wikitable"
! 代码 !! 结果
|-
| %a || Day abbreviation: Mon, Tue, ...
|-
| %A || Day name: Monday, Tuesday, ...
|-
| %u || Day of week: 1 to 7 (Monday to Sunday)
|-
| %w || Day of week: 0 to 6 (Sunday to Saturday)
|-
| %d || Day of month zero-padded: 01 to 31
|-
| %b || Month abbreviation: Jan to Dec
|-
| %B || Month name: January to December
|-
| %m || Month zero-padded: 01 to 12
|-
| %Y || Year zero-padded: 0012, 0120, 1200
|-
| %H || Hour 24-hour clock zero-padded: 00 to 23
|-
| %I || Hour 12-hour clock zero-padded: 01 to 12
|-
| %p || AM or PM or as in options
|-
| %M || Minute zero-padded: 00 to 59
|-
| %S || Second zero-padded: 00 to 59
|-
| %j || Day of year zero-padded: 001 to 366
|-
| %-d || Day of month: 1 to 31
|-
| %-m || Month: 1 to 12
|-
| %-Y || Year: 12, 120, 1200
|-
| %-H || Hour: 0 to 23
|-
| %-M || Minute: 0 to 59
|-
| %-S || Second: 0 to 59
|-
| %-j || Day of year: 1 to 366
|-
| %-I || Hour: 1 to 12
|-
| %% || %
|}

此外，可以使用<code>%{''property''}</code>（其中 <code>''property''</code> 是日期的任何属性）来进行格式化。

例如，<code>Date('1 Feb 2015 14:30:45 A.D.')</code> 具有以下属性：

{| class="wikitable"
! 代码 !! 结果
|-
| %{calendar} || Gregorian
|-
| %{year} || 2015
|-
| %{month} || 2
|-
| %{day} || 1
|-
| %{hour} || 14
|-
| %{minute} || 30
|-
| %{second} || 45
|-
| %{dayabbr} || Sun
|-
| %{dayname} || Sunday
|-
| %{dayofweek} || 0
|-
| %{dow} || 0 (same as dayofweek)
|-
| %{dayofweekiso} || 7
|-
| %{dowiso} || 7 (same as dayofweekiso)
|-
| %{dayofyear} || 32
|-
| %{era} || A.D.
|-
| %{gsd} || 735630 (numbers of days from 1 January 1 CE; the first is day 1)
|-
| %{juliandate} || 2457055.1046875 ([[Julian day]])
|-
| %{jd} || 2457055.1046875 (same as juliandate)
|-
| %{isleapyear} || false
|-
| %{monthdays} || 28
|-
| %{monthabbr} || Feb
|-
| %{monthname} || February
|}

一些快捷方式也是可用的。给定 <code>date = Date('1 Feb 2015 14:30')</code>，将产生以下结果：
{| class="wikitable"
! 代码 !! 描述 !! 结果 !! 等同于
|-
| date:text('%c') || date and time || 2:30 pm 1 February 2015 || %-I:%M %p %-d %B %-Y %{era}
|-
| date:text('%x') || date || 1 February 2015 || %-d %B %-Y %{era}
|-
| date:text('%X') || time || 2:30 pm || %-I:%M %p
|}

== 儒略日期 ==

下面是一个将儒略日期转换为日期，并获取日期信息的示例：
<syntaxhighlight lang="lua">
-- 代码 -- 结果
Date = require('Module:Date')._Date
date = Date('juliandate', 320)
number = date.gsd -- -1721105
number = date.jd -- 320
text = date.dayname -- Saturday
text = date:text() -- 9 October 4713 BC
text = date:text('%Y-%m-%d') -- 4713-10-09
text = date:text('%{era} %Y-%m-%d') -- BC 4713-10-09
text = date:text('%Y-%m-%d %{era}') -- 4713-10-09 BC
text = date:text('%Y-%m-%d %{era}', 'era=B.C.E.') -- 4713-10-09 B.C.E.
text = date:text('%Y-%m-%d', 'era=BCNEGATIVE') -- -4712-10-09
text = date:text('%Y-%m-%d', 'era=BCMINUS') -- −4712-10-09 (uses Unicode MINUS SIGN U+2212)
text = Date('juliandate',320):text('%{gsd} %{jd}') -- -1721105 320
text = Date('Oct 9, 4713 B.C.E.'):text('%{gsd} %{jd}') -- -1721105 320
text = Date(-4712,10,9):text('%{gsd} %{jd}') -- -1721105 320
</syntaxhighlight>

== 日期差 ==
两个日期之间的差值可以通过 <code>date1 - date2</code> 来确定。如果两个日期都使用公历或儒略历，那么计算的结果是有效的；如果两个日期使用不同的历法，那么计算的结果将为空值。日期差异可以被用于计算年龄和时间间隔。

例子：
<syntaxhighlight lang="lua">
-- 代码 -- 结果
Date = require('Module:Date')._Date
date1 = Date('21 Mar 2015')
date2 = Date('4 Dec 1999')
diff = date1 - date2
d = diff.age_days -- 5586
y, m, d = diff.years, diff.months, diff.days -- 15, 3, 17 (15 years + 3 months + 17 days)
y, m, d = diff:age('ymd') -- 15, 3, 17
y, m, w, d = diff:age('ymwd') -- 15, 3, 2, 3 (15 years + 3 months + 2 weeks + 3 days)
y, m, w, d = diff:duration('ymwd') -- 15, 3, 2, 4
d = diff:duration('d') -- 5587 (duration 包含最后一天)
</syntaxhighlight>

日期差包含原始的日期，只是它们可能被交换以满足 <code>diff.date1 >= diff.date2</code> 的条件（其中 <code>diff.date1</code> 是较靠后的日期）。以下是示例说明：
<syntaxhighlight lang="lua">
date1 = Date('21 Mar 2015')
date2 = Date('4 Dec 1999')
diff = date1 - date2
neg = diff.isnegative -- false
text = diff.date1:text() -- 21 March 2015
text = diff.date2:text() -- 4 December 1999
diff = date2 - date1
neg = diff.isnegative -- true (日期被交换了)
text = diff.date1:text() -- 21 March 2015
text = diff.date2:text() -- 4 December 1999
</syntaxhighlight>

除了包含日期之间的差，还包含时间之间的差：
<syntaxhighlight lang="lua">
date1 = Date('8 Mar 2016 0:30:45')
date2 = Date('19 Jan 2014 22:55')
diff = date1 - date2
y, m, d = diff.years, diff.months, diff.days -- 2, 1, 17
H, M, S = diff.hours, diff.minutes, diff.seconds -- 1, 35, 45
</syntaxhighlight>

日期差值可以被加到一个日期上，也可以从一个日期上减去：
<syntaxhighlight lang="lua">
date1 = Date('8 Mar 2016 0:30:45')
date2 = Date('19 Jan 2014 22:55')
diff = date1 - date2
date3 = date2 + diff
date4 = date1 - diff
text = date3:text('ymd hms') -- 2016-03-08 00:30:45
text = date4:text('ymd hms') -- 2014-01-19 22:55:00
equal = (date1 == date3) -- true
equal = (date2 == date4) -- true
</syntaxhighlight>

年龄和时间间隔的日期差可以接受一个代码，用于指定需要返回的日期间隔组成部分。对于时间间隔，会额外包含一天，因为它包含了最后一天：
{| class="wikitable"
! 代码 !! 返回值
|-
| <code>'ymwd'</code> || years, months, weeks, days
|-
| <code>'ymd'</code> || years, months, days
|-
| <code>'ym'</code> || years, months
|-
| <code>'y'</code> || years
|-
| <code>'m'</code> || months
|-
| <code>'wd'</code> || weeks, days
|-
| <code>'w'</code> || weeks
|-
| <code>'d'</code> || days
|}
<includeonly>{{Sandbox other||


}}</includeonly>

Module:Date/doc - 版本历史

imported>InstantNull 来自 2023年7月30日 (日) 00:46