Moment.js

Статус проекта

Moment.js успешно используется в миллионах проектов, и мы рады, что внесли свой вклад в улучшение работы с датами и временем в интернете. По состоянию на сентябрь 2020 года Moment скачивают более 12 миллионов раз в неделю! Однако Moment был создан для предыдущей эпохи экосистемы JavaScript. Сегодня современный веб сильно отличается от прежнего. За прошедшие годы Moment в некоторой степени изменился, но его основная архитектура осталась такой же, какой была при создании в 2011 году. Учитывая, сколько проектов от него зависит, мы решили отдавать предпочтение стабильности, а не новым функциям.

Например, объекты Moment являются изменяемыми. Это частая причина недовольства Moment. Мы рассказываем об этом в рекомендациях по использованию, но для большинства новых пользователей это всё равно становится неожиданностью. Изменение Moment так, чтобы он стал неизменяемым, нарушило бы работу каждого проекта, который его использует. Создание «Moment v3» с неизменяемыми объектами стало бы огромной задачей и превратило бы Moment в совершенно другую библиотеку. Поскольку другие библиотеки уже решили эту задачу, мы считаем, что важнее сохранить изменяемый API.

Ещё один распространённый аргумент против использования Moment в современных приложениях — его размер. Moment плохо взаимодействует с современными алгоритмами «tree shaking», поэтому он обычно увеличивает размер пакетов веб-приложений. Если нужна поддержка интернационализации или часовых поясов, Moment может стать довольно большим. Современные веб-браузеры (и Node.js) предоставляют поддержку интернационализации и часовых поясов через объект Intl, закреплённый стандартом ECMA-402. Такие библиотеки, как Luxon (и другие), используют эту возможность, уменьшая или устраняя необходимость включать собственные файлы данных.

Недавно Chrome Dev Tools начали рекомендовать замену Moment исключительно из-за его размера. В целом мы поддерживаем эту инициативу.

Возможно, вам также будет интересно прочитать:

• Возможно, Moment.js вам больше не нужен
• Вам (возможно) не нужен Moment.js
• Почему не стоит использовать Moment.js...
• 4 альтернативы Moment.js для интернационализации дат

Команда Moment подробно обсудила эти вопросы. Мы понимаем, что многие существующие проекты могут и дальше использовать Moment, но хотели бы не рекомендовать его для новых проектов. Вместо этого мы хотели бы порекомендовать альтернативы, которые сегодня отлично подходят для современных приложений. Мы также хотели бы привлечь внимание к дополнению Temporal для языка JavaScript, которое находится на стадии сбора отзывов и поиска участников.

Теперь мы в целом считаем Moment устаревшим проектом, находящимся в режиме поддержки. Он не мёртв, но его развитие действительно завершено.

На практике это означает следующее:

• Мы не будем добавлять новые функции и возможности.
• Мы не будем изменять API Moment, чтобы сделать его неизменяемым.
• Мы не будем решать проблемы с tree shaking и размером пакетов.
• Мы не будем вносить никаких крупных изменений (версии 3 не будет).
• Мы можем отказаться от исправления ошибок и особенностей поведения, особенно если это давно известные проблемы.

Что касается файлов локалей для интернационализации Moment:

• Мы можем отказаться от принятия исправлений строк локалей или локализованных форматов дат, особенно если существующий вариант уже был успешно обоснован.
• Для изменений локалей необходимо предоставить убедительные аргументы, подкреплённые значимыми, не основанными на отдельных случаях доказательствами.
• Если строка или формат, которые вы просите изменить, отражены в CLDR, сначала необходимо отправить изменение туда и добиться его принятия.

Однако мы понимаем, что Moment широко используется в миллионах существующих проектов, поэтому:

• Мы будем устранять критические проблемы безопасности по мере их возникновения.
• Мы будем выпускать обновления данных для Moment-Timezone после выпуска обновлений базы данных часовых поясов IANA.

Причины продолжать использовать Moment

В большинстве случаев для новых проектов не следует выбирать Moment. Однако есть несколько причин, по которым вы можете захотеть продолжить его использовать.

Поддержка браузеров

Moment хорошо работает в Internet Explorer 8 и более поздних версиях. В отличие от него, Luxon работает только в IE 10 и более поздних версиях и требует для этого полифилла. Подробнее можно прочитать в документации Luxon.

У других библиотек также возникали проблемы с Safari, особенно на мобильных устройствах. Если вам необходимо поддерживать старые браузеры, возможно, стоит ещё некоторое время использовать Moment.

Однако Day.js заявляет о совместимости с IE8 и более поздними версиями, поэтому вы всё ещё можете рассмотреть эту альтернативу.

Зависимость других библиотек

Некоторые другие библиотеки, особенно средства выбора дат и библиотеки для построения графиков, зависят от Moment. Если вы используете такой компонент и не можете найти ему альтернативу, значит, Moment уже включён в ваш проект. Поэтому имеет смысл продолжать использовать Moment во всём проекте, а не добавлять ещё одну библиотеку для работы с датой и временем.

Привычность

Если вы давно используете Moment, возможно, вы уже хорошо знакомы с его API и ограничениями. Если это так и перечисленные выше проблемы вас не беспокоят, вы, конечно, можете продолжать его использовать.

Рекомендации

Вместо Moment можно рассмотреть несколько отличных вариантов.

При выборе учитывайте, что:

• Некоторые библиотеки разделены на модули, плагины или сопутствующие библиотеки.
• Некоторые библиотеки используют API ECMAScript Intl для локалей, часовых поясов или того и другого.
• Некоторые библиотеки, как и Moment и Moment-Timezone, по-прежнему предоставляют собственные файлы локалей и часовых поясов.

Мы рекомендуем следующие альтернативы:

Luxon

Luxon можно считать дальнейшим развитием Moment. Её создал Айзек Кэмброн, давний участник проекта Moment. Прочитайте страницы Зачем нужен Luxon? и Для пользователей Moment в документации Luxon.

• Локали: предоставляются Intl
• Часовые пояса: предоставляются Intl

Day.js

Day.js создана как минималистичная замена Moment.js с похожим API. Это не полная замена, но если вы привыкли к API Moment и хотите быстро приступить к работе, рассмотрите Day.js.

• Локали: собственные файлы данных, которые можно импортировать по отдельности
• Часовые пояса: предоставляются Intl с помощью плагина

date-fns

Date-fns предоставляет набор функций для работы с объектами JavaScript Date. Дополнительные сведения см. в разделе «Зачем date-fns?» на главной странице date-fns.

• Локали: собственные файлы данных, которые можно импортировать по отдельности
• Часовые пояса: предоставляются Intl с помощью отдельной сопутствующей библиотеки

js-Joda

js-Joda — порт библиотеки Java Three-Ten Backport для JavaScript. Она лежит в основе реализации JSR-310 пакета java.time для Java SE 8. Если вы знакомы с java.time, Joda-Time или Noda Time, js-Joda покажется вам похожей библиотекой.

• Локали: собственные файлы данных через дополнительный модуль
• Часовые пояса: собственные файлы данных через дополнительный модуль

Без библиотеки

В JavaScript всегда был объект Date, определённый спецификацией ECMAScript (ECMA-262), здесь.

При использовании объектов Date учитывайте следующее:

• Объект Date внутренне представляет собой метку времени Unix с точностью до миллисекунды. Он предоставляет функции преобразования в местный часовой пояс системы и обратно, но внутри всегда использует UTC. В отличие от объекта Moment, его нельзя настроить на использование другого часового пояса: понятия «режима» у него нет.

• Использование Date.parse или new Date(<string>) в прошлом вызывало проблемы, а реализация отличалась в разных средах. Текущая спецификация определяет разбор строк, соответствующих варианту ISO 8601, при этом формы, содержащие только дату (например, "2020-09-14"), разбираются как UTC, а не как местное время, как это было бы согласно ISO 8601. Даже сейчас не все современные реализации корректно реализуют эту спецификацию (например, Safari). Другие типы строк могут работать, но их разбор зависит от конкретной реализации и может существенно различаться, особенно в старых браузерах. Результат может оказаться неожиданным в зависимости от реализации и компонентов, указанных в строке. По этим причинам мы согласны с утверждением MDN, что разбор строк с помощью объекта Date настоятельно не рекомендуется.

В современных средах JavaScript также реализована спецификация ECMA-402, предоставляющая объект Intl и определяющая параметры поведения функций toLocaleString, toLocaleDateString и toLocaleTimeString объекта Date.

При использовании объекта Intl учитывайте следующее:

• Не каждая среда реализует спецификацию полностью. В частности, для поддержки интернационализации в средах Node.js требуется ICU. Дополнительные сведения см. в документации Node.js.
• Таблица совместимости ECMAScript Intl (автор — kangax) поможет определить, какие функции поддерживаются, а какие нет.
• В большинстве новых сред поддержка часовых поясов IANA предоставляется через параметр timeZone конструктора Intl.DateTimeFormat (а также функций Date.toLocaleString, Date.toLocaleDateString и Date.toLocaleTimeString). Этот параметр позволяет взять внутреннюю метку времени объекта Date, основанную на UTC, и получить строку, преобразованную в именованный часовой пояс. Однако его нельзя использовать для преобразования объекта Date в другой часовой пояс.

Если объектов Date и Intl вам достаточно и вы полностью понимаете их ограничения, можете рассмотреть возможность использовать их напрямую.

Будущее

Temporal — улучшенная работа с датами и временем в языке JavaScript!

Мы надеемся, что в скором будущем библиотеки для работы с датой и временем в JavaScript вообще не понадобятся. Вместо них мы сможем пользоваться возможностями самого языка JavaScript. Некоторые из этих возможностей уже доступны благодаря Date и Intl, но, как показывают наш опыт и данные, их можно значительно улучшить.

Работа над улучшением API для работы с датой и временем в языке JavaScript ведётся в рамках предложения ECMA TC39 Temporal. Сейчас оно находится на третьем этапе процесса TC39.

Temporal станет новым глобальным объектом, выступающим в роли пространства имён верхнего уровня (как Math). Он предоставляет множество отдельных типов объектов, включая Temporal.Instant, Temporal.ZonedDateTime, Temporal.PlainDateTime, Temporal.PlainDate, Temporal.PlainTime и другие. В сборнике рецептов Temporal приведено множество примеров использования этих объектов в различных ситуациях.

Попробовать Temporal можно уже сегодня с помощью полифилла, не предназначенного для промышленного использования. Попробуйте его, но пока не используйте в промышленной среде!

Оставляйте отзывы и рассмотрите возможность внести вклад в эту работу — особенно если у вас есть опыт использования Moment или других библиотек для работы с датой и временем!

Использование Moment

Moment создан для работы как в браузере, так и в Node.js.

Весь код должен работать в обеих этих средах, и все модульные тесты запускаются в каждой из них.

В настоящее время в системе CI используются следующие браузеры: Chrome в Windows XP, IE 8, 9 и 10 в Windows 7, IE 11 в Windows 10, последняя версия Firefox в Linux и последняя версия Safari в OSX 10.8 и 10.11.

Чтобы попробовать приведённые ниже примеры кода, откройте консоль браузера и введите их.

Node.js

npm install moment

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

Или с использованием синтаксиса ES6:

import moment from 'moment';
moment().format();

Примечание: В версии 2.4.0 глобально экспортируемый объект moment был объявлен устаревшим. Он будет удалён в следующем крупном выпуске.

Если вы также хотите подключить Moment Timezone, примеры см. в отдельной документации Moment Timezone для Node.js.

Браузер

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

Moment.js доступен на cdnjs.com и jsDelivr.

Bower

bower

bower install --save moment

