第 24 章 脚本编制参考(二) 类DateTimeSpan

类 DateTimeSpan
静态 DateTimeSpan 类提供了一些函数来确定两个日期或时间之间的时间量以及加上或减去时间范围。它提供了一组函数来处理两个日期之间的时间差。因为日期范围仅仅是数字，所以应用程序可对它们使用正常的数学运算：加减乘除等等。此类是静态类。应用程序不能创建此类的实例。

DateTimeSpan.addDate
此函数返回一个新日期，它是用起始日期加上指定的年数、月数和天数之和。月数可以大于 12，而天数可以大于一个月的天数。实际效果就好像是三个不同的操作。先加上年数。然后使用生成的日期加上月数。接着使用生成的日期加上天数。

在加上月时，生成的日期可能无效。例如，将 1 月 31 日加上一个月会生成无效日期 2 月 31 日。在此情况下，函数会将其调整为有效日期，如果该年不是闰年，则 2 月有 28 天，所以生成的日期将为 3 月 3 日。

任何年数、月数或天数参数都可以为空或者是未定义的。如此一来该值会被视为零。

任何年数、月数或天数参数都可以是负数。在此情况下，结果将被认为是从基本日期减去该单元。

语法
DateTimeSpan.addDate( startDate, years, months, days )

参数
startDate
用于表示基本日期的日期对象。
years
该日期要加上的年数。
months
该日期要加上的月数。
days
该日期要加上的天数。
返回
表示用起始日期加上年数、月数和天数生成的日期。

示例
var startDate = date.parse( "2004-12-31" );
var endDate;
endDate = DateTimeSpan( startDate, 1, 0, 0 ); // 返回 2005-12-31
endDate = DateTimeSpan( startDate, 0, 1, 0 ); // 返回 2005-1-31
endDate = DateTimeSpan( startDate, 0, 0, 1 ); // 返回 2005-1-1
endDate = DateTimeSpan( startDate, 1, 1, 1 ); // 返回 2005-3-4

另请参阅
DateTimeSpan.addTime 函数

DateTimeSpan.subDate 函数

DateTimeSpan.addTime
此函数返回一个新日期，它是用起始日期加上指定的小时数、分钟数和秒数之和。小时数可以大于 24，而分钟数和秒数可以大于 60。实际效果就好像是三个不同的操作：先加上小时数。然后使用生成的日期加上分钟数。接着使用生成的日期加上秒数。

任何小时数、分钟数和秒数参数可以为空或者是未定义的。如此一来该值会被视为零。

任何小时数、分钟数和秒数参数都可以是负数。在此情况下，结果将被认为是从基本日期减去该单元。

语法
DateTimeSpan.addTime( startDate, hours, minutes, seconds )

参数
startDate
用于表示基本日期的日期对象。
hours
该日期要加上的小时数。
minutes
该日期要加上的分钟数。
seconds
该日期要加上的秒数。
返回
表示用起始日期加上小时数、分钟数和秒数生成的日期。

另请参阅
DateTimeSpan.addDate 函数

DateTimeSpan.subTime 函数

DateTimeSpan.days
返回两个日期之间的天数。一天被定义为日历的变化。因此，2 月 27 日下午 11:59:59 到 2 月 28 日午夜为一天，2 月 27 日午夜到 2 月 28 日 11:59:59 也为一天。

语法
DateTimeSpan.days( startDate, endDate )

参数
startDate
用于表示范围起始位置的日期对象。
endDate
用于表示范围结束位置的日期对象。
返回
返回两个日期之间的天数。

DateTimeSpan.hours
此函数返回两个时间之间的整小时数。整小时被定义为一小时的指定分钟至下一小时的同一分钟。例如，1:23:00 到 2:23:00 为一小时，而 1:23:00 到 2:22:59 的整小时数为零。

语法
DateTimeSpan.hours( startDate, endDate )

参数
startDate
用于表示范围起始位置的日期对象。
endDate
用于表示范围结束位置的日期对象。
返回
两个日期之间的整小时数。

