DateTime

显示已弃用

*此内容使用人工智能（Beta）翻译，可能包含错误。若要查看英文页面，请点按 此处。

DateTime 数据类型使用 Unix 时间戳表示一个时刻。 它可以用于在特定区域轻松格式化日期和时间。当转换为字符串时，返回存储的时间戳整数的字符串转换。它们不存储时区值。相反，在构造和使用 DateTime 对象时考虑时区。

DateTime 对象相等的条件是其 UnixTimestampMillis 属性相等。

时间值表

ToUniversalTime() 和 ToLocalTime() 方法返回一个时间相关值的表，例如 Year、Month 和 Day。这些函数返回的表格格式描述如下，每个整数元素按大小顺序排列。

名称范围备注
Year1400–9999—
Month1–12—
Day1–31—
Hour0–23—
Minute0–59—
Second0–60通常为 0–59，有时为 60，以适应某些系统中的闰秒。
Millisecond0–999—

字符串格式

DateTime 对象通过 FormatUniversalTime() 和 FormatLocalTime() 方法支持将日期/时间转换为字符串。它们的工作方式相同，只是解释的时区不同。

传递给这些方法的第一个参数必须是表示下列标记之一的字符串。然后根据提供的区域替换标记为特定值。

local dt = DateTime.now()



-- "dddd" 标记被替换为完整的星期几

print("今天是 " .. dt:FormatLocalTime("dddd", "en-us"))



-- 对于 "en-us" 区域，"LL" 标记等于 "MMMM D, YYYY"

print("日期是 " .. dt:FormatLocalTime("LL", "en-us"))
复合标记

根据区域，这些标记替换为 特定组合 的 基本标记，如下一节所述。这会根据区域产生正确的日期/时间字符串。例如，在英语中，日期的格式为 "[month] [day]"，如 "June 11"。在法语中，日期的格式为 "[day] [month]"，如 "11 juin"。这些特殊规则通过以下复合标记自动处理，因此如果您显示简单的时间和/或日期信息，请使用这些标记。

标记区域示例（格式）
时间
LT
en-us : 8:30 PM (h:mm A)
zh-cn : 20:30 (HH:mm)
带秒的时间
LTS
en-us : 8:30:25 PM (h:mm:ss A)
zh-cn : 20:30:25 (HH:mm:ss)
月份（数字）、日期、年份
L
en-us : 09/04/1986 (MM/DD/YYYY)
zh-cn : 1986/09/04 (YYYY/MM/DD)
l
en-us : 9/4/1986 (M/D/YYYY)
zh-cn : 1986/9/4 (YYYY/M/D)
月份（名称）、日期、年份
LL
en-us : September 4, 1986 (MMMM D, YYYY)
zh-cn : 1986年9月4日 (YYYY年M月D日)
ll
en-us : Sep 4, 1986 (MMM D, YYYY)
zh-cn : 1986年9月4日 (YYYY年M月D日)
月份（名称）、日期、年份、时间
LLL
en-us : September 4, 1986 8:30 PM (MMMM D, YYYY h:mm A)
zh-cn : 1986年9月4日晚上8点30分 (YYYY年M月D日Ah点mm分)
lll
en-us : Sep 4, 1986 8:30 PM (MMM D, YYYY h:mm A)
zh-cn : 1986年9月4日 20:30 (YYYY年M月D日 HH:mm)
星期几、月份（名称）、日期、年份、时间
LLLL
en-us : Thursday, September 4, 1986 8:30 PM (dddd, MMMM D, YYYY h:mm A)
zh-cn : 1986年9月4日星期四晚上8点30分 (YYYY年M月D日ddddAh点mm分)
llll
en-us : Thu, Sep 4, 1986 8:30 PM (ddd, MMM D, YYYY h:mm A)
zh-cn : 1986年9月4日星期四 20:30 (YYYY年M月D日dddd HH:mm)
基本标记

这些标记分别替换为 单个值 并可用作更大时间字符串的元素。如果您只需要简单的日期和时间信息，则避免使用这些，因为 复合标记 更适合这些目的。

标记示例
年份
YY70、71、…、29、30
YYYY1970、1971、…、2029、2030
月份
M1、2、…、11、12
MM01、02、…、11、12
MMMJan、Feb、…、Nov、Dec
MMMMJanuary、February、…、November、December
日期
D1、2、…、30、31
DD01、02、…、30、31
一年中的天数
DDD1、2、…、364、365
DDDD001、002、…、364、365
星期几
d0、1、…、5、6
ddSu、Mo、…、Fr、Sa
dddSun、Mon、…、Fri、Sat
ddddSunday、Monday、…、Friday、Saturday
小时
H0、1、…、22、23
HH00、01、…、22、23
h1、2、…、11、12
hh01、02、…、11、12
分钟
m0、1、…、58、59
mm00、01、…、58、59
秒
s0、1、…、58、59
ss00、01、…、58、59
分数秒
S0、1、…、8、9
SS00、01、…、98、99
SSS000、001、…、998、999
AM/PM
A
en-us : AM、PM
zh-cn : 凌晨|早上|上午|中午|下午|晚上
a
en-us : am、pm
zh-cn : 凌晨|早上|上午|中午|下午|晚上

概要

构造工具

属性

方法

构造工具

now

返回一个新的 DateTime，表示当前时刻，使用设备的本地时钟。大多数操作系统会自动将其本地时间与在线时间服务器同步，因此这应该在几百毫秒内。然而，用户可以轻松地禁用同步行为并将系统时间设置为任何他们想要的；对于客户端和服务器之间同步的时间，请使用 Workspace:GetServerTimeNow()。

