Пользовательские форматы

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

Форматирование в Moment.js основано на строке-шаблоне, где специальные токены заменяются соответствующими частями даты. Метод format() не изменяет исходный объект, а возвращает строковое представление:

moment().format('YYYY-MM-DD HH:mm:ss');

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

  • YYYY — полный год
  • MM — месяц с ведущим нулём
  • DD — день месяца
  • HH — часы (24-часовой формат)
  • mm — минуты
  • ss — секунды

Отсутствие токена интерпретируется как обычный текст.

Состав пользовательских форматов

Год, месяц, день

Работа с календарными компонентами даты чаще всего строится на следующих токенах:

  • YY — последние две цифры года
  • YYYY — полный год
  • M — номер месяца без нуля
  • MM — номер месяца с нулём
  • MMM — сокращённое название месяца
  • MMMM — полное название месяца
  • D — день месяца
  • DD — день месяца с нулём
  • DDD — день года

Пример:

moment('2026-05-21').format('DD MMMM YYYY');

Результат:

21 May 2026

Время: часы, минуты, секунды

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

  • H — часы (0–23)
  • HH — часы с нулём
  • h — часы (1–12)
  • hh — часы (1–12 с нулём)
  • m — минуты
  • mm — минуты с нулём
  • s — секунды
  • ss — секунды с нулём
  • A — AM/PM в верхнем регистре
  • a — am/pm в нижнем регистре

Пример 12-часового формата:

moment().format('hh:mm:ss A');

Текстовые вставки и экранирование

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

moment().format('[Дата создания:] YYYY-MM-DD');

Результат:

Дата создания: 2026-05-21

Любой текст вне квадратных скобок может быть интерпретирован как токены, поэтому экранирование критично при смешанных форматах.

Пользовательские шаблоны отображения

Комбинированные форматы

Сложные строки формируются через комбинацию токенов и текста:

moment().format('YYYY/MM/DD [время] HH:mm');

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

Форматы для интерфейсов

Часто используются предсобранные шаблоны:

moment().format('DD.MM.YYYY');
moment().format('DD.MM.YYYY HH:mm');
moment().format('YYYY-MM-DDTHH:mm:ss');

Последний вариант соответствует ISO-подобному представлению, но не является строгим ISO 8601, если не использовать toISOString().

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

Форматы тесно связаны с текущей локалью. Некоторые токены зависят от языка:

  • MMMM — полное название месяца
  • dddd — день недели

Пример:

moment().locale('ru').format('dddd, D MMMM YYYY');

Результат:

четверг, 21 мая 2026

Локаль влияет только на текстовые элементы, но не изменяет числовые токены.

Форматы дня недели

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

  • d — номер дня недели (0–6)
  • dd — короткое обозначение
  • ddd — сокращённое название
  • dddd — полное название

Пример:

moment().format('dddd');

Пользовательские числовые представления

Moment.js позволяет контролировать вывод чисел:

  • Do — день месяца с порядковым суффиксом (1st, 2nd, 3rd)
  • Qo — квартал с суффиксом

Пример:

moment().format('Do [day of] MMMM');

Форматы для машинной обработки

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

const payload = {
  createdAt: moment().format('YYYY-MM-DD HH:mm:ss')
};

Однако при обмене данными предпочтительнее использовать ISO:

moment().toISOString();

Строгость интерпретации формата при парсинге

Пользовательские форматы применяются не только при выводе, но и при разборе строки:

moment('21-05-2026', 'DD-MM-YYYY');

При этом формат определяет:

  • порядок элементов
  • допустимые разделители
  • строгую интерпретацию значений

Строгий режим:

moment('21-05-2026', 'DD-MM-YYYY', true);

Третий параметр включает проверку соответствия формату без автоматических исправлений.

Несколько форматов одновременно

Moment.js позволяет передавать массив форматов для повышения гибкости:

moment('21/05/2026', ['DD-MM-YYYY', 'DD/MM/YYYY', 'YYYY-MM-DD']);

Парсинг выполняется последовательно до первого совпадения.

Специальные случаи форматирования

Календарные представления

Хотя это не напрямую format(), поведение часто используется совместно:

  • calendar() отображает относительные форматы
  • может переопределяться пользовательскими шаблонами

Кастомные шаблоны вывода

При построении систем логирования форматы часто стандартизируются:

'[LOG]' YYYY-MM-DD HH:mm:ss '[EVENT]' type

Ограничения пользовательских форматов

  • отсутствие строгой типизации токенов может приводить к неоднозначности
  • часть форматов зависит от локали
  • при сложных сценариях форматирования возникают конфликты между парсингом и отображением
  • некоторые токены устарели в современных практиках работы с датами

Типовые шаблоны, применяемые в системах

// Дата
YYYY-MM-DD

// Дата и время
YYYY-MM-DD HH:mm

// Человекочитаемый формат
DD MMMM YYYY

// Полный таймстамп
YYYY-MM-DD HH:mm:ss.SSS

// URL/ISO-подобный
YYYY-MM-DDTHH:mm:ssZ

Работа с нестандартными строками формата

При создании доменно-ориентированных представлений формат может включать условный текст:

moment().format('[Заказ создан:] DD.MM.YYYY [в] HH:mm');

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

Оглавление