Работа с формами

Библиотека date-fns предоставляет набор функций для форматирования и преобразования дат без изменения исходного объекта Date. Все операции строятся вокруг чистых функций и модульной архитектуры.

Главная функция форматирования:

import { format } from 'date-fns'

const date = new Date(2026, 4, 22)

console.log(format(date, 'dd.MM.yyyy'))
// 22.05.2026

Функция format() принимает:

объект Date;
строку шаблона.

Форматирующие токены

День месяца

Токен	Описание	Пример
`d`	день без ведущего нуля	`5`
`dd`	день с ведущим нулём	`05`

format(new Date(2026, 4, 5), 'd')
format(new Date(2026, 4, 5), 'dd')

Месяц

Токен	Описание	Пример
`M`	месяц без нуля	`5`
`MM`	месяц с нулём	`05`
`MMM`	краткое название	`May`
`MMMM`	полное название	`May`

format(date, 'MM')
format(date, 'MMMM')

Год

Токен	Описание	Пример
`yy`	короткий год	`26`
`yyyy`	полный год	`2026`

format(date, 'yyyy')

Время

Токен	Описание
`H`	часы 0–23
`HH`	часы с нулём
`m`	минуты
`mm`	минуты с нулём
`s`	секунды
`ss`	секунды с нулём

format(new Date(), 'HH:mm:ss')

Комбинирование шаблонов

Формы дат формируются путём объединения токенов.

format(date, 'dd.MM.yyyy')
format(date, 'yyyy-MM-dd')
format(date, 'dd MMMM yyyy')

Результат:

22.05.2026
2026-05-22
22 May 2026

Экранирование текста

Любой текст внутри одинарных кавычек считается литералом.

format(date, "dd.MM.yyyy 'год'")

Результат:

22.05.2026 год

Локализация форм

Подключение локали

import { format } from 'date-fns'
import { ru } from 'date-fns/locale'

const date = new Date()

console.log(
  format(date, 'd MMMM yyyy', {
    locale: ru
  })
)

Результат:

22 мая 2026

Различие между `MM` и `mm`

Одна из самых распространённых ошибок — путаница между месяцами и минутами.

Токен	Значение
`MM`	месяц
`mm`	минуты

Неправильно:

format(date, 'HH:MM')

Правильно:

format(date, 'HH:mm')

Формирование ISO-строк

Формат ISO

format(date, "yyyy-MM-dd'T'HH:mm:ss")

Пример:

2026-05-22T14:30:00

Формирование человекочитаемых дат

Короткая форма

format(date, 'dd.MM.yyyy')

Результат:

22.05.2026

Полная форма

format(date, 'EEEE, d MMMM yyyy')

Результат:

Friday, 22 May 2026

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

Только часы и минуты

format(date, 'HH:mm')

Время с секундами

format(date, 'HH:mm:ss')

12-часовой формат

Токен	Описание
`h`	часы 1–12
`hh`	часы с нулём
`a`	AM/PM

format(date, 'hh:mm a')

Результат:

02:30 PM

Работа с Unix Timestamp

Форматирование timestamp

const timestamp = 1747900000000

format(new Date(timestamp), 'dd.MM.yyyy')

Форматирование текущей даты

const now = new Date()

format(now, 'dd.MM.yyyy HH:mm')

Относительные формы дат

Библиотека поддерживает представление времени в виде относительных выражений.

`formatDistance`

import { formatDistance } from 'date-fns'

const result = formatDistance(
  new Date(2026, 4, 1),
  new Date(2026, 4, 10)
)

console.log(result)

Результат:

9 days

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

import { ru } from 'date-fns/locale'

formatDistance(
  new Date(2026, 4, 1),
  new Date(2026, 4, 10),
  {
    locale: ru
  }
)

Результат:

9 дней

`formatDistanceToNow`

Функция показывает расстояние до текущего момента.

import { formatDistanceToNow } from 'date-fns'

formatDistanceToNow(
  new Date(2026, 4, 20)
)

Результат:

2 days

Добавление суффиксов

formatDistanceToNow(date, {
  addSuffix: true
})

Результат:

in 5 days

или:

5 days ago

`formatRelative`

Функция отображает дату относительно текущего дня.

import { formatRelative } from 'date-fns'

formatRelative(
  new Date(2026, 4, 22),
  new Date(2026, 4, 20)
)

Результат:

Friday at 12:00 AM

Международные стандарты

RFC 3339

import { formatRFC3339 } from 'date-fns'

formatRFC3339(new Date())

ISO 8601

import { formatISO } from 'date-fns'

formatISO(new Date())

ISO с указанием представления

formatISO(new Date(), {
  representation: 'date'
})

Результат:

2026-05-22

Длинные предустановленные формы

`P` и `PPPP`

Date-fns поддерживает локализованные шаблоны.

Токен	Формат
`P`	короткий
`PP`	средний
`PPP`	длинный
`PPPP`	полный

format(date, 'P')
format(date, 'PPPP')

Формы времени

