Moment.js в React — форматирование, парсинг и манипуляции

Часы, символизирующие дату и время

Краткое введение

Moment.js — библиотека для работы с датами и временем в JavaScript. Она упрощает форматирование, парсинг, арифметику с датами и вывод относительного времени. В React её удобно использовать в компонентах для отображения человеко-читаемых дат или при преобразовании времени, полученного с сервера.

Важно: Moment.js официально находится в режиме поддержания (maintenance). Это значит, что для новых проекторов стоит рассмотреть альтернативы, особенно если важен размер бандла и модульность.

Установка

Установите пакет через npm или yarn и импортируйте его в компонент.

Пример установки:

npm install moment

Пример базового импорта в React:

import React from 'react'
import moment from 'moment'

function App() {
  const date = moment().format('MMMM DD YYYY')
  const time = moment().format('HH mm ss')

  return (
    
      Сегодня: {date}
      Время: {time}
    
  )
}

export default App

Отображение дат и времени — основные приёмы

moment() — создаёт объект moment для текущего времени (с учётом локальной часовой зоны).
format(string) — преобразует момент в строку по указанному шаблону.
moment.utc() — создаёт объект в UTC.
moment.tz(… ) — требуется moment-timezone для работы с конкретными часовыми поясами.

Пример вывода текущей даты/времени с форматированием:

const date = moment().format('MMMM DD YYYY') // e.g. "June 23 2025"
const time = moment().format('HH:mm:ss')     // e.g. "14:05:09"

Шаблоны форматирования — шпаргалка

YYYY — год из четырёх цифр (2025)
YY — год из двух цифр (25)
MMMM — полное название месяца (June / Июнь при локали)
MM — месяц двумя цифрами (06)
M — месяц без ведущего нуля (6)
DD — день месяца двумя цифрами (09)
D — день месяца без ведущего нуля (9)
Do — порядковый день (1st, 2nd — зависит от локали)
HH — часы 24-ч формат двумя цифрами (08, 14)
H — часы без ведущего нуля
mm — минуты двумя цифрами
ss — секунды двумя цифрами

Пример с русской локалью (нужно подключить локаль):

import 'moment/locale/ru'
moment.locale('ru')
console.log(moment().format('Do MMMM YYYY')) // "23 июня 2025 г." (пример)

Манипуляции: add, subtract, set, get

Moment предоставляет удобные методы для арифметики:

add(value, unit) — добавить (например, add(1, ‘day’))
subtract(value, unit) — вычесть время
set(unit, value) — установить конкретную единицу времени
get(unit) — получить значение единицы времени

Пример:

function App() {
  const tomorrow = moment().add(1, 'day').format('Do MMMM, YYYY')
  const oneHourAgo = moment().subtract(1, 'hour').format('HH:mm:ss')
  // При set('month', 1) месяц устанавливается как индекс 1 => февраль
  const lastYear = moment().set('year', 2022).set('month', 1).format('Do MMMM, YYYY')
  const hour = moment().get('hour')

  return (
    
      Завтра: {tomorrow}
      Час назад: {oneHourAgo}
      {lastYear}
      Текущий час: {hour}
    
  )
}

Примечание: при установке месяца числом в методе set месяц нумеруется с 0 (0 — январь, 1 — февраль).

Парсинг строк в даты

Moment умеет парсить строки с указанием формата. Это полезно при приёме данных от API или пользовательского ввода.

const m = moment('1998-06-23', 'YYYY-MM-DD')
console.log(m.toDate()) // вернёт native Date

// Пример более сложного парсинга
const parsed = moment('29-20-130000', 'Do-MMMM-YYYY')
console.log(parsed.toDate())

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

Относительное время

fromNow() — сколько времени прошло с момента (“7 дней назад”)
toNow() — сколько времени до момента относительно сейчас (“через 7 дней”)

const yesterday = moment().subtract(7, 'day')
console.log(yesterday.fromNow()) // "7 дней назад" (при локали ru)
console.log(yesterday.toNow())   // "через 7 дней"

Локали и часовые пояса

Локаль: подключайте ‘moment/locale/ru’ и вызывайте moment.locale(‘ru’) для русских имён месяцев и форм.
Часовые пояса: используйте момент с расширением moment-timezone, если нужно работать с зонами вроде ‘Europe/Moscow’.

Пример UTC и timezone:

const utc = moment.utc()
const moscow = moment.tz('2025-06-23 12:00', 'Europe/Moscow')

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

Important: Moment.js работает хорошо и удобно, но имеет ограничения:

