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

В библиотеке Luxon объект DateTime предоставляет несколько уровней форматирования: от предустановленных шаблонов до полностью кастомных строк. Основной метод для гибкого форматирования — toFormat, основанный на токенах, аналогичных ICU-подобной нотации.

import { DateTime } from "luxon";

const dt = DateTime.local(2026, 1, 24, 18, 45);

dt.toFormat("yyyy LLL dd, HH:mm");

Результат зависит от локали и настроек, но при стандартной английской локали будет выглядеть как:

2026 Jan 24, 18:45

Каждый символ в строке формата интерпретируется как токен, если он не экранирован.

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

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

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

  • yyyy — полный год (2026)
  • yy — две последние цифры года (26)
  • LLLL — полное название месяца (January)
  • LLL — сокращённое название месяца (Jan)
  • MM — месяц числом с ведущим нулём (01–12)
  • dd — день месяца с ведущим нулём (01–31)
dt.toFormat("dd.LL.yyyy");

Время

  • HH — часы в 24-часовом формате
  • hh — часы в 12-часовом формате
  • mm — минуты
  • ss — секунды
  • a — AM/PM
dt.toFormat("hh:mm:ss a");

День недели

  • cccc — полное название дня недели
  • ccc — сокращённое название дня недели
  • c — числовой индекс дня недели
dt.toFormat("cccc");

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

Любые символы, не являющиеся токенами, могут интерпретироваться как форматные элементы. Для вывода текста используется экранирование с помощью одинарных кавычек.

dt.toFormat("yyyy 'year' LLL dd");

Результат:

2026 year Jan 24

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

dt.toFormat("yyyy 'it''s' LLL");

Предустановленные форматы

Luxon содержит набор стандартных форматов, доступных через toLocaleString. Они основаны на локалях и упрощают работу без ручного задания токенов.

dt.toLocaleString(DateTime.DATE_FULL);

Основные константы

  • DateTime.DATE_SHORT — краткая дата
  • DateTime.DATE_MED — средний формат даты
  • DateTime.DATE_FULL — полная дата
  • DateTime.DATE_HUGE — расширенный формат с названием дня недели

Для времени:

  • DateTime.TIME_SIMPLE — часы и минуты
  • DateTime.TIME_WITH_SECONDS — с секундами

Для комбинации:

  • DateTime.DATETIME_SHORT
  • DateTime.DATETIME_MED
  • DateTime.DATETIME_FULL
dt.toLocaleString(DateTime.DATETIME_MED);

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

Форматирование зависит от локали, установленной в объекте DateTime.

const dtRu = DateTime.local().setLocale("ru");

dtRu.toFormat("cccc, dd LLLL yyyy");

В русской локали названия месяцев и дней недели будут автоматически локализованы.

Форматирование через Intl API

Luxon позволяет использовать стандартный Intl.DateTimeFormat через toLocaleString с кастомными параметрами.

dt.toLocaleString({
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "2-digit"
});

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

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

Форматирование всегда учитывает текущую временную зону объекта DateTime.

const ny = dt.setZone("America/New_York");

ny.toFormat("yyyy-LL-dd HH:mm ZZZZ");

Дополнительные токены для зон:

  • z — короткое название зоны
  • ZZZZ — полное название зоны
  • Z — смещение (например, +03:00)

Форматирование ISO и стандартизированных строк

Luxon поддерживает вывод в ISO 8601 без использования токенов:

dt.toISO();

Варианты:

  • toISODate() — только дата
  • toISOTime() — только время
  • toISOWeekDate() — неделя ISO
dt.toISODate();

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

Для работы с timestamp используется преобразование к числу:

dt.toMillis();
dt.toSeconds();

Форматирование как строки выполняется вручную:

new DateTime.fromMillis(1700000000000).toFormat("yyyy-LL-dd");

Пользовательские шаблоны и повторное использование

Часто используемые форматы можно выносить в константы:

const FORMAT = "yyyy-LL-dd HH:mm:ss";

dt.toFormat(FORMAT);

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

Форматирование дробных значений времени

Luxon позволяет отображать миллисекунды:

  • S — десятые доли секунды
  • SS — сотые
  • SSS — миллисекунды
dt.toFormat("HH:mm:ss.SSS");

Управление паддингом и шириной вывода

Некоторые токены поддерживают вариации длины:

  • M / MM — месяц без/с ведущим нулём
  • d / dd — день без/с ведущим нулём
  • H / HH — часы 24h
DateTime.local(2026, 4, 5).toFormat("d.M.yyyy");

Комбинирование локали и кастомных форматов

Локализация влияет только на текстовые элементы (месяцы, дни недели), но не на числовые токены.

DateTime.local()
  .setLocale("fr")
  .toFormat("cccc dd LLLL yyyy");

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

Форматирование относительных элементов через DateTime

Хотя относительные строки относятся к Duration, их часто комбинируют с форматированием DateTime.

dt.toRelative();
dt.toRelativeCalendar();

Эти методы не используют toFormat, но участвуют в общей системе представления даты.

Особенности и ограничения токенов

Некоторые символы имеют конфликтующее поведение:

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

Ошибки в токенах приводят к их буквальному выводу без преобразования.

dt.toFormat("YYYY-MM-DD"); // может дать неожиданный результат

Правильный вариант:

dt.toFormat("yyyy-LL-dd");

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

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

Логирование

"yyyy-LL-dd HH:mm:ss.SSS"

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

"cccc, dd LLL yyyy"

Сокращённая запись

"dd/LL/yyyy"

Временные метки

"HH:mm"

Согласованность форматирования в приложении

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

const formatDate = (dt) => dt.toFormat("yyyy-LL-dd");
const formatDateTime = (dt) => dt.toFormat("yyyy-LL-dd HH:mm");

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

Оглавление