当您需要精确测量两个时刻之间的经过时间时，比如在测试性能时，请使用 os.clock()。

fromUnixTimestamp

从给定的 Unix 时间戳返回一个新的 DateTime 对象，或自 1970 年 1 月 1 日 00:00（UTC）以来的 秒数。

此函数的粒度仅为 1 秒。要表示亚秒时间戳，请使用 DateTime.fromUnixTimestampMillis()。

参数

unixTimestamp: number

fromUnixTimestampMillis

从给定的 Unix 时间戳返回一个新的 DateTime 对象，或自 1970 年 1 月 1 日 00:00（UTC）以来的 毫秒数。

参数

unixTimestampMillis: number

fromUniversalTime

返回一个使用给定单位从 UTC 时间构造的新 DateTime。接受的值类似于从 ToUniversalTime() 返回的时间值表中找到的值。

  • 产生无效日期的日期单位（年、月、日）将引发错误。例如，1 月 32 日或非闰年的 2 月 29 日。
  • 超出正常范围的时间单位（小时、分钟、秒、毫秒）是有效的。例如，90 分钟将导致小时增加 1；-10 秒将导致分钟数减小 1。
  • 非整数值向下取整。例如，提供 2.5 小时相当于提供 2 小时，而不是 2 小时 30 分钟。
  • 被省略的值将被假定为其正常范围内的最低值，除了年份默认值为 1970。

参数

year: number
默认值：1970
month: number
默认值：1
day: number
默认值：1
hour: number
默认值：0
minute: number
默认值：0
second: number
默认值：0
millisecond: number
默认值：0

fromLocalTime

返回一个使用给定单位从当地时间构造的新 DateTime。接受的值类似于从 ToLocalTime() 返回的时间值表中找到的值。

  • 产生无效日期的日期单位（年、月、日）将引发错误。例如，1 月 32 日或非闰年的 2 月 29 日。
  • 超出正常范围的时间单位（小时、分钟、秒、毫秒）是有效的。例如，90 分钟将导致小时增加 1；-10 秒将导致分钟数减小 1。
  • 非整数值向下取整。例如，提供 2.5 小时相当于提供 2 小时，而不是 2 小时 30 分钟。
  • 被省略的值将被假定为其正常范围内的最低值，除了年份默认值为 1970。

参数

year: number
默认值：1970
month: number
默认值：1
day: number
默认值：1
hour: number
默认值：0
minute: number
默认值：0
second: number
默认值：0
millisecond: number
默认值：0

fromIsoDate

从 ISO 8601 日期时间字符串（以 UTC 时间表示）返回一个 DateTime，例如由 ToIsoDate() 返回的字符串。如果字符串解析失败，函数返回 nil。

一个示例 ISO 8601 日期时间字符串是 2020-01-02T10:30:45Z，表示 2020 年 1 月 2 日上午 10:30 45 秒。

参数

isoDate: string

属性

UnixTimestamp

number

自 1970 年 1 月 1 日 00:00 UTC（Unix 纪元）以来的 秒数。范围是 -17,987,443,200 至 253,402,300,799，大约为 1400–9999 年。

UnixTimestampMillis

number

自 1970 年 1 月 1 日 00:00 UTC（Unix 纪元）以来的 毫秒数。范围是 -17,987,443,200,000 至 253,402,300,799,999，大约为 1400–9999 年。

方法

ToUniversalTime

Dictionary

将此 DateTime 对象的值转换为协调世界时间（UTC）。返回的表格包含以下键： Year、Month、Day、Hour、Minute、Second、Millisecond。有关详细信息，请参阅此数据类型描述中的时间值表。 此表中的值可以传递给 fromUniversalTime() 以生成原始的 DateTime 对象。

返回

Dictionary

ToLocalTime

Dictionary

将此 DateTime 对象的值转换为当地时间。返回的表格包含以下键：Year、Month、Day、Hour、Minute、Second、Millisecond。有关详细信息，请参阅此数据类型描述中的时间值表。此表中的值可以传递给 fromLocalTime() 以生成原始的 DateTime 对象。

返回

Dictionary

ToIsoDate

string

将日期格式化为 ISO 8601 日期时间字符串。此函数返回的值可以传递给 fromIsoDate() 以生成原始的 DateTime 对象。

一个示例 ISO 8601 日期时间字符串是 2020-01-02T10:30:45Z，表示 2020 年 1 月 2 日上午 10:30 45 秒。

返回

string

FormatUniversalTime

string

根据 DateTime 值生成一个字符串，将其视为协调世界时间（UTC）和格式字符串。格式字符串应包含标记，这些标记将替换为 DateTime 对象描述的某些日期/时间值。有关详细信息，请参阅此数据类型描述中的 字符串格式 部分。

local dt = DateTime.now()

-- 对于 en-us，"LL" 标记等于 "MMM D, YYYY"，输出为 "June 11, 2020"

print("日期是 " .. dt:FormatUniversalTime("LL", "en-us"))

--> "日期是 June 11, 2020"

参数

format: string
locale: string

返回

string

FormatLocalTime

string

根据 当地时间 生成一个字符串，格式化为 DateTime 值和格式字符串。格式字符串应包含标记，这些标记将替换为 DateTime 对象描述的某些日期/时间值。有关详细信息，请参阅此数据类型描述中的 字符串格式 部分。

local dt = DateTime.now()

-- 对于 en-us，"LL" 标记等于 "MMM D, YYYY"，输出为 "June 11, 2020"

print("日期是 " .. dt:FormatLocalTime("LL", "en-us"))

--> "日期是 June 11, 2020"

参数

format: string
locale: string

返回

string