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, но мы хотели бы не рекомендовать 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 — это JavaScript-порт Java Three-Ten Backport, который является основой для реализации JSR-310 в пакете Java SE 8 java.time. Если вы знакомы с 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 и определяет параметры поведения функций Date объекта toLocaleString, toLocaleDateString, и toLocaleTimeString.

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

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

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

Будущее

Temporal - Лучшие даты и время в языке JavaScript!

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

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

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

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

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

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

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

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

В настоящее время для системы непрерывной интеграции используются следующие браузеры: 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();

Примечание: если вы хотите работать с конкретной вариацией часового пояса Moment, например, используя только данные с 2012 по 2022 год, вам необходимо импортировать его из каталога builds следующим образом:

import moment from 'moment-timezone/builds/moment-timezone-with-data-2012-2022';

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

Браузер

<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 вместе с каталогом locales в базовую папку. Затем вам следует использовать инструмент, такой как adapt-pkg-main, или вручную — с использованием настроек конфигурации пакетов.

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

NuGet

NuGet / Moment.js

Install-Package Moment.js

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

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 очень активны на Stack Overflow, как и многие другие опытные пользователи. Там вы получите самую быструю реакцию.

Парсинг

Вместо модификации встроенного объекта 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 не обязательно означает, что вы находитесь в часовой зоне Тихоокеанского времени США.

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

Now 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().diff(moment()) не всегда может возвращать 0. Более подробную информацию см. в этой проблеме GitHub.

String 1.0.0+

moment(String);

При создании момента из строки сначала проверяется, соответствует ли строка известным форматам ISO 8601, затем проверяется, соответствует ли строка формату RFC 2822 Date time, прежде чем переходить к падению на new Date(string) в случае отсутствия известного формата.

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

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

Для получения согласованных результатов разбора строк, отличных от строк ISO 8601, следует использовать String + Format.

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

Строка ISO 8601 требует части даты.

2013-02-08  # A calendar date part
2013-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 строка очищается для удаления комментариев и/или символов новой строки. Дополнительные символы допустимы в формате, но не добавляют ничего для создания экземпляра момента.

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

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 спецификации для получения подробностей.

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

String + Format 1.0.0+

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

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

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

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

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

Вы можете получить неожиданные результаты при разборе даты и времени. Приведённый ниже пример может не обработаться ожидаемо:

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

Вы можете использовать строгий режим, который обнаружит ошибку разбора и установит объект момента как недействительный:

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

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

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

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

YYYY начиная с версии 2.10.5 поддерживает 2-значные годы и преобразует их в год, близкий к 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.

Начиная с версии 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, вы можете указать boolean значение в последнем аргументе, чтобы 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, но это можно явно указать в формате/списке форматов при создании момента.

Для указания разбора 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

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

Пропущенные единицы по умолчанию равны 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), вы можете создать момент, передав целое значение, представляющее количество миллисекунд с эпохи Unix (1 января 1970 г. 00:00:00 UTC).

var day = moment(1318781876406);

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

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

moment.unix(Number)

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

var day = moment.unix(1318781876);

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

var day = moment.unix(1318781876.721);

Примечание: Несмотря на то, что маркеры времени Unix основаны на UTC, эта функция создаёт объект момента в локальном режиме. Если вам нужен 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[]);

Вы можете создать момент с массивом чисел, отражающих параметры, передаваемые в 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)

Дата ASP.NET JSON 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

Клонирование момента 1.2.0+

moment(Moment);

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

Вызов moment() для момента создаст его копию.

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

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

Если вы хотите выполнить разбор или отобразить момент в 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.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: Указывает, какой meridiem (AM/PM) был проанализирован, если таковой имеется. Строка.
• parsedDateParts: Возвращает массив проанализированных частей даты в порядке убывания — т. е. parsedDateParts[0] === год. Если частей нет, но meridiem имеет значение, дата недействительна. Массив.

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

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

Примечание: Концепция действительности Moment стала более строгой и согласованной между версиями 2.2 и 2.3. Примечание: Действительность определяется при создании момента. Измененный момент (например, 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. миллисекунды

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

Недействительные моменты

Если момент недействителен, он ведет себя как NaN в операциях с плавающей запятой.

Все нижеприведенные примеры создают недействительные моменты:

• 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.

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

Примечание: Начиная с 2.19.0, передача NaN любому сеттеру — это нетдействие. До 2.19.0 это делало момент недействительным неправильным способом.

Миллисекунды 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 дней (то же самое относится к манипуляциям с Date, JavaScript), возвращаемая дата будет 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().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 зависит от локалей данного момента.

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

Неделя года (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().month("January");
moment().month("Feb");

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

Начиная с версии 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 января, и, следовательно, тому же году недели, что и 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]()

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

Установить 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});

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

Обработка объектов была добавлена в 2.9.0

Максимальное значение 2.7.0+

moment.max(Moment[,Moment...]);
moment.max(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'

Без аргументов функция возвращает момент с текущим временем.

С версии 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[]);

Возвращает минимальный (наиболее отдалённый в прошлом) из заданных моментов.

Например:

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

Без аргументов функция возвращает момент с текущим временем.

