DateTime

概述

该分类下的函数通常都支持使用date、datetime、datetimezone作为日期时间计算。

时间的精度为100ns，即一天中的时间范围是00:00:00到23:59:59.9999999。前面说的是理论情况，在实际使用时，不同环境的精度会不同。

注意

由于日期函数能够接受其它类型的值（尤其是datetimezone类型的值），同时还有很多函数的结果会受到计算机、软件或环境设置的影响。
因此，如果你不确定你的业务是否会跨时区，请考虑清楚是否固定区域设置（通常由culture参数设置）。

#datetime

#datetime(
    year as number, month as number, day as number, 
    hour as number, minute as number, second as number
) as datetime

根据输入值返回datetime类型的值。

取值范围：

• 1≤ year ≤ 9999
• 1≤ month ≤ 12
• 1 ≤ day ≤ 31
• 0≤ hour ≤ 23
• 0≤ minute ≤ 59
• 0≤ second < 60

除second之外，其他参数都必须是整数。

参数second最大精度为100ns，另外该参数会被舍入到小数点后7位。因此最大取值不超过59.99999995。

如果输入的指定日期时间不存在会报错。

#datetime(2022, 1, 1, 0, 0, 59.99999994)

#datetime(2022, 1, 1, 0, 0, 59.99999995)

DateTime.AddZone

DateTime.AddZone(
    dateTime as nullable datetime, 
    timezoneHours as number, 
    optional timezoneMinutes as nullable number
) as nullable datetimezone

对dateTime添加时区信息（偏移小时timezoneHours和分钟timezoneMinutes）并返回datetimezone类型的值。

