Функция format и её синтаксис

Синтаксис функции format в date-fns представляет собой один из базовых механизмов преобразования объектов Date в человекочитаемые строки. В отличие от нативных методов JavaScript, этот подход использует строгую систему токенов, позволяющую точно управлять отображением даты и времени.

Функция имеет следующий общий вид:

format(date, formatString, [options])

Параметры

date Объект типа Date, который необходимо преобразовать. Допустимы также значения, приводимые к дате через конструктор Date.

formatString Строка шаблона, содержащая токены форматирования. Именно она определяет итоговый вид результата.

options (необязательный параметр) Объект конфигурации, включающий:

  • locale — локализация (для вывода месяцев, дней недели и т.д.)
  • дополнительные настройки, влияющие на поведение форматирования

Шаблон формата и токены

В основе работы format лежит система токенов — специальных символов, которые заменяются на соответствующие части даты.

Например:

format(new Date(2026, 0, 15), 'yyyy-MM-dd')

Результат:

2026-01-15

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

Основные принципы токенизации

  • y — год
  • M — месяц
  • d — день месяца
  • H — часы (24-часовой формат)
  • h — часы (12-часовой формат)
  • m — минуты
  • s — секунды
  • S — миллисекунды

Комбинирование токенов позволяет формировать практически любой формат отображения даты.

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

Год

Наиболее часто используемые варианты:

  • yy — две последние цифры года
  • yyyy — полный год

Примеры:

format(date, 'yy')    // 26
format(date, 'yyyy')  // 2026

Месяц

Месяцы имеют несколько форматов отображения:

  • M — номер месяца без ведущего нуля
  • MM — номер месяца с ведущим нулём
  • MMM — сокращённое название месяца
  • MMMM — полное название месяца

Пример:

format(date, 'MMMM yyyy')

Результат (в английской локали):

January 2026

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

День месяца

  • d — день без ведущего нуля
  • dd — день с ведущим нулём
format(date, 'dd.MM.yyyy')

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

Часы

Date-fns различает два формата часов:

  • H / HH — 24-часовой формат
  • h / hh — 12-часовой формат
format(date, 'HH:mm')  // 14:30
format(date, 'hh:mm a') // 02:30 pm

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

  • m / mm — минуты
  • s / ss — секунды
  • S, SS, SSS — миллисекунды

Пример:

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

Результат:

14:30:15.123

Индикатор времени суток

Токен a используется для обозначения периода суток:

  • am
  • pm
format(date, 'hh:mm a')

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

Локализация

Функция format поддерживает локализацию через объект locale.

Пример использования:

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

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

Результат:

15 января 2026

Локализация влияет на:

  • названия месяцев
  • дни недели
  • формат вывода некоторых текстовых токенов

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

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

Пример:

format(date, "yyyy 'год'")

Результат:

2026 год

Если внутри текста требуется использовать апостроф, он экранируется удвоением:

format(date, "yyyy 'don''t'")

Результат:

2026 don't

Работа с днями недели

Date-fns предоставляет токены для отображения дня недели:

  • E — сокращённое название дня
  • EEEE — полное название дня

Пример:

format(date, 'EEEE')

Результат (английская локаль):

Thursday

При использовании локали:

четверг

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

Функция format по умолчанию работает в локальном часовом поясе среды выполнения JavaScript. Это означает:

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

Например, один и тот же объект Date может давать разные визуальные результаты на устройствах с разными часовыми поясами.

Для работы с фиксированными временными зонами используется дополнительный инструментарий, расширяющий базовые возможности форматирования, однако сам format остаётся локально-ориентированным.

Типовые комбинации форматов

ISO-подобный формат

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

Полный datetime

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

Человекочитаемый формат

format(date, 'd MMMM yyyy, HH:mm')

Логирование времени

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

Сложные шаблоны

Комбинация токенов позволяет создавать гибкие представления:

format(date, "EEEE, d MMMM yyyy 'в' HH:mm")

Результат:

четверг, 15 января 2026 в 14:30

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

Типичные ошибки при использовании format

Ошибка с регистром токенов

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

  • MM — месяц
  • mm — минуты

Ошибка:

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

Результат будет содержать минуты вместо месяца.

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

Отсутствие кавычек приводит к интерпретации текста как токенов:

format(date, yyyy год)

Такой вызов некорректен.

Использование несуществующих токенов

Любой неподдерживаемый символ может быть проигнорирован или привести к неожиданному выводу.

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

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

  • Invalid Date
  • исключение в зависимости от контекста использования

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

Производительность и предсказуемость

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

  • создание множества объектов Date
  • повторное использование одинаковых шаблонов
  • влияние локализации на производительность

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

Оглавление