DateTimeSpan.minutes
此函数返回两个时间之间的整分钟数。整分钟被定义为一分钟的指定秒至下一分钟的同一秒。例如，1:23:00 到 1:24:00 为一分钟，而 1:23:00 到 1:22:59 的整分钟数为零。

语法
DateTimeSpan.minutes( startDate, endDate )

参数
startDate
用于表示范围起始位置的日期对象。
endDate
用于表示范围结束位置的日期对象。
返回
两个日期之间的整分钟数。

DateTimeSpan.months
此函数返回两个日期之间的整月数。整月被定义为一个月的第 N 天到下个月的第 N 天的时间范围。例如，2 月 28 日到 3 月 28 日是一个月，而 2 月 28 日到 3 月 26 日的整月数为零。

语法
DateTimeSpan.months( startDate, endDate )

参数
startDate
用于表示范围起始位置的日期对象。
endDate
用于表示范围结束位置的日期对象。
返回
返回两个日期之间的整月数。

DateTimeSpan.seconds
此函数返回两个时间之间的秒数。

语法
DateTimeSpan.seconds( startDate, endDate )

参数
startDate
用于表示范围起始位置的日期对象。
endDate
用于表示范围结束位置的日期对象。
返回
两个日期之间的整分钟数。

DateTimeSpan.subDate
此函数返回一个新日期，它是从起始日期减去指定的年数、月数和天数生成的结果。月数可以大于 12，而天数可以大于一个月的天数。实际效果就好像是三个不同的操作。先减去年数。然后使用生成的日期减去月数。接着使用生成的日期减去天数。

在减去月时，生成的日期可能无效。例如，从 3 月 30 日减去一个月会生成无效日期 2 月 30 日。此函数会通过将日期调整为该月的最后一个有效日来生成有效日期。在此情况下，如果该年不是闰年，则日期会调整为 2 月 28 日。

任何年数、月数或天数参数都可以为空或者是未定义的。在此情况下，该值会被视为零。

任何年数、月数或天数参数都可以是负数。在此情况下，结果将被认为是用基本日期加上该单元。

语法
DateTimeSpan.subDate( startDate, years, months, days )

参数
startDate
用于表示基本日期的日期对象。
years
要从该日期减去的年数。
months
要从该日期减去的月数。
days
要从该日期减去的天数。
返回
表示从起始日期减去年数、月数和天数生成的日期。

另请参阅
DateTimeSpan.addDate 函数

DateTimeSpan.subTime 函数

DateTimeSpan.subTime
此函数返回一个新日期，它是从起始日期减去指定的小时数、分钟数和秒数的结果。小时数可以大于 24，而分钟数和秒数可以大于 60。实际效果就好像是三个不同的操作。先减去小时数。然后使用生成的日期减去分钟数。接着使用生成的日期减去秒数。

任何小时数、分钟数和秒数参数可以为空或者是未定义的。在此情况下，该值会被视为零。

任何小时数、分钟数和秒数参数都可以是负数。在此情况下，结果将被认为是用基本日期加上该单元。

语法
DateTimeSpan.subTime( startDate, hours, minutes, seconds )

参数
startDate
用于表示基本日期的日期对象。
hours
要从该日期减去的小时数。
minutes
要从该日期减去的分钟数。
seconds
要从该日期减去的秒数。
返回
表示从起始日期减去小时数、分钟数和秒数生成的日期。

另请参阅
DateTimeSpan.addTime 函数

DateTimeSpan.subDate 函数

DateTimeSpan.years
此函数计算两个日期之间的整年数。整年被定义为从一年的指定月份、日期和时间到下一年的同一月份、日期和时间的时间范围。因为闰年，整年有时包含 365 天，有时包含 366 天。

如果任一参数不是日期，则会抛出异常。如果任一参数为空，则结果也为空。

语法
DateTimeSpan.years( startDate, endDate )

参数
startDate
用于表示范围起始位置的日期对象。
endDate
用于表示范围结束位置的日期对象。
返回
两个日期之间的整年数。