Основные файлы: moment.js, locale/*.js и min/moment-with-locales.js.

Require.js

Мы настоятельно рекомендуем прочитать этот материал, если вы планируете использовать moment с Require.js. Для наилучшей работы также обновитесь до версии 2.14.0 или более поздней.

Для начала вы могли получить moment через bower, node_modules или другой источник, который размещает moment.js вместе с каталогом локалей в базовой папке. Тогда следует воспользоваться таким инструментом, как adapt-pkg-main, или настроить параметры вручную с помощью конфигурации packages.

requirejs.config({
  packages: [{
    name: 'moment',
    // This location is relative to baseUrl. Choose bower_components
    // or node_modules, depending on how moment was installed.
    location: '[bower_components|node_modules]/moment',
    main: 'moment'
  }]
});

С такой настройкой можно подключить ядро с помощью moment, а локаль de — с помощью moment/locale/de.

// only needing core
define(['moment'], function (moment) {
    console.log(moment().format('LLLL'));  // 'Friday, June 24, 2016 1:42 AM'
});

// core with single locale
define(['moment', 'moment/locale/de'], function (moment) {
    moment.locale('de');
    console.log(moment().format('LLLL')); // 'Freitag, 24. Juni 2016 01:42'
});

// core with all locales
define(['moment/min/moment-with-locales'], function (moment) {
    moment.locale('de');
    console.log(moment().format('LLLL')); // 'Freitag, 24. Juni 2016 01:42'
});

// async load locale
define(['require', 'moment'], function(require, moment) {
  // Inside some module after the locale is detected. This is the
  // case where the locale is not known before module load time.
  require(['moment/locale/de'], function(localeModule) {
    // here the locale is loaded, but not yet in use
    console.log(moment().format('LLLL'));  // 'Friday, June 24, 2016 1:42 AM'

    moment.locale('de');
    // Use moment now that the locale has been properly set.
    console.log(moment().format('LLLL')); // 'Freitag, 24. Juni 2016 01:42'
  })
});

Для более сложных случаев использования прочитайте подробное объяснение @jrburke.

Moment по-прежнему создаёт глобальную переменную moment, полезную для плагинов и другого стороннего кода. Чтобы убрать эту глобальную переменную, используйте параметр noGlobal в конфигурации модуля.

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

Если не указать noGlobal, глобально экспортируемый объект moment выведет предупреждение об устаревании. Начиная со следующего крупного выпуска, если вам нужно такое поведение, вам придётся экспортировать его самостоятельно.

Для версии 2.5.x, если вы используете другие плагины, зависящие от Moment, но несовместимые с AMD, возможно, потребуется добавить wrapShim: true в конфигурацию r.js.

Примечание: Чтобы плагины moment.js можно было загружать в средах requirejs, moment создаётся как именованный модуль. Поэтому moment необходимо загружать точно так же, как "moment", используя paths для определения каталога. Подключение moment по пути, например "vendor\moment", вернёт undefined.

Примечание: Начиная с версии 2.9.0, moment экспортируется как анонимный модуль. Поэтому, если вы используете только ядро (без локалей и плагинов), конфигурация не нужна, если вы размещаете его в нестандартном каталоге.

meteor

meteor / atmosphere / momentjs:moment

meteor add momentjs:moment

Browserify

npm install moment

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

Примечание: Из-за ошибки загрузка moment.locale невозможна.

var moment = require('moment');
moment.locale('cs');
console.log(moment.locale()); // en

Используйте приведённый ниже обходной путь

var moment = require('moment');
require('moment/locale/cs');
console.log(moment.locale()); // cs

Чтобы включить все локали

var moment = require('moment');
require("moment/min/locales.min");
moment.locale('cs');
console.log(moment.locale()); // cs

Webpack

npm install moment

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

Примечание: По умолчанию webpack включает в пакет все локали Moment.js (в Moment.js 2.18.1 это 160 КБ в минифицированном виде). Чтобы удалить ненужные локали и включить в пакет только используемые, добавьте moment-locales-webpack-plugin:

// webpack.config.js
const MomentLocalesPlugin = require('moment-locales-webpack-plugin');

module.exports = {
    plugins: [
        // To strip all locales except “en”
        new MomentLocalesPlugin(),

        // Or: To strip all locales except “en”, “es-us” and “ru”
        // (“en” is built into Moment and can’t be removed)
        new MomentLocalesPlugin({
            localesToKeep: ['es-us', 'ru'],
        }),
    ],
};

Есть и другие способы оптимизировать Moment.js при работе с webpack, например этот.

Typescript 2.13.0+

Начиная с версии 2.13.0, Moment включает файл описаний типов TypeScript.

Установите через NPM

npm install moment

Импортируйте и используйте в файле TypeScript

const moment = require('moment');

let now = moment().format('LLLL');

Примечание: Если у вас возникли проблемы с импортом moment

Для Typescript 2.x попробуйте добавить "moduleResolution": "node" в compilerOptions в файле tsconfig.json

Для Typescript 1.x попробуйте добавить "allowSyntheticDefaultImports": true в compilerOptions в файле tsconfig.json, а затем использовать следующий синтаксис

import moment from 'moment';

Импорт локали

Чтобы использовать moment.locale, сначала импортируйте нужный язык.

import * as moment from 'moment';
import 'moment/locale/pt-br';

console.log(moment.locale()); // en
moment.locale('fr');
console.log(moment.locale()); // fr
moment.locale('pt-br');
console.log(moment.locale()); // pt-br

System.js

Чтобы загрузить moment, поместите его по пути, указанному в конфигурации System.config в параметре baseURL. Затем импортируйте его на страницу.

<script src="system.js"></script>
<script>
  System.config({
    baseURL: '/app'
  });

  System.import('moment.js');
 </script>

Если необходимо загрузить moment как глобальную переменную, это можно сделать с помощью конфигурации meta:

System.config({
  meta: {
    'moment': { format: 'global' }
  }
});

Можно также предоставить Moment как глобальную переменную только для определённой зависимости:

System.config({
  meta: {
    'path/to/global-file.js': {
      globals: {
        moment: 'moment'
      }
    }
  }
});

Другие варианты

Инструкции по использованию в Java/Rhino см. здесь.

Инструкции по использованию в Demandware см. здесь.

Устранение неполадок

Если у вас возникли проблемы, в первую очередь ознакомьтесь с руководствами.

Если вы не нашли там нужной информации, задайте вопрос на Stack Overflow с тегом momentjs.

Примечание: более чем на половину вопросов, встречающихся на Stack Overflow, можно ответить, прочитав эту публикацию в блоге.

Вы также можете воспользоваться системой отслеживания ошибок GitHub, чтобы найти похожие проблемы или открыть новую.

Кроме того, у Moment есть канал Gitter, где часто можно связаться с командой проекта.

Для общих вопросов по устранению неполадок лучше всего подходит Stack Overflow. Сопровождающие Moment активно отвечают там, как и многие другие опытные пользователи. Быстрее всего вам ответят именно там.

Разбор

Вместо изменения встроенного Date.prototype Moment.js создаёт оболочку для объекта Date. Чтобы получить этот объект-оболочку, просто вызовите moment(), передав один из поддерживаемых типов входных данных.

Прототип Moment доступен через moment.fn. Если вы хотите добавить собственные функции, добавляйте их туда.

Для удобства ссылки на любые методы Moment.prototype в документации имеют вид moment#method. Таким образом, Moment.prototype.format == moment.fn.format == moment#format.

Обратите внимание:

• moment(...) — локальный режим. Неоднозначные входные данные (без смещения) считаются местным временем. Однозначные входные данные (со смещением) преобразуются в местное время.
• moment.utc(...) — режим UTC. Неоднозначные входные данные считаются временем UTC. Однозначные входные данные преобразуются в UTC.
• moment.parseZone() сохраняет переданный входной часовой пояс. Неоднозначные входные данные считаются временем UTC.
• moment.tz(...) с плагином moment-timezone позволяет разбирать входные данные в определённом часовом поясе.

Помните, что часовой пояс и смещение часового пояса — это разные вещи. Смещение -08:00 не обязательно означает, что вы находитесь в часовом поясе Тихоокеанского побережья США.

Дополнительные сведения см. в руководстве по разбору.

Текущий момент 1.0.0+

moment();
moment(undefined);
// From 2.14.0 onward, also supported
moment([]);
moment({});

Чтобы получить текущие дату и время, просто вызовите moment() без параметров.

var now = moment();

По сути, это то же самое, что вызвать moment(new Date()).

Примечание: Начиная с версии 2.14.0, moment([]) и moment({}) также возвращают текущий момент. До версии 2.14.0 по умолчанию они возвращали начало текущего дня, но это было произвольное решение, поэтому поведение изменили.

Примечание: Если параметры функции не переданы, по умолчанию они имеют значение undefined. Moment трактует moment(undefined) как moment().

Примечание: Объекты Moment создаются во время вычисления, поэтому moment().diff(moment()) не всегда возвращает 0. Подробнее см. эту проблему на GitHub.

Строка 1.0.0+

moment(String);

При создании объекта moment из строки мы сначала проверяем, соответствует ли строка известным форматам ISO 8601, затем проверяем, соответствует ли она формату даты и времени RFC 2822. Если известный формат не найден, выполняется резервный разбор с помощью new Date(string).

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

Предупреждение: Поддержка разбора строк в браузерах неодинакова. Поскольку не существует спецификации форматов, которые должны поддерживаться, то, что работает в одном браузере, может не работать в другом.

Для стабильного разбора строк, не соответствующих ISO 8601, используйте строку с указанием формата.

Поддерживаемые строки ISO 8601

Строка ISO 8601 должна содержать дату.

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

20130208    # Basic (short) full date
201303      # Basic (short) year+month
2013        # Basic (short) year only
2013W065    # Basic (short) week, weekday
2013W06     # Basic (short) week only
2013050     # Basic (short) ordinal date (year + day-of-year)

Также можно указать время, отделив его от даты пробелом или заглавной буквой 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

20130208T080910,123      # Short date and time up to ms, separated by comma
20130208T080910.123      # Short date and time up to ms
20130208T080910          # Short date and time up to seconds
20130208T0809            # Short date and time up to minutes
20130208T08              # Short date and time, hours only

Любая часть даты может сопровождаться временем.

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, +-HH или 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
2013-02-08 09:30:26.123+07     # +-HH

Примечание: Поддержка форматов с номером недели и порядковым номером дня года появилась в версии 2.3.0.

Если строка не соответствует ни одному из указанных выше форматов и не может быть разобрана с помощью Date.parse, moment#isValid вернёт false.

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

Формат даты и времени RFC 2822

Перед разбором даты и времени RFC 2822 из строки удаляются все комментарии и символы новой строки. Эти дополнительные символы допустимы в формате, но не влияют на создание корректного экземпляра moment.

После очистки строка проверяется по следующим разделённым пробелами частям, все они должны быть на английском языке:

6 Mar 17 21:22 UT
6 Mar 17 21:22:23 UT
6 Mar 2017 21:22:23 GMT
06 Mar 2017 21:22:23 Z
Mon 06 Mar 2017 21:22:23 z
Mon, 06 Mar 2017 21:22:23 +0000

1. Трёхбуквенное сокращение дня недели, после которого может идти запятая. (необязательно)
2. День месяца (1 или 2 цифры), затем трёхбуквенное название месяца и год из 2 или 4 цифр
3. Часы и минуты из двух цифр, разделённые двоеточием (:), после которых могут идти секунды из двух цифр, также отделённые двоеточием
4. Часовой пояс или смещение в одном из следующих форматов:
5. UT : +0000
6. GMT : +0000
7. EST | CST | MST | PST | EDT | CDT | MDT | PDT : часовые пояса США*
8. A - I | K - Z : военные часовые пояса*
9. Смещение времени +/-9999

[*] Подробнее см. раздел 4.3 спецификации.

Парсер также проверяет, соответствует ли день недели (если он указан) дате.

Строка + формат 1.0.0+

moment(String, String);
moment(String, String, String);
moment(String, String, String[]);
moment(String, String, Boolean);
moment(String, String, String, Boolean);

Если формат входной строки вам известен, используйте его для разбора даты Moment.

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

По умолчанию парсер игнорирует небуквенно-цифровые символы, поэтому оба следующих примера вернут одинаковый результат.

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

При разборе даты и времени можно получить неожиданный результат. Следующий пример может быть разобран не так, как вы ожидаете:

moment('24/12/2019 09:15:00', "DD MM YYYY hh:mm:ss");

Можно включить строгий режим: он обнаружит ошибку разбора и сделает объект Moment недействительным:

moment('24/12/2019 09:15:00', "DD MM YYYY hh:mm:ss", true);

Токены разбора похожи на токены форматирования, используемые в moment#format.

Токены года, месяца и дня

Регистр токенов имеет значение.

Версия YYYY начиная с 2.10.5 поддерживает двузначные годы в режиме, отличном от strict, и преобразует их в год около 2000 (как YY).

Y добавлен в версии 2.11.1. Он соответствует любому числу, со знаком или без него. Этот токен полезен для годов, записанных не четырьмя цифрами, или дат до нашей эры. Его можно использовать для любого года.

Токены года недели, недели и дня недели

Для этих токенов строчные буквы используют начало недели, заданное локалью, а заглавные — начало недели согласно неделе по ISO.

Регистр токенов имеет значение.

Форматы с учетом локали

Также доступны форматы даты и времени с учетом локали с помощью LT LTS L LL LLL LLLL. Они добавлены в версии 2.2.1, за исключением LTS, который добавлен в версии 2.8.4.

Токены чувствительны к регистру.

Токены часов, минут, секунд, миллисекунд и смещения

Токены чувствительны к регистру.

Начиная с версии 2.10.5: токены дробных секунд длиной от 4 до 9 символов могут разбирать любое количество цифр, но учитываются только первые 3 (миллисекунды). Используйте их, если время задано большим количеством дробных цифр и нужно обработать всю строку ввода.

Обратите внимание: количество указанных символов S имеет значение только при разборе в строгом режиме. В стандартном режиме S, SS, SSS, SSSS эквивалентны и интерпретируются как доли секунды. Например, .12 всегда означает 120 миллисекунд; передача SS не приведет к интерпретации значения как 12 миллисекунд.

Z ZZ добавлены в версии 1.2.0.

S SS SSS добавлены в версии 1.6.0.

X добавлен в версии 2.0.0.

SSSSS ... SSSSSSSSS добавлены в версии 2.10.5.

k kk добавлены в версии 2.13.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

Токены года и эры

Токены чувствительны к регистру.

Поддержка эр добавлена в версии 2.25.0. Токены и API пока могут измениться.

Примечания и подводные камни

Если момент времени, полученный в результате разбора входных данных, не существует, 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('2012 July',    'YYYY MMM', ['qj', 'en']);

Парсер Moment очень снисходителен, что может привести к нежелательному или неожиданному поведению.

Например, можно наблюдать следующее поведение:

moment('2016 is a date', 'YYYY-MM-DD').isValid() //true, 2016 was matched

До версии 2.13.0 парсер вел себя следующим образом. Это исправлено.

moment('I am spartacus', 'h:hh A').isValid();     //true - the 'am' matches the 'A' flag.

Начиная с версии 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.05.25',       'YYYY-MM-DD', true).isValid(); // false

Можно одновременно задать локаль и строгость разбора.

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

Строгий разбор часто является наилучшим вариантом. Подробнее о выборе строгого или снисходительного разбора см. в руководстве по разбору.

Разбор двухзначных годов

По умолчанию двухзначные годы больше 68 считаются годами 1900-х, а годы 68 и меньше — годами 2000-х. Это поведение можно изменить, переопределив метод moment.parseTwoDigitYear. Единственный аргумент этого метода — строка с двумя цифрами года, введенными пользователем; метод должен вернуть год в виде целого числа.

moment.parseTwoDigitYear = function(yearString) {
    return parseInt(yearString) + 2000;
}

Разбор слитно записанных часов и минут

Начиная с версии 2.11.0, поддерживается разбор hmm, Hmm, hmmss и Hmmss:

moment("123", "hmm").format("HH:mm") === "01:23"
moment("1234", "hmm").format("HH:mm") === "12:34"

Строка + форматы 1.0.0+

moment(String, String[], String, Boolean);

Если точный формат входной строки неизвестен, но известно, что он может быть одним из нескольких, можно использовать массив форматов.

Это аналогично Строка + формат, но здесь будет предпринята попытка сопоставить входные данные с несколькими форматами.

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

Начиная с версии 2.3.0, Moment использует простые эвристики для выбора формата. В порядке приоритета:

• Предпочитать форматы, дающие допустимые даты, а не недопустимые.
• Предпочитать форматы, которые разбирают большую часть строки и используют большую часть формата, то есть отдавать предпочтение более строгому разбору.
• Предпочитать форматы, расположенные раньше в массиве.

moment("29-06-1995", ["MM-DD-YYYY", "DD-MM", "DD-MM-YYYY"]); // uses the last format
moment("05-06-1995", ["MM-DD-YYYY", "DD-MM-YYYY"]);          // uses the first format

Также можно указать аргументы локали и строгости разбора. Они работают так же, как и при использовании одного формата.

moment("29-06-1995", ["MM-DD-YYYY", "DD-MM-YYYY"], 'fr');       // uses 'fr' locale
moment("29-06-1995", ["MM-DD-YYYY", "DD-MM-YYYY"], true);       // uses strict parsing
moment("05-06-1995", ["MM-DD-YYYY", "DD-MM-YYYY"], 'fr', true); // uses 'fr' locale and strict parsing

Примечание: Разбор с использованием нескольких форматов значительно медленнее разбора с одним форматом. Если есть возможность, использование одного формата существенно быстрее.

Специальные форматы 2.7.0+

moment(String, moment.CUSTOM_FORMAT, [String], [Boolean]);
moment(String, moment.HTML5_FMT.DATETIME_LOCAL, [String], [Boolean]); // from 2.20.0
moment(String, [..., moment.ISO_8601, ...], [String], [Boolean]);

ISO-8601 — стандарт представления времени и длительности. Moment уже поддерживает разбор строк ISO-8601, но при создании объекта moment этот формат можно указать явно в формате или списке форматов.

Для разбора ISO-8601 укажите константу moment.ISO_8601.

moment("2010-01-01T05:06:07", moment.ISO_8601);
moment("2010-01-01T05:06:07", ["YYYY", moment.ISO_8601]);

Начиная с версии 2.20.0, следующие форматы HTML5 доступны в качестве констант в свойстве HTML5_FMT объекта moment (moment.HTML5_FMT.*):

Объект 2.2.1+

moment({unit: value, ...});

moment({ hour:15, minute:10 });
moment({ y    :2010, M     :3, d   :5, h    :15, m      :10, s      :3, ms          :123});
moment({ year :2010, month :3, day :5, hour :15, minute :10, second :3, millisecond :123});
moment({ years:2010, months:3, days:5, hours:15, minutes:10, seconds:3, milliseconds:123});
moment({ years:2010, months:3, date:5, hours:15, minutes:10, seconds:3, milliseconds:123});
moment({ years:'2010', months:'3', date:'5', hours:'15', minutes:'10', seconds:'3', milliseconds:'123'});  // from 2.11.0

Можно создать объект moment, указав некоторые единицы измерения в объекте.

Для неуказанных единиц используются значения 0 или текущие дата, месяц и год.

Ключи day и date означают день месяца.

date добавлен в версии 2.8.4.

Строковые значения (как показано в последней строке) поддерживаются начиная с версии 2.11.0.

Обратите внимание: как и moment(Array) и new Date(year, month, date), месяцы нумеруются с 0.

Метка времени Unix (миллисекунды) 1.0.0+

moment(Number);

Как и в случае с new Date(Number), можно создать объект moment, передав целочисленное значение, представляющее количество миллисекунд с начала эпохи Unix (1 января 1970 года, 00:00 UTC).

var day = moment(1318781876406);

Примечание: ECMAScript называет это «значением времени»

Метка времени Unix (секунды) 1.6.0+

moment.unix(Number)

Чтобы создать объект moment из метки времени Unix (секунд с начала эпохи Unix), используйте moment.unix(Number).

var day = moment.unix(1318781876);

Реализация основана на moment(timestamp * 1000), поэтому дробные секунды во входной метке времени учитываются.

var day = moment.unix(1318781876.721);

Примечание: Несмотря на то что метки времени Unix основаны на UTC, эта функция создает объект moment в локальном режиме. Если требуется UTC, вызовите затем .utc(), например:

var day = moment.unix(1318781876).utc();

Дата 1.0.0+

moment(Date);

Можно создать Moment на основе существующего нативного объекта JavaScript Date.

var day = new Date(2011, 9, 16);
var dayWrapper = moment(day);

Этот вызов клонирует объект Date; дальнейшие изменения объекта Date не повлияют на Moment, и наоборот.

Массив 1.0.0+

moment(Number[]);

Можно создать объект moment с помощью массива чисел, соответствующих параметрам, передаваемым в new Date()

[year, month, day, hour, minute, second, millisecond]

moment([2010, 1, 14, 15, 25, 50, 125]); // February 14th, 3:25:50.125 PM

Все значения после года необязательны и по умолчанию принимают наименьшее возможное значение.

moment([2010]);        // January 1st
moment([2010, 6]);     // July 1st
moment([2010, 6, 10]); // July 10th

Создание объекта с помощью массива создает дату в текущем часовом поясе. Чтобы создать дату по UTC из массива, используйте moment.utc(Number[]).

moment.utc([2010, 1, 14, 15, 25, 50, 125]);

Примечание: Поскольку используются те же параметры, что и у нативного Date, месяцы, часы, минуты, секунды и миллисекунды нумеруются с 0. Годы и дни месяца нумеруются с 1.

Это часто вызывает затруднения, особенно при работе с месяцами, поэтому имейте это в виду!

Если дата, заданная массивом, не существует, moment#isValid вернет false.

moment([2010, 12]).isValid();     // false (not a real month)
moment([2010, 10, 31]).isValid(); // false (not a real day)
moment([2010, 1, 29]).isValid();  // false (not a leap year)

Дата JSON ASP.NET 1.3.0+

moment(String);

Microsoft Web API по умолчанию возвращает даты JSON в корректном формате ISO-8601, однако более старые технологии ASP.NET могут возвращать даты JSON в виде /Date(1198908717056)/ или /Date(1198908717056-0700)/

Если передать строку, соответствующую этому формату, она будет корректно разобрана.

moment("/Date(1198908717056-0700)/"); // 2007-12-28T23:11:57.056-07:00

Клонирование Moment 1.2.0+

moment(Moment);

Все объекты moment являются изменяемыми. Клонировать объект moment можно неявно или явно.

Вызов moment() для объекта moment создаст его клон.

var a = moment([2012]);
var b = moment(a);
a.year(2000);
b.year(); // 2012

Кроме того, для клонирования объекта moment можно вызвать moment#clone.

var a = moment([2012]);
var b = a.clone();
a.year(2000);
b.year(); // 2012

UTC 1.5.0+

moment.utc();
moment.utc(Number);
moment.utc(Number[]);
moment.utc(String);
moment.utc(String, String);
moment.utc(String, String[]);
moment.utc(String, String, String);
moment.utc(String, String, String[]);
moment.utc(String, String, Boolean);
moment.utc(String, String, String, Boolean);
moment.utc(Moment);
moment.utc(Date);

По умолчанию Moment разбирает и отображает время в локальном часовом поясе.

Чтобы разобрать или отобразить объект moment в UTC, можно использовать moment.utc() вместо moment().

Это приводит нас к интересной особенности Moment.js — режиму UTC.

В режиме UTC все методы отображения показывают время UTC вместо локального времени.

moment().format();     // 2013-02-04T10:35:24-08:00
moment.utc().format(); // 2013-02-04T18:35:24+00:00

Кроме того, в режиме UTC все методы получения и установки значений внутри используют методы Date#getUTC* и Date#setUTC* вместо методов Date#get* и Date#set*.

moment.utc().seconds(30).valueOf() === new Date().setUTCSeconds(30);
moment.utc().seconds()   === new Date().getUTCSeconds();

Важно отметить, что, хотя отображаемые значения выше различаются, они обозначают один и тот же момент времени.

var a = moment();
var b = moment.utc();
a.format();  // 2013-02-04T10:35:24-08:00
b.format();  // 2013-02-04T18:35:24+00:00
a.valueOf(); // 1360002924000
b.valueOf(); // 1360002924000

Любой объект moment, созданный с помощью moment.utc(), будет находиться в режиме UTC, а объект, созданный с помощью moment(), — нет.

Чтобы переключиться с UTC на локальное время, можно использовать moment#utc или moment#local.

var a = moment.utc([2011, 0, 1, 8]);
a.hours(); // 8 UTC
a.local();
a.hours(); // 0 PST

parseZone 2.3.0+

moment.parseZone()
moment.parseZone(String)
moment.parseZone(String, String)
moment.parseZone(String, [String])
moment.parseZone(String, String, Boolean)
moment.parseZone(String, String, String, Boolean)

Функции разбора строк Moment, такие как moment(string) и moment.utc(string), принимают информацию о смещении, если она указана, но преобразуют полученный объект Moment в локальное время или UTC. В отличие от них, moment.parseZone() разбирает строку, но сохраняет полученный объект Moment в часовом поясе с фиксированным смещением, указанным в строке.

moment.parseZone("2013-01-01T00:00:00-13:00").utcOffset(); // -780 ("-13:00" in total minutes)
moment.parseZone('2013 01 01 05 -13:00', 'YYYY MM DD HH ZZ').utcOffset(); // -780  ("-13:00" in total minutes)
moment.parseZone('2013-01-01-13:00', ['DD MM YYYY ZZ', 'YYYY MM DD ZZ']).utcOffset(); // -780  ("-13:00" in total minutes);

Также можно передать аргументы локали и строгости разбора.

moment.parseZone("2013 01 01 -13:00", 'YYYY MM DD ZZ', true).utcOffset(); // -780  ("-13:00" in total minutes)
moment.parseZone("2013-01-01-13:00", 'YYYY MM DD ZZ', true).utcOffset(); // NaN (doesn't pass the strictness check)
moment.parseZone("2013 01 01 -13:00", 'YYYY MM DD ZZ', 'fr', true).utcOffset(); // -780 (with locale and strictness argument)
moment.parseZone("2013 01 01 -13:00", ['DD MM YYYY ZZ', 'YYYY MM DD ZZ'], 'fr', true).utcOffset(); // -780 (with locale and strictness argument alongside an array of formats)

moment.parseZone эквивалентен разбору строки с использованием moment#utcOffset для разбора часового пояса.

var s = "2013-01-01T00:00:00-13:00";
moment(s).utcOffset(s);

Проверка корректности 1.7.0+

moment().isValid();

Moment применяет более строгие правила инициализации, чем конструктор Date.

new Date(2013, 25, 14).toString(); // "Sat Feb 14 2015 00:00:00 GMT-0500 (EST)"
moment([2015, 25, 35]).format();   // 'Invalid date'

Проверить, считает ли Moment дату некорректной, можно с помощью moment#isValid. Метрики, используемые #isValid, можно проверить с помощью moment#parsingFlags, который возвращает объект.

Следующие флаги разбора указывают на некорректную дату:

• overflow: переполнение поля даты, например 13-й месяц, 32-й день месяца (или 29 февраля в невисокосном году), 367-й день года и т. д. overflow содержит индекс некорректной единицы, соответствующей #invalidAt (см. ниже); значение -1 означает отсутствие переполнения.
• invalidMonth: некорректное название месяца, например moment('Marbruary', 'MMMM');. Содержит саму некорректную строку месяца или null.
• empty: входная строка, не содержащая данных, которые можно разобрать, например moment('this is nonsense');. Логическое значение.
• nullInput: некорректный ввод null, например moment(null);. Логическое значение.
• invalidFormat: пустой список форматов, например moment('2013-05-25', []). Логическое значение.
• userInvalidated: дата, явно созданная как некорректная, например moment.invalid(). Логическое значение.

Кроме того, начиная с версии 2.13.0, флаги meridiem и parsedDateParts совместно определяют корректность даты.

• meridiem: указывает, какое обозначение времени суток (AM/PM) было разобрано, если оно присутствовало. Строка.
• parsedDateParts: возвращает массив разобранных частей даты в порядке убывания значимости — например, parsedDateParts[0] === year. Если частей даты нет, но meridiem задан, дата считается некорректной. Массив.

Кроме того, если Moment разбирается в строгом режиме, для корректности Moment эти флаги должны быть пустыми:

• unusedTokens: массив подстрок формата, не найденных во входной строке
• unusedInput: массив подстрок входных данных, не соответствующих строке формата

Примечание: Критерии корректности Moment стали строже и последовательнее в версиях от 2.2 до 2.3. Примечание: Корректность определяется при создании объекта moment. Измененный объект moment (например, moment().hour(NaN)) останется корректным.

Кроме того, с помощью moment#invalidAt можно определить, для какой единицы даты произошло переполнение.

var m = moment("2011-10-10T10:20:90");
m.isValid(); // false
m.invalidAt(); // 5 for seconds

Возвращаемое значение имеет следующий смысл:

1. годы
2. месяцы
3. дни
4. часы
5. минуты
6. секунды
7. миллисекунды

Примечание: Если некорректны несколько единиц, возвращается первая из них (поскольку корректность дней, например, может зависеть от месяца).

Некорректные объекты Moment

При операциях с плавающей точкой некорректный объект moment ведет себя как NaN.

Все перечисленные ниже выражения создают некорректные объекты moment:

• invalid.add(unit, value)
• another.add(invalid)
• invalid.clone()
• invalid.diff(another)
• invalid.endOf(unit)
• invalid.max(another)
• another.max(invalid)
• invalid.min(another)
• another.min(invalid)
• invalid.set(unit, value)
• invalid.startOf(unit)
• invalid.subtract(unit, value)

Следующие выражения возвращают локализованную версию 'InvalidDate':

• invalid.format(anyFmt) возвращает 'Invalid Date' для текущей локали
• invalid.from(another)
• another.from(invalid)
• invalid.fromNow(suffix)
• invalid.to(another)
• another.to(invalid)
• invalid.toNow(suffix)
• invalid.toISOString() (до версии 2.18.0)
• invalid.toString()

Следующие выражения возвращают false:

• invalid.isAfter(another)
• invalid.isAfter(invalid)
• another.isAfter(invalid)
• invalid.isBefore(another)
• invalid.isBefore(invalid)
• another.isBefore(invalid)
• invalid.isBetween(another, another)
• invalid.isBetween(invalid, invalid)
• invalid.isSame(another)
• invalid.isSame(invalid)
• another.isSame(invalid)
• invalid.isSameOrAfter(another)
• invalid.isSameOrAfter(invalid)
• another.isSameOrAfter(invalid)
• invalid.isSameOrBefore(another)
• invalid.isSameOrBefore(invalid)
• another.isSameOrBefore(invalid)

А следующие выражения возвращают null или NaN с некоторой структурой:

• invalid.get(unit) возвращает null, как и все остальные именованные методы получения значений
• invalid.toArray() === [NaN, NaN, NaN, NaN, NaN, NaN]
• invalid.toObject(): всем значениям присвоено NaN
• invalid.toDate() возвращает некорректный объект Date
• invalid.toJSON() возвращает null
• invalid.unix() возвращает null
• invalid.valueOf() возвращает null
• invalid.toISOString() возвращает null (начиная с версии 2.18.0)

Данные создания 2.11.0+

moment().creationData();

После создания объекта moment все входные данные можно получить с помощью метода creationData():

moment("2013-01-02", "YYYY-MM-DD", true).creationData() === {
    input: "2013-01-02",
    format: "YYYY-MM-DD",
    locale: Locale obj,
    isUTC: false,
    strict: true
}

Значения по умолчанию 2.2.1+

moment("15", "hh")

Можно создать объект moment, указав только некоторые единицы измерения. Для остальных будут установлены текущие день, месяц или год либо значение 0 для часов, минут, секунд и миллисекунд.

Если ничего не передано, по умолчанию используется текущий момент:

moment();  // current date and time

Если переданы только часы, минуты, секунды и миллисекунды, по умолчанию используется сегодняшний день:

moment(5, "HH");  // today, 5:00:00.000
moment({hour: 5});  // today, 5:00:00.000
moment({hour: 5, minute: 10});  // today, 5:10.00.000
moment({hour: 5, minute: 10, seconds: 20});  // today, 5:10.20.000
moment({hour: 5, minute: 10, seconds: 20, milliseconds: 300});  // today, 5:10.20.300

Если переданы только дни и меньшие единицы, по умолчанию используются текущие месяц и год:

moment(5, "DD");  // this month, 5th day-of-month
moment("4 05:06:07", "DD hh:mm:ss");  // this month, 4th day-of-month, 05:06:07.000

Если год не указан, по умолчанию используется текущий год:

moment(3, "MM");  // this year, 3rd month (March)
moment("Apr 4 05:06:07", "MMM DD hh:mm:ss");  // this year, 4th April, 05:06:07.000

Получение и установка значений

В Moment.js используются перегруженные методы получения и установки значений. Возможно, вы знакомы с этим шаблоном по его использованию в jQuery.

Вызов этих методов без параметров возвращает значение, а вызов с параметром задает его.

Эти методы соответствуют одноименным функциям нативного объекта Date.

moment().seconds(30).valueOf() === new Date().setSeconds(30);
moment().seconds()   === new Date().getSeconds();

Если включен режим UTC, они будут соответствовать эквивалентным функциям UTC.

moment.utc().seconds(30).valueOf() === new Date().setUTCSeconds(30);
moment.utc().seconds()   === new Date().getUTCSeconds();

Для удобства, начиная с версии 2.0.0, доступны имена методов как в единственном, так и во множественном числе.

Примечание: При использовании в качестве методов установки все эти методы изменяют исходный объект moment.

Примечание: Начиная с версии 2.19.0, передача NaN любому методу установки не выполняет никаких действий. До версии 2.19.0 это приводило к некорректной инвалидизации объекта moment.

Миллисекунда 1.3.0+

moment().millisecond(Number);
moment().millisecond(); // Number
moment().milliseconds(Number);
moment().milliseconds(); // Number

Получает или задает миллисекунды.

Принимает числа от 0 до 999. Если значение выходит за пределы диапазона, оно переносится в секунды.

Секунда 1.0.0+

moment().second(Number);
moment().second(); // Number
moment().seconds(Number);
moment().seconds(); // Number

Получает или задает секунды.

Принимает числа от 0 до 59. Если значение выходит за пределы диапазона, оно переносится в минуты.

Минута 1.0.0+

moment().minute(Number);
moment().minute(); // Number
moment().minutes(Number);
moment().minutes(); // Number

Получает или задает минуты.

Принимает числа от 0 до 59. Если значение выходит за пределы диапазона, оно переносится в часы.

Час 1.0.0+

moment().hour(Number);
moment().hour(); // Number
moment().hours(Number);
moment().hours(); // Number

Получает или задает час.

Принимает числа от 0 до 23. Если значение выходит за пределы диапазона, оно переносится на следующий день.

День месяца 1.0.0+

moment().date(Number);
moment().date(); // Number
moment().dates(Number);
moment().dates(); // Number

Получает или задает день месяца.

Принимает числа от 1 до 31. Если значение выходит за пределы диапазона, оно переносится на следующие месяцы.

Примечание: Moment#date обозначает день месяца, а Moment#day — день недели.

Примечание: если для создания даты объединяются несколько операций, следует начинать с года, затем задавать месяц, день и т. д. Иначе можно получить неожиданные результаты: например, если day=31, а в текущем месяце только 30 дней (то же относится к манипуляциям с нативным объектом JavaScript Date), возвращенная дата будет 30-м числом текущего месяца (подробнее см. раздел «Месяц»).

Неправильно: moment().date(day).month(month).year(year)

Правильно: moment().year(year).month(month).date(day)

В версии 2.16.0 использование moment().dates() объявлено устаревшим. Вместо него используйте moment().date().

День недели 1.3.0+

moment().day(Number|String);
moment().day(); // Number
moment().days(Number|String);
moment().days(); // Number

Получает или задает день недели.

Этот метод можно использовать для задания дня недели: воскресенье обозначается числом 0, суббота — числом 6.

Если задано значение от 0 до 6, результирующая дата будет относиться к текущей неделе (с воскресенья по субботу).

Если значение выходит за пределы диапазона, оно переносится на другие недели.

moment().day(-7); // last Sunday (0 - 7)
moment().day(0); // this Sunday (0)
moment().day(7); // next Sunday (0 + 7)
moment().day(10); // next Wednesday (3 + 7)
moment().day(24); // 3 Wednesdays from now (3 + 7 + 7 + 7)

Примечание: Moment#date обозначает день месяца, а Moment#day — день недели.

Начиная с версии 2.1.0, также поддерживается название дня недели. Оно разбирается с учетом текущей локали объекта moment.

moment().day("Sunday");
moment().day("Monday");

День недели (с учетом локали) 2.1.0+

moment().weekday(Number);
moment().weekday(); // Number

Получает или задает день недели с учетом локали.

Если согласно локали неделя начинается с понедельника, moment().weekday(0) будет понедельником. Если неделя начинается с воскресенья, moment().weekday(0) будет воскресеньем.

Как и в случае с moment#day, если значение выходит за пределы диапазона, оно переносится на другие недели.

// when Monday is the first day of the week
moment().weekday(-7); // last Monday
moment().weekday(7); // next Monday
// when Sunday is the first day of the week
moment().weekday(-7); // last Sunday
moment().weekday(7); // next Sunday

День недели по ISO 2.1.0+

moment().isoWeekday(Number);
moment().isoWeekday(); // Number

Получает или задает день недели по ISO, где 1 — понедельник, а 7 — воскресенье.

Как и в случае с moment#day, если значение выходит за пределы диапазона, оно переносится на другие недели.

moment().isoWeekday(1); // Monday
moment().isoWeekday(7); // Sunday

Также поддерживается название дня недели. Оно разбирается с учетом текущей локали объекта moment.

moment().isoWeekday("Sunday");
moment().isoWeekday("Monday");

День года 2.0.0+

moment().dayOfYear(Number);
moment().dayOfYear(); // Number

Получает или задает день года.

Принимает числа от 1 до 366. Если значение выходит за пределы диапазона, оно переносится на следующий год.

Неделя года 2.0.0+

moment().week(Number);
moment().week(); // Number
moment().weeks(Number);
moment().weeks(); // Number

Получает или задает неделю года.

Поскольку в разных локалях нумерация недель года определяется по-разному, в Moment.js добавлен moment#week для получения или задания номера недели года с учетом локали.

Номер недели года зависит от дня, с которого начинается неделя (воскресенье, понедельник и т. д.), и от того, какая неделя считается первой неделей года.

Например, в США неделя начинается в воскресенье. Неделя, на которую приходится 1 января, считается первой неделей года.

Во Франции неделя начинается в понедельник, а первой неделей года считается неделя, на которую приходится 4 января.

Результат moment#week зависит от локали этого объекта moment.

При задании недели года день недели сохраняется.

Неделя года (ISO) 2.0.0+

moment().isoWeek(Number);
moment().isoWeek(); // Number
moment().isoWeeks(Number);
moment().isoWeeks(); // Number

Получает или задает неделю года по ISO.

При задании недели года день недели сохраняется.

Месяц 1.0.0+

moment().month(Number|String);
moment().month(); // Number
moment().months(Number|String);
moment().months(); // Number

Получает или задает месяц.

Принимает числа от 0 до 11. Если значение выходит за пределы диапазона, оно переносится на следующий год.

Примечание: Нумерация месяцев начинается с нуля, поэтому январь — это месяц 0.

Начиная с версии 2.1.0, также поддерживается название месяца. Оно разбирается с учетом текущей локали объекта moment.

moment().month("January");
moment().month("Feb");

До версии 2.1.0, если месяц объекта moment изменялся и в новом месяце не хватало дней для сохранения текущего дня месяца, дата переносилась на следующий месяц.

Начиная с версии 2.1.0, дата ограничивается последним днем целевого месяца.

// before 2.1.0
moment([2012, 0, 31]).month(1).format("YYYY-MM-DD"); // 2012-03-02
// after 2.1.0
moment([2012, 0, 31]).month(1).format("YYYY-MM-DD"); // 2012-02-29

В версии 2.16.0 использование moment().months() объявлено устаревшим. Вместо него используйте moment().month().

Квартал 2.6.0+

moment().quarter(); // Number
moment().quarter(Number);
moment().quarters(); // Number
moment().quarters(Number);

Получает квартал (от 1 до 4).

moment('2013-01-01T00:00:00.000').quarter() // 1
moment('2013-04-01T00:00:00.000').subtract(1, 'ms').quarter() // 1
moment('2013-04-01T00:00:00.000').quarter() // 2
moment('2013-07-01T00:00:00.000').subtract(1, 'ms').quarter() // 2
moment('2013-07-01T00:00:00.000').quarter() // 3
moment('2013-10-01T00:00:00.000').subtract(1, 'ms').quarter() // 3
moment('2013-10-01T00:00:00.000').quarter() // 4
moment('2014-01-01T00:00:00.000').subtract(1, 'ms').quarter() // 4

Задает квартал (от 1 до 4).

moment('2013-01-01T00:00:00.000').quarter(2) // '2013-04-01T00:00:00.000'
moment('2013-02-05T05:06:07.000').quarter(2).format() // '2013-05-05T05:06:07-07:00'

Год 1.0.0+

moment().year(Number);
moment().year(); // Number
moment().years(Number);
moment().years(); // Number

Получает или задает год.

Принимает числа от -270 000 до 270 000.

В версии 2.6.0 использование moment().years() объявлено устаревшим. Вместо него используйте moment().year().

Год недели 2.1.0+

moment().weekYear(Number);
moment().weekYear(); // Number

Получает или задает год недели с учетом локали.

Поскольку первый день первой недели не всегда приходится на первый день года, год недели иногда отличается от календарного года.

Например, в США неделя, на которую приходится 1 января, всегда является первой неделей. В США недели также начинаются в воскресенье. Если 1 января приходится на понедельник, 31 декабря будет относиться к той же неделе, что и 1 января, а значит, и к тому же году недели. У 30 декабря год недели будет отличаться от года недели 31 декабря.

Год недели (ISO) 2.1.0+

moment().isoWeekYear(Number);
moment().isoWeekYear(); // Number

Получает или задает неделю-года ISO.

Количество недель в году 2.6.0+

moment().weeksInYear();

Получает количество недель в году текущего момента согласно локали.

Количество недель в году (ISO) 2.6.0+

moment().isoWeeksInYear();

Получает количество недель в году текущего момента согласно неделям ISO.

Получение 2.2.1+

moment().get('year');
moment().get('month');  // 0 to 11
moment().get('date');
moment().get('hour');
moment().get('minute');
moment().get('second');
moment().get('millisecond');

Геттер, принимающий строку. В общем случае

moment().get(unit) === moment()[unit]()

Единицы измерения не чувствительны к регистру; поддерживаются формы множественного числа и сокращения: год (years, y), месяц (months, M), дата (dates, D), час (hours, h), минута (minutes, m), секунда (seconds, s), миллисекунда (milliseconds, ms).

Установка 2.2.1+

moment().set(String, Int);
moment().set(Object(String, Int));

Универсальный сеттер: первым аргументом принимает единицу измерения, вторым — значение:

moment().set('year', 2013);
moment().set('month', 3);  // April
moment().set('date', 1);
moment().set('hour', 13);
moment().set('minute', 20);
moment().set('second', 30);
moment().set('millisecond', 123);

moment().set({'year': 2013, 'month': 3});

Единицы измерения не чувствительны к регистру; поддерживаются формы множественного числа и сокращения: год (years, y), месяц (months, M), дата (dates, D), час (hours, h), минута (minutes, m), секунда (seconds, s), миллисекунда (milliseconds, ms).

Разбор объекта добавлен в версии 2.9.0

Максимум 2.7.0+

moment.max(Moment[,Moment...]);
moment.max(Moment[]);

Возвращает максимальное (наиболее позднее) из заданных экземпляров moment.

Например:

var a = moment().subtract(1, 'day');
var b = moment().add(1, 'day');
moment.max(a, b);  // b

var friends = fetchFriends(); /* [{name: 'Dan', birthday: '11.12.1977'}, {name: 'Mary', birthday: '11.12.1986'}, {name: 'Stephan', birthday: '11.01.1993'}]*/
var friendsBirthDays = friends.map(function(friend){
    return moment(friend.birthday, 'DD.MM.YYYY');
});
moment.max(friendsBirthDays);  // '11.01.1993'