Токен	Формат
`p`	короткое время
`pp`	среднее
`ppp`	длинное
`pppp`	полное

format(date, 'pp')

Совмещение шаблонов даты и времени

format(date, 'PPpp')

Форматирование с часовыми поясами

Базовая библиотека Date-fns не управляет часовыми поясами напрямую. Для этого используется пакет:

npm install date-fns-tz

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

import { formatInTimeZone } from 'date-fns-tz'

formatInTimeZone(
  new Date(),
  'Europe/Moscow',
  'dd.MM.yyyy HH:mm:ss'
)

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

Формирование даты для input[type=“date”]

format(date, 'yyyy-MM-dd')

Формирование времени для input[type=“time”]

format(date, 'HH:mm')

Формирование имени файла

format(new Date(), 'yyyyMMdd_HHmmss')

Результат:

20260522_143015

Формы для журналов и логов

format(
  new Date(),
  'yyyy-MM-dd HH:mm:ss.SSS'
)

Миллисекунды

Токен	Значение
`S`	миллисекунды
`SS`	две цифры
`SSS`	три цифры

format(date, 'HH:mm:ss.SSS')

День недели

Токен	Описание
`E`	краткий день
`EEEE`	полный день

format(date, 'EEEE')

День года

Токен	Значение
`D`	день года
`DD`	день года с нулём

format(date, 'D')

Номер недели

format(date, 'w')

Кварталы

Токен	Значение
`Q`	номер квартала
`QQQQ`	текстовый квартал

format(date, 'QQQQ')

Безопасное форматирование

Перед форматированием необходимо проверять корректность даты.

import { isValid } from 'date-fns'

const date = new Date('invalid')

if (isValid(date)) {
  console.log(format(date, 'dd.MM.yyyy'))
}

Ошибки форматирования

Неправильные токены

format(date, 'YYYY')

В Date-fns используется:

format(date, 'yyyy')

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

Неправильно:

format('2026-05-22', 'dd.MM.yyyy')

Правильно:

format(new Date('2026-05-22'), 'dd.MM.yyyy')

Производительность

Date-fns импортирует только используемые функции.

import { format } from 'date-fns'

Такой подход уменьшает размер итогового bundle.

Практические шаблоны

Карточка пользователя

format(user.createdAt, 'dd.MM.yyyy')

Новостная лента

formatDistanceToNow(post.createdAt, {
  addSuffix: true
})

API-ответы

format(date, "yyyy-MM-dd'T'HH:mm:ssXXX")

Календари

format(date, 'EEEE, d MMMM')

Часто используемые комбинации

Назначение	Формат
Российская дата	`dd.MM.yyyy`
Международная дата	`yyyy-MM-dd`
Время	`HH:mm:ss`
ISO	`yyyy-MM-dd'T'HH:mm:ss`
Дата и время	`dd.MM.yyyy HH:mm`
Имя файла	`yyyyMMdd_HHmmss`

Сравнение с `Intl.DateTimeFormat`

Date-fns

format(date, 'dd.MM.yyyy')

Intl

new Intl.DateTimeFormat('ru-RU')
  .format(date)

Date-fns предоставляет:

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

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

Универсальная функция

import { format } from 'date-fns'

export function formatDate(date) {
  return format(date, 'dd.MM.yyyy')
}

Форматирование с проверкой

import { format, isValid } from 'date-fns'

export function safeFormat(date) {
  if (!isValid(date)) {
    return ''
  }

  return format(date, 'dd.MM.yyyy')
}

Работа с формами

Форматирующие токены

День месяца

Месяц

Год

Время

Комбинирование шаблонов

Экранирование текста

Локализация форм

Подключение локали

Различие между MM и mm

Формирование ISO-строк

Формат ISO

Формирование человекочитаемых дат

Короткая форма

Полная форма

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

Только часы и минуты

Время с секундами

12-часовой формат

Работа с Unix Timestamp

Форматирование timestamp

Форматирование текущей даты

Относительные формы дат

formatDistance

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

formatDistanceToNow

Добавление суффиксов

formatRelative

Международные стандарты

RFC 3339

ISO 8601

ISO с указанием представления

Длинные предустановленные формы

P и PPPP

Формы времени

Совмещение шаблонов даты и времени

Форматирование с часовыми поясами

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

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

Формирование даты для input[type=“date”]

Формирование времени для input[type=“time”]

Формирование имени файла

Формы для журналов и логов

Миллисекунды

День недели

День года

Номер недели

Кварталы

Безопасное форматирование

Ошибки форматирования

Неправильные токены

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

Производительность

Практические шаблоны

Карточка пользователя

Новостная лента

API-ответы

Календари

Часто используемые комбинации

Сравнение с Intl.DateTimeFormat

Date-fns

Intl

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

Универсальная функция

Форматирование с проверкой

Различие между `MM` и `mm`

`formatDistance`

`formatDistanceToNow`

`formatRelative`

`P` и `PPPP`

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

Сравнение с `Intl.DateTimeFormat`