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

Токены форматирования в Luxon представляют собой строковые инструкции, по которым объект даты и времени преобразуется в человекочитаемое представление. Они используются в методе `DateTime

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

Основные числовые токены даты и времени

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

Год

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

Пример:

DateTime.local().toFormat("yyyy")
// 2026

DateTime.local().toFormat("yy")
// 26

Месяц

  • M — месяц без ведущего нуля (1–12)
  • MM — месяц с ведущим нулём (01–12)
DateTime.local().toFormat("M")
// 5

DateTime.local().toFormat("MM")
// 05

День месяца

  • d — день месяца без нуля (1–31)
  • dd — день месяца с нулём (01–31)
DateTime.local().toFormat("d")
// 7

DateTime.local().toFormat("dd")
// 07

Часы, минуты, секунды

Часы

  • H — 24-часовой формат без нуля (0–23)
  • HH — 24-часовой формат с нулём (00–23)
  • h — 12-часовой формат без нуля (1–12)
  • hh — 12-часовой формат с нулём (01–12)

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

  • m — минуты (0–59)
  • mm — минуты с нулём (00–59)
  • s — секунды (0–59)
  • ss — секунды с нулём (00–59)
DateTime.local().toFormat("HH:mm:ss")
// 14:05:09

Миллисекунды и дробные части секунды

  • S — десятые доли секунды
  • SS — сотые доли секунды
  • SSS — миллисекунды
DateTime.local().toFormat("ss.SSS")
// 09.482

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

Обозначение времени суток

  • a — AM/PM (локализованное значение)
DateTime.local().toFormat("hh:mm a")
// 02:15 PM

В разных локалях вывод AM/PM может заменяться на локальные обозначения.

Токены месяцев и дней в текстовом виде

Месяцы

  • L — номер месяца (1–12)
  • LL — 2-значный месяц (01–12)
  • LLL — сокращённое название месяца (Jan, Feb)
  • LLLL — полное название месяца (January)
DateTime.local().setLocale("en").toFormat("LLLL")
// January

Дни недели

  • c — номер дня недели (1–7)
  • ccc — сокращённое название дня (Mon)
  • cccc — полное название дня (Monday)
DateTime.local().setLocale("en").toFormat("cccc")
// Monday

Год недели и порядковые форматы

Luxon поддерживает ISO-нумерацию недель.

  • kkkk — год недели (week year)
  • W — номер недели в году
DateTime.local().toFormat("kkkk-'W'WW")
// 2026-W21

Часовые пояса и смещения

Смещение относительно UTC

  • Z — смещение в формате +02:00
  • ZZ — компактное смещение +0200
DateTime.local().toFormat("ZZ")
// +0600

Название часового пояса

  • z — короткое имя зоны (если доступно)
  • zz — полное имя зоны
DateTime.local().toFormat("z")
// GMT+6

Локализация текстовых токенов

Luxon тесно связан с Intl и поддерживает локали через .setLocale().

DateTime.local()
  .setLocale("ru")
  .toFormat("cccc, LLLL")
// понедельник, май

При смене локали меняется не только язык, но и правила отображения чисел и названий.

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

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

DateTime.local().toFormat("dd 'дня'")
// 07 дня

Если требуется вывести сам апостроф:

DateTime.local().toFormat("HH:mm ''")
// 14:05 '

Комбинирование токенов

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

DateTime.local().toFormat("cccc, dd LLLL yyyy HH:mm")
// понедельник, 07 май 2026 14:05
DateTime.local().toFormat("yyyy/MM/dd HH:mm:ss.SSS Z")
// 2026/05/07 14:05:09.482 +0600

Отличие форматирования от ISO

Luxon поддерживает стандартные ISO-методы:

  • toISO()
  • toISODate()
  • toISOTime()

Токены toFormat() дают полный контроль над представлением, тогда как ISO-методы фиксированы стандартом.

DateTime.local().toISO()
// 2026-05-07T14:05:09.482+06:00
DateTime.local().toFormat("yyyy-MM-dd HH:mm")
// 2026-05-07 14:05

Частые шаблоны форматирования

Дата без времени

"yyyy-LL-dd"

Читабельная дата

"dd LLLL yyyy"

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

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

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

"EEE, dd LLL yyyy HH:mm:ss Z"

Приоритет и интерпретация токенов

Парсер Luxon обрабатывает строку слева направо, сопоставляя максимально длинные токены первыми. Например, yyyy всегда будет распознан как единый токен, а не как четыре отдельных y.

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

Поведение при отсутствии данных

Если часть даты отсутствует (например, время в DateTime без точного значения секунд), Luxon подставляет значения из объекта времени или использует нули, не выбрасывая ошибку форматирования.

Оглавление