Если аргументы не указаны, функция возвращает экземпляр moment с текущим временем.

Начиная с версии 2.10.5, если среди аргументов есть некорректный момент, результатом будет некорректный момент.

moment.max(moment(), moment.invalid()).isValid() === false
moment.max(moment.invalid(), moment()).isValid() === false
moment.max([moment(), moment.invalid()]).isValid() === false
moment.max([moment.invalid(), moment()]).isValid() === false

Минимум 2.7.0+

moment.min(Moment[,Moment...]);
moment.min(Moment[]);

Возвращает минимальное (наиболее раннее) из заданных экземпляров moment.

Например:

var a = moment().subtract(1, 'day');
var b = moment().add(1, 'day');
moment.min(a, b);  // a
moment.min([a, b]); // a

Если аргументы не указаны, функция возвращает экземпляр moment с текущим временем.

Начиная с версии 2.10.5, если среди аргументов есть некорректный момент, результатом будет некорректный момент.

moment.min(moment(), moment.invalid()).isValid() === false
moment.min(moment.invalid(), moment()).isValid() === false
moment.min([moment(), moment.invalid()]).isValid() === false
moment.min([moment.invalid(), moment()]).isValid() === false

Изменение

Получив Moment, вы можете изменить его нужным образом. Для этого предусмотрен ряд методов.

