MomentJS教程：时长

Moment.js 也有时长的对象。 将 moment 定义为单个时间点，将 duration 定义为时间的长度。

时长没有定义的开始和结束日期。 它们是无上下文的。

从概念上讲，时长比 ‘今天下午2点到4点之间’ 更类似于 ‘2 小时’。 因此，它们不是在依赖上下文的单位之间进行转换的好方法。

例如，一年可以定义为366天、365天、365.25天、12个月、52周。 没有上下文，试图将年转换为天是毫无意义的。 与使用 Durations 相比，使用 moment#diff 计算两个时刻之间的天数或年数要好得多。

duration() 1.6.0+

moment.duration(Number, String);
moment.duration(Number);
moment.duration(Object);
moment.duration(String);

要创建时长，则调用 moment.duration()，并以毫秒为单位。

moment.duration(100); // 100 毫秒

如果要使用毫秒以外的其他度量单位来创建 moment，则也可以传入度量单位。

moment.duration(2, 'seconds');
moment.duration(2, 'minutes');
moment.duration(2, 'hours');
moment.duration(2, 'days');
moment.duration(2, 'weeks');
moment.duration(2, 'months');
moment.duration(2, 'years');

同样，moment#add 和 moment#subtract的简写在这里也适用。

与 moment#add 相似，如果需要多个不同的度量单位，则可以传入值的对象。

moment.duration({
    seconds: 2,
    minutes: 2,
    hours: 2,
    days: 2,
    weeks: 2,
    months: 2,
    years: 2
});

从 2.1.0 开始，moment 支持解析 ASP.NET 风格的时间跨度。 支持以下格式。

