MomentJS教程：显示

一旦解析和操作完成后，需要某些方式来显示 moment。

format() 1.0.0+

moment().format();
moment().format(String);

这是最稳健的显示选项。 它接受一串令牌并将其替换为其相应的值。

moment().format();                                // "2014-09-08T08:02:17-05:00" (ISO 8601，无小数秒钟)
moment().format("dddd, MMMM Do YYYY, h:mm:ss a"); // "Sunday, February 14th 2010, 3:25:50 pm"
moment().format("ddd, hA");                       // "Sun, 3PM"
moment('gibberish').format('YYYY MM DD');         // "Invalid date"

X 新增于 2.0.0。

e E gg gggg GG GGGG 新增于 2.1.0。

x 新增于 2.8.4。

SSSS 至 SSSSSSSSS 新增于 2.10.5。 它们会显示 3 位有效数字，其余部分用零填充。

k 和 kk 新增于 2.13.0。

本地化格式

由于首选的格式会根据语言环境而有所不同，因此有一些令牌可用于根据语言环境格式 moment。

同一格式有大小写变体。 小写版本旨在作为大写版本的简化版本。

l ll lll llll 在 2.0.0 中可用。 LTS 新增于 2.8.4。

转义字符

要转义格式字符串中的字符，可以将字符包装在方括号中。

moment().format('[今天] dddd'); // '今天 Sunday'

与 LDML 的异同

注意：虽然这些日期格式与 LDML 日期格式非常相似，但是在月份的日期、年份的日期、星期几等方面存在一些细微的差异。

有关跨不同语言环境的一些不同的日期格式令牌的详细信息，参阅日期格式令牌的图表。

格式化速度

要与其他库比较 Moment.js 的格式化速度，请差异与其他库的比较。

其他令牌

如果更习惯使用 strftime 而不是类似 LDML 的解析令牌，则可以使用 Ben Oakes 的插件 benjaminoakes/moment-strftime。

默认的格式

不使用格式调用 moment#format 将会默认为 moment.defaultFormat。 开箱即用的 moment.defaultFormat 是 ISO8601 格式 YYYY-MM-DDTHH:mm:ssZ。

从 2.13.0 版本开始，当在 UTC 模式中时，默认的格式由 moment.defaultFormatUtc 管理的，其格式是 YYYY-MM-DDTHH:mm:ss[Z]。 这会返回 Z 作为偏移量，而不是 +00:00。

在某些情况下，本地时区（例如 Atlantic/Reykjavik）可能具有零偏移量，且将会被视为 UTC。 在这种情况下，将 moment.defaultFormat 和 moment.defaultFormatUtc 设置为使用相同的格式可能很有用。

更改 moment.defaultFormat 的值仅会影响格式化，而不会影响解析。 例如：

moment.defaultFormat = "DD.MM.YYYY HH:mm";
// 使用 .toDate() 解析。
moment('20.07.2018 09:19').toDate() // Invalid date
// 使用新的 defaultFormat 格式化日期字符串，然后解析。
moment('20.07.2018 09:19', moment.defaultFormat).toDate() // Fri Jul 20 2018 09:19:00 GMT+0300

fromNow() 1.0.0+

moment().fromNow();
moment().fromNow(Boolean);

显示时间的常用方法是通过 moment#fromNow 处理。 有时称为时间间隔或相对时间。

moment([2007, 0, 29]).fromNow(); // 4 年前

If you pass true, you can get the value without the suffix. 如果传入 true，则可以获得不带后缀的值。

基本的字符串由当前的语言环境自定义。 时间会舍入到最接近的秒数。

下表概述了每个时间长度显示的字符串的细分。

注意：从 2.10.3 版本开始，如果目标 moment 对象无效，则结果为本地化的无效日期字符串。

注意：ss 键新增于 2.18.0。 这是一个可选的阈值。 除非用户手动设置 ss 阈值，否则它将永远不会显示。 在设置 ss 阈值之前，它默认为 s 阈值减去 1（因此对用户不可见）的值。

from() 1.0.0+

moment().from(Moment|String|Number|Date|Array);
moment().from(Moment|String|Number|Date|Array, Boolean);

可能想要显示 moment 与现在以外的时间的相对时间。 在这种情况下，可以使用 moment#from。

第一个参数是可以传给 moment() 的任何值或实际的 Moment。

var a = moment([2007, 0, 28]);
var b = moment([2007, 0, 29]);
a.from(b);                     // "1 天前"
a.from([2007, 0, 29]);         // "1 天前"
a.from(new Date(2007, 0, 29)); // "1 天前"
a.from("2007-01-29");          // "1 天前"

与 moment#fromNow 一样，将 true 用作第二个参数会返回不带后缀的值。 无论何时需要有可读的时间长度，这都非常有用。