Moment.js использует шаблон текучего интерфейса, также известный как цепочка вызовов методов. Благодаря этому можно делать такие необычные вещи, как показано ниже.

moment().add(7, 'days').subtract(1, 'months').year(2009).hours(0).minutes(0).seconds(0);

Примечание: Обратите внимание, что объекты moment изменяемы. Вызов любого метода изменения приведет к изменению исходного момента.

Если вы хотите создать копию и изменить ее, перед изменением момента вызовите moment#clone. Подробнее о клонировании.

Добавление 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

Также следует учитывать особые случаи при добавлении времени с переходом на летнее время или обратно. При добавлении лет, месяцев, недель или дней исходный час всегда останется тем же.

Добавление месяца увеличит дату на указанное количество месяцев.

moment([2010, 1, 28]);                 // February 28
moment([2010, 1, 28]).add(1, 'month'); // March 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 (but you may have to set the timezone first)

В качестве альтернативы для добавления времени к моментам можно использовать длительности.

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.12.0, десятичные значения дней и месяцев округляются до ближайшего целого числа. Недели, кварталы и годы преобразуются в дни или месяцы, а затем округляются до ближайшего целого числа.

moment().add(1.5, 'months') == moment().add(2, 'months')
moment().add(.7, 'years') == moment().add(8, 'months') //.7*12 = 8.4, rounded to 8

Вычитание 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.12.0, десятичные значения дней и месяцев округляются до ближайшего целого числа. Недели, кварталы и годы преобразуются в дни или месяцы, а затем округляются до ближайшего целого числа.

moment().subtract(1.5, 'months') == moment().subtract(2, 'months')
moment().subtract(.7, 'years') == moment().subtract(8, 'months') //.7*12 = 8.4, rounded to 8

Обратите внимание: чтобы операции moment.add(-.5, 'days') и moment.subtract(.5, 'days') были эквивалентны, значения -.5, -1.5, -2.5 и т. д. округляются вниз.

Начало периода 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('date');     // 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.

Примечание: moment#startOf('date') добавлен как псевдоним дня в версии 2.13.0

Конец периода 1.7.0+

moment().endOf(String);

Изменяет исходный момент, устанавливая его на конец единицы времени.

Работает так же, как moment#startOf, но вместо начала единицы времени устанавливает ее конец.

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

Начиная с версии 2.0.0, moment#endOf('day') заменил moment#eod.

Примечание: moment#endOf('week') добавлен в версии 2.0.0.

Начиная с версии 2.1.0, moment#endOf('week') использует день начала недели, заданный для локали.

Максимум Начиная с 2.1.0, устарел в 2.7.0

moment().max(Moment|String|Number|Date|Array);

Примечание: Эта функция устарела в версии 2.7.0. Вместо нее рассмотрите moment.min.

Ограничивает момент максимальным значением другого момента. Таким образом, a.max(b) эквивалентно a = moment.min(a, b) (обратите внимание, что max преобразуется в min).

Иногда часы сервера и клиента идут не совсем синхронно. В результате отображаются такие относительные строки, как «через несколько секунд», вместо «несколько секунд назад». Этого можно избежать с помощью moment#max():

Это аналог moment#min.

var momentFromServer = moment(input);
var clampedMoment = momentFromServer.max();

В moment#max можно передать все, что можно передать в moment().

moment().max(moment().add(1, 'd'));
moment().max("2013-04-20T20:00:00+0800");
moment().max("Jan 1 2001", "MMM D YYYY");
moment().max(new Date(2012, 1, 8));

Минимум Начиная с 2.1.0, устарел в 2.7.0

moment().min(Moment|String|Number|Date|Array);

Примечание: Эта функция устарела в версии 2.7.0. Вместо нее рассмотрите moment.max.

Ограничивает момент минимальным значением другого момента. Таким образом, a.min(b) эквивалентно a = moment.max(a, b) (обратите внимание, что min преобразуется в max).

Это аналог moment#max.

moment().min("2013-04-20T20:00:00+0800");

Можно использовать вместе с moment#max, чтобы ограничить момент заданным диапазоном.

var start  = moment().startOf('week');
var end    = moment().endOf('week');
var actual = moment().min(start).max(end);

Местное время 1.5.0+

moment().local();
moment().local(Boolean); // from 2.8.0

Устанавливает для исходного момента флаг, указывающий, что его нужно отображать в местном времени, а не в исходном времени момента.

var a = moment.utc([2011, 0, 1, 8]);
a.hours(); // 8 UTC
a.local();
a.hours(); // 0 PST

Local также можно использовать для выхода из режима фиксированного смещения:

moment.parseZone('2016-05-03T22:15:01+02:00').local().format(); // "2016-05-03T15:15:01-05:00"

Передача true изменит часовой пояс, не меняя текущего времени.

moment.parseZone('2016-05-03T22:15:01+02:00').local(true).format(); //"2016-05-03T22:15:01-05:00"

Подробнее о режиме UTC см. в разделе moment.utc().

UTC 1.5.0+

moment().utc();
moment().utc(Boolean); // from 2.8.0

Устанавливает для исходного момента флаг, указывающий, что его нужно отображать в UTC, а не в исходном времени момента.

var a = moment([2011, 0, 1, 8]);
a.hours(); // 8 PST
a.utc();
a.hours(); // 16 UTC

UTC также можно использовать для выхода из режима фиксированного смещения:

moment.parseZone('2016-05-03T22:15:01+02:00').utc().format(); //"2016-05-03T20:15:01Z"

Передача true изменит часовой пояс, не меняя текущего времени.

moment.parseZone('2016-05-03T22:15:01+02:00').utc(true).format(); //"2016-05-03T22:15:01Z"

Подробнее о режиме UTC см. в разделе moment.utc().

Смещение UTC 2.9.0++

moment().utcOffset();
moment().utcOffset(Number|String);
moment().utcOffset(Number|String, Boolean);

Получает или задает смещение UTC в минутах.

Примечание: В отличие от moment.fn.zone, эта функция возвращает фактическое смещение относительно UTC, а не обратное смещение (которое возвращает Date.prototype.getTimezoneOffset).

Получение utcOffset текущего объекта:

moment().utcOffset(); // (-240, -120, -60, 0, 60, 120, 240, etc.)

Установка смещения UTC путем передачи количества минут. Смещение устанавливается для объекта moment, на котором вызывается utcOffset(). Если нужно задать смещение глобально, воспользуйтесь moment-timezone. Обратите внимание: заданное смещение будет фиксированным и не изменится самостоятельно (то есть правила перехода на летнее время применяться не будут). Если нужен настоящий часовой пояс — время в определенном месте, например America/Los_Angeles, — воспользуйтесь moment-timezone.

moment().utcOffset(120);

Если входное значение меньше 16 и больше -16, оно будет интерпретировано как количество часов.

// these are equivalent
moment().utcOffset(8);  // set hours offset
moment().utcOffset(480);  // set minutes offset (8 * 60)

Смещение UTC также можно задать строкой.

// these are equivalent
moment().utcOffset("+08:00");
moment().utcOffset(8);
moment().utcOffset(480);

moment#utcOffset ищет в строке последнее совпадение с +00 -00 +00:00 +0000 -00:00 -0000 Z, поэтому можно передать даже строку в формате ISO8601 со смещением — и момент будет изменен согласно этому смещению UTC.

Обратите внимание: если строка не содержит «Z», в ней должен присутствовать символ + или -.

moment().utcOffset("2013-03-07T07:00:00+08:00");

Функция utcOffset принимает необязательный второй параметр — логическое значение, указывающее, нужно ли сохранять текущее время суток.

• Передача false (значение по умолчанию) сохранит тот же момент времени по всемирному времени, но местное время изменится.

• Передача true сохранит то же местное время, но при этом изменится соответствующий момент по всемирному времени.

Эта возможность пригодится, если нужно создать момент с заданным смещением часового пояса, используя только числовые входные значения:

moment([2016, 0, 1, 0, 0, 0]).utcOffset(-5, true) // Equivalent to "2016-01-01T00:00:00-05:00"

Смещение часового пояса Начиная с 1.2.0, устарело в 2.9.0+

moment().zone();
moment().zone(Number|String);

Примечание: Эта функция устарела в версии 2.9.0. Вместо нее рассмотрите moment.fn.utcOffset.

Получает смещение часового пояса в минутах.

moment().zone(); // (60, 120, 240, etc.)

Начиная с версии 2.1.0, смещение можно задавать, передав количество минут относительно GMT.

moment().zone(120);

Если входное значение меньше 16 и больше -16, оно будет интерпретировано как количество часов.

// these are equivalent
moment().zone(480);
moment().zone(8);

Часовой пояс также можно задать строкой.

moment().zone("-08:00");

moment#zone ищет в строке первое совпадение с +00:00 +0000 -00:00 -0000, поэтому можно передать даже строку в формате ISO8601 — и момент будет изменен согласно этому часовому поясу.

moment().zone("2013-03-07T07:00:00-08:00");

Отображение

После разбора и изменения момента нужно каким-либо образом его отобразить.

Форматирование 1.0.0+

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

Это наиболее универсальный способ отображения. Он принимает строку с токенами и заменяет их соответствующими значениями.

moment().format();                                // "2014-09-08T08:02:17-05:00" (ISO 8601, no fractional seconds)
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().format("[Today is] dddd");               // "Today is Sunday"
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.

Форматы для локали

Поскольку предпочтительный формат зависит от локали, существуют токены, позволяющие форматировать момент с учетом его локали.

Для одних и тех же форматов предусмотрены варианты в верхнем и нижнем регистре. Вариант в нижнем регистре предназначен для сокращенной записи соответствующего варианта в верхнем регистре.

l ll lll llll доступны в версии 2.0.0. LTS добавлен в версии 2.8.4.

Экранирование символов

Чтобы экранировать символы в строках формата, заключите их в квадратные скобки.

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

Сходства и различия с LDML

Примечание: Хотя эти форматы даты очень похожи на форматы LDML, есть несколько небольших различий, связанных с днем месяца, днем года и днем недели.

Сравнение нескольких токенов форматирования даты для разных локалей см. в этой таблице токенов форматирования даты.

Другие токены

Если вам удобнее работать со strftime, а не с токенами разбора в стиле LDML, воспользуйтесь плагином Бена Оукса. 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";
// parse with .toDate()
moment('20.07.2018 09:19').toDate() // Invalid date
// format the date string with the new defaultFormat then parse
moment('20.07.2018 09:19', moment.defaultFormat).toDate() // Fri Jul 20 2018 09:19:00 GMT+0300

Время от текущего момента 1.0.0+

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

Распространенный способ отображения времени реализован в moment#fromNow. Иногда его называют timeago или относительным временем.

moment([2007, 0, 29]).fromNow(); // 4 years ago

Если передать true, можно получить значение без суффикса.

moment([2007, 0, 29]).fromNow();     // 4 years ago
moment([2007, 0, 29]).fromNow(true); // 4 years

Базовые строки настраиваются согласно текущей локали. Время округляется до ближайшей секунды.

В таблице ниже указано, какая строка отображается для каждого временного интервала.

Примечание: Начиная с версии 2.10.3, если целевой объект moment некорректен, результатом будет локализованная строка «Неверная дата».

Примечание: Ключ ss добавлен в версии 2.18.0. Это необязательный порог. Он никогда не отображается, ЕСЛИ только пользователь вручную не задаст порог ss. Пока порог ss не задан, по умолчанию используется значение порога s минус 1 (поэтому пользователь его не увидит).

Время от заданного момента 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.10.3, если одна из конечных точек некорректна, результатом будет локализованная строка «Неверная дата».

Время до текущего момента 2.10.3+

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

Распространенный способ отображения времени реализован в moment#toNow. Иногда его называют timeago или относительным временем.

Этот метод похож на moment.fromNow, но возвращает противоположный интервал: a.fromNow() = - a.toNow().

Этот метод похож на moment.to, но специально предназначен для текущего времени. Используйте moment.to, если нужно задать обе конечные точки интервала.

moment([2007, 0, 29]).toNow(); // in 4 years

Если передать true, можно получить значение без префикса.

moment([2007, 0, 29]).toNow();     // in 4 years
moment([2007, 0, 29]).toNow(true); // 4 years

Базовые строки настраиваются согласно текущей локали.

В таблице ниже указано, какая строка отображается для каждого временного интервала.

Начиная с версии 2.10.3, если целевой объект moment некорректен, результатом будет локализованная строка «Неверная дата».

Время до заданного момента 2.10.3+

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

Иногда нужно отобразить момент относительно времени, отличного от текущего. В таком случае можно использовать moment#to.

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

В качестве первого параметра можно передать все, что допустимо для moment(), или фактический объект Moment.

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

Как и для moment#toNow, передача true в качестве второго параметра возвращает значение без суффикса. Это удобно, когда нужно получить понятное человеку обозначение длительности.

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

Начиная с версии 2.10.3, если одна из конечных точек некорректна, результатом будет локализованная строка «Неверная дата».

Календарное время 1.3.0+

moment().calendar();
moment().calendar(referenceDay);
moment().calendar(referenceDay, formats);  // from 2.10.5
moment().calendar(formats);  // from 2.25.0

Календарное время отображает время относительно заданного referenceDay (по умолчанию — начала сегодняшнего дня), но делает это несколько иначе, чем moment#fromNow.

moment#calendar форматирует дату разными строками в зависимости от того, насколько близка она к дате referenceDay (по умолчанию — к сегодняшней дате).

Эти строки локализуются и могут быть настроены.

Начиная с версии 2.10.5, moment поддерживает указание форматов календарного вывода для каждого вызова:

moment().calendar(null, {
    sameDay: '[Today]',
    nextDay: '[Tomorrow]',
    nextWeek: 'dddd',
    lastDay: '[Yesterday]',
    lastWeek: '[Last] dddd',
    sameElse: 'DD/MM/YYYY'
});

sameElse используется как формат, если момент отстоит от referenceDay более чем на неделю.

Примечание: Начиная с версии 2.14.0, аргумент форматов для calendar может быть функцией обратного вызова, выполняемой в контексте moment и принимающей один аргумент now:

moment().calendar(null, {
  sameDay: function (now) {
    if (this.isBefore(now)) {
      return '[Will Happen Today]';
    } else {
      return '[Happened Today]';
    }
    /* ... */
  }
});

Примечание: Начиная с версии 2.25.0, можно передавать только аргумент форматов; это может быть объект со строками и функциями:

moment().calendar({
    sameDay: '[Today]',
    nextDay: '[Tomorrow]',
    nextWeek: 'dddd',
    lastDay: '[Yesterday]',
    lastWeek: '[Last] dddd',
    sameElse: 'DD/MM/YYYY'
});

moment().calendar({
  sameDay: function (now) {
    if (this.isBefore(now)) {
      return '[Will Happen Today]';
    } else {
      return '[Happened Today]';
    }
    /* ... */
  }
});

Разница 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

Чтобы получить длительность интервала между двумя моментами, можно передать diff в качестве аргумента в moment#duration. Подробнее см. документацию по 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 обрабатывает разницу в месяцах и годах особым образом. Этот метод оптимизирован так, чтобы разница между двумя месяцами с одинаковым числом всегда была целым числом.

