Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Time

继承: Object

用于处理时间数据的单例。

描述

Time 单例可以转换各种不同格式的时间,也可以从系统获取时间信息。

这个类尽可能多地符合了 ISO 8601 标准。所有日期都遵循“外推格里历”。因此 1582-10-15 的前一天是 1582-10-14,而不是 1582-10-04。公元 1 年的前一年(即公元前 1 年)是数字 0,再往前的一年(公元前 2 年)是 -1,以此类推。

转换方法假设“时区相同”,不会自动处理时区或 DST(夏令时)的转换。不会对闰秒进行处理,如果需要必须手动处理。“Z”等后缀也没有处理,你需要进行手动剥除。

从系统获取时间信息时,时间可能是本地时间或 UTC 时间,取决于 utc 参数。不过 get_unix_time_from_system 方法始终使用 UTC,因为返回的是从 Unix 时间原点起经过的秒数。

重要:_from_system 系列方法使用的是系统始终,用户可以自行设置。千万不要使用该方法进行精确的时间计算,因为计算结果可能受到用户或操作系统的自动调整的影响。精确时间的计算请始终使用 get_ticks_usecget_ticks_msec,可以保证单调性(即不会变小)。

方法

Dictionary

get_date_dict_from_system(utc: bool = false) const

Dictionary

get_date_dict_from_unix_time(unix_time_val: int) const

String

get_date_string_from_system(utc: bool = false) const

String

get_date_string_from_unix_time(unix_time_val: int) const

Dictionary

get_datetime_dict_from_datetime_string(datetime: String, weekday: bool) const

Dictionary

get_datetime_dict_from_system(utc: bool = false) const

Dictionary

get_datetime_dict_from_unix_time(unix_time_val: int) const

String

get_datetime_string_from_datetime_dict(datetime: Dictionary, use_space: bool) const

String

get_datetime_string_from_system(utc: bool = false, use_space: bool = false) const

String

get_datetime_string_from_unix_time(unix_time_val: int, use_space: bool = false) const

String

get_offset_string_from_offset_minutes(offset_minutes: int) const

int

get_ticks_msec() const

int

get_ticks_usec() const

Dictionary

get_time_dict_from_system(utc: bool = false) const

Dictionary

get_time_dict_from_unix_time(unix_time_val: int) const

String

get_time_string_from_system(utc: bool = false) const

String

get_time_string_from_unix_time(unix_time_val: int) const

Dictionary

get_time_zone_from_system() const

int

get_unix_time_from_datetime_dict(datetime: Dictionary) const

int

get_unix_time_from_datetime_string(datetime: String) const

float

get_unix_time_from_system() const


枚举

enum Month: 🔗

Month MONTH_JANUARY = 1

一月份,使用数字 01 表示。

Month MONTH_FEBRUARY = 2

二月份,使用数字 02 表示。

Month MONTH_MARCH = 3

三月份,使用数字 03 表示。

Month MONTH_APRIL = 4

四月份,使用数字 04 表示。

Month MONTH_MAY = 5

五月份,使用数字 05 表示。

Month MONTH_JUNE = 6

六月份,使用数字 06 表示。

Month MONTH_JULY = 7

七月份,使用数字 07 表示。

Month MONTH_AUGUST = 8

八月份,使用数字 08 表示。

Month MONTH_SEPTEMBER = 9

九月份,使用数字 09 表示。

Month MONTH_OCTOBER = 10

十月份,使用数字 10 表示。

Month MONTH_NOVEMBER = 11

十一月份,使用数字 11 表示。

Month MONTH_DECEMBER = 12

十二月份,使用数字 12 表示。


enum Weekday: 🔗

Weekday WEEKDAY_SUNDAY = 0

星期日,使用数字 0 表示。

Weekday WEEKDAY_MONDAY = 1

星期一,使用数字 1 表示。

Weekday WEEKDAY_TUESDAY = 2

星期二,使用数字 2 表示。

Weekday WEEKDAY_WEDNESDAY = 3

星期三,使用数字 3 表示。

Weekday WEEKDAY_THURSDAY = 4

星期四,使用数字 4 表示。

Weekday WEEKDAY_FRIDAY = 5

星期五,使用数字 5 表示。

Weekday WEEKDAY_SATURDAY = 6

星期六,使用数字 6 表示。


方法说明

Dictionary get_date_dict_from_system(utc: bool = false) const 🔗

以字典的形式返回当前时间,包含的键为:yearmonthdayweekday

utcfalse 时,返回的是系统的本地时间,否则为 UTC 时间。


Dictionary get_date_dict_from_unix_time(unix_time_val: int) const 🔗

将给定的 Unix 时间戳转换为字典,包含的键为:yearmonthdayweekday


String get_date_string_from_system(utc: bool = false) const 🔗

以 ISO 8601 日期字符串的形式返回当前日期(YYYY-MM-DD)。

utcfalse 时,返回的是系统的本地时间,否则为 UTC 时间。


String get_date_string_from_unix_time(unix_time_val: int) const 🔗

将给定的 Unix 时间戳转换为 ISO 8601 日期字符串(YYYY-MM-DD)。


Dictionary get_datetime_dict_from_datetime_string(datetime: String, weekday: bool) const 🔗