Большой размер бандла по сравнению с модульными альтернативами.
Момент — mutable (изменяемые объекты), что может привести к ошибкам, если не аккуратно клонировать объекты.
Библиотека в режиме поддержки — новые фичи не добавляются.

Когда не использовать: если важен размер билда, частое манипулирование датами в клиенте или нужен современный API — лучше смотреть в сторону date-fns, Luxon или стандарта Temporal.

Альтернативы и миграция — краткое руководство

date-fns: модульная, функциональная, меньший размер, функции импортируются по одной.
Luxon: создавалась авторами Moment (вдохновлённая им), поддерживает immutability и часовые пояса через Intl API.
Temporal (проект TC39): современный стандарт для работы с датами и временем (пока в стадии внедрения, есть полифиллы).

Миграция — советы:

Определите кейсы: форматирование, парсинг, зоны, relative time.
Найдите парные функции: moment.format() -> date-fns/format, moment.add() -> date-fns/add, moment.tz() -> Luxon/DateTime.fromObject(…).
Пишите обёртки в утилитах проекта, чтобы снижать количество мест замены.

Пример соответствия (ориентир):

moment().format(‘YYYY-MM-DD’) -> date-fns: format(new Date(), ‘yyyy-MM-dd’)
moment().add(1, ‘day’) -> date-fns: addDays(new Date(), 1)

Простая модель принятия решения (диаграмма)

flowchart TD
  A[Новый проект?] -->|Да| B{Нужна поддержка таймзон?}
  A -->|Нет, проект с Moment| C[Оставьте Moment и добавьте тесты]
  B -->|Да| D[Рассмотрите Luxon или Temporal]
  B -->|Нет| E[Рассмотрите date-fns для маленького бандла]
  D --> F[Если нужен Intl — Luxon]
  E --> F2[Если функциональный стиль — date-fns]

Роль-базированные чек-листы

Разработчик:

Установил moment и локаль при необходимости.
Проверил работу с часовыми поясами.
Написал unit-тесты для ключевых преобразований.

QA:

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

Продукт/PO:

Подтвердил требуемый формат отображения дат.
Уточнил политику хранения времени (UTC vs локальное).

Критерии приёмки

Даты отображаются в требуемом формате и локали.
Временные вычисления корректны при смене локали и часовой зоны.
API возвращает унифицированные временные метки (рекомендуется ISO 8601 или Unix timestamp).
Наличие unit-тестов для ключевых сценариев (парсинг, add/subtract, форматирование).

Советы по безопасности и хранению

Храните все временные метки на сервере в UTC.
Выполняйте локализацию и форматирование на клиенте, если нужно показать локальное время пользователю.
Если вы храните PII вместе с временными метками, следите за политикой хранения данных и сроками давности (GDPR/локальные требования).

Техническая шпаргалка (cheat sheet)

Создать текущее время: moment()
Создать UTC: moment.utc()
Парсинг: moment(‘2025-06-23’, ‘YYYY-MM-DD’)
Формат: m.format(‘Do MMMM YYYY’)
Добавить: m.add(7, ‘days’)
Вычесть: m.subtract(1, ‘hour’)
Временная зона: moment.tz(…)

Частые ошибки и как их избегать

Ошибка: изменение одного и того же объекта moment (mutable). Решение: перед изменением клонируйте moment(), например moment().clone().add(…).
Ошибка: полагаться на “угадывание” формата при парсинге. Решение: всегда указывайте формат при парсинге входных строк.
Ошибка: не учитывать локаль и timezone. Решение: явно задавайте локаль и используйте moment-timezone, если нужно.

Примеры приёма/тест-кейсы

Парсинг ISO-строки должен вернуть корректную дату и час в UTC.
Добавление дня в 23:00 в зоне с переходом на летнее/зимнее время должно давать ожидаемый результат (покрыть тестом).
Форматирование в русской локали должно выдавать русские названия месяцев.

Заключение

Moment.js — быстрый путь к работе с датами и временем в React. Он прост и понятен, но в новых проектах стоит оценить альтернативы из-за размера бандла и статуса библиотеки. Если вы продолжаете использовать Moment.js, следуйте правилам: храните отметки времени в UTC, явно указывайте форматы при парсинге, подключайте локали и покрывайте изменения времени тестами.

Краткое резюме:

Установите moment и при необходимости moment-timezone.
Используйте format/parse/add/subtract/set/get для основного функционала.
Рассмотрите миграцию на date-fns или Luxon для новых проектов.