Таким образом, с 15 января по 15 февраля проходит ровно 1 месяц.

С 28 февраля по 28 марта проходит ровно 1 месяц.

С 28 февраля 2011 года по 28 февраля 2012 года проходит ровно 1 год.

Подробнее о разнице в месяцах и годах можно узнать здесь

Это изменение вычисления разницы в месяцах и годах было внесено в версии 2.0.0. Начиная с версии 2.9.0, diff также поддерживает единицу измерения «квартал».

Метка времени Unix (миллисекунды) 1.0.0+

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

moment#valueOf просто выводит количество миллисекунд, прошедших с начала эпохи Unix, как и Date#valueOf.

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

Чтобы получить метку времени Unix (количество секунд, прошедших с начала эпохи) из Moment, используйте moment#unix.

Примечание: в ECMAScript это называется «значением времени»

Метка времени Unix (секунды) 1.6.0+

moment().unix();

moment#unix возвращает метку времени Unix (количество секунд, прошедших с начала эпохи Unix).

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

Значение округляется вниз до ближайшей секунды и не включает миллисекунды.

Количество дней в месяце 1.5.0+

moment().daysInMonth();

Получить количество дней в текущем месяце.

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

Как объект даты JavaScript 1.0.0+

moment().toDate();

Чтобы получить копию нативного объекта Date, который оборачивает Moment.js, используйте moment#toDate.

Будет возвращена копия Date, используемого объектом moment, поэтому любые изменения этого Date не приведут к изменению объекта moment. Если вы хотите изменить Date объекта moment, см. moment#manipulate или moment#set.

moment#native заменён на moment#toDate и считается устаревшим начиная с версии 1.6.0.

Как массив 1.7.0+

moment().toArray();

Возвращает массив, соответствующий параметрам new Date().

moment().toArray(); // [2013, 1, 4, 14, 40, 16, 154];

Как JSON 2.0.0+

moment().toJSON();

При сериализации объекта в JSON объект Moment будет представлен строкой ISO8601, скорректированной по UTC.

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

Если вместо этого вам нужна строка ISO8601, отражающая utcOffset() момента времени, можно изменить функцию toJSON следующим образом:

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

Это изменит поведение следующим образом:

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

Как строка ISO 8601 2.1.0+

moment().toISOString();
moment().toISOString(keepOffset); // from 2.20.0

Форматирует строку в соответствии со стандартом ISO8601.

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

Обратите внимание, что .toISOString() возвращает метку времени в UTC, даже если рассматриваемый момент времени задан в локальном режиме. Это сделано для соответствия спецификации нативного JavaScript Date .toISOString(), изложенной в спецификации ES2015. Начиная с версии 2.20.0, можно вызвать .toISOString(true), чтобы предотвратить преобразование в UTC.

Начиная с версии 2.8.4, для повышения производительности при наличии используется нативный Date.prototype.toISOString.

Как объект 2.10.5+

moment().toObject();

Возвращает объект, содержащий год, месяц, число месяца, часы, минуты, секунды и миллисекунды.

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

Как строка 2.1.0+

moment().toString();

Возвращает строку на английском языке в формате, похожем на .toString() объекта JS Date.

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

Инспекция 2.16.0+

moment().inspect();

Возвращает машиночитаемую строку, которую можно вычислить, чтобы получить тот же момент времени. Из-за своего названия эта функция также используется для отображения объектов в интерактивной оболочке Node.

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 */)'

Примечание: Эта функция предназначена главным образом для отладки; не все случаи обрабатываются точно.

Проверки

Раньше 2.0.0+

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

Проверяет, предшествует ли один момент времени другому. Первый аргумент будет разобран как момент времени, если это ещё не так.

moment('2010-10-20').isBefore('2010-10-21'); // true

Чтобы ограничить точность единицей измерения, отличной от миллисекунд, передайте эту единицу вторым параметром.

Поскольку второй параметр определяет точность, а не только одно проверяемое значение, при указании дня проверяются год, месяц и день.

moment('2010-10-20').isBefore('2010-12-31', 'year'); // false
moment('2010-10-20').isBefore('2011-01-01', 'year'); // true

Как и moment#isAfter и moment#isSame, moment#startOf поддерживает все единицы времени, поддерживаемые для moment#isBefore.

year month week isoWeek day hour minute second

Если moment#isBefore не передан, по умолчанию будет использовано текущее время.

ПРИМЕЧАНИЕ: moment().isBefore() имеет неопределённое поведение, поэтому использовать его не следует! Если код выполняется быстро, созданный изначально момент времени будет таким же, как момент, созданный в isBefore для выполнения проверки, поэтому результатом будет false. Но если код выполняется медленнее, момент, созданный в isBefore, может оказаться заметно позже момента, созданного в moment(), и вызов вернёт true.

Совпадает 2.0.0+

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

Проверяет, совпадает ли один момент времени с другим. Первый аргумент будет разобран как момент времени, если это ещё не так.

moment('2010-10-20').isSame('2010-10-20'); // true

Чтобы ограничить точность единицей измерения, отличной от миллисекунд, передайте её вторым параметром.

moment('2010-10-20').isSame('2009-12-31', 'year');  // false
moment('2010-10-20').isSame('2010-01-01', 'year');  // true
moment('2010-10-20').isSame('2010-12-31', 'year');  // true
moment('2010-10-20').isSame('2011-01-01', 'year');  // false

При указании второго параметра будут сопоставлены все единицы, равные указанной или превышающие её. Передача month приведёт к проверке month и year. Передача day приведёт к проверке day, month и year.

moment('2010-01-01').isSame('2011-01-01', 'month'); // false, different year
moment('2010-01-01').isSame('2010-02-01', 'day');   // false, different month

Как и moment#isAfter и moment#isBefore, moment#startOf поддерживает все единицы времени, поддерживаемые для moment#isSame.

year month week isoWeek day hour minute second

Если у двух моментов времени разные часовые пояса, для сравнения будет использоваться часовой пояс первого момента.

// Note: Australia/Sydney is UTC+11:00 on these dates
moment.tz("2018-11-09T10:00:00", "Australia/Sydney").isSame(moment.tz("2018-11-08T12:00:00", "UTC"), "day"); // false
moment.tz("2018-11-08T12:00:00", "UTC").isSame(moment.tz("2018-11-09T10:00:00", "Australia/Sydney"), "day"); // true

ПРИМЕЧАНИЕ: moment().isSame() имеет неопределённое поведение, поэтому использовать его не следует! Если код выполняется быстро, созданный изначально момент времени будет таким же, как момент, созданный в isSame для выполнения проверки, поэтому результатом будет true. Но если код выполняется медленнее, момент, созданный в isSame, может оказаться заметно позже момента, созданного в moment(), и вызов вернёт false.

Позже 2.0.0+

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

Проверяет, следует ли один момент времени за другим. Первый аргумент будет разобран как момент времени, если это ещё не так.

moment('2010-10-20').isAfter('2010-10-19'); // true

Чтобы ограничить точность единицей измерения, отличной от миллисекунд, передайте эту единицу вторым параметром.

Поскольку второй параметр определяет точность, а не только одно проверяемое значение, при указании дня проверяются год, месяц и день.

moment('2010-10-20').isAfter('2010-01-01', 'year'); // false
moment('2010-10-20').isAfter('2009-12-31', 'year'); // true

Как и moment#isSame и moment#isBefore, moment#startOf поддерживает все единицы времени, поддерживаемые для moment#isAfter.

year month week isoWeek day hour minute second

Если moment#isAfter не передан, по умолчанию будет использовано текущее время.

moment().isAfter(); // false

Совпадает или раньше 2.11.0+

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

Проверяет, предшествует ли один момент времени другому или совпадает с ним. Первый аргумент будет разобран как момент времени, если это ещё не так.

moment('2010-10-20').isSameOrBefore('2010-10-21');  // true
moment('2010-10-20').isSameOrBefore('2010-10-20');  // true
moment('2010-10-20').isSameOrBefore('2010-10-19');  // false

Чтобы ограничить точность единицей измерения, отличной от миллисекунд, передайте эту единицу вторым параметром.

Поскольку второй параметр определяет точность, а не только одно проверяемое значение, при указании дня проверяются год, месяц и день.

moment('2010-10-20').isSameOrBefore('2009-12-31', 'year'); // false
moment('2010-10-20').isSameOrBefore('2010-12-31', 'year'); // true
moment('2010-10-20').isSameOrBefore('2011-01-01', 'year'); // true

Как и moment#isAfter и moment#isSame, moment#startOf поддерживает все единицы времени, поддерживаемые для moment#isSameOrBefore:

year month week isoWeek day hour minute second

Совпадает или позже 2.11.0+

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

Проверяет, следует ли один момент времени за другим или совпадает с ним. Первый аргумент будет разобран как момент времени, если это ещё не так.

moment('2010-10-20').isSameOrAfter('2010-10-19'); // true
moment('2010-10-20').isSameOrAfter('2010-10-20'); // true
moment('2010-10-20').isSameOrAfter('2010-10-21'); // false

Чтобы ограничить точность единицей измерения, отличной от миллисекунд, передайте эту единицу вторым параметром.

Поскольку второй параметр определяет точность, а не только одно проверяемое значение, при указании дня проверяются год, месяц и день.

moment('2010-10-20').isSameOrAfter('2011-12-31', 'year'); // false
moment('2010-10-20').isSameOrAfter('2010-01-01', 'year'); // true
moment('2010-10-20').isSameOrAfter('2009-12-31', 'year'); // true

Как и moment#isSame и moment#isBefore, moment#startOf поддерживает все единицы времени, поддерживаемые для moment#isSameOrAfter:

year month week isoWeek day hour minute second

Между 2.9.0+

//From 2.13.0 onward
moment().isBetween(moment-like, moment-like);
moment().isBetween(moment-like, moment-like, String);
moment().isBetween(moment-like, moment-like, String, String);
// where moment-like is Moment|String|Number|Date|Array

//2.9.0 to 2.12.0
moment().isBetween(moment-like, moment-like);
moment().isBetween(moment-like, moment-like, String);
// where moment-like is Moment|String|Number|Date|Array

Проверяет, находится ли момент времени между двумя другими моментами, при необходимости учитывая единицу измерения (минуты, часы, дни и т. д.). Границы не включаются. Первые два аргумента будут разобраны как моменты времени, если это ещё не так.

moment('2010-10-20').isBetween('2010-10-19', '2010-10-25'); // true
moment('2010-10-20').isBetween('2010-10-19', undefined); // true, since moment(undefined) evaluates as moment()

Обратите внимание: порядок двух аргументов имеет значение — более ранняя дата должна быть указана первым аргументом.

moment('2010-10-20').isBetween('2010-10-19', '2010-10-25'); // true
moment('2010-10-20').isBetween('2010-10-25', '2010-10-19'); // false

Чтобы ограничить точность единицей измерения, отличной от миллисекунд, передайте эту единицу третьим параметром.

moment('2010-10-20').isBetween('2010-01-01', '2012-01-01', 'year'); // false
moment('2010-10-20').isBetween('2009-12-31', '2012-01-01', 'year'); // true

Как и moment#isSame, moment#isBefore, moment#isAfter поддерживает все единицы времени, поддерживаемые для moment#startOf и moment#isBetween: год, месяц, неделя, неделя ISO, день, час, минута и секунда.