格式是以冒号分隔的小时、分钟、秒钟的字符串，例如 23:59:59。 天数可以加上点分隔符，如 7.23:59:59。 还支持部分秒数如23:59:59.999`。

moment.duration('23:59:59');
moment.duration('23:59:59.999');
moment.duration('7.23:59:59.999');
moment.duration('23:59'); // 新增于 2.3.0

从 2.3.0 开始，moment 还支持解析 ISO 8601 时长。

moment.duration('P1Y2M3DT4H5M6S');
moment.duration('P1M');

从 2.11.0 开始，支持时长的格式字符串，其中天数和剩下的时间之间有空格。

moment.duration('7 23:59:59.999');

从 2.13.0 开始，解析时长时支持混合的负号和正号。

moment.duration('PT-6H3M')

从 2.18.0 开始，支持无效的时长，类似于无效的时刻。 要创建无效的时长，可以为单位的值传入 NaN。

在即将发布的版本中，预期无效的时长可以覆盖更多情况（例如单位的空值）。

moment.duration(NaN);
moment.duration(NaN, 'days');
moment.duration.invalid();

clone() 2.19.0+

moment.duration().clone();

创建时长的副本。 时长是可变的，就像 moment 对象一样，因此可以在某个时间点获取快照。

var d1 = moment.duration();
var d2 = d1.clone();
d1.add(1, 'second');
d1.asMilliseconds() !== d2.asMilliseconds();

humanize() 1.6.0+

moment.duration().humanize();

有时，只想要 moment#from 的所有优点，但又不想创建两个 moment，而只想显示一段时长。

使用 moment.duration().humanize()。

moment.duration(1, "minutes").humanize(); // 1 分钟
moment.duration(2, "minutes").humanize(); // 2 分钟
moment.duration(24, "hours").humanize();  // 1 天

默认情况下，返回的字符串是没有后缀。 如果需要后缀，则按如下所示传入 true。

moment.duration(1, "minutes").humanize(true); // 1 分钟内

对于当前时间之前的后缀，则传入负数。

moment.duration(-1, "minutes").humanize(true); // 1 分钟前

无效的时长会被人性化为 Invalid Date 的本地化版本。

moment.duration.invalid().humanize(); // Invalid Date

milliseconds() 1.6.0+

中英对照 | 提交修改

moment.duration().milliseconds();
moment.duration().asMilliseconds();

要获取时长的毫秒数，则使用 moment.duration().milliseconds()。

它将会返回 0 至 999 之间的数字。

moment.duration(500).milliseconds(); // 500
moment.duration(1500).milliseconds(); // 500
moment.duration(15000).milliseconds(); // 0

如果想要时长的长度（以毫秒为单位），则改用 moment.duration().asMilliseconds()。

moment.duration(500).asMilliseconds(); // 500
moment.duration(1500).asMilliseconds(); // 1500
moment.duration(15000).asMilliseconds(); // 15000

seconds() 1.6.0+

moment.duration().seconds();
moment.duration().asSeconds();

要获取时长的秒数，则使用 moment.duration().seconds()。

它将会返回 0 至 59 之间的数字。

moment.duration(500).seconds(); // 0
moment.duration(1500).seconds(); // 1
moment.duration(15000).seconds(); // 15

如果想要时长的长度（以秒为单位），则改用 moment.duration().asSeconds()。

moment.duration(500).asSeconds(); // 0.5
moment.duration(1500).asSeconds(); // 1.5
moment.duration(15000).asSeconds(); // 15

minutes() 1.6.0+

moment.duration().minutes();
moment.duration().asMinutes();

与时长的其他获取器一样，moment.duration().minutes() 用于获取分钟数（0-59）。

moment.duration().asMinutes() 用于获取时长的长度（以分钟为单位）。

hours() 1.6.0+

moment.duration().hours();
moment.duration().asHours();

与时长的其他获取器一样，moment.duration().hours() 用于获取小时数（0-23）。

moment.duration().asHours() 用于获取时长的长度（以小时为单位）。

days() 1.6.0+

moment.duration().days();
moment.duration().asDays();

与时长的其他获取器一样，moment.duration().days() 用于获取天数（0-30）。

moment.duration().asDays() 用于获取时长的长度（以天为单位）。

weeks() 1.6.0+

moment.duration().weeks();
moment.duration().asWeeks();

与时长的其他获取器一样，moment.duration().weeks() 用于获取星期数（0-4）。

moment.duration().asWeeks() 用于获取时长的长度（以星期为单位）。

与时长的其他获取器不同，星期数获取器是作为天数的子集，且不会从天数中扣除。

注意：以星期为单位的时长的长度定义为 7 天。

months() 1.6.0+

moment.duration().months();
moment.duration().asMonths();

与时长的其他获取器一样，moment.duration().months() 用于获取月数（0-11）。

moment.duration().asMonths() 用于获取时长的长度（以月为单位）。

years() 1.6.0+

moment.duration().years();
moment.duration().asYears();

与时长的其他获取器一样，moment.duration().years() 用于获取年数。

moment.duration().asYears() 用于获取时长的长度（以年为单位）。

add() 2.1.0+

moment.duration().add(Number, String);
moment.duration().add(Number);
moment.duration().add(Duration);
moment.duration().add(Object);

通过增加时间来更改原始的时长。

用于创建时长的相同的键和速记可以在此处用作第二个参数。

var a = moment.duration(1, 'd');
var b = moment.duration(2, 'd');
a.add(b).days(); // 3

注意，将无效的时长添加到任何其他时长会产生无效的时长。

subtract() 2.1.0+

moment.duration().subtract(Number, String);
moment.duration().subtract(Number);
moment.duration().subtract(Duration);
moment.duration().subtract(Object);

通过减去时间来更改原始的时长。

用于创建时长的相同的键和速记可以在此处用作第二个参数。

var a = moment.duration(3, 'd');
var b = moment.duration(2, 'd');
a.subtract(b).days(); // 1

注意，将无效的时长添加到任何其他时长会产生无效的时长。

duration(x.diff(y)) 2.1.0+

var duration = moment.duration(x.diff(y))

可以将时长与 moment#diff 一起使用，以获取两个时刻之间的时长。 为此，只需将 moment#diff 方法传给 moment#duration，如下所示：

  var x = new moment()
  var y = new moment()
  var duration = moment.duration(x.diff(y))
  // 返回时长对象，其时长在 x 和 y 之间。

参阅此处以获取有关 moment#diff 的更多信息。

as() 2.1.0+

moment.duration().as(String);

作为 Duration#asX 的替代，可以使用 Duration#as('x')。 同样，moment#add 中的所有简写键也适用于此。

duration.as('hours');
duration.as('minutes');
duration.as('seconds');
duration.as('milliseconds');

无效的时长将会为所有单位返回 NaN。

get() 2.1.0+

moment.duration().get(String);

作为 Duration#x() 获取器的替代，可以使用 Duration#get('x')。 同样，moment#add 中的所有简写键也适用于此。

无效的时长将会为所有单位返回 NaN。

toJSON() 2.9.0+

moment.duration().toJSON();

当将时长对象序列化为 JSON 时，它将会表示为 ISO8601 字符串。

JSON.stringify({
    postDuration : moment.duration(5, 'm')
}); // '{"postDuration":"PT5M"}'

无效的时长返回 json 表示的 Invalid Date。

isDuration() 1.6.0+

moment.isDuration(obj);

要检查变量是否为 moment 的时长对象，则使用 moment.isDuration()。

moment.isDuration() // false
moment.isDuration(new Date()) // false
moment.isDuration(moment()) // false
moment.isDuration(moment.duration()) // true
moment.isDuration(moment.duration(2, 'minutes')) // true

toISOString() 2.8.0+

moment.duration().toISOString();

返回 ISO 8601 标准指定的字符串形式的时长。

moment.duration(1, 'd').toISOString() // "P1D"

格式 PnYnMnDTnHnMnS 的说明：

locale() 2.17.1+

moment.duration().locale();
moment.duration().locale(String);

可以使用 locale(...) 获取或设置时长的语言环境。 语言环境将会影响时长的字符串方法，例如 humanize()。 有关国际化的常用信息，请参见国际化章节。

moment.duration(1, "minutes").locale("en").humanize(); // a minute
moment.duration(1, "minutes").locale("fr").humanize(); // une minute
moment.duration(1, "minutes").locale("es").humanize(); // un minuto

humanize() 的后缀也已国际化：

moment.duration(1, "minutes").locale("en").humanize(true); // in a minute
moment.duration(1, "minutes").locale("fr").humanize(true); // dans une minute
moment.duration(1, "minutes").locale("es").humanize(true); // en un minuto

moment.duration(-1, "minutes").locale("en").humanize(true); // a minute ago
moment.duration(-1, "minutes").locale("fr").humanize(true); // il y a une minute
moment.duration(-1, "minutes").locale("es").humanize(true); // hace un minuto

实用函数

Moment 公开了一些方法，这些方法可能对扩展库或编写自定义解析器的开发者有用。

normalizeUnits() 2.3.0+

moment.normalizeUnits(String);

Moment 的许多函数都允许调用者传入单位枚举的别名。 例如，下面的所有 get 都是等效的。

var m = moment();
m.get('y');
m.get('year');
m.get('years');

如果要扩展库，则可能需要访问 Moment 的工具，以便更好地使函数与 Moment 的函数保持一致。

moment.normalizeUnits('y');      // 'year'
moment.normalizeUnits('Y');      // 'year'
moment.normalizeUnits('year');   // 'year'
moment.normalizeUnits('years');  // 'year'
moment.normalizeUnits('YeARS');  // 'year'

invalid() 2.3.0+

moment.invalid(Object);

可以创建自己的无效 Moment 对象，这对于创建自己的解析器很有用。

var m = moment.invalid();
m.isValid();                      // false
m.format();                       // 'Invalid date'
m.parsingFlags().userInvalidated; // true

invalid 还接受一个对象，该对象指定要设置的解析标志。 这不会设置 userInvalidated 解析标志，除非它是指定的属性之一。

var m = moment.invalid({invalidMonth: 'Actober'});
m.parsingFlags().invalidMonth; // 'Actober'

无需指定 Moment 可以识别的解析标志。 但是，Moment 将会是无效的，并且解析标志将会由 parsingFlags() 返回。