var start = moment([2007, 0, 5]);
var end   = moment([2007, 0, 10]);
end.from(start);       // "5 天内"
end.from(start, true); // "5 天"

从 2.10.3 版本开始，如果任一端点无效，则结果为本地化的无效日期字符串。

toNow() 2.10.3+

moment().toNow();
moment().toNow(Boolean);

显示时间的常用方法是通过 moment#toNow 处理。 有时称为时间间隔或相对时间。

这类似于 moment.fromNow，但给出相反的间隔：a.fromNow() = - a.toNow()。

这类似于 moment.to，但在当前时间有特殊情况。 如果要控制间隔的两个端点，则使用 moment.to。

moment([2007, 0, 29]).toNow(); // 4 年内

如果传入 true，则可以获取不带前缀的值。

基本的字符串由当前的语言环境自定义。

下表概述了每个时间长度显示的字符串的细分。

从 2.10.3 版本开始，如果目标 moment 对象无效，则结果为本地化的无效日期字符串。

to() 2.10.3+

moment().to(Moment|String|Number|Date|Array);
moment().to(Moment|String|Number|Date|Array, Boolean);

可能想要显示 moment 与现在以外的时间的相对时间。 在这种情况下，可以使用 moment#to。

var a = moment([2007, 0, 28]);
var b = moment([2007, 0, 29]);
a.to(b) // "1 天内"

第一个参数是可以传给 moment() 的任何值或实际的 Moment。

var a = moment([2007, 0, 28]);
var b = moment([2007, 0, 29]);
a.to(b);                     // "1 天内"
a.to([2007, 0, 29]);         // "1 天内"
a.to(new Date(2007, 0, 29)); // "1 天内"
a.to("2007-01-29");          // "1 天内"

与 moment#toNow 一样，将 true 用作第二个参数会返回不带后缀的值。 无论何时需要有可读的时间长度，这都非常有用。

var start = moment([2007, 0, 5]);
var end   = moment([2007, 0, 10]);
end.to(start);       // "5 天前"
end.to(start, true); // "5 天"

从 2.10.3 版本开始，如果任一端点无效，则结果为本地化的无效日期字符串。

calendar() 1.3.0+

moment().calendar();
moment().calendar(referenceTime);
moment().calendar(referenceTime, formats);  // 从 2.10.5 开始

日历时间显示相对于给定的 referenceTime 的时间（默认为现在），但与 moment#fromNow 略有不同。

moment#calendar 会根据日期与 referenceTime 的日期（默认为今天）的接近程度，使用不同的字符串格式化日期。

这些字符串是本地化的，可以自定义。

从 2.10.5 开始，moment 支持指定每次调用的日历输出格式：

moment().calendar(null, {
    sameDay: '[今天]',
    nextDay: '[明天]',
    nextWeek: 'dddd',
    lastDay: '[昨天]',
    lastWeek: '[上个] dddd',
    sameElse: 'DD/MM/YYYY'
});

当 moment 与 referenceTime 相距超过一周时，则将 sameElse 用作格式。

注意：从 2.14.0 版本开始，日历的格式参数可以是一个在 moment 上下文中使用单个参数执行的回调：

diff() 1.0.0+

moment().diff(Moment|String|Number|Date|Array);
moment().diff(Moment|String|Number|Date|Array, String);
moment().diff(Moment|String|Number|Date|Array, String, Boolean);

要获取以毫秒为单位的差异，则像使用 moment#from 一样使用 moment#diff。

var a = moment([2007, 0, 29]);
var b = moment([2007, 0, 28]);
a.diff(b) // 86400000

要获取另一个度量单位中的差异，则将该度量作为第二个参数传入。

var a = moment([2007, 0, 29]);
var b = moment([2007, 0, 28]);
a.diff(b, 'days') // 1

要获取两个时刻之间的差值的时长，则可以将 diff 作为参数传给 moment#duration。

支持的度量有 years、months、weeks、days、hours、minutes 和 seconds。 为了便于开发，从 2.0.0 版本开始支持单数形式。 1.1.1 版本中提供了毫秒以外的度量单位。

默认情况下，moment#diff 会将结果截断为零个小数位，并返回一个整数。 如果需要浮点数，则将 true 作为第三个参数传入。 在 2.0.0 之前，moment#diff 返回的数字会四舍五入到最接近的整数，而不是截断的数字。

var a = moment([2008, 9]);
var b = moment([2007, 0]);
a.diff(b, 'years');       // 1
a.diff(b, 'years', true); // 1.75

如果该时刻早于传给 moment.fn.diff 的时刻，则返回值为负数。

var a = moment();
var b = moment().add(1, 'seconds');
a.diff(b) // -1000
b.diff(a) // 1000

