Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
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 时间。
重要：_from_system 系列方法使用的是系统始终，用户可以自行设置。千万不要使用该方法进行精确的时间计算，因为计算结果可能受到用户或操作系统的自动调整的影响。精确时间的计算请始终使用 get_ticks_usec 或 get_ticks_msec，可以保证单调性（即不会变小）。
方法¶
枚举¶
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 ( bool utc=false ) const
以字典的形式返回当前时间，包含的键为：year、month、day 和 weekday。
当 utc 为 false 时，返回的是系统的本地时间，否则为 UTC 时间。
Dictionary get_date_dict_from_unix_time ( int unix_time_val ) const
将给定的 Unix 时间戳转换为字典，包含的键为：year、month、day、weekday。
String get_date_string_from_system ( bool utc=false ) const
以 ISO 8601 日期字符串的形式返回当前日期（YYYY-MM-DD）。
当 utc 为 false 时，返回的是系统的本地时间，否则为 UTC 时间。
String get_date_string_from_unix_time ( int unix_time_val ) const
将给定的 Unix 时间戳转换为 ISO 8601 日期字符串（YYYY-MM-DD）。
Dictionary get_datetime_dict_from_datetime_string ( String datetime, bool weekday ) const
将给定的 ISO 8601 日期和时间字符串（YYYY-MM-DDTHH:MM:SS）转换为字典，包含的键为：year、month、day、weekday、hour、minute、second。
当 weekday 为 false 时，不包含 weekday 记录（计算花费相对较大）。
注意：时间字符串中的小数会被静默忽略。
Dictionary get_datetime_dict_from_system ( bool utc=false ) const
以字典形式返回当前日期，包含的键为：year、month、day、weekday、hour、minute、second 以及 dst（夏令时，Daylight Savings Time）。
Dictionary get_datetime_dict_from_unix_time ( int unix_time_val ) const
将给定的 Unix 时间戳转换为字典，包含的键为：year、month、day、weekday、hour、minute、和 second。
如果 Unix 时间戳是当前时间，则返回的字典值将与 get_datetime_dict_from_system 相同，夏令时除外，因为它无法根据纪元确定。
String get_datetime_string_from_datetime_dict ( Dictionary datetime, bool use_space ) const
将给定的时间值字典转换为 ISO 8601 日期和时间字符串（YYYY-MM-DDTHH:MM:SS）。
给定的字典可以包含以下键：year、month、day、hour、minute、second。其他的记录（包括 dst）都会被忽略。
字典为空时将返回 0。如果省略了部分键，默认使用 Unix 纪元时间戳 0（1970-01-01 的 00:00:00）的对应部分。
当 use_space 为 true 时，将使用空格代替中间的字母 T。
String get_datetime_string_from_system ( bool utc=false, bool use_space=false ) const
以 ISO 8601 日期和时间字符串的形式返回当前日期和时间（YYYY-MM-DDTHH:MM:SS）。
当 utc 为 false 时，返回的是系统的本地时间，否则为 UTC 时间。
当 use_space 为 true 时，将使用空格代替中间的字母 T。
String get_datetime_string_from_unix_time ( int unix_time_val, bool use_space=false ) const
将给定的 Unix 时间戳转换为 ISO 8601 日期和时间字符串（YYYY-MM-DDTHH:MM:SS）。
当 use_space 为 true 时，将使用空格代替中间的字母 T。
String get_offset_string_from_offset_minutes ( int offset_minutes ) 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 ( bool utc=false ) const
以字典的形式返回当前时间，包含的键为：hour、minute、second。
当 utc 为 false 时，返回的是系统的本地时间，否则为 UTC 时间。
Dictionary get_time_dict_from_unix_time ( int unix_time_val ) const
将给定的时间转换为字典，包含的键为：时 hour、分 minute、秒 second。
String get_time_string_from_system ( bool utc=false ) const
以 ISO 8601 时间字符串的形式返回当前时间（HH:MM:SS）。
当 utc 为 false 时，返回的是系统的本地时间，否则为 UTC 时间。
String get_time_string_from_unix_time ( int unix_time_val ) const
将给定的 Unix 时间戳转换为 ISO 8601 时间字符串（HH:MM:SS）。
Dictionary get_time_zone_from_system ( ) const
以字典的形式返回当前时区，包含的键为：bias 和 name。
bias是相对于 UTC 的偏移量，单位为分钟，因为并不是所有时区与 UTC 的时间差都是整数倍小时。name是时区的本地化名称，取决于当前用户的操作系统区域设置。
int get_unix_time_from_datetime_dict ( Dictionary datetime ) const
将时间值字典转换为 Unix 时间戳。
给定的字典可以包含以下键：year、month、day、hour、minute、second。其他的记录（包括 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 ( String datetime ) const
将给定的 ISO 8601 日期和/或时间字符串转换为 Unix 时间戳。字符串中可以只包含日期、只包含时间，也可以两者都包含。
注意：Unix 时间戳通常是 UTC 的。本方法不会做任何时区转换，所以时间戳的时区与给定的日期时间字符串相同。
注意：时间字符串中的小数会被静默忽略。
float get_unix_time_from_system ( ) const
返回当前的 Unix 时间戳，以秒为单位，基于 UTC 系统时间。本方法由操作系统实现，返回的时间总是 UTC 的。
注意：与其他使用整数时间戳的方法不同，这个方法返回的是 float 类型的时间戳，可以表示比秒更高的精度。