В версии 2.13.0 добавлена возможность задавать включение границ. Символ [ указывает на включение значения. Символ ( указывает на исключение. Если используется параметр включения границ, необходимо передать оба символа.

moment('2016-10-30').isBetween('2016-10-30', '2016-12-30', undefined, '()'); //false
moment('2016-10-30').isBetween('2016-10-30', '2016-12-30', undefined, '[)'); //true
moment('2016-10-30').isBetween('2016-01-01', '2016-10-30', undefined, '()'); //false
moment('2016-10-30').isBetween('2016-01-01', '2016-10-30', undefined, '(]'); //true
moment('2016-10-30').isBetween('2016-10-30', '2016-10-30', undefined, '[]'); //true

Обратите внимание: если параметры from и to совпадают, но параметры включения границ различаются, приоритет имеет значение false.

moment('2016-10-30').isBetween('2016-10-30', '2016-10-30', undefined, '(]'); //false

Если параметр включения границ не указан, по умолчанию Moment использует ().

Летнее время 1.2.0+

moment().isDST();

moment#isDST проверяет, действует ли в текущий момент летнее время.

ПРИМЕЧАНИЕ: Эта функция — ХАК. У moment нет способа определить, действует ли в заданное время настоящее летнее время. Некоторые изменения времени в часовом поясе связаны с летним временем, а некоторые нет; без полной информации о часовом поясе это невозможно определить.

В настоящее время Moment проверяет зимнее и летнее время и, если смещение совпадает с летним (и отличается от зимнего), сообщает, что действует летнее время. Это работает в подавляющем большинстве случаев, но, как сказано выше, метод не является «правильным» и не работает во всех случаях. Поэтому не жалуйтесь нам.

Библиотека moment-timezone (на момент написания — 0.5.37) не поддерживает информацию о летнем времени (то есть о том, действует ли официально летнее время в заданный момент), поэтому для улучшения ситуации потребуется добавить новые возможности (и включить данные tzdata) в moment-timezone.

moment([2011, 2, 12]).isDST(); // false, March 12 2011 is not DST
moment([2011, 2, 14]).isDST(); // true, March 14 2011 is DST
// This example is for "en" locale: https://www.timeanddate.com/time/dst/2011.html

Смещение из-за перехода на летнее время Начиная с 2.3.0, устарело с 2.14.0

moment('2013-03-10 2:30', 'YYYY-MM-DD HH:mm').isDSTShifted()

Примечание: Начиная с версии 2.14.0 эта функция устарела. После изменения объекта moment она возвращает неверный результат. Дополнительные сведения см. в moment/3160.

Ещё один важный аспект проверки — определить, было ли изменено время из-за перехода на летнее время. Например, в большей части США:

moment('2013-03-10 2:30', 'YYYY-MM-DD HH:mm').format(); //=> '2013-03-10T01:30:00-05:00'

Это происходит потому, что при переходе на летнее время часы переводятся с 2:00 на 3:00, поэтому 2:30 не является реальным временем. Результирующее время зависит от браузера: оно может быть сдвинуто вперёд или назад. Используйте moment#isDSTShifted для проверки этого условия.

Примечание: до версии 2.3.0 объекты Moment в этом состоянии всегда возвращали false для moment#isValid; теперь они возвращают true.

Високосный год 1.0.0+

moment().isLeapYear();

moment#isLeapYear возвращает true, если год високосный, и false, если нет.

moment([2000]).isLeapYear() // true
moment([2001]).isLeapYear() // false
moment([2100]).isLeapYear() // false

Является объектом Moment 1.5.0+

moment.isMoment(obj);

Чтобы проверить, является ли переменная объектом moment, используйте moment.isMoment().

moment.isMoment() // false
moment.isMoment(new Date()) // false
moment.isMoment(moment()) // true

Начиная с версии 2.11.0, объект moment также можно проверить с помощью оператора instanceof:

moment() instanceof moment // true

Является объектом Date 2.9.0+

moment.isDate(obj);

Чтобы проверить, является ли переменная нативным объектом js Date, используйте moment.isDate().

moment.isDate(); // false
moment.isDate(new Date()); // true
moment.isDate(moment()); // false

i18n

Moment.js обеспечивает широкую поддержку интернационализации.

Можно загружать несколько локалей и легко переключаться между ними.

Помимо назначения глобальной локали, можно назначить локаль отдельному объекту moment.

Глобальное изменение локали 1.0.0+

// From 2.8.1 onward
moment.locale(String);
moment.locale(String[]);
moment.locale(String, Object);

// Deprecated in 2.8.1
moment.lang(String);
moment.lang(String[]);
moment.lang(String, Object);

По умолчанию Moment.js включает строки локали для английского языка (США). Если нужны другие локали, их можно загрузить в Moment.js для последующего использования.

Чтобы загрузить локаль, передайте ключ и строковые значения в moment.locale.

Подробнее о каждой части набора локали можно узнать в разделе настройки.

moment.locale('fr', {
    months : 'janvier_février_mars_avril_mai_juin_juillet_août_septembre_octobre_novembre_décembre'.split('_'),
    monthsShort : 'janv._févr._mars_avr._mai_juin_juil._août_sept._oct._nov._déc.'.split('_'),
    monthsParseExact : true,
    weekdays : 'dimanche_lundi_mardi_mercredi_jeudi_vendredi_samedi'.split('_'),
    weekdaysShort : 'dim._lun._mar._mer._jeu._ven._sam.'.split('_'),
    weekdaysMin : 'Di_Lu_Ma_Me_Je_Ve_Sa'.split('_'),
    weekdaysParseExact : true,
    longDateFormat : {
        LT : 'HH:mm',
        LTS : 'HH:mm:ss',
        L : 'DD/MM/YYYY',
        LL : 'D MMMM YYYY',
        LLL : 'D MMMM YYYY HH:mm',
        LLLL : 'dddd D MMMM YYYY HH:mm'
    },
    calendar : {
        sameDay : '[Aujourd’hui à] LT',
        nextDay : '[Demain à] LT',
        nextWeek : 'dddd [à] LT',
        lastDay : '[Hier à] LT',
        lastWeek : 'dddd [dernier à] LT',
        sameElse : 'L'
    },
    relativeTime : {
        future : 'dans %s',
        past : 'il y a %s',
        s : 'quelques secondes',
        m : 'une minute',
        mm : '%d minutes',
        h : 'une heure',
        hh : '%d heures',
        d : 'un jour',
        dd : '%d jours',
        M : 'un mois',
        MM : '%d mois',
        y : 'un an',
        yy : '%d ans'
    },
    dayOfMonthOrdinalParse : /\d{1,2}(er|e)/,
    ordinal : function (number) {
        return number + (number === 1 ? 'er' : 'e');
    },
    meridiemParse : /PD|MD/,
    isPM : function (input) {
        return input.charAt(0) === 'M';
    },
    // In case the meridiem units are not separated around 12, then implement
    // this function (look at locale/id.js for an example).
    // meridiemHour : function (hour, meridiem) {
    //     return /* 0-23 hour, given meridiem token and hour 1-12 */ ;
    // },
    meridiem : function (hours, minutes, isLower) {
        return hours < 12 ? 'PD' : 'MD';
    },
    week : {
        dow : 1, // Monday is the first day of the week.
        doy : 4  // Used to determine first week of the year.
    }
});

Сведения о week.dow и week.doy приведены в разделе настройки.

После загрузки локаль становится активной. Чтобы сменить активную локаль, вызовите moment.locale, передав ключ загруженной локали.

moment.locale('fr');
moment(1316116057189).fromNow(); // il y a une heure
moment.locale('en');
moment(1316116057189).fromNow(); // an hour ago

Начиная с версии 2.21.0, Moment будет console.warn, если локаль недоступна.

Начиная с версии 2.8.0, изменение глобальной локали не влияет на существующие экземпляры.

moment.locale('fr');
var m = moment(1316116057189);
m.fromNow(); // il y a une heure

moment.locale('en');
m.fromNow(); // il y a une heure
moment(1316116057189).fromNow(); // an hour ago

moment.locale возвращает используемую локаль. Это полезно, поскольку Moment не изменит локаль, если указанная вами локаль ему неизвестна.

moment.locale('fr'); // 'fr'
moment.locale('tq'); // 'fr'

Также можно указать список локалей, и Moment выберет первую, для которой доступны локализованные данные.

moment.locale(['tq', 'fr']); // 'fr'

Moment также проверяет подстроки идентификатора локали от наиболее конкретной к наименее конкретной, пока не найдёт известную ему локаль. Это полезно, когда Moment получает строку локали из среды пользователя, например window.navigator.language.

moment.locale('en-nz'); // 'en'

Наконец, Moment выполняет интеллектуальный поиск по массиву локалей и их подстрок.

moment.locale(['en-nz', 'en-au']); // 'en-au', not 'en'

Логика работает следующим образом: выбирается следующая локаль и выполняется попытка использовать её как есть. Если это не удаётся, код обычно отсекает последнюю часть (как правило, обозначение страны) и повторяет попытку. Однако если следующий элемент массива имеет такой же или более длинный общий префикс, чем проверяемая локаль, итерация продолжается. Например, если массив содержит последовательность

"AA-BB", "AA-CC", "XX-YY"

сначала проверяется «AA-BB», затем наивное решение проверило бы «AA», но этот алгоритм сначала проверяет, что «AA-CC» конкретнее, чем «AA», и пробует «AA-CC». И только после неудачи (если она произойдёт) проверяется «AA», поскольку у «XX-YY» нет префикса «AA». В итоге локали проверяются в следующем порядке (при условии, что каждая проверка завершается неудачей):

"AA-BB", "AA-CC", "AA", "XX-YY", "XX"

Локальное изменение локали 1.7.0+

// From version 2.8.1 onward
moment().locale(String|String[]|Boolean);

// Deprecated version 2.8.1
moment().lang(String|String[]|Boolean);

Глобальная настройка локали может создавать проблемы при передаче объектов moment, которые нужно форматировать с использованием разных локалей.

moment.locale('en'); // default the locale to English
var localLocale = moment();

localLocale.locale('fr'); // set this instance to use French
localLocale.format('LLLL'); // dimanche 15 juillet 2012 11:01
moment().format('LLLL'); // Sunday, July 15 2012 11:01 AM

moment.locale('es'); // change the global locale to Spanish
localLocale.format('LLLL'); // dimanche 15 juillet 2012 11:01
moment().format('LLLL'); // Domingo 15 Julio 2012 11:01

localLocale.locale(['tq', 'fr']); // set this instance to the first localization found
localLocale.format('LLLL'); // dimanche 15 juillet 2012 11:01
moment().format('LLLL'); // Sunday, July 15 2012 11:01 AM

localLocale.locale(false); // reset the instance locale
localLocale.format('LLLL'); // Domingo 15 Julio 2012 11:01
moment().format('LLLL'); // Domingo 15 Julio 2012 11:01

Если вызвать moment#locale без параметров, будет возвращена конфигурация локали, которая используется для этого момента времени.

var fr = moment().locale('fr');
fr.localeData().months(moment([2012, 0])) // "janvier"
fr.locale('en');
fr.localeData().months(moment([2012, 0])) // "January"

Если нужно получить доступ к данным локали для момента времени, рекомендуется использовать именно этот способ.

Начиная с версии 2.3.0, можно также указать массив идентификаторов локалей. Он работает так же, как глобальная настройка локали.

Загрузка локалей в NodeJS 1.0.0+

moment.locale(String);

Загрузить локали в NodeJS очень просто. Если в moment/locale/ есть файл локали с таким ключом, сначала импортируйте его, а затем вызовите moment.locale, чтобы загрузить его.

var moment = require('moment');
//or
// import moment from 'moment';

// import locale file(s)
import 'moment/locale/fr';

moment.locale('fr');
moment(1316116057189).fromNow(); // il y a 6 ans

Чтобы пропустить этап загрузки отдельных локалей (то есть загрузить их все), импортируйте вместо этого модуль moment/min/moment-with-locales.

import moment from 'moment/min/moment-with-locales';

moment.locale('de');
moment(1316116057189).fromNow(); // vor 6 Jahren

Если вы хотите добавить поддержку своей локали, создайте pull request в ветку develop с необходимыми файлами локали и модульного теста.

Загрузка локалей в браузере 1.0.0+

// From 2.8.1 onward
moment.locale(String, Object);

// Deprecated in 2.8.1
moment.lang(String, Object);

Чтобы загрузить локали в браузере, достаточно подключить файлы локалей. Обязательно укажите кодировку, чтобы избежать проблем с кодированием.

<script src="moment.js"></script>
<script src="locale/fr.js" charset="UTF-8"></script>
<script src="locale/pt.js" charset="UTF-8"></script>
<script>
  moment.locale('fr');  // Set the default/global locale
  // ...
</script>

Доступны минифицированные файлы со всеми локалями:

<script src="moment.js"></script>
<script src="min/locales.js" charset="UTF-8"></script>

Чтобы сократить количество HTTP-запросов, используйте задачу Grunt для сборки Moment с пользовательским списком локалей:

grunt transpile:fr,it

<script src="min/moment-with-locales.custom.js" charset="UTF-8"></script>

Если вы используете JSPM в качестве менеджера плагинов, добавьте локаль в свою библиотеку.

import * as moment from 'moment';
import 'moment/locale/fr';

Примечание: Файлы локалей определены в стиле UMD, поэтому они должны беспрепятственно работать во всех средах.

Добавление локали в Moment.js

Чтобы добавить свою локаль в Moment.js, отправьте pull request с файлом локали и файлом тестов. Примеры можно найти в moment/src/locale/fr.js и moment/src/test/locale/fr.js.

Чтобы запустить тесты в Node.js, выполните npm install, а затем grunt.

Если все тесты пройдут, отправьте pull request. Спасибо за ваш вклад!

Проверка текущей локали Moment.js 1.6.0+

// From version 2.8.1 onward
moment.locale();

// Deprecated in version 2.8.1
moment.lang();

Если вы часто меняете локали, может потребоваться узнать, какая локаль используется в данный момент. Для этого достаточно вызвать moment.locale без параметров.

moment.locale('en'); // set to english
moment.locale(); // returns 'en'
moment.locale('fr'); // set to french
moment.locale(); // returns 'fr'

Начиная с версии 2.12.0, можно вывести список всех загруженных и доступных для использования локалей:

moment.locales()

Список месяцев и дней недели текущей локали Moment.js 2.3.0+

moment.months()
moment.monthsShort()
moment.weekdays()
moment.weekdaysShort()
moment.weekdaysMin()

Иногда полезно получить список месяцев или дней недели для локали, например при заполнении раскрывающегося списка.

moment.months();

Возвращает список месяцев текущей локали.

[ 'January',
  'February',
  'March',
  'April',
  'May',
  'June',
  'July',
  'August',
  'September',
  'October',
  'November',
  'December' ]

Аналогично, moment.monthsShort возвращает сокращённые названия месяцев, а moment.weekdays, moment.weekdaysShort, moment.weekdaysMin возвращают списки дней недели.

В каждую из этих функций можно передать целое число, чтобы получить конкретный месяц или день недели.

moment.weekdays(3); // 'Wednesday'

Начиная с версии 2.13.0, в качестве первого параметра функций для дней недели можно передать логическое значение. Если оно равно true, дни недели будут возвращены в порядке, заданном локалью. Например, в арабской локали первым днём недели является суббота:

moment.locale('ar');
moment.weekdays(true); // lists weekdays Saturday-Friday in Arabic
moment.weekdays(true, 2); //will result in Monday in Arabic

Примечание: Если параметр локали не указан, индекс воскресенья всегда равен 0 независимо от того, какой день считается первым днём недели в данной локали.

В некоторых локалях при форматировании названий месяцев учитываются особые правила. Например, в нидерландском языке сокращения месяцев записываются без точки в конце, но только если месяц форматируется между дефисами. Метод months позволяет передать формат, чтобы список месяцев формировался с учётом контекста.

moment.locale('nl');
moment.monthsShort(); // ['jan.', 'feb.', 'mrt.', ...]
moment.monthsShort('-MMM-'); // [ 'jan', 'feb', 'mrt', ...]

Наконец, можно одновременно использовать параметр формата и параметр целого числа.

moment.monthsShort('-MMM-', 3); // 'apr'

Доступ к функциям конкретной локали 2.8.0+

localeData = moment.localeData()
localeData.months(Moment)
localeData.months()
localeData.monthsShort(Moment)
localeData.monthsShort()
localeData.monthsParse(String)
localeData.weekdays(Moment)
localeData.weekdays()
localeData.weekdays(Boolean)      ## Added 2.24.0, sorts weekdays by locale
localeData.weekdaysShort(Moment)
localeData.weekdaysShort()
localeData.weekdaysShort(Boolean) ## Added 2.24.0, sorts weekdays by locale
localeData.weekdaysMin(Moment)
localeData.weekdaysMin()
localeData.weekdaysMin(Boolean)   ## Added 2.24.0, sorts weekdays by locale
localeData.weekdaysParse(String)
localeData.longDateFormat(String)
localeData.isPM(String)
localeData.meridiem(Number, Number, Boolean)
localeData.calendar(String, Moment)
localeData.relativeTime(Number, Boolean, String, Boolean)
localeData.pastFuture(Number, String)
localeData.ordinal(Number)
localeData.preparse(String)
localeData.postformat(String)
localeData.week(Moment)
localeData.invalidDate()
localeData.firstDayOfWeek()
localeData.firstDayOfYear()

Получить доступ к свойствам текущей загруженной локали можно с помощью функции moment.localeData(key). Она возвращает текущую локаль или локаль с заданным ключом:

// get current locale
var currentLocaleData = moment.localeData();
var frLocaleData = moment.localeData('fr');

Возвращаемый объект содержит следующие методы:

localeData.months(aMoment);  // full month name of aMoment
localeData.monthsShort(aMoment);  // short month name of aMoment
localeData.monthsParse(longOrShortMonthString);  // returns month id (0 to 11) of input
localeData.weekdays(aMoment);  // full weekday name of aMoment
localeData.weekdaysShort(aMoment);  // short weekday name of aMoment
localeData.weekdaysMin(aMoment);  // min weekday name of aMoment
localeData.weekdaysParse(minShortOrLongWeekdayString);  // returns weekday id (0 to 6) of input
localeData.longDateFormat(dateFormat);  // returns the full format of abbreviated date-time formats LT, L, LL and so on
localeData.isPM(amPmString);  // returns true iff amPmString represents PM
localeData.meridiem(hours, minutes, isLower);  // returns am/pm string for particular time-of-day in upper/lower case
localeData.calendar(key, aMoment);  // returns a format that would be used for calendar representation. Key is one of 'sameDay', 'nextDay', 'lastDay', 'nextWeek', 'prevWeek', 'sameElse'
localeData.relativeTime(number, withoutSuffix, key, isFuture);  // returns relative time string, key is on of 's', 'm', 'mm', 'h', 'hh', 'd', 'dd', 'M', 'MM', 'y', 'yy'. Single letter when number is 1.
localeData.pastFuture(diff, relTime);  // convert relTime string to past or future string depending on diff
localeData.ordinal(number);  // convert number to ordinal string 1 -> 1st
localeData.preparse(str);  // called before parsing on every input string
localeData.postformat(str);  // called after formatting on every string
localeData.week(aMoment);  // returns week-of-year of aMoment
localeData.invalidDate();  // returns a translation of 'Invalid date'
localeData.firstDayOfWeek();  // 0-6 (Sunday to Saturday)
localeData.firstDayOfYear();  // 0-15 Used to determine first week of the year.

Сведения о firstDayOfYear приведены в разделе настройки.

Псевдолокаль 2.13.0+

moment.locale('x-pseudo')

Начиная с версии 2.13.0, Moment дополнительно включает псевдолокаль. Эта локаль подставляет в даты явно изменённые данные. Псевдолокали могут быть полезны при тестировании, поскольку с их помощью легко заметить, какие данные были локализованы, а какие нет. Просто подключите псевдолокаль и задайте для moment локаль x-pseudo. Текст от Moment будет легко распознать.

moment.locale('x-pseudo');
moment().format('LLL'); //14 F~ébrú~árý 2010 15:25
moment().fromNow(); //'á ~féw ~sécó~ñds á~gó'
moment().calendar(); //'T~ódá~ý át 02:00'

Настройка

Moment.js очень легко настраивать. Как правило, для своих настроек следует создать локаль.

moment.locale('en-my-settings', {
    // customizations.
});

Ранее определённую локаль можно удалить, передав null вторым аргументом. Удалённая локаль больше не будет доступна для использования.

moment.locale('fr'); // 'fr'
moment.locale('en'); // 'en'
moment.locale('fr', null);
moment.locale('fr'); // 'en'

Начиная с версии 2.12.0, можно создавать локаль, наследующую родительскую локаль.

moment.defineLocale('en-foo', {
  parentLocale: 'en',
  /* */
});

Свойства, не указанные в локали, будут унаследованы от родительской локали.

Начиная с версии 2.16.0, можно определить локаль с родительской локалью, которая сама не была определена или загружена.

moment.defineLocale('fakeLocale', {parentLocale:'xyz'})

Начиная с версии 2.21.0, при создании объекта moment с только что определённой локалью moment попытается отложенно загрузить родительскую локаль, если она существует. Если это не удастся, в качестве родительской будет использована глобальная локаль.

Начиная с версии 2.12.0, также можно обновлять свойства локали.

moment.updateLocale('en', {
  /**/
});

Указанные свойства будут обновлены, а остальные останутся без изменений. Эта функция не влияет на уже существующие объекты moment. Обратите внимание, что вызов updateLocale также изменяет текущую глобальную локаль на обновлённую; дополнительные сведения см. в этой задаче на GitHub.

Чтобы отменить обновление, используйте:

moment.updateLocale('en', null);

В версии 2.12.0 использование moment.locale() для изменения существующей локали было признано устаревшим. Вместо этого используйте moment.updateLocale().

Названия месяцев 1.0.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    months : String[]
});
moment.updateLocale('en', {
    months : Function
});
moment.updateLocale('en', {
    months : {
        format : String[],
        standalone : String[]
    }
});
// From 2.11.0
moment.locale('en', {
    months : {
        format : String[],
        standalone : String[]
    }
});
// From 2.8.1 to 2.11.2
moment.locale('en', {
    months : String[]
});
moment.locale('en', {
    months : Function
});

// Deprecated in 2.8.1
moment.lang('en', {
    months : String[]
});
moment.lang('en', {
    months : Function
});

Locale#months должен быть массивом названий месяцев.

moment.updateLocale('en', {
    months : [
        "January", "February", "March", "April", "May", "June", "July",
        "August", "September", "October", "November", "December"
    ]
});

Если для вычисления названия месяца требуется дополнительная обработка (например, если грамматическая форма зависит от формата), Locale#months может быть функцией со следующей сигнатурой. Она всегда должна возвращать название месяца.

moment.updateLocale('en', {
    months : function (momentToFormat, format) {
        // momentToFormat is the moment currently being formatted
        // format is the formatting string
        if (/^MMMM/.test(format)) { // if the format starts with 'MMMM'
            return nominative[momentToFormat.month()];
        } else {
            return subjective[momentToFormat.month()];
        }
    }
});

Начиная с версии 2.11.0, месяцы также можно задать объектом с формами standalone и format (именительный и винительный падежи). Чтобы определить, следует ли использовать форму format, к формату применяется регулярное выражение /D[oD]?(\[[^\[\]]*\]|\s+)+MMMM?/. Начиная с версии 2.14.0, другое регулярное выражение можно указать с помощью ключа isFormat.

moment.updateLocale('en', {
    months : {
         format: 'sausio_vasario_kovo_balandžio_gegužės_birželio_liepos_rugpjūčio_rugsėjo_spalio_lapkričio_gruodžio'.split('_'),
         standalone: 'sausis_vasaris_kovas_balandis_gegužė_birželis_liepa_rugpjūtis_rugsėjis_spalis_lapkritis_gruodis'.split('_'),
         isFormat: /D[oD]?(\[[^\[\]]*\]|\s+)+MMMM?|MMMM?(\[[^\[\]]*\]|\s+)+D[oD]?/  // from 2.14.0
    }
});

Сокращения названий месяцев 1.0.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    monthsShort : String[]
});
moment.updateLocale('en', {
    monthsShort : Function
});
moment.updateLocale('en', {
    monthsShort : {
        format: String[],
        standalone : String[]
    }
});
// From 2.11.0
moment.locale('en', {
    monthsShort : {
        format: String[],
        standalone : String[]
    }
});
// From 2.8.1 to 2.11.2
moment.locale('en', {
    monthsShort : String[]
});
moment.locale('en', {
    monthsShort : Function
});

// Deprecated in 2.8.1
moment.lang('en', {
    monthsShort : String[]
});
moment.lang('en', {
    monthsShort : Function
});

Locale#monthsShort должен быть массивом сокращений названий месяцев.

moment.updateLocale('en', {
    monthsShort : [
        "Jan", "Feb", "Mar", "Apr", "May", "Jun",
        "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
    ]
});

Как и Locale#months, Locale#monthsShort также может быть функцией обратного вызова.

