Day.js в React: управление датой и временем

Открытый ноутбук на столе с редактором кода на экране.

Зачем использовать библиотеку для работы с датами

Встроенные объекты Date и методы JavaScript покрывают базовые задачи, но быстро становятся неудобными: код громоздкий, нет удобных формат-строк, неясна работа с часовыми поясами и относительным временем. Day.js предлагает компактный API, совместимый по стилю с Moment.js, но с компактностью и лучшей производительностью. Day.js — иммутабельный: все методы возвращают новые объекты, что упрощает управление состоянием в React.

лог вывода Day.js в консоли

Установка

Установите библиотеку в корне проекта React:

npm install dayjs

Для дополнительных возможностей (относительное время, часовые пояса, локали и т.д.) подключайте соответствующие плагины из подпакета dayjs/plugin.

Парсинг и форматирование: базовый пример

Импортируйте dayjs и используйте метод dayjs() для получения объекта, представляющего текущую дату/время.

import React from 'react'
import dayjs from 'dayjs'

function App() {
  const date = dayjs()
  console.log(date)

  return (
    
      Date and Time Management
    
  )
}

export default App

dayjs() принимает опциональный аргумент: строку, unix-метку (число), объект Date или другой объект Day.js.

Примеры парсинга из строки и Unix-метки:

import React from 'react'
import dayjs from 'dayjs'

function App() {
  const date = dayjs('2023-05-01')
  console.log(date)

  const unixDate = dayjs(1651382400000)
  console.log(unixDate)

  return (
    
      Date and Time Management
    
  )
}

export default App

Чтобы преобразовать Day.js объект в строку, используйте format(). Форматная строка состоит из токенов (дни, месяцы, годы, часы и т.д.).

import React from 'react'
import dayjs from 'dayjs'

function App() {
  const date = dayjs('2023-05-01').format('dddd, MMMM D, YYYY') // Monday, May 1, 2023
  const time = dayjs().format('HH:mm:ss') // 09:50:23
  const unixDate = dayjs(1651382400000).format('MM/DD/YY') // 05/01/22

  return (
    
      {date}
      {unixDate}
      {time}
    
  )
}

export default App

Короткая справка по токенам: dddd — день недели словами; MMMM — месяц словами; D — число месяца; YYYY — год из четырёх цифр; HH/mm/ss — часы/минуты/секунды. Для локализованного вывода используйте плагин локали (см. ниже).

Манипуляции с датами

Day.js предоставляет методы add() и subtract() для математических операций с датами. Они возвращают новые объекты, не изменяя оригинал.

import React from 'react'
import dayjs from 'dayjs'

function App() {
  const date = dayjs().add(7, 'day').format('dddd, MMMM D, YYYY')
  const time = dayjs().subtract(2, 'hour').format('HH:mm:ss')

  return (
    
      {date}
      {time}
    
  )
}

export default App

Замечание: единицы измерения в Day.js используют формы в единственном числе: ‘day’, ‘hour’, ‘month’, ‘year’, ‘minute’, ‘second’.

Относительное время (плагины)

Для фраз типа «2 часа назад» или «через 3 дня» подключите плагин relativeTime.

import React from 'react'
import dayjs from 'dayjs'
import relativeTime from 'dayjs/plugin/relativeTime'

function App() {
  dayjs.extend(relativeTime)

  const date = dayjs().add(7, 'day')
  const relativeDate = date.fromNow() // in 7 days

  const date2 = dayjs().subtract(2, 'hour')
  const relativeDate2 = date2.toNow() // in 2 hours

  const lastYear = dayjs().subtract(1, 'year')
  const diff = date.from(lastYear) // in a year
  const diff2 = date.to(lastYear) // a year ago

  return (
    
      {relativeDate}
      {relativeDate2}
      {diff}
      {diff2}
    
  )
}

export default App

У всех методов fromNow(), toNow(), from(), to() есть необязательный булевый аргумент, который отключает суффикс (“ago” / “in”). Пример: date.fromNow(true) вернёт только “7 days” вместо “in 7 days”.

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

По умолчанию Day.js использует английскую локаль. Для вывода на русском подключите локаль и установите её глобально:

import dayjs from 'dayjs'
import 'dayjs/locale/ru'

dayjs.locale('ru')

Для работы с UTC и часовыми поясами подключайте плагины utc и timezone (timezone зависит от utc). После подключения можно переводить дату в конкретный часовой пояс и форматировать её.

Пример (упрощённый):

import dayjs from 'dayjs'
import utc from 'dayjs/plugin/utc'
import timezone from 'dayjs/plugin/timezone'

