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

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

Функция форматирования работает на основе сопоставления символов шаблона с компонентами объекта Date. Каждый токен определяет, как именно будет отображаться часть даты: год, месяц, день, часы, минуты, секунды и дополнительные элементы локали.

Основная функция:

format(date, formatString, options)
  • date — объект Date
  • formatString — строка шаблона
  • options — дополнительные параметры (локаль, настройки недели и т.д.)

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

Базовые токены формата

Система токенов в date-fns строго определена. Каждый токен имеет смысл и поведение:

  • yyyy — полный год (2026)
  • yy — сокращённый год (26)
  • MM — месяц с ведущим нулём (01–12)
  • M — месяц без ведущего нуля (1–12)
  • dd — день месяца (01–31)
  • d — день месяца (1–31)
  • HH — часы в 24-часовом формате
  • mm — минуты
  • ss — секунды

Комбинация токенов формирует итоговый формат:

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

Результат:

2026-01-05

Формирование пользовательских шаблонов

Гибкость системы заключается в возможности комбинировать токены с любыми символами-разделителями:

format(date, 'dd/MM/yyyy HH:mm')
format(date, 'yyyy год, MMMM d')

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

Экранирование текстовых значений

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

format(date, "yyyy 'year' MM 'month'")

Без экранирования часть текста может быть интерпретирована как токены, что приведёт к искажению результата.

Особенности:

  • текст внутри '...' не анализируется как токены
  • одиночные кавычки внутри строки требуют удвоения

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

Система форматирования тесно связана с локалями. Локаль определяет:

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

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

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

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

Результат:

5 января 2026

Локали также влияют на расширенные токены:

  • MMM — сокращённое название месяца
  • MMMM — полное название месяца
  • eee — сокращённый день недели
  • eeee — полный день недели

Расширенные токены времени

Помимо базовых единиц времени, поддерживаются более тонкие элементы:

  • a — AM/PM
  • h — часы в 12-часовом формате
  • hh — часы с ведущим нулём в 12-часовом формате
  • SSS — миллисекунды

Пример:

format(date, 'hh:mm:ss.SSS a')

Результат:

03:25:10.123 PM

Работа с порядковыми числами

Некоторые локали поддерживают форматирование порядковых чисел:

  • do — день месяца с суффиксом (1st, 2nd, 3rd)
format(date, 'do MMMM')

В зависимости от локали результат может изменяться:

5th January

или

5 января

Контроль недели и календарных систем

Форматы могут учитывать особенности календаря:

  • начало недели (понедельник или воскресенье)
  • номер недели года
  • ISO-нумерация

Токены:

  • I — ISO-неделя года
  • R — ISO-день недели

Пример:

format(date, 'RRRR-I')

Форматирование без локали

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

  • названия месяцев
  • дни недели
  • AM/PM обозначения
format(date, 'MMMM d, yyyy')
January 5, 2026

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

Построение сложных шаблонов часто включает несколько уровней информации:

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

Такие конструкции объединяют:

  • день недели
  • дату
  • месяц
  • время

Результат становится человекочитаемым представлением полной временной метки.

Ошибки интерпретации токенов

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

  • M — месяц, но также может конфликтовать с текстом
  • d — день, но при некорректной строке интерпретируется как часть текста
  • повторяющиеся символы усиливают точность (например, M vs MM)

Корректность шаблона зависит от строгого соблюдения синтаксиса токенов.

Принцип неизменяемости формата

Форматирование не изменяет объект Date. Все операции являются чистыми:

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

Это позволяет использовать функцию в функциональных и реактивных архитектурах без побочных эффектов.

Композиция форматов в прикладных задачах

В прикладной разработке часто используется генерация шаблонов:

  • форматы для API
  • форматы для UI
  • форматы для логирования

Пример:

const apiFormat = 'yyyy-MM-dd'
const logFormat = 'yyyy-MM-dd HH:mm:ss'
const uiFormat = 'd MMMM yyyy'

Такая сегрегация позволяет отделять представление данных от бизнес-логики и централизованно управлять отображением дат.

Оглавление