moment.updateLocale('en', {
    monthsShort : function (momentToFormat, format) {
        if (/^MMMM/.test(format)) {
            return nominative[momentToFormat.month()];
        } else {
            return subjective[momentToFormat.month()];
        }
    }
});

Примечание: Начиная с версии 2.11.0, как и Locale#months, Locale#monthsShort может быть объектом с формами standalone и format.

moment.updateLocale('en', {
    monthsShort : {
        format: 'янв_фев_мар_апр_мая_июня_июля_авг_сен_окт_ноя_дек'.split('_'),
        standalone: 'янв_фев_март_апр_май_июнь_июль_авг_сен_окт_ноя_дек'.split('_')
    }
});

Названия дней недели 1.0.0+

// From version 2.12.0 onward
moment.updateLocale('en', {
    weekdays : String[]
});
moment.updateLocale('en', {
    weekdays : Function
});
moment.updateLocale('en', {
    weekdays : {
        standalone : String[],
        format : String[],
        isFormat : RegExp
    }
});
// From version 2.11.0
moment.locale('en', {
    weekdays : {
        standalone : String[],
        format : String[],
        isFormat : Boolean
    }
});
// From version 2.8.1 to 2.11.2
moment.locale('en', {
    weekdays : String[]
});
moment.locale('en', {
    weekdays : Function
});

// Deprecated version 2.8.1
moment.lang('en', {
    weekdays : String[]
});
moment.lang('en', {
    weekdays : Function
});

Locale#weekdays должен быть массивом названий дней недели.

moment.updateLocale('en', {
    weekdays : [
        "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"
    ]
});

Locale#weekdays также может быть функцией обратного вызова.

moment.updateLocale('en', {
    weekdays : function (momentToFormat, format) {
        return weekdays[momentToFormat.day()];
    }
});

Примечание: Начиная с версии 2.11.0, также можно передать формы для контекста и автономного употребления. Для определения нужной формы ко всей строке формата будет применяться isFormat.

moment.updateLocale('en', {
    weekdays : {
        standalone: 'Воскресенье_Понедельник_Вторник_Среда_Четверг_Пятница_Суббота'.split('_'),
        format: 'Воскресенье_Понедельник_Вторник_Среду_Четверг_Пятницу_Субботу'.split('_'),
        isFormat: /\[ ?[Вв] ?(?:прошлую|следующую|эту)? ?\] ?dddd/
    }
});

Сокращения названий дней недели 1.0.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    weekdaysShort : String[]
});
moment.updateLocale('en', {
    weekdaysShort : Function
});
// From 2.8.1 to 2.11.2
moment.locale('en', {
    weekdaysShort : String[]
});
moment.locale('en', {
    weekdaysShort : Function
});

// Deprecated in 2.8.1
moment.lang('en', {
    weekdaysShort : String[]
});
moment.lang('en', {
    weekdaysShort : Function
});

Locale#weekdaysShort должен быть массивом сокращений названий дней недели.

moment.updateLocale('en', {
    weekdaysShort : ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
});

Locale#weekdaysShort также может быть функцией обратного вызова.

moment.updateLocale('en', {
    weekdaysShort : function (momentToFormat, format) {
        return weekdaysShort[momentToFormat.day()];
    }
});

Краткие сокращения дней недели 1.7.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    weekdaysMin : String[]
});
moment.updateLocale('en', {
    weekdaysMin : Function
});

// From 2.8.1 to 2.11.2
moment.locale('en', {
    weekdaysMin : String[]
});
moment.locale('en', {
    weekdaysMin : Function
});

// Deprecated in 2.8.1
moment.lang('en', {
    weekdaysMin : String[]
});
moment.lang('en', {
    weekdaysMin : Function
});

Locale#weekdaysMin должен быть массивом двухбуквенных сокращений дней недели. Они предназначены для таких элементов, как календари выбора даты, поэтому должны быть как можно короче.

moment.updateLocale('en', {
    weekdaysMin : ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"]
});

Locale#weekdaysMin также может быть функцией обратного вызова.

moment.updateLocale('en', {
    weekdaysMin : function (momentToFormat, format) {
        return weekdaysMin[momentToFormat.day()];
    }
});

Длинные форматы даты 1.1.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    weekdaysMin : String[]
});
moment.updateLocale('en', {
    weekdaysMin : Function
});

// From 2.8.1 to 2.11.2
moment.locale('en', {
    longDateFormat : Object
});

// Deprecated in 2.8.1
moment.lang('en', {
    longDateFormat : Object
});

Locale#longDateFormat должен быть объектом, содержащим пару ключ/значение для каждого длинного формата даты L LL LLL LLLL LT LTS. LT должен быть форматом времени; он также используется для moment#calendar.

moment.updateLocale('en', {
    longDateFormat : {
        LT: "h:mm A",
        LTS: "h:mm:ss A",
        L: "MM/DD/YYYY",
        l: "M/D/YYYY",
        LL: "MMMM Do YYYY",
        ll: "MMM D YYYY",
        LLL: "MMMM Do YYYY LT",
        lll: "MMM D YYYY LT",
        LLLL: "dddd, MMMM Do YYYY LT",
        llll: "ddd, MMM D YYYY LT"
    }
});

Можно не указывать токены l в нижнем регистре: они будут созданы автоматически путём замены длинных токенов соответствующими короткими вариантами.

moment.updateLocale('en', {
    longDateFormat : {
        LT: "h:mm A",
        LTS: "h:mm:ss A",
        L: "MM/DD/YYYY",
        LL: "MMMM Do YYYY",
        LLL: "MMMM Do YYYY LT",
        LLLL: "dddd, MMMM Do YYYY LT"
    }
});

Относительное время 1.0.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    relativeTime : Object
});
// From 2.8.1 to 2.11.2
moment.locale('en', {
    relativeTime : Object
});

// Deprecated in 2.8.1
moment.lang('en', {
    relativeTime : Object
});

Locale#relativeTime должен быть объектом строк-замен для moment#from.

moment.updateLocale('en', {
    relativeTime : {
        future: "in %s",
        past:   "%s ago",
        s  : 'a few seconds',
        ss : '%d seconds',
        m:  "a minute",
        mm: "%d minutes",
        h:  "an hour",
        hh: "%d hours",
        d:  "a day",
        dd: "%d days",
        w:  "a week",
        ww: "%d weeks",
        M:  "a month",
        MM: "%d months",
        y:  "a year",
        yy: "%d years"
    }
});

Locale#relativeTime.future обозначает префикс/суффикс для будущих дат, а Locale#relativeTime.past — префикс/суффикс для дат в прошлом. Для всех остальных случаев один символ обозначает единственное число, а два символа — множественное.

Если для токена в локали требуется дополнительная обработка, его можно задать как функцию со следующей сигнатурой. Функция должна возвращать строку.

function (number, withoutSuffix, key, isFuture) {
    return string;
}

Аргумент key обозначает ключ замены в объекте Locale#relativeTime (например, s m mm h и т. д.).

Аргумент number обозначает количество единиц для этого ключа. Для m это количество минут и т. д.

Аргумент withoutSuffix будет равен true, если токен будет отображён без суффикса, и false, если он будет отображён с суффиксом. (Логика инвертирована, потому что по умолчанию отображается суффикс.)

Аргумент isFuture будет равен true, если будет использоваться суффикс/префикс для будущего времени, и false, если будет использоваться префикс/суффикс для прошлого.

Примечание: Поддержка w и ww добавлена в версии 2.25.0.

AM/PM 1.6.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    meridiem : Function
});
// From 2.8.1 to 2.11.2
moment.locale('en', {
    meridiem : Function
});

// Deprecated in 2.8.1
moment.lang('en', {
    meridiem : Function
});

Если в вашей локали используются «am/pm», Locale#meridiem можно не указывать, так как эти значения используются по умолчанию.

Если в вашей локали для am/pm нужны другие правила вычисления, Locale#meridiem должна быть функцией обратного вызова, возвращающей правильную строку на основе часа, минут и регистра.

moment.updateLocale('zh-cn', {
    meridiem : function (hour, minute, isLowercase) {
        if (hour < 9) {
            return "早上";
        } else if (hour < 11 && minute < 30) {
            return "上午";
        } else if (hour < 13 && minute < 30) {
            return "中午";
        } else if (hour < 18) {
            return "下午";
        } else {
            return "晚上";
        }
    }
});

Разбор AM/PM 2.1.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    meridiemParse : RegExp
    isPM : Function
});

// From 2.8.1 to 2.11.2
moment.locale('en', {
    meridiemParse : RegExp
    isPM : Function
});

// Deprecated in 2.8.1
moment.lang('en', {
    meridiemParse : RegExp
    isPM : Function
});

Locale#isPM должна возвращать true, если время во входной строке позже полудня. Это используется при разборе токенов a A.

moment.updateLocale('en', {
    isPM : function (input) {
        return ((input + '').toLowerCase()[0] === 'p');
    }
});

Чтобы указать, какие строки следует разбирать как входные данные, задайте свойство meridiemParse.

moment.updateLocale('en', {
    meridiemParse : /[ap]\.?m?\.?/i
});

Календарь 1.3.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    calendar : Object
});
// From 2.8.1 to 2.11.2
moment.locale('en', {
    calendar : Object
});

// Deprecated in 2.8.1
moment.lang('en', {
    calendar : Object
});

Locale#calendar должна содержать следующие строки форматирования.

moment.locale('en', {
    calendar : {
        lastDay : '[Yesterday at] LT',
        sameDay : '[Today at] LT',
        nextDay : '[Tomorrow at] LT',
        lastWeek : '[last] dddd [at] LT',
        nextWeek : 'dddd [at] LT',
        sameElse : 'L'
    }
});

Каждый из ключей Locale#calendar также может быть функцией обратного вызова в контексте текущего момента. Первым аргументом ей передаётся момент, обозначающий настоящее время. Функция должна возвращать строку форматирования.

function callback (now) {
    return '[hoy a la' + ((this.hours() !== 1) ? 's' : '') + '] LT';
}

Формат календаря 2.14.0+

moment.calendarFormat = Function

Это позволяет изменять токены, используемые в календаре.

moment.calendarFormat = function (myMoment, now) {
    var diff = myMoment.diff(now, 'days', true);
    var nextMonth = now.clone().add(1, 'month');

    var retVal =  diff < -6 ? 'sameElse' :
        diff < -1 ? 'lastWeek' :
        diff < 0 ? 'lastDay' :
        diff < 1 ? 'sameDay' :
        diff < 2 ? 'nextDay' :
        diff < 7 ? 'nextWeek' :
        // introduce thisMonth and nextMonth
        (myMoment.month() === now.month() && myMoment.year() === now.year()) ? 'thisMonth' :
        (nextMonth.month() === myMoment.month() && nextMonth.year() === myMoment.year()) ? 'nextMonth' : 'sameElse';
    return retVal;
};

Порядковые числительные 1.0.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    ordinal : Function
});
// From 2.8.1 to 2.11.2
moment.locale('en', {
    ordinal : Function
});

// Deprecated in 2.8.1
moment.lang('en', {
    ordinal : Function
});

Locale#ordinal должна быть функцией, возвращающей порядковое числительное для заданного числа.

moment.updateLocale('en', {
    ordinal : function (number, token) {
        var b = number % 10;
        var output = (~~ (number % 100 / 10) === 1) ? 'th' :
            (b === 1) ? 'st' :
            (b === 2) ? 'nd' :
            (b === 3) ? 'rd' : 'th';
        return number + output;
    }
});

Начиная с версии 2.0.0, функция порядкового числительного должна возвращать и число, и его порядковое представление. Ранее возвращалось только порядковое представление.

В версии 2.1.0 был добавлен параметр токена. Это строка токена, для которого формируется порядковое числительное, например: M или d.

Подробнее о порядковых числительных см. в Википедии.

Пороговые значения относительного времени 2.7.0+

moment.relativeTimeThreshold(unit);  // getter
moment.relativeTimeThreshold(unit, limit);  // setter

duration.humanize использует пороговые значения, которые определяют, когда единица времени считается минутой, часом и т. д. Например, по умолчанию интервал больше 45 секунд считается минутой, а интервал больше 22 часов — днём, и так далее. Чтобы изменить эти пороговые значения, используйте moment.relativeTimeThreshold(unit, limit), где единицей измерения может быть ss, s, m, h, d, w или M.

  // Retrieve existing thresholds
  moment.relativeTimeThreshold('ss'); // 44
  moment.relativeTimeThreshold('s');  // 45
  moment.relativeTimeThreshold('m');  // 45
  moment.relativeTimeThreshold('h');  // 22
  moment.relativeTimeThreshold('d');  // 26
  moment.relativeTimeThreshold('w');  // null (disabled)
  moment.relativeTimeThreshold('M');  // 11

  // Set new thresholds
  moment.relativeTimeThreshold('s', 40);
  moment.relativeTimeThreshold('ss', 3);
  moment.relativeTimeThreshold('m', 40);
  moment.relativeTimeThreshold('h', 20);
  moment.relativeTimeThreshold('d', 25);
  moment.relativeTimeThreshold('w', 4);  // enables weeks
  moment.relativeTimeThreshold('M', 10);

Примечание: Единица «неделя» добавлена в версии 2.25.0. По умолчанию она не используется (значение равно null), однако ей можно присвоить ненулевое значение, а также при необходимости установить d на меньшее значение, чтобы переход от дней к неделям происходил раньше.

Примечание: Получение пороговых значений добавлено в версии 2.8.1.

Примечание: Получение и установка порогового значения ss добавлены в версии 2.18.0.

Округление относительного времени 2.14.0+

moment.relativeTimeRounding();  // getter
moment.relativeTimeRounding(fn);  // setter

duration.humanize округляет потенциально дробное значение перед передачей его строке форматирования relativeTime, заданной в локали. Чтобы управлять округлением, используйте moment.relativeTimeRounding.

var roundingDefault = moment.relativeTimeRounding();

// Round relative time evaluation down
moment.relativeTimeRounding(Math.floor);

moment.relativeTimeThreshold('s', 60);
moment.relativeTimeThreshold('m', 60);
moment.relativeTimeThreshold('h', 24);
moment.relativeTimeThreshold('d', 7);
moment.relativeTimeThreshold('w', 4);
moment.relativeTimeThreshold('M', 12);

var a = moment();
a.subtract({hours: 23, minutes: 59, seconds: 59});
a.toNow();  // == 'in 23 hours'  'Round down towards the nearest hour'

// back to default
moment.relativeTimeRounding(roundingDefault);

Можно также отключить округление:

var retainValue = function (value) {
    return value;
};
moment.relativeTimeRounding(retainValue);

var a = moment();
a.subtract({hours: 39});
a.toNow(); // == 'in 1.625 days', 'Round down towards the nearest year'

Изменение источника времени 2.11.0+

moment.now = function () { return +new Date(); }

Чтобы изменить время, которое использует Moment, можно задать метод, возвращающий количество миллисекунд с начала эпохи Unix (1 января 1970 года).

По умолчанию используется:

moment.now = function () {
    return +new Date();
}

Это значение будет использоваться при вызове moment(), а также в качестве текущей даты, если в format() пропущены токены. В общем случае любой метод, которому требуется текущее время, использует это значение.

Первый день недели и первая неделя года 1.0.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    week : {
        dow : Int,
        doy : Int
     }
});
// From 2.8.1 to 2.11.2
moment.locale('en', {
    week : {
        dow : Int,
        doy : Int
    }
});

// Deprecated in 2.8.1
moment.lang('en', {
    week : {
        dow : Int,
        doy : Int
    }
});

Locale#week.dow должно быть целым числом, обозначающим первый день недели: 0 — воскресенье, 1 — понедельник, ..., 6 — суббота.

Locale#week.doy должно быть целым числом. doy используется вместе с dow для определения первой недели года. doy вычисляется как 7 + dow - janX, где janX — первый день января, который должен относиться к первой неделе года.

// ISO-8601, Europe
moment.updateLocale("en", { week: {
  dow: 1, // First day of week is Monday
  doy: 4  // First week of year must contain 4 January (7 + 1 - 4)
}});

// US, Canada
moment.updateLocale("en", { week: {
  dow: 0, // First day of week is Sunday
  doy: 6  // First week of year must contain 1 January (7 + 0 - 1)
}});

// Many Arab countries
moment.updateLocale("en", { week: {
  dow: 6, // First day of week is Saturday
  doy: 12 // First week of year must contain 1 January (7 + 6 - 1)
}});

// Also common
moment.updateLocale("en", { week: {
  dow: 1, // First day of week is Monday
  doy: 7  // First week of year must contain 1 January (7 + 1 - 1)
}});

Эры 2.25.0+

moment.updateLocale('en', {
    eras: [{
        since:  '0001-01-01',
        until:  +Infinity,
        offset: 1,
        name:   'Anno Domini',
        narrow: 'AD',
        abbr:   'AD'
    }, {
        until:   -Infinity,
        since:  '0000-12-31',
        offset: 1,
        name:   'Before Christ',
        narrow: 'BC',
        abbr:   'BC'
    }],
});

Задайте эры для конкретной локали. Эра — это временной интервал с названием и нумерацией лет. Абсолютный номер года (например, 2020) также можно указать как 2020 AD: 2020-й год эры AD. Аналогично абсолютный номер года -0500 можно описать как 501 BC — 501-й год эры BC.

eras: [{
    since:  '0001-01-01', // the start of the era
    until:  +Infinity,    // the end of the era, can be +/-Infinity
    offset: 1,            // added to year to (mostly) avoid 0 era years
    name:   'Anno Domini',// full name of era
    narrow: 'AD',         // narrow name of era
    abbr:   'AD'          // abbreviated name of era
}]

since и until задают направление эры. Как и в случае с BC, оно увеличивается в направлении -Infinity, поэтому since > until. Для эр, возрастающих в направлении +Infinity, since < until.

Разбор и форматирование эр выполняются с помощью токенов yo, y* и N*.

Примечание: API, связанные с эрами, могут измениться.

Недопустимая дата 2.3.0+

// From 2.12.0 onward
moment.updateLocale('en', {
    invalidDate : String
});

// From 2.8.1 to 2.11.2
moment.locale('en', {
    invalidDate : String
});

// Deprecated in 2.8.1
moment.lang('en', {
    invalidDate : String
});