dayjs.extend(utc)
dayjs.extend(timezone)

const moscow = dayjs().tz('Europe/Moscow').format()

Учтите, что точное поведение timezone зависит от данных IANA и от того, как вы импортируете/поставляете данные о зонах в окружение (в браузере или на сервере).

Частые плагины

Плагины, которые чаще всего пригодятся в проектах:

relativeTime — относительные формулировки (“2 часа назад”);
utc — работа с UTC;
timezone — перевод между часовыми поясами (зависит от utc);
localizedFormat — дополнительные удобные формат-строки;
customParseFormat — если вам нужно парсить даты из пользовательских форматов;
advancedFormat — дополнительные токены форматирования.

Подключение плагинов происходит через dayjs.extend(…)

Пример: кастомный хук для текущего времени в React

Чтобы отображать текущее время и обновлять его каждую секунду, можно написать хук useNow:

import { useState, useEffect } from 'react'
import dayjs from 'dayjs'

export function useNow(intervalMs = 1000) {
  const [now, setNow] = useState(() => dayjs())

  useEffect(() => {
    const id = setInterval(() => setNow(dayjs()), intervalMs)
    return () => clearInterval(id)
  }, [intervalMs])

  return now
}

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

import React from 'react'
import { useNow } from './useNow'

function Clock() {
  const now = useNow(1000)
  return {now.format('HH:mm:ss')}
}

Тестирование и критерии приёмки

Критерии приёмки для функциональности, связанной с датами:

Форматирование соответствует требованиям (набор тестовых дат + ожидаемые строки).
Парсинг корректно обрабатывает граничные и некорректные входы.
Относительное время показывает ожидаемые значения для ±1, ±24 часов, дней и лет.
Переключение локали даёт корректные названия месяцев и дней недели.
Работа с часовыми поясами корректна для тестовых зон (UTC, Europe/Moscow, America/New_York), включая переходы DST.

Тестовые сценарии (пример):

Парсинг строки “2023-03-26T01:30:00” в Europe/London и проверка, что при переходе на летнее время результат ожидаемый.
Проверка, что add(1, ‘day’) от 23:00 даёт следующую дату с сохранением времени.

Миграция: Moment.js и другие альтернативы

Если проект использовал Moment.js, миграция на Day.js обычно проста, потому что API похожи по стилю. Основные отличия:

Day.js иммутабелен и меньше по размеру;
Некоторые методы Moment могут отсутствовать в Day.js и требовать плагинов;
Пара токенов форматирования и поведений могут немного отличаться — обязательно прогоните набор тестов.

Альтернативы Day.js:

date-fns: модульная и функциональная библиотека с tree-shaking;
Luxon: создан на базе Intl и удобен для работы с часовыми поясами и локалями;
Native Intl API: для простых задач форматирования без дополнительных зависимостей.

Выбор зависит от потребностей: нужен небольшой размер — Day.js; нужны расширенные временные операции и локализация через Intl — Luxon; нужен функциональный API по частям — date-fns.

Когда Day.js может не подойти

Если в проекте активно используются сложные временные расчёты (например, интервалы, длительности с высокой точностью, бизнес-правила календаря), лучше рассмотреть более специализированные решения.
Если требуется полный набор функций Moment (без плагинов) — возможно, проще остаться на Moment или перейти на Luxon.
В средах с ограниченным доступом к данным часовых поясов может потребоваться дополнительная конфигурация.

Рольные чек-листы при внедрении

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

Подключил Day.js и нужные плагины;
Написал юнит-тесты для форматирования/парсинга;
Убедился в иммутабельности операций.

Код-ревьювер:

Проверил все места, где меняется время/дата;
Прогнал тесты для перевода между часовыми поясами;
Убедился в корректной локализации.

Продакт/менеджер:

Подтвердил список форматов и требования к локалям;
Утвердил поведение при DST и отображение относительного времени.

Глоссарий (в одну строку)

Day.js — компактная JS-библиотека для работы с датами; Unix timestamp — количество миллисекунд/секунд с 1970-01-01; UTC — координированное всемирное время; локаль — правила отображения дат и времени для языка/региона.

Итог

Day.js — удобный инструмент для React-приложений, где важны компактность, простота API и скорость. Подключив нужные плагины, вы получите мощный набор инструментов: локализация, работа с часовыми поясами, относительное время и кастомный парсинг. Протестируйте критичные сценарии (DST, парсинг, форматы), используйте хуки для обновляемых представлений времени и следуйте чек-листам при внедрении.

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