DateTimeZone

概述

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

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

注意

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

#datetimezone

#datetimezone(
    year as number, month as number, day as number, 
    hour as number, minute as number, second as number, 
    offsetHours as number, offsetMinutes as number
) as datetimezone

取值范围：

• 1≤ year ≤ 9999
• 1≤ month ≤ 12
• 1 ≤ day ≤ 31
• 0≤ hour ≤ 23
• 0≤ minute ≤ 59
• 0≤ second < 60
• -14≤ offsetHours + offsetMinutes / 60 < 14

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

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

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

#datetimezone(2022, 1, 1, 1, 1, 1, 1.5, 30)

DateTimeZone.FixedLocalNow

DateTimeZone.FixedLocalNow() as datetimezone

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

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

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

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

DateTimeZone.FixedUtcNow

DateTimeZone.FixedUtcNow() as datetimezone

返回修正后的UTC+0:00时区（GMT时区）当前带时区的日期时间。

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

DateTimeZone.UTCNow()始终返回本次调用的UTC+0:00时区（GMT时区）当前带时区的日期时间。

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

DateTimeZone.From

DateTimeZone.From(
    value as any, 
    optional culture as nullable text
) as nullable datetimezone

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

value为不同类型时：

• null，返回null。
• text，文本形式的日期时间使用DateTimeZone.FromText计算。
• date，返回日期value和#time(0, 0, 0)的拼接结果，并修正为本机时区的日期时间。
• datetime，返回日期时间部分，并修正为本机时区的日期时间。
• number，OLE自动化的日期时间等效的日期时间，并修正为本机时区的日期时间。
• time，返回#date(1899, 12, 30)（数值0对应的OLE自动化日期）和时间value的拼接结果，并修正为本机时区的日期时间。

DateTimeZone.FromFileTime

DateTimeZone.FromFileTime(fileTime as nullable number) as nullable datetimezone

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

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

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

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

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

DateTimeZone.FromText

DateTimeZone.FromText(
    text as nullable text, 
    optional options as any
) as nullable datetimezone

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

options可以是不同类型：

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

如果有缺失值：

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

// 2022-09-15T12:34:59.6789000+08:30
DateTimeZone.FromText("2022-09-15T12:34:59.6789+08:30")

// 2022/1/15 0:00:00 +08:00
DateTimeZone.FromText("今天是15日", [Format = "今天是d日"])

// 2022/9/20 0:00:00 +08:30
DateTimeZone.FromText("时区是+8:30", [Format = "时区是zzz"])
DateTimeZone.FromText("时区是+08:30", [Format = "时区是zzz"])
DateTimeZone.FromText("时区是+0830", [Format = "时区是zzz"])

// 2022/1/1 0:00:00 +08:30
DateTimeZone.FromText("2022时区是+8:30", [Format = "yyyy时区是zzz"])

// error
DateTimeZone.FromText("时区是+830", [Format = "时区是zzz"])
DateTimeZone.FromText("时区是8:30", [Format = "时区是zzz"])
DateTimeZone.FromText("时区是08:30", [Format = "时区是zzz"])

DateTimeZone.LocalNow

DateTimeZone.LocalNow() as datetimezone

返回本地当前带时区的日期时间。

DateTimeZone.FixedLocalNow()在连续调用时始终返回相同的值。

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

DateTimeZone.RemoveZone

DateTimeZone.RemoveZone(
    dateTimeZone as nullable datetimezone
) as nullable datetime

将dateTimeZone中的时区信息删除并返回datetime类型的值。

DateTimeZone.RemoveZone(DateTimeZone.LocalNow())

DateTimeZone.SwitchZone

DateTimeZone.SwitchZone(
    dateTimeZone as nullable datetimezone, 
    timezoneHours as number, 
    optional timezoneMinutes as nullable number
) as nullable datetimezone

根据新的时区信息timezoneHours和timezoneMinutes，将dateTimeZone的时区信息重新设置。

设置新的时区可能还会影响日期时间部分。

DateTimeZone.SwitchZone(DateTimeZone.LocalNow(), -8)

DateTimeZone.ToLocal

DateTimeZone.ToLocal(dateTimeZone as nullable datetimezone) as nullable datetimezone

将带时区的日期时间值dateTimeZone的时区修正为本地时区。

会修正时区和日期时间。

// 2022/2/3 7:05:06 +08:00
DateTimeZone.ToLocal(#datetimezone(2022, 2, 3, 4, 5, 6, 5, 0))

DateTimeZone.ToRecord

DateTimeZone.ToRecord(dateTimeZone as datetimezone) as record

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

/*
[
	Year = 2022, Month = 2, Day = 3, 
	Hour = 4, Minute = 5, Second = 6, 
	ZoneHours = 5, ZoneMinutes = 0
]
*/
DateTimeZone.ToRecord(#datetimezone(2022, 2, 3, 4, 5, 6, 5, 0))

DateTimeZone.ToText

DateTimeZone.ToText(
    dateTimeZone as nullable datetimezone, 
    optional options as any, 
    optional culture as nullable text
) as nullable text

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

options可以是不同类型：

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

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

// 04:05:06+05:00
DateTimeZone.ToText(#datetimezone(2022, 2, 3, 4, 5, 6, 5, 0), "HH:mm:sszzz")

DateTimeZone.ToUtc

DateTimeZone.ToUtc(dateTimeZone as nullable datetimezone) as nullable datetimezone

将带时区的日期时间的值dateTimeZone转换为UTC时区（UTC0）。

// 2022/2/2 23:05:06 +00:00
DateTimeZone.ToUtc(#datetimezone(2022, 2, 3, 4, 5, 6, 5, 0))

DateTimeZone.UtcNow

DateTimeZone.UtcNow() as datetimezone

返回UTC+0:00时区（GMT时区）当前带时区的日期时间。

DateTimeZone.FixedUTCNow()在连续调用时始终返回相同值。

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

DateTimeZone.ZoneHours

DateTimeZone.ZoneHours(
    dateTimeZone as nullable datetimezone
) as nullable number

返回dateTimeZone的时区信息中的小时部分。

DateTimeZone.ZoneHours(DateTimeZone.LocalNow())

DateTimeZone.ZoneMinutes

DateTimeZone.ZoneMinutes(
    dateTimeZone as nullable datetimezone
) as nullable number

返回dateTimeZone的时区信息中的分钟部分。

DateTimeZone.ZoneMinutes(DateTimeZone.LocalNow())