将给定的 ISO 8601 日期和时间字符串(YYYY-MM-DDTHH:MM:SS)转换为字典,包含的键为:yearmonthdayweekdayhourminutesecond

weekdayfalse 时,不包含 weekday 记录(计算花费相对较大)。

注意:时间字符串中的小数会被静默忽略。


Dictionary get_datetime_dict_from_system(utc: bool = false) const 🔗

以字典形式返回当前日期,包含的键为:yearmonthdayweekdayhourminutesecond 以及 dst(夏令时,Daylight Savings Time)。


Dictionary get_datetime_dict_from_unix_time(unix_time_val: int) const 🔗

将给定的 Unix 时间戳转换为字典,包含的键为:yearmonthdayweekdayhourminutesecond

如果 Unix 时间戳是当前时间,则返回的字典值将与 get_datetime_dict_from_system 相同,夏令时除外,因为它无法根据纪元确定。


String get_datetime_string_from_datetime_dict(datetime: Dictionary, use_space: bool) const 🔗

将给定的时间值字典转换为 ISO 8601 日期和时间字符串(YYYY-MM-DDTHH:MM:SS)。

给定的字典可以包含以下键:yearmonthdayhourminutesecond。其他的记录(包括 dst)都会被忽略。

字典为空时将返回 0。如果省略了部分键,默认使用 Unix 纪元时间戳 0(1970-01-01 的 00:00:00)的对应部分。

use_spacetrue 时,将使用空格代替中间的字母 T。


String get_datetime_string_from_system(utc: bool = false, use_space: bool = false) const 🔗

以 ISO 8601 日期和时间字符串的形式返回当前日期和时间(YYYY-MM-DDTHH:MM:SS)。

utcfalse 时,返回的是系统的本地时间,否则为 UTC 时间。

use_spacetrue 时,将使用空格代替中间的字母 T。


String get_datetime_string_from_unix_time(unix_time_val: int, use_space: bool = false) const 🔗

将给定的 Unix 时间戳转换为 ISO 8601 日期和时间字符串(YYYY-MM-DDTHH:MM:SS)。

use_spacetrue 时,将使用空格代替中间的字母 T。


String get_offset_string_from_offset_minutes(offset_minutes: int) const 🔗

将给定的时区偏移分钟数转换为时区偏移字符串。例如,-480 返回 "-08:00"、345 返回 "+05:45"、0 返回 "+00:00"。


int get_ticks_msec() const 🔗

返回从引擎启动开始所经过的时间,单位为毫秒。

始终为正数或 0,使用 64 位值(会在约 5 亿年后绕回)。


int get_ticks_usec() const 🔗

返回从引擎启动开始所经过的时间,单位为微秒。

始终为正数或 0,使用 64 位值(会在约 50 万年后绕回)。


Dictionary get_time_dict_from_system(utc: bool = false) const 🔗

以字典的形式返回当前时间,包含的键为:hourminutesecond

utcfalse 时,返回的是系统的本地时间,否则为 UTC 时间。


Dictionary get_time_dict_from_unix_time(unix_time_val: int) const 🔗

将给定的时间转换为字典,包含的键为:时 hour、分 minute、秒 second


String get_time_string_from_system(utc: bool = false) const 🔗

以 ISO 8601 时间字符串的形式返回当前时间(HH:MM:SS)。

utcfalse 时,返回的是系统的本地时间,否则为 UTC 时间。


String get_time_string_from_unix_time(unix_time_val: int) const 🔗

将给定的 Unix 时间戳转换为 ISO 8601 时间字符串(HH:MM:SS)。


Dictionary get_time_zone_from_system() const 🔗

Returns the current time zone as a dictionary of keys: bias and name.

  • bias is the offset from UTC in minutes, since not all time zones are multiples of an hour from UTC.

  • name is the localized name of the time zone, according to the OS locale settings of the current user.


int get_unix_time_from_datetime_dict(datetime: Dictionary) const 🔗

将时间值字典转换为 Unix 时间戳。

给定的字典可以包含以下键:yearmonthdayhourminutesecond。其他的记录(包括 dst)都会被忽略。

字典为空时将返回 0。如果省略了部分键,默认使用 Unix 纪元时间戳 0(1970-01-01 的 00:00:00)的对应部分。

你可以将 get_datetime_dict_from_unix_time 的输出直接传给本函数,得到的就是最初的输入。

注意:Unix 时间戳通常是 UTC 的。本方法不会做任何时区转换,所以时间戳的时区与给定的日期时间字典相同。


int get_unix_time_from_datetime_string(datetime: String) const 🔗

将给定的 ISO 8601 日期和/或时间字符串转换为 Unix 时间戳。字符串中可以只包含日期、只包含时间,也可以两者都包含。

注意:Unix 时间戳通常是 UTC 的。本方法不会做任何时区转换,所以时间戳的时区与给定的日期时间字符串相同。

注意:时间字符串中的小数会被静默忽略。


float get_unix_time_from_system() const 🔗

返回当前的 Unix 时间戳,以秒为单位,基于 UTC 系统时间。本方法由操作系统实现,返回的时间总是 UTC 的。Unix 时间戳是从 Unix 时间原点 1970-01-01 的 00:00:00 起经过的秒数。

注意:与其他使用整数时间戳的方法不同,这个方法返回的是 float 类型的时间戳,可以表示比秒更高的精度。