С версии 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#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'), значения -0.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

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

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"

См. moment.utc() для получения дополнительной информации о режиме 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"

См. moment.utc() для получения дополнительной информации о режиме 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 путем предоставления минут. Смещение устанавливается в объекте момента, на котором вызывается utcOffset(). Если вы хотите установить смещение глобально, используйте moment-timezone. Обратите внимание, что после установки смещения оно фиксируется и не будет изменяться автоматически (то есть нет правил DST). Если вам нужен фактический часовой пояс — время в определённом месте, как 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.

Локализованные форматы

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

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

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

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

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

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

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

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

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

Скорость форматирования

Чтобы сравнить скорость форматирования Moment.js с другими библиотеками, ознакомьтесь со этим сравнением с другими библиотеками.

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

Если вам удобнее работать с 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. Это иногда называется временем "от сейчас" или относительным временем.

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 (невидим для пользователя).

Время от X 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. Это иногда называется временем "от сейчас" или относительным временем.

Это похоже на 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, если объект целевого момента недействителен, результат — локализованная строка «Недействительная дата».

Время до X 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 аргумент форматов для календаря может быть функцией, которая выполняется в контексте 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 Date 1.0.0+

moment().toDate();

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

Это вернёт копию Date, который использует момент, поэтому любые изменения в этом Date не заставят момент измениться. Если вы хотите изменить момент Date, см. 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.

Is Same 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.

Is After 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

Is Same or Before 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

Is Same or After 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

Is Between 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 по умолчанию использует ().

Is Daylight Saving Time 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

Is DST Shifted From 2.3.0, Deprecated 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.

Is Leap Year 1.0.0+

moment().isLeapYear();

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

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

Is a 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

Is a Date 2.9.0+

moment.isDate(obj);

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

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

i18n

Moment.js имеет мощную поддержку интернационализации.

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

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

Changing locale globally 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.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

Если вы хотите, чтобы ваша локаль была поддерживаемой, создайте запрос на добавление в ветку 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, отправьте запрос на добавление с файлом локали и файлом теста. Примеры можно найти в moment/src/locale/fr.js и moment/src/test/locale/fr.js.

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

Если все тесты пройдут, отправьте запрос на добавление, и спасибо за вклад!

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

Начиная с версии 2.12.0, также можно обновить свойства локали.

moment.updateLocale('en', {
  /**/
});

Все указанные свойства будут обновлены, а другие останутся неизменными. Эта функция не влияет на уже существующие моменты. Обратите внимание, что вызов 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"
    }
});

Вы можете исключить токены lowercase 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), но вы можете установить ее в отличное от null значение, а также (необязательно) установить d меньше, чтобы переход от дней к неделям происходил раньше.

Примечание: Получение пороговых значений было добавлено в 2.8.1.

Примечание: Получение и установка пороговых значений ss была добавлена в 2.18.0.

Округление относительного времени 2.14.0+

moment.relativeTimeRounding();  // getter
moment.relativeTimeRounding(fn);  // setter

duration.humanize округляет возможное двойное значение перед его передачей в строку форматирования относительного времени, указанную в локали. Чтобы контролировать округление, вы можете использовать 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. Для эр, которые увеличиваются в направлении +Бесконечность, 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, момент поддерживает разбор временных отрезков в стиле 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, момент также поддерживает разбор длительностей 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, a month ago (с суффиксом), передайте в качестве аргумента значение true, как показано ниже.

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, передайте их в качестве единственного аргумента или после аргумента suffix:

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#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"}'

Некорректные продолжительности возвращают Invalid Date как представление в формате JSON.

Является ли продолжительностью 1.6.0+

moment.isDuration(obj);

Для проверки, является ли переменная объектом продолжительности момента, используйте 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(). См. раздел intl для получения дополнительной информации об интернационализации.

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 позволяют вызывающему методу передавать псевдонимы для перечислений единиц измерения. Например, все следующие get эквивалентны.

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

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

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

Некорректный 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, вы можете использовать плагин Бена Оуксa moment-strftime.

Репозиторий находится по адресу github.com/benjaminoakes/moment-strftime.

MSDate

Если вы используете даты OLE Automation в .NET, обратите внимание на плагин Markit On Demand moment-msdate. Использование этого плагина позволяет форматировать даты 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

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

Плагин Точный диапазон, написанный Робом Доусоном, позволяет отображать точные, удобочитаемые представления диапазонов дат и времени:

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 для объекта moment вернет массив, подобный следующему:

[year, week_of_year, day_of_week, minutes_since_midnight]

moment().isocalendar(); // [2012, 8, 5, 870]

Вы также можете восстановить объект moment из массива 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.js для лунного календаря Хиджры, основанный на расчётах Umm al-Qura. Этот плагин разработан Сухайлом Альковаилетом.

При установке он обернёт 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

Если вам нужно работать с тайваньской календарной системой, вы можете использовать плагин Брэдвуда8621 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, которая позволяет выполнять операции Moment для западных рабочих недель: 7-дневные недели, где суббота и воскресенье — нерабочие дни.

Например,

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-feiertage) для Moment.js определяет, является ли дата немецким праздничным днём. Праздники взяты из Википедии (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.