Locale#invalidDate должна быть строкой.

moment.updateLocale("es", {
  invalidDate: "Fecha invalida"
});

Длительности

В Moment.js также есть объекты длительности. Если момент определяет единственную точку во времени, то длительность определяет временной интервал.

У длительности нет определённых дат начала и окончания. Она не зависит от контекста.

По смыслу длительность ближе к «2 часам», чем к «времени между 2 и 4 часами дня». Поэтому длительности не подходят для преобразования между единицами измерения, зависящими от контекста.

Например, год может составлять 366 дней, 365 дней, 365,25 дня, 12 месяцев или 52 недели. Преобразование лет в дни не имеет смысла без контекста. Для вычисления количества дней или лет между двумя моментами лучше использовать moment#diff, а не Durations.

Как обсуждалось здесь, формат длительности Moment.js незначительно отличается от спецификаций номинальной длительности ISO 8601 и длительности RFC 5545.

Создание 1.6.0+

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

Чтобы создать длительность, вызовите moment.duration(), передав ей интервал времени в миллисекундах.

moment.duration(100); // 100 milliseconds

Чтобы создать длительность в единицах измерения, отличных от миллисекунд, можно также передать единицу измерения.

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.duration('2', 'years'); // from 2.25.0

Здесь также работают те же сокращения, что и для 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'); // added in 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();

Клонирование 2.19.0+

moment.duration().clone();

Создаёт копию длительности. Длительности изменяемы, как и объекты моментов, поэтому это позволяет сохранить их состояние в определённый момент времени.

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

Удобочитаемое представление 1.6.0+

moment.duration().humanize();
moment.duration().humanize(withSuffix);
moment.duration().humanize(withSuffix, thresholds); // from 2.25.0
moment.duration().humanize(thresholds);             // from 2.25.0

Иногда нужны все возможности moment#from, но при этом не требуется создавать два момента — нужно лишь отобразить временной интервал.

Для этого используйте moment.duration().humanize().

moment.duration(1, "minutes").humanize(); // a minute
moment.duration(2, "minutes").humanize(); // 2 minutes
moment.duration(24, "hours").humanize();  // a day

По умолчанию возвращаемая строка описывает длительность a month (без суффикса). Если нужно направленное описание длительности in a month, передайте true в a month ago (с суффиксом), как показано ниже.

moment.duration(1, "minutes").humanize(true); // in a minute

Чтобы получить суффиксы для времени до текущего момента, передайте отрицательное число.

moment.duration(-1, "minutes").humanize(true); // a minute ago

Для недопустимых длительностей возвращается локализованный вариант Invalid Date.

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

Формат вывода метода humanize можно настроить с помощью пороговых значений относительного времени. Чтобы указать пороговые значения для конкретного вызова humanize, передайте их единственным аргументом или после аргумента суффикса:

moment.duration(-1, 'week').humanize(true, {d: 7, w: 4}); // a week ago
moment.duration(-1, 'week').humanize({d: 7, w: 4}); // a week

Примечание: Передача пороговых значений в humanize добавлена в версии 2.25.0.

Миллисекунды 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

Секунды 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

Минуты 1.6.0+

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

Как и другие методы получения значений длительности, moment.duration().minutes() возвращает количество минут (0–59).

moment.duration().asMinutes() возвращает длительность в минутах.

Часы 1.6.0+

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

Как и другие методы получения значений длительности, moment.duration().hours() возвращает количество часов (0–23).

moment.duration().asHours() возвращает длительность в часах.

Дни 1.6.0+

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

Как и другие методы получения значений длительности, moment.duration().days() возвращает количество дней (0–30).

moment.duration().asDays() возвращает длительность в днях.

Недели 1.6.0+

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

Как и другие методы получения значений длительности, moment.duration().weeks() возвращает количество недель (0–4).

moment.duration().asWeeks() возвращает длительность в неделях.

Обратите внимание: в отличие от других методов получения значений длительности, недели считаются частью количества дней и не вычитаются из него.

Примечание: Длительность в неделях определяется как 7 дней.

Месяцы 1.6.0+

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

Как и другие методы получения значений длительности, moment.duration().months() возвращает количество месяцев (0–11).

moment.duration().asMonths() возвращает длительность в месяцах.

Годы 1.6.0+

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

Как и другие методы получения значений длительности, moment.duration().years() возвращает количество лет.

moment.duration().asYears() возвращает длительность в годах.

Добавление времени 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

Обратите внимание: добавление недопустимой длительности к любой другой длительности приводит к недопустимой длительности.

Вычитание времени 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

Обратите внимание: добавление недопустимой длительности к любой другой длительности приводит к недопустимой длительности.

Использование длительности с методом diff 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))
  // returns duration object with the duration between x and y

Подробнее о moment#diff см. здесь.

В единицах времени 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 для всех единиц измерения.

Получение единиц времени 2.1.0+

moment.duration().get(String);

Вместо методов получения значений Duration#x() можно использовать Duration#get('x'). Здесь также применяются все сокращённые ключи из moment#add.

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

Для недопустимых длительностей возвращается NaN для всех единиц измерения.

В формате JSON 2.9.0+

moment.duration().toJSON();

При сериализации объекта длительности в JSON он будет представлен строкой ISO8601.

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

Для недопустимых длительностей в качестве представления JSON возвращается Invalid Date.

Проверка длительности 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

Строка ISO 8601 2.8.0+

moment.duration().toISOString();

Возвращает длительность в виде строки, соответствующей стандарту ISO 8601.

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

Описание формата PnYnMnDTnHnMnS:

Локаль 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 предоставляет несколько методов, которые могут быть полезны тем, кто расширяет библиотеку или пишет собственные парсеры.

Нормализация единиц измерения 2.3.0+

moment.normalizeUnits(String);

Многие функции Moment позволяют передавать псевдонимы перечислений единиц измерения. Например, все приведённые ниже gets эквивалентны.

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'

Недопустимый объект 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().

Плагины

Другие разработчики создали плагины для Moment.js, которые могут быть вам полезны.

Strftime

npm install moment-strftime

Если вам удобнее работать с strftime, а не с токенами разбора, подобными LDML, воспользуйтесь плагином Бена Оукса moment-strftime.

Репозиторий находится по адресу github.com/benjaminoakes/moment-strftime.

MSDate

Если вы используете даты OLE Automation в .NET, ознакомьтесь с moment-msdate от Markit On Demand. Этот плагин позволяет преобразовывать даты OA в даты JavaScript и обратно.

Преобразование moment в дату OA:

moment().toOADate(); // a floating point number

Или преобразование даты OA в moment:

moment.fromOADate(41493); // Wed Aug 07 2013 00:00:00 GMT-0600 (MDT)

Дополнительные сведения и подробную документацию можно найти на GitHub: http://markitondemand.github.io/moment-msdate/.

Парсер Java DateFormat

npm install moment-jdateformatparser

Если вы хотите работать с java.text.DateFormat, воспользуйтесь этим плагином.

Например:

moment("2013-12-24 14:30").formatWithJDF("dd.MM.yyyy");  // returns the formatted date "24.12.2013"
moment().toJDFString("DD.MM.YYYY");  // returns the Java format pattern "dd.MM.yyyy"

Репозиторий находится по адресу github.com/MadMG/moment-jdateformatparser.

Диапазоны дат

npm install moment-range

Если вам нужно работать с диапазонами дат, воспользуйтесь плагином Джанни Кьяппетты moment-range.

Документацию можно найти на домашней странице github.com/rotaready/moment-range.

Плагин также доступен для веб-разработки в репозитории ниже.

Репозиторий находится по адресу github.com/rotaready/moment-range.

Twix

npm install twix

Ещё один плагин для работы с диапазонами — библиотека Айзека Кэмброна Twix. Она предоставляет множество функций для работы с диапазонами и особенно удобна для наглядного форматирования диапазонов. Например:

var t = moment("1/25/1982 9:30 AM").twix("1/25/1982 1:30 PM");
t.isCurrent(); // false
t.count('minutes'); // 241
t.format();  // 'Jan 25, 1982, 9:30 AM - 1:30 PM'
t.simpleFormat("h:m"); // '9:30 - 1:30'

Здесь доступна полная документация по всем параметрам и функциям.

Пакет можно установить из npm:

npm install twix

Или просто скачать файл JS здесь.

Точный диапазон

npm install moment-precise-range-plugin

Плагин Precise Range, созданный Робом Доусоном, позволяет выводить точное и удобочитаемое представление диапазонов дат и времени:

moment("2014-01-01 12:00:00").preciseDiff("2015-03-04 16:05:06");
 // 1 year 2 months 3 days 4 hours 5 minutes 6 seconds

moment.preciseDiff("2014-01-01 12:00:00", "2014-04-20 12:00:00");
// 3 months 19 days

Чтобы получить необработанные числовые значения, а не строку, передайте значение true третьим аргументом метода:

moment.preciseDiff(m1, m2, true); 
// {years : 0, months : 1, days : 2, hours : 3, minutes : 4, seconds : 5, firstDateWasLater : false}

Календарь ISO

npm install moment-isocalendar

Если вам нужен метод isocalendar, подобный методу в Python, воспользуйтесь плагином Рокки Мезы.

moment-isocalendar

Вызов метода isocalendar для момента вернёт массив следующего вида:

[year, week_of_year, day_of_week, minutes_since_midnight]

moment().isocalendar(); // [2012, 8, 5, 870]

Также можно восстановить момент из массива isocalendar.

moment.fromIsocalendar([2011, 51, 5, 870]).format('LLLL');
// "Friday, December 23 2011 2:30 PM"

Репозиторий находится по адресу github.com/fusionbox/moment-isocalendar.

Календарь джалали

npm install moment-jalaali

Для работы с календарной системой джалали (джалали, персидским, хоршиди или шамси) можно использовать плагин Бехранга Норузи Нии moment-jalaali.

После установки плагин обернёт moment, и moment сможет форматировать и разбирать годы и месяцы календаря джалали. Краткий пример:

var m = moment('1360/5/26', 'jYYYY/jM/jD'); // Parse a Jalaali date.
m.format('jYYYY/jM/jD [is] YYYY/M/D'); // 1360/5/26 is 1981/8/17

Репозиторий находится по адресу github.com/behrang/moment-jalaali.

Календарь хиджры

npm install moment-hijri

Для работы с календарём хиджры можно использовать плагин moment-hijri. moment-hijri — это плагин для moment, реализующий лунный календарь хиджры на основе вычислений Умм аль-Кура. Плагин разработан Сухаилом Альковаилитом.

После установки плагин обернёт moment, и вы сможете разбирать даты хиджры. Краткий пример:

m = moment('1410/8/28', 'iYYYY/iM/iD'); // Parse a Hijri date.
m.format('iYYYY/iM/iD [is] YYYY/M/D'); // 1410/8/28 is 1990/3/25

Репозиторий находится по адресу github.com/xsoh/moment-hijri.

Исламский гражданский календарь

npm install moment-islamic-civil

Это ещё один календарь хиджры, основанный на гражданских вычислениях.

Репозиторий находится по адресу github.com/ACGC/moment-islamic-civil.

Повторение

npm install moment-recur

Для работы с повторяющимися датами можно использовать плагин Кейси Тримма moment-recur.

Этот плагин позволяет создавать интервалы фиксированной длины (дни, недели и т. д.) и интервалы на основе календаря (daysOfMonth, monthsOfYear и т. д.).

В нём есть функция matches для проверки того, повторяется ли дата согласно заданным правилам, а также функции-генераторы для получения следующих и предыдущих дат в последовательности.

Репозиторий, документацию и множество других примеров можно найти по адресу github.com/c-trimm/moment-recur

var interval = moment( "01/01/2014" ).recur().every(2).days(); // Length Interval
interval.matches( "01/03/2014" ); // true
interval.next( 2, "L" ); // ["01/03/2014", "01/05/2014"]
interval.forget( "days" ); // Remove a rule
interval.dayOfMonth( 10 ); // Calendar Interval
interval.matches( "05/10/2014" ); // true
interval.previous( 2, "L" ); // ["12/10/2013", "11/10/2013"]

Twitter

Если вы хотите форматировать время в твитах так же, как это делает Twitter, воспользуйтесь плагином moment.twitter от @hijonathan.

Это простой способ отображать короткие и полные удобочитаемые временные метки.

moment().subtract(5, 'hours').twitterLong();
// 5 hours

Да, плагин умеет правильно образовывать множественное число.

moment().subtract(1, 'hour').twitterLong();
// 1 hour

Нужно ещё короче?

moment().subtract(6, 'days').twitterShort();
// 6d

Финансовые кварталы

Если вам нужны финансовые, календарные или учебные кварталы, воспользуйтесь плагином moment-fquarter от @robgallen.

Для простейшего использования вызовите метод fquarter у любого объекта moment. Он возвращает отформатированную строку, считая первым кварталом квартал, начинающийся в апреле.

moment("2013-01-01").fquarter();
// Q4 2012/13

Можно передать любой месяц в качестве начала квартала, например июль.

moment("2013-01-01").fquarter(7);
// Q3 2012/13

Чтобы использовать календарные кварталы, задайте январь.

moment("2013-01-01").fquarter(1);
// Q1 2013

Разбор формата даты

npm install moment-parseformat

Этот плагин определяет формат строки даты и времени.

var format = moment.parseFormat('Thursday, February 6th, 2014 9:20pm');
// dddd, MMMM Do, YYYY h:mma
moment().format(format); // format

Это позволяет создавать интеллектуальные поля ввода дат, в которых пользователи указывают дату и время, а приложение определяет предпочитаемый ими формат для дальнейшего использования. Пример использования можно найти на сайте minutes.io.

Плагин создан @gr2m. Ссылки: демонстрация | исходный код

Округление

npm install moment-round

Этот плагин округляет дату и время до заданного интервала.

Например:

require('moment-round');
var m = new moment(); // 2015-06-18 15:30:19
m.round(5, 'seconds'); // 2015-06-18 15:30:20
m.ceil(3, 'minutes'); // 2015-06-18 15:33:00
m.floor(16, 'hours'); // 2015-06-18 00:00:00
m.ceil(21, 'hours'); // 2015-06-18 21:00:00
m.ceil(20, 'hours'); // 2015-06-19 00:00:00

Репозиторий находится по адресу github.com/WebDevTmas/moment-round.

Преобразование

bower install moment-transform

moment-transform — это плагин для преобразования дат с помощью шаблонов. Он позволяет выполнять базовые операции — установить, добавить и вычесть — для отдельных компонентов объекта Moment (часы, месяц и т. д.).

moment().transform('YYYY-MM-+01 00:00:00.000'); // Tonight at midnight
moment().transform('14:30:00.000'); // Today, 2:30 pm
moment().transform('YYYY-MM--30 00:00:00.000'); // 30 days ago

Необязательные параметры позволяют задавать собственные шаблоны и включать строгую проверку соответствия шаблону (по умолчанию в переданной строке необязательно наличие неалфавитных символов).

moment().transform('+01MMYYYY', 'DD/MM/YYYY', false); // Tomorrow, same time
moment().transform('+01MMYYYY', 'DD/MM/YYYY', true); // Invalid date

Попробовать плагин можно здесь, а репозиторий находится здесь.

Тайваньский календарь

npm install moment-taiwan

Для работы с тайваньской календарной системой можно использовать плагин Брэду moment-taiwan.

После установки он обернёт moment, и moment сможет форматировать и разбирать годы тайваньского календаря. Краткий пример:

m = moment('104/01/01', 'tYY/MM/DD') // Parse a Taiwan date
m.format('tYY/MM/DD [is] YYYY/M/D') // 104/01/01 is 2015/01/01

m.twYear() // 104

Репозиторий находится по адресу github.com/bradwoo8621/moment-taiwan.

Форматирование длительности

npm install moment-duration-format

Этот плагин обеспечивает расширенные возможности форматирования длительностей Moment.

Например:

moment.duration(123, "minutes").format("h:mm");
// "2:03"

Репозиторий находится по адресу github.com/jsmreese/moment-duration-format.

Таймер

npm install moment-timer

Этот плагин для Moment.js позволяет использовать таймеры, обеспечивающие гораздо более гибкое управление, чем встроенные таймеры JavaScript. По сути, это переписанные функции setInterval и setTimeout самого JavaScript.

Например:

var timer = moment.duration(5, "seconds").timer({loop: true}, function() {
  // Callback
});

Репозиторий находится по адресу github.com/SeverinDK/moment-timer.

Рабочие дни

npm install moment-business

Эта библиотека для Moment.js позволяет выполнять операции с моментами в рамках западной рабочей недели: семидневной недели, в которой суббота и воскресенье являются выходными.

Например:

import business from 'moment-business';

// true if the moment is Mon-Fri, false otherwise
business.isWeekDay(someMoment);

// Adds five work days to the Moment
business.addWeekDays(someMoment, 5);

Репозиторий находится по адресу github.com/jmeas/moment-business.

Краткое форматирование дат

Для краткого форматирования времени можно использовать плагин moment-shortformat от @researchgate.

Он основан на плагине moment.twitter и похож на него, но формирует другой вывод.

moment().subtract(5, 'hours').short();
// 5h ago
moment().add(5, 'hours').short();
// in 5h

Также можно отключить использование шаблонов относительного времени.

moment().subtract(1, 'hour').short(false);
// 1h

Если дата слишком далеко в будущем или прошлом, она будет отображаться именно так

moment().subtract(500, 'days').short();
// 5 Mar, 1970

Немецкий праздник (Feiertag)

npm install moment-feiertage --save

Этот плагин для Moment.js (moment-feiertage) позволяет определить, является ли дата немецким праздником. Список праздников взят из Википедии (de). Определить, является ли дата праздником, довольно сложно, поскольку религиозные праздники меняются каждый год и различаются в 16 федеральных землях Германии.

Автор: DaniSchenk.

var someDateInSomeStates = moment('2018-11-01').isHoliday(['BW', 'SH', 'TH']);
/* returns {
  allStates: false,
  holidayName: 'Allerheiligen',
  holidayStates: [ 'BW' ],
  testedStates: [ 'BW', 'SH', 'TH' ]
}*/

Репозиторий находится по адресу github.com/DaniSchenk/moment-feiertage.