// 2022/1/1 0:00:00 +08:00
DateTime.AddZone(#datetime(2022, 1, 1, 0, 0, 0), 12, 0)

DateTime.Date

DateTime.Date(dateTime as any) as nullable date

以date类型的值的形式返回dateTime中的日期部分。

DateTime.Date(#datetime(2022, 1, 1, 0, 0, 0))

DateTime.FixedLocalNow

DateTime.FixedLocalNow() as datetime

返回修正后的本地当前日期时间。

修正后是指在连续调用时该函数会返回相同的值。

DateTime.LocalNow()始终返回本次调用的本地当前日期时间。

DateTime.FixedLocalNow()

List.Transform(
    {1..5}, 
    each Function.InvokeAfter(
        DateTime.FixedLocalNow, 
        #duration(0, 0, 0, 1)
	)
)

DateTime.From

DateTime.From(
    value as any, 
    optional culture as nullable text
) as nullable datetime

根据给定的值value和可选的区域culture返回日期时间。

value为不同类型时：

• null，返回null。
• text，文本形式的日期时间使用DateTime.FromText计算。
• date，返回日期value和#time(0, 0, 0)的拼接结果。
• datetimezone，返回等效的日期时间部分（根据value和culture的时区信息计算出新的日期时间）。
• number，OLE自动化的日期时间等效的日期时间。
• time，返回#date(1899, 12, 30)（数值0对应的OLE自动化日期）和时间value的拼接结果。

DateTime.FromFileTime

DateTime.FromFileTime(
    fileTime as nullable number
) as nullable datetime

根据值fileTime创建日期时间，该日期时间会被转换为本地时间，即根据本机时区调整日期时间。

fileTime是一个Windows文件的时间值，表示从1601/01/01T00:00:00开始的间隔100ns的间隔数。

// 2012-07-25T05:50:52.9842245
DateTime.FromFileTime(129876402529842245)

等效形式（会有500ns误差）：

// 2012-07-25T05:50:52.9842240
DateTime.From(
    DateTimeZone.ToLocal(#datetimezone(1601, 1, 1, 0, 0, 0, 0, 0)) + 
    	#duration(0, 0, 0, 129876402529842245 / 10000000)
)

DateTime.FromText

DateTime.FromText(
    text as nullable text, 
    optional options as any
) as nullable datetime

根据提供的文本text和可选的参数options返回日期时间。

options可以是不同类型：

• 记录类型，字段名可以是
  • Format，一个文本值，指示如何解析文本日期时间，具体参见标准日期时间格式字符串和自定义日期时间格式字符串。
  • Culture，可为空的文本值，指定文本日期时间的区域。默认使用本机区域（Culture.Current）。
• 文本类型，指示国家地区。

如果有缺失值：

• 日期部分缺失
  • 年使用当前年份。
  • 月使用1月。
  • 日使用1日。
• 日期全部缺失
  • 使用本地日期
• 日期全部或部分缺失时，时、分、秒使用0。

// 2022/1/15 0:00:00
DateTime.FromText("15日", "zh-CN")

// error，hh只能表示1-12的时范围
DateTime.FromText("18日 1516", [Format = "dd日 hhmm"])
// 2022/1/18 15:16:00
DateTime.FromText("18日 1516", [Format = "dd日 HHmm"])

// 2022/1/18 0:00:05
DateTime.FromText("18日5秒", [Format = "dd日s秒"])
// 2022/1/18 0:00:00
DateTime.FromText("18日", [Format = "dd日"])

// 2022/9/20 0:00:15
DateTime.FromText("15秒", [Format = "s秒"])

DateTime.IsInCurrentHour

DateTime.IsInCurrentHour(dateTime as any) as nullable logical

判定dateTime是否是和本地日期时间的年月日时相等。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

DateTime.IsInCurrentHour(#datetime(2022, 12, 3, 23, 0, 0))

DateTime.IsInCurrentHour(#datetimezone(2022, 12, 3, 23, 0, 0, 8, 0))

DateTime.IsInCurrentHour(#date(2022, 12, 3))

DateTime.IsInCurrentMinute

DateTime.IsInCurrentMinute(dateTime as any) as nullable logical

判定dateTime是否是本地日期时间的年月日时分相等。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

DateTime.IsInCurrentMinute(#datetime(2022, 12, 3, 23, 52, 0))

DateTime.IsInCurrentMinute(#datetimezone(2022, 12, 3, 23, 0, 0, 8, 0))

DateTime.IsInCurrentMinute(#date(2022, 12, 3))

DateTime.IsInCurrentSecond

DateTime.IsInCurrentSecond(dateTime as any) as nullable logical

判定dateTime是否是本地日期时间的年月日时分秒相等。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

DateTime.IsInCurrentSecond(#datetime(2022, 12, 3, 23, 52, 0))

DateTime.IsInCurrentSecond(#datetimezone(2022, 12, 3, 23, 0, 0, 8, 0))

DateTime.IsInCurrentSecond(#date(2022, 12, 3))

DateTime.IsInNextHour

DateTime.IsInNextHour(dateTime as any) as nullable logical

判定dateTime是否在本地日期时间的之后一小时范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

DateTime.IsInNextHour(#datetime(2022, 12, 4, 1, 52, 0))

DateTime.IsInNextMinute

DateTime.IsInNextMinute(dateTime as any) as nullable logical

判定dateTime是否在本地日期时间的之后一分钟范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

DateTime.IsInNextMinute(#datetime(2022, 12, 4, 1, 52, 0))

DateTime.IsInNextNHours

DateTime.IsInNextNHours(
    dateTime as any, 
    hours as number
) as nullable logical

判定dateTime是否在本地日期时间的之后一小时到hours小时的范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

参数hours是一个32位整数，可以指定负数或0，但是没有意义。指定浮点数会在dateTime超过本地日期时间时报错。

DateTime.IsInNextNHours(#datetime(2022, 12, 4, 1, 0, 0), 2)

DateTime.IsInNextNHours(#date(2022, 12, 5), 66)

DateTime.IsInNextNMinutes

DateTime.IsInNextNMinutes(
    dateTime as any, 
    minutes as number
) as nullable logical

判定dateTime是否在本地日期时间的之后一分钟到minutes分钟的范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

参数minutes是一个32位整数，可以指定负数或0，但是没有意义。指定浮点数会在dateTime超过本地日期时间时报错。

DateTime.IsInNextNHours(#datetime(2022, 12, 4, 1, 0, 0), 2)

DateTime.IsInNextNHours(#date(2022, 12, 5), 66)

DateTime.IsInNextNSeconds

DateTime.IsInNextNSeconds(
    dateTime as any, 
    seconds as number
) as nullable logical

判定dateTime是否在本地日期时间的之后一秒到seconds秒的范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

参数seconds是一个32位整数，可以指定负数或0，但是没有意义。指定浮点数会在dateTime超过本地日期时间时报错。

DateTime.IsInNextNSeconds(#datetime(2022, 12, 4, 1, 0, 0), 2)

DateTime.IsInNextNSeconds(#date(2022, 12, 5), 66)

DateTime.IsInNextSecond

DateTime.IsInNextSecond(dateTime as any) as nullable logical

判定dateTime是否在本地日期时间的之后一秒范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

DateTime.IsInNextSecond(#datetime(2022, 12, 4, 1, 52, 0))

DateTime.IsInPreviousHour

DateTime.IsInPreviousHour(dateTime as any) as nullable logical

判定dateTime是否在本地日期时间的之前一小时范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

DateTime.IsInPreviousHour(#datetime(2022, 12, 4, 1, 52, 0))

DateTime.IsInPreviousMinute

DateTime.IsInPreviousMinute(dateTime as any) as nullable logical

判定dateTime是否在本地日期时间的之前一分钟范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

DateTime.IsInPreviousMinute(#datetime(2022, 12, 4, 1, 52, 0))

DateTime.IsInPreviousNHours

DateTime.IsInPreviousNHours(
    dateTime as any, 
    hours as number
) as nullable logical

判定dateTime是否在本地日期时间的之前一小时到hours小时的范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

参数hours是一个32位整数，可以指定负数或0，但是没有意义。指定浮点数会报错。

DateTime.IsInPreviousNHours(#datetime(2022, 12, 4, 1, 0, 0), 2)

DateTime.IsInPreviousNHours(#date(2022, 12, 5), 66)

DateTime.IsInPreviousNMinutes

DateTime.IsInPreviousNMinutes(
    dateTime as any,
    minutes as number
) as nullable logical

判定dateTime是否在本地日期时间的之前一小时到minutes小时的范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

参数minutes是一个32位整数，可以指定负数或0，但是没有意义。指定浮点数会报错。

DateTime.IsInPreviousNMinutes(#datetime(2022, 12, 4, 1, 0, 0), 2)

DateTime.IsInPreviousNMinutes(#date(2022, 12, 5), 66)

DateTime.IsInPreviousNSeconds

DateTime.IsInPreviousNSeconds(
    dateTime as any, 
    seconds as number
) as nullable logical

判定dateTime是否在本地日期时间的之前一小时到seconds小时的范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

参数seconds是一个32位整数，可以指定负数或0，但是没有意义。指定浮点数会报错。

DateTime.IsInPreviousNSeconds(#datetime(2022, 12, 4, 1, 0, 0), 2)

DateTime.IsInPreviousNSeconds(#date(2022, 12, 5), 66)

DateTime.IsInPreviousSecond

DateTime.IsInPreviousSecond(dateTime as any) as nullable logical

判定dateTime是否在本地日期时间的之前一秒范围内。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)。
• time：因为缺失日期部分并且系统日期设置范围有限，因此可以认为始终为false。

DateTime.IsInPreviousSecond(#datetime(2022, 12, 4, 1, 52, 0))

DateTime.LocalNow

DateTime.LocalNow() as datetime

返回本地当前日期时间。

DateTime.FixedLocalNow()在连续调用时始终返回相同值，而DateTime.LocalNow返回实时值。

List.Transform(
    {1..5}, 
    each Function.InvokeAfter(
        DateTime.LocalNow, 
        #duration(0, 0, 0, 1)
    )
)

DateTime.Time

DateTime.Time(dateTime as any) as nullable time

以time类型的值的形式返回dateTime的时间部分。

DateTime.Time(#datetime(2022, 12, 4, 1, 52, 0))

DateTime.ToRecord

DateTime.ToRecord(
    dateTime as datetime
) as record

将日期时间值dateTime的转换成记录，记录的字段名是日期时间的各部分。

DateTime.ToText

DateTime.ToText(
    dateTime as nullable datetime, 
    optional options as any, 
    optional culture as nullable text
) as nullable text

根据日期dateTime返回日期的文本，文本结果会考虑参数options和culture。

options可以是不同类型：

• 记录类型，字段名可以是
  • Format，一个文本值，格式化文本字符串，具体参见标准日期时间格式字符串和自定义日期时间格式字符串。
  • Culture，可为空的文本值，指定文本日期时间的区域。默认使用本机区域（Culture.Current）。
• 文本类型，一个文本值，指示如何解析文本日期时间。等同Format字段的意思。

culture用于指定区域，默认为本机区域。该参数仅可用于传统工作流。如果options为记录，将会忽略culture参数。

如果格式化文本需要输出时区，不会使用设置的区域，而是使用本机区域的时区。

当options为记录时，无法使用时区格式字符串。

// 04:05:06+08:00
DateTime.ToText(#datetime(2022, 2, 3, 4, 5, 6), "HH:mm:sszzz")
// error 无法使用指定格式将文本值转换为 datetime。该格式包括 时区 组件。
DateTime.ToText(#datetime(2022, 2, 3, 4, 5, 6), [Format="HH:mm:sszzz", Culture="en-US"])