Метод toFormat

Метод toFormat в библиотеке Luxon используется для преобразования объектов даты и времени в строковое представление по заданному шаблону. Он является одним из основных инструментов форматирования и предоставляет гибкий механизм управления выводом дат без необходимости ручной сборки строк.

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

Базовый синтаксис

Метод вызывается у экземпляра DateTime:

DateTime.toFormat(formatString)

formatString представляет собой строку, содержащую набор токенов Luxon.

Пример:

import { DateTime } from "luxon";

const dt = DateTime.local(2026, 1, 15, 10, 30);

const result = dt.toFormat("dd-MM-yyyy");
console.log(result); // 15-01-2026

Каждый токен в строке форматирования заменяется на соответствующее значение даты.

Система токенов форматирования

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

Год

  • y — год без ведущих нулей
  • yy — последние две цифры года
  • yyyy — полный год

Пример:

dt.toFormat("yyyy"); // 2026
dt.toFormat("yy");   // 26

Месяц

  • M — номер месяца (1–12)
  • MM — месяц с ведущим нулём
  • MMM — краткое название месяца
  • MMMM — полное название месяца
dt.toFormat("MM");   // 01
dt.toFormat("MMMM"); // January

День месяца

  • d — день без нуля
  • dd — день с нулём
dt.toFormat("d");  // 15
dt.toFormat("dd"); // 15

Часы

Luxon поддерживает 24-часовой и 12-часовой формат.

  • H — 24-часовой формат без нуля
  • HH — 24-часовой с нулём
  • h — 12-часовой без нуля
  • hh — 12-часовой с нулём
dt.toFormat("HH:mm"); // 10:30
dt.toFormat("hh:mm"); // 10:30 (12h формат)

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

  • m — минуты
  • mm — минуты с нулём
  • s — секунды
  • ss — секунды с нулём
dt.toFormat("HH:mm:ss"); // 10:30:00

Составные форматы

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

dt.toFormat("dd/MM/yyyy HH:mm"); 
// 15/01/2026 10:30
dt.toFormat("MMMM dd, yyyy");
// January 15, 2026

Локализация вывода

Метод toFormat не выполняет автоматическую локализацию в стиле toLocaleString, но поддерживает локализованные названия месяцев и дней недели при корректно заданной локали в объекте DateTime.

const dt = DateTime.local(2026, 1, 15).setLocale("ru");

dt.toFormat("MMMM");
// январь

Локаль влияет на текстовые токены (MMMM, EEE и подобные), но не изменяет структуру числовых форматов.

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

Поддерживаются следующие токены:

  • E — день недели (1–7)
  • EEE — краткое название дня
  • EEEE — полное название дня
dt.toFormat("EEEE");
// Thursday (или "четверг" при ru-локали)

Преформатированные шаблоны

Сложные шаблоны часто включают текстовые вставки. В Luxon текст фиксируется в одинарных кавычках.

dt.toFormat("dd 'of' MMMM yyyy");
// 15 of January 2026

Любой текст вне токенов остаётся неизменным.

Экранирование и спецсимволы

Если необходимо использовать символы, совпадающие с токенами, они заключаются в кавычки.

dt.toFormat("HH 'hours' mm 'minutes'");
// 10 hours 30 minutes

Без экранирования Luxon может интерпретировать символы как токены.

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

  • S — миллисекунды
  • SSS — миллисекунды с фиксированной длиной
const dt = DateTime.local(2026, 1, 15, 10, 30, 0, 123);

dt.toFormat("HH:mm:ss.SSS");
// 10:30:00.123

Практика составления шаблонов

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

Пример логов

dt.toFormat("yyyy-MM-dd HH:mm:ss");
// 2026-01-15 10:30:00

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

Пример пользовательского интерфейса

dt.toFormat("dd MMMM yyyy");
// 15 January 2026

При смене локали меняется только текстовая часть:

dt.setLocale("ru").toFormat("dd MMMM yyyy");
// 15 января 2026

Пример краткого отображения

dt.toFormat("dd/MM HH:mm");
// 15/01 10:30

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

Особенности поведения метода

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

Также отсутствует автоматическое добавление разделителей — все символы должны быть явно указаны в формате.

Совместимость с другими методами Luxon

toFormat часто используется вместе с другими методами DateTime:

  • setLocale — управление языком вывода
  • setZone — управление часовым поясом
  • plus и minus — изменение даты перед форматированием
dt.plus({ days: 3 }).toFormat("yyyy-MM-dd");

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

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

В системах, где требуется единообразие отображения, шаблоны toFormat выносятся в константы:

const FORMAT_FULL = "yyyy-MM-dd HH:mm:ss";
const FORMAT_SHORT = "dd/MM/yyyy";

dt.toFormat(FORMAT_FULL);

Это снижает вероятность ошибок и упрощает поддержку кода.

Использование в многокомпонентных приложениях

В прикладной разработке форматирование через toFormat применяется в:

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

Единый формат обеспечивает согласованность представления времени во всех слоях приложения.

Оглавление