表示一个时间点,例如:July 20, 1969, 8:18pm GMT。

通过构造函数或解析格式化的字符串创建DateTime对象, 并且符合ISO 8601标准的子集。 请注意,小时是24小时制,范围在0-23之间。 例如:

DateTime now = new DateTime.now();
DateTime berlinWallFell = new DateTime(1989, 11, 9);
DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");  // 8:18pm

DateTime对象创建之后,将是固定不变的,无论UTC时区还是当前计算机的本地时区。

一旦被创建,DateTime对象的值和时区都不能被修改。

你可以使用属性来获取DateTime对象的各自单位:

assert(berlinWallFell.month == 11);
assert(moonLanding.hour == 20);

为了便利性和可读性,DateTime类提供有每月和星期对应名称的常量。 例如,AUGUST(八月)和FRIDAY(周五)。 你可以使用这些常量来提高代码的可读性:

DateTime berlinWallFell = new DateTime(1989, DateTime.NOVEMBER, 9);
assert(berlinWallFell.weekday == DateTime.THURSDAY);

号数和月份从1开始递增,星期也是从MONDAY(周一)开始。 也就是说,常量JANUARYMONDAY的值都是1。

UTC和本地时间

DateTime对象默认使用的是本地时区,除非显示地指定UTC时区。

DateTime dDay = new DateTime.utc(1944, 6, 6);

isUtc可以判断DateTime对象是否基于UTC。 toLocaltoUtc方法可以得到等效的另一个时区的日期/时间值。 使用DateTime对象的timeZoneName属性,可得到时区的简称。 查看UTC和对象时区之间的时差,可调用timeZoneOffset

比较DateTime对象

DateTime包含有一些实用的方法用于比较对象, 如:isAfterisBeforeisAtSameMomentAs

assert(berlinWallFell.isAfter(moonLanding) == true);
assert(berlinWallFell.isBefore(moonLanding) == false);

使用DateTime和Duration

addsubtract方法可通过Duration对象创建另一个新的DateTime。 例如,查找今天过后60天的日期,写作:

DateTime today = new DateTime.now();
DateTime sixtyDaysFromNow = today.add(new Duration(days: 60));

获取两个DateTime对象之间的时间差,使用difference方法,将返回一个Duration对象。

Duration difference = berlinWallFell.difference(moonLanding)
assert(difference.inDays == 7416);

对于不同时区的两个日期的时间差,两个时间点之间仅仅只相差的数纳秒。 它并不需要考虑日历日。这也就意味着, 在本地时间,如果白天在两个时间点之间保留修改的话, 当日零点到次日零点之间的时间差可能小于24小时。 如果上面的时间差使用澳大利亚的本地时间进行计算,时间差是7415天23小时, inDays的返回值只有7415天。

TODO 待确定完善 class DateTime

翻译上面这段的时候,没有直译,原文很难懂。然后我理解的大概意思是:

国际协调时间(UTC)以原子时秒长为基础,准确度每日数纳秒。如果过去很长的时间,如上面的7416天,
误差会很明显,然后在某一时刻,取余后天数可能会比实际小1天。

下面是原文,如果不对的地方请指正:

The difference between two dates in different time zones is just
the number of nanoseconds between the two points in time.
It doesn't take calendar days into account.
That means that the difference between two midnights in local time
may be less than 24 hours times the number of days between them,
if there is a daylight saving change in between.
If the difference above is calculated using Australian local time,
the difference is 7415 days and 23 hours,
which is only 7415 whole days as reported by inDays.

其他资源

Duration表示一个时间跨度。 Stopwatch用于测量时间间隔。

DateTime类并不提供国际化。如果要使代码国际化,可使用 intl包。

Implements

Constants

APRIL int

4
AUGUST int

8
DAYS_PER_WEEK int

7
DECEMBER int

12
FEBRUARY int

2
FRIDAY int

5
JANUARY int

1
JULY int

7
JUNE int

6
MARCH int

3
MAY int

5
MONDAY int

1
MONTHS_PER_YEAR int

12
NOVEMBER int

11
OCTOBER int

10
SATURDAY int

6
SEPTEMBER int

9
SUNDAY int

7
THURSDAY int

4
TUESDAY int

2
WEDNESDAY int

3

Static Methods

parse(String formattedString) DateTime

基于格式化字符串formattedString构建一个新的DateTime实例。

Constructors

DateTime(int year, [int month = 1, int day = 1, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0])

构造一个指定为本地时区的DateTime

DateTime.fromMicrosecondsSinceEpoch(int microsecondsSinceEpoch, {bool isUtc: false})

用指定的微秒microsecondsSinceEpoch构建一个新的DateTime实例。

DateTime.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch, {bool isUtc: false})

用指定的毫秒millisecondsSinceEpoch构建一个新的DateTime实例。

DateTime.now()

在本地时区,通过当前日期和时间构造一个DateTime实例。

DateTime.utc(int year, [int month = 1, int day = 1, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0])

构造一个指定为UTC时区的DateTime

Properties

day int

月份中的天数 1..31

read-only
hashCode int

read-only
hour int

小时,使用24小时制 0..23

read-only
isUtc bool

如果DateTime设置成UTC时间,则为True。

read-only
microsecond int

微秒 0...999

read-only
microsecondsSinceEpoch int

Unix epoch 1970-01-01T00:00:00Z (UTC)开始经过的微秒数。

read-only
millisecond int

毫秒 0...999

read-only
millisecondsSinceEpoch int

Unix epoch 1970-01-01T00:00:00Z (UTC)开始经过的毫秒数。

read-only
minute int

0...59

read-only
month int

月份 1..12

read-only
runtimeType Type

表示对象的运行时类型。

read-only, inherited
second int

0...59

read-only
timeZoneName String

由平台提供的时区名称。

read-only
timeZoneOffset Duration

时区偏移量,即本地时间和UTC之间的时间差。

read-only
weekday int

一周中的哪一天,值为MONDAY..SUNDAY

read-only
year int

年。

read-only

Operators

operator ==(other) bool

返回true,如果otherDateTime是同一时刻,并且在相同时区(UTC或本地)。

Methods

add(Duration duration) DateTime

this加上duration,返回一个新的DateTime实例。

compareTo(DateTime other) int

比较此DateTime对象与other, 返回0,如果值相等。

difference(DateTime other) Duration

计算thisother的时间差,返回一个Duration

isAfter(DateTime other) bool

返回true,如果thisother之后出现。

isAtSameMomentAs(DateTime other) bool

返回true,如果thisother在同一时刻出现。

isBefore(DateTime other) bool

返回true,如果thisother之前出现。

noSuchMethod(Invocation invocation) → dynamic

当一个不存在的函数或成员变量被访问时,该函数被调用。

inherited
subtract(Duration duration) DateTime

this减去duration,返回一个新的DateTime实例。

toIso8601String() String

返回一个按国际标准ISO-8601、全精度扩展格式表示的字符串。

toLocal() DateTime

返回此DateTime在本地时区的值。

toString() String

返回一个对于此实例人们可读的字符串。

toUtc() DateTime

返回此DateTime在UTC时区的值。