Moment

作者：高天阳

邮箱：[email protected]

更改历史

* 2018-09-25        高天阳      添加.diff()方法文档
* 2018-08-15        高天阳      初始化文档

1. 简介

1.1 什么是Moment

Moment旨在在浏览器和Node.js中工作。

目前，以下浏览器用于ci系统：Windows 7上的IE8，IE9，Windows XP上的稳定Chrome， Mac上的Safari 10.8和Linux上的稳定Firefox。

所有代码都适用于这两种环境。所有单元测试都在两种环境中运行。

moment.js不依赖任何第三方库，支持字符串、Date、时间戳以及数组等格式， 可以像PHP的date()函数一样，格式化日期时间，计算相对时间，获取特定时间后的日期时间等等。

2. 安装和使用

2.1 安装

2.1.1 Node.js

npm install moment

var moment = require('moment');
moment().format();

• 注意：在2.4.0版本，不推荐使用全局导出的时刻对象。它将在下一个主要版本中删除。

2.1.2 script标签引入

<script src="moment.js"></script>
<script>
    moment().format();
</script>

• 注意：Moment.js可在cdnjs.com上找到。但请记住将他们的script标签串联以最小化http请求。

2.1.3 Bower

bower install --save moment

• 注意：moment.js，locale/*.js和min/moment-with-locales.js。

2.1.4 Require.js

require.config({
    paths: {
        "moment": "path/to/moment",
    }
});
define(["moment"], function (moment) {
    moment().format();
});

Moment仍将创建一个moment全局，这对插件和其他第三方代码很有用。如果您希望压缩全局，请使用noGlobal模块配置中的选项。

require.config({
    config: {
        moment: {
            noGlobal: true
        }
    }
});

如果未指定，noGlobal则全局导出的时刻将打印弃用警告。从下一个主要版本开始，如果你想要这种行为，你必须自己导出它。

对于版本2.5.x，如果您使用其他依赖Moment但不兼容AMD的插件，则可能需要添加wrapShim: true 到r.js配置中。

• 注意：要允许在requirejs环境中加载moment.js插件，请将时刻创建为命名模块。正因为如此，时刻必须被加载完全一样的"moment"，用paths确定的目录。需要时刻与路径一样"vendor\moment"将返回undefined。

• 注意：从版本2.9.0开始，将自身导出为匿名模块，因此如果您只使用核心（没有区域设置/插件），那么如果将其放在非标准位置，则不需要配置。

2.1.5 NuGet

Install-Package Moment.js

2.1.6 spm

spm install moment --save

2.1.7 meteor

meteor add momentjs:moment

2.2 使用

Date.prototypeMoment.js 不是修改本机日期，而是为Date对象创建一个包装器。 要获取此包装器对象，只需moment()使用其中一种受支持的输入类型进行调用即可。

该Moment原型是通过暴露moment.fn。如果你想添加自己的功能，那就是你要放置它们的地方。

为便于参考，Moment.prototype将在文档中引用任何方法moment#method。 所以Moment.prototype.format=== moment.fn.format=== moment#format。

2.2.1 当前时间 1.0.0+

moment();

要获取当前日期和时间，只需moment()使用无参数调用即可。

var now = moment();

这与调用moment(new Date())基本相同。

var year1995 = moment("1995-12-25");

格式化日期1995-12-25。

2.2.2 字符串 1.0.0+

moment(String);

从字符串创建时刻时，我们首先检查字符串是否与已知的ISO 8601格式匹配， 然后在new Date(string)找不到已知格式时返回。

var day = moment("1995-12-25");

• 警告：浏览器对解析字符串支持不一致。 由于没有关于应支持哪种格式的规范，因此在某些浏览器中有效的功能将无法在其他浏览器中使用。

为了解析除ISO 8601字符串以外的任何其他内容的一致结果， 您应该使用String + Format。

支持的ISO 8601字符串

ISO 8601字符串需要日期部分。

2013-02-08  # A calendar date part
2013-W06-5  # A week date part
2013-039    # An ordinal date part

还可以包括时间部分，通过空格或大写T与日期部分分开。

2013-02-08T09            # An hour time part separated by a T
2013-02-08 09            # An hour time part separated by a space
2013-02-08 09:30         # An hour and minute time part
2013-02-08 09:30:26      # An hour, minute, and second time part
2013-02-08 09:30:26.123  # An hour, minute, second, and millisecond time part
2013-02-08 24:00:00.000  # hour 24, minute, second, millisecond equal 0 means next day at midnight

任何日期部分都可以包含时间部分。

2013-02-08 09  # A calendar date part and hour time part
2013-W06-5 09  # A week date part and hour time part
2013-039 09    # An ordinal date part and hour time part

如果一个时间部分被包括，一个从UTC偏移量也可被包括为+-HH:mm，+-HHmm，或Z。

2013-02-08 09+07:00            # +-HH:mm
2013-02-08 09-0100             # +-HHmm
2013-02-08 09Z                 # Z
2013-02-08 09:30:26.123+07:00  # +-HH:mm

• 注意：1.5.0版中添加了自动跨浏览器ISO-8601支持。版本2.3.0中添加了对星期和序数格式的支持。 如果字符串与上述任何格式都不匹配且无法解析Date.parse，moment#isValid则返回false。

moment("not a real date").isValid(); // false

2.2.3 字符串+格式 1.0.0+

moment(String, String);
moment(String, String, String);
moment(String, String, Boolean);
moment(String, String, String, Boolean);

如果您知道输入字符串的格式，可以使用它来解析片刻。

moment("12-25-1995", "MM-DD-YYYY");

解析器忽略非字母数字字符，因此以下两个都将返回相同的内容。

moment("12-25-1995", "MM-DD-YYYY");
moment("12/25/1995", "MM-DD-YYYY");

解析令牌类似于使用的格式化令牌moment#format。

年，月，日缩写

YYYY从版本2.10.5支持2位数年份，并将它们转换为2000年附近的一年（相同YY）。

周年，周和工作日缩写

对于这些，小写标记使用区域设置感知周开始日期，而大写标记使用ISO周日期开始日期。

小时，分钟，秒，毫秒和偏移缩写

从版本2.10.5：小数秒标记长度4到9可以解析任意数量的数字，但只考虑前3（毫秒）。如果您有时间打印了许多小数位并想要消耗输入，请使用。

还可以使用区域设置感知日期和时间格式LT LTS L LL LLL LLLL。它们是在2.2.1版本中添加的，除了LTS增加了 2.8.4。

Z ZZ在版本中添加1.2.0。

S SS SSS在版本中添加1.6.0。

X在版本中添加2.0.0。

除非指定时区偏移量，否则解析字符串将在当前时区中创建日期。

moment("2010-10-20 4:30",       "YYYY-MM-DD HH:mm");   // parsed as 4:30 local time
moment("2010-10-20 4:30 +0000", "YYYY-MM-DD HH:mm Z"); // parsed as 4:30 UTC

如果由解析的输入产生的时刻不存在，moment#isValid则返回false。

moment("2010 13",           "YYYY MM").isValid();     // false (not a real month)
moment("2010 11 31",        "YYYY MM DD").isValid();  // false (not a real day)
moment("2010 2 29",         "YYYY MM DD").isValid();  // false (not a leap year)
moment("2010 notamonth 29", "YYYY MMM DD").isValid(); // false (not a real month name)

从版本开始2.0.0，可以将区域设置键作为第三个参数传递给moment()和moment.utc()。

moment('2012 juillet', 'YYYY MMM', 'fr');
moment('2012 July',    'YYYY MMM', 'en');

Moment的解析器非常宽容，这可能会导致不良行为。从版本开始2.3.0，您可以为最后一个参数指定一个布尔值， 以使Moment使用严格的解析。严格的解析要求格式和输入完全匹配。

moment('It is 2012-05-25', 'YYYY-MM-DD').isValid();       // true
moment('It is 2012-05-25', 'YYYY-MM-DD', true).isValid(); // false
moment('2012-05-25',       'YYYY-MM-DD', true).isValid(); // true

您可以同时使用区域设置和严格性。

moment('2012-10-14', 'YYYY-MM-DD', 'fr', true);

解析两位数年份

默认情况下，68岁以上的两位数年份假定为1900年，68年或以下年份假定为2000年。可以通过替换moment.parseTwoDigitYear方法来更改此设置。

2.2.4 格式化时间 1.0.0+

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

var day = moment().format()  // 2018-08-17T08:41:34+08:00
var dayMMDoYYYYHHmmssa = moment().format('MMMM Do YYYY, h:mm:ss a')  // 八月 17日 2018, 8:41:34 早上 
var daydddd = moment().format('dddd')  // 星期五
var dayMMMDoYY = moment().format('MMM Do YY')  // 8月 17日 18
var dayYYYYescapedYYYY = moment().format('YYYY [escaped] YYYY')  // 2018 escaped 2018

2.2.5 时差(之前，现在为基准) 1.0.0+

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

显示时间的常用方法由处理moment#fromNow。这有时被称为timeago或相对时间。

var dayYYYYMMDD = moment("20111031", "YYYYMMDD").fromNow(); // 7 年前
var dayYYYYMMDD2 = moment("20120620", "YYYYMMDD").fromNow(); // 6 年前

如果通过true，则可以获得不带后缀的值。

var dayYear = moment([2007, 0, 29]).fromNow(true);       // 4 年

2.2.6 时差(之前) 1.0.0+

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

您可能希望显示与现在不同的时间相关的时刻。在这种情况下，您可以使用moment#from。

var a = moment([2007, 0, 28]);
var b = moment([2007, 0, 29]);
a.from(b) // "a day ago"

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

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

比如moment#fromNow，传递true第二个参数返回没有后缀的值。只要您需要具有人类可读的时间长度，这就非常有用。

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

2.2.7 时差(毫秒) 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#diff像使用一样使用moment#from。

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

支持的测量包括年，月，周，日，小时，分钟和秒。为了便于开发，从2.0.0开始支持单数形式。版本1.1.1中提供了毫秒以外的度量单位。

默认情况下，moment#diff将向下舍入数字。如果需要浮点数，则传递true为第三个参数。 在2.0.0之前，moment#diff返回舍入的数字，而不是向下舍入的数字。

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

如果时刻早于您传递的时刻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版本，差异也支持季度单位。

2.2.8 操纵时间(加法) 1.0.0+

通过增加时间来改变原始时刻。

这是一个非常强大的功能，可以为现有时刻增加时间。要添加时间，请传递要添加的时间键以及要添加的金额。

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

如果你涉及整个简洁的事情，也有一些速记键。

moment().add(7, 'days');
moment().add(7, 'd');

如果要同时添加多个不同的键，可以将它们作为对象文字传递。

moment().add(7, 'days').add(1, 'months'); // with chaining
moment().add({days:7,months:1}); // with object literal

金额没有上限，因此您可以重载任何参数。

moment().add(1000000, 'milliseconds'); // a million milliseconds
moment().add(360, 'days'); // 360 days

几个月和几年的特殊考虑

如果原始日期的月份日期大于最后一个月的天数，则该月的日期将更改为最后一个月的最后一天。

moment([2010, 0, 31]);                  // January 31
moment([2010, 0, 31]).add(1, 'months'); // February 28

在添加跨越夏令时的时间时，还要特别注意。如果您要添加年，月，周或天，则原始小时将始终与添加的小时相匹配。

var m = moment(new Date(2011, 2, 12, 5, 0, 0)); // the day before DST in the US
m.hours(); // 5
m.add(1, 'days').hours(); // 5

如果要添加小时，分钟，秒或毫秒，则假设您需要精确到小时，并且将导致不同的小时。

var m = moment(new Date(2011, 2, 12, 5, 0, 0)); // the day before DST in the US
m.hours(); // 5
m.add(24, 'hours').hours(); // 6

或者，您可以使用持续时间添加到时刻。

var duration = moment.duration({'days' : 1});
moment([2012, 0, 31]).add(duration); // February 1

在版本之前2.8.0，moment#add(String, Number)还支持语法。它已经被弃用了moment#add(Number, String)。

moment().add('seconds', 1); // Deprecated in 2.8.0
moment().add(1, 'seconds');

2.2.9 操纵时间(减法) 1.0.0+

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

通过减去时间来改变原始时刻。

这与完全相同moment#add，只是减去时间，而不是增加时间。

moment().subtract(7, 'days');

在版本之前2.8.0，moment#subtract(String, Number)还支持语法。它已经被弃用了moment#subtract(Number, String)。

moment().subtract('seconds', 1); // Deprecated in 2.8.0
moment().subtract(1, 'seconds');

2.2.10 开始时间 1.7.0+

moment().startOf(String);

通过将其设置为单位时间的开始来突变原始时刻。

moment().startOf('year');    // set to January 1st, 12:00 am this year
moment().startOf('month');   // set to the first of this month, 12:00 am
moment().startOf('quarter');  // set to the beginning of the current quarter, 1st day of months, 12:00 am
moment().startOf('week');    // set to the first day of this week, 12:00 am
moment().startOf('isoWeek'); // set to the first day of this week according to ISO 8601, 12:00 am
moment().startOf('day');     // set to 12:00 am today
moment().startOf('hour');    // set to now, but with 0 mins, 0 secs, and 0 ms
moment().startOf('minute');  // set to now, but with 0 seconds and 0 milliseconds
moment().startOf('second');  // same as moment().milliseconds(0);

这些快捷方式基本上与以下内容相同。

moment().startOf('year');
moment().month(0).date(1).hours(0).minutes(0).seconds(0).milliseconds(0);

moment().startOf('hour');
moment().minutes(0).seconds(0).milliseconds(0)

从版本2.0.0开始，moment#startOf('day')替换moment#sod。

注意： moment#startOf('week')在2.0.0版中添加了。

从版本2.1.0开始，moment#startOf('week')使用区域设置感知周开始日。

注意： moment#startOf('isoWeek')在2.2.0版中添加了。

2.2.11 结束时间 1.7.0+

moment().endOf(String);

通过将其设置为单位时间的结尾来突变原始时刻。

这与moment#startOf仅设置为单位时间的开始，而不是设置为单位时间的结束。

moment().endOf("year"); // set the moment to 12-31 11:59:59.999 pm this year

从版本2.0.0开始，moment#endOf('day')替换moment#eod。

注意： moment#endOf('week')在2.0.0版中添加了。

从版本2.1.0开始，moment#endOf('week')使用区域设置感知周开始日。

参考资料

• Moment.js 文档
• 使用moment.js轻松管理日期和时间