考虑这一点的一种简单方法是将 .diff( 替换为减号运算符。

          // a < b
a.diff(b) // a - b < 0
b.diff(a) // b - a > 0

月份和年份的差异

moment#diff 对月份和年份的差异进行一些特殊处理。 它做了一些优化，以确保具有相同日期的两个月始终是整数。

因此，1月15日至2月15日应该恰好是1个月。

2月28日至3月28日应该恰好是1个月。

2011年2月28日至2012年2月28日应该恰好是1年。

对月份和年份的差异的更改于 2.0.0。 从 2.9.0 版本开始，diff 还支持季度单位。

valueOf() 1.0.0+

moment().valueOf();
+moment();

moment#valueOf 简单地输出自 Unix 纪元以来的毫秒数，就像 Date#valueOf 一样。

moment(1318874398806).valueOf(); // 1318874398806
+moment(1318874398806); // 1318874398806

要从 Moment 获取 Unix 时间戳（自该纪元以来的秒数），则使用 moment#unix。

unix() 1.6.0+

moment().unix();

moment#unix 输出 Unix 时间戳（自 Unix 纪元以来的秒数）

moment(1318874398806).unix(); // 1318874398

此值的下限为最接近的秒数，且不包括毫秒部分。

daysInMonth() 1.5.0+

moment().daysInMonth();

获取当月的天数。

moment("2012-02", "YYYY-MM").daysInMonth() // 29
moment("2012-01", "YYYY-MM").daysInMonth() // 31

toDate() 1.0.0+

要获取 Moment.js 封装的原生 Date 对象的副本，则使用 moment#toDate。

这将会返回该 moment 使用的 Date 的副本，因此对该 Date 的任何更改都不会导致 moment 发生变化。 如果要更改 moment 的 Date，则参阅 moment#manipulate 或 moment#set。

moment#native 已由 moment#toDate 取代，并已弃用于 1.6.0。

toArray() 1.7.0+

moment().toArray();

这会返回一个数组，该数组反映了 new Date() 中的参数。

toJSON() 2.0.0+

moment().toJSON();

当将对象序列化为 JSON 时，如果有 Moment 对象，则它会将被解释为 ISO8601 字符串，并调整到 UTC。

JSON.stringify({
    postDate : moment()
}); // '{"postDate":"2013-02-04T22:44:30.652Z"}'

如果希望使用一个 ISO8601 字符串来反映该 moment 的 utcOffset()，则可以像这样修改 toJSON 函数：

moment.fn.toJSON = function() { return this.format(); }

这会更改行为，如下所示：

JSON.stringify({
    postDate : moment()
}); // '{"postDate":"2013-02-04T14:44:30-08:00"}'

toISOString() 2.1.0+

moment().toISOString();
moment().toISOString(keepOffset); // 从 2.20.0 开始

将字符串格式化为 ISO8601 标准。

moment().toISOString() // 2013-02-04T22:44:30.652Z

注意，即使问题中的 moment 处于本地模式，.toISOString() 也会以 UTC 返回时间戳。 这样做是为了与 ES2015 规范中概述的原生 JavaScript Date .toISOString() 规范保持一致。 从 2.20.0 版本开始，可以调用 .toISOString(true) 以防止 UTC 转换。

从 2.8.4 版本开始，出于性能原因，尽可能使用原生 Date.prototype.toISOString。

toObject() 2.10.5+

moment().toObject();

这会返回一个包含年份、月份、月份的日期、小时、分钟、秒钟、毫秒的对象。

moment().toObject()  // {
                     //     years: 2015
                     //     months: 6
                     //     date: 26,
                     //     hours: 1,
                     //     minutes: 53,
                     //     seconds: 14,
                     //     milliseconds: 600
                     // }

toString() 2.1.0+

以与 JS Date 的 .toString() 类似的格式返回英文字符串。

moment().toString() // "Sat Apr 30 2016 16:59:46 GMT-0500"

inspect() 2.16.0+

moment().inspect();

返回机器可读的字符串，可以对其进行评估以产生相同的 moment。 由于其名称，它还用于节点交互式 shell 中以显示对象。

moment().inspect() // 'moment("2016-11-09T22:23:27.861")'
moment.utc().inspect() // 'moment.utc("2016-11-10T06:24:10.638+00:00")'
moment.parseZone('2016-11-10T06:24:12.958+05:00').inspect() // 'moment.parseZone("2016-11-10T06:24:12.958+05:00")'
moment(new Date('nope')).inspect() // 'moment.invalid(/* Invalid Date */)'
moment('blah', 'YYYY').inspect() // 'moment.invalid(/* blah */)'

注意：此函数主要用于调试，并非所有情况都经过精确处理。