Работа с формами

Работа с формами в Luxon строится вокруг преобразования объекта DateTime в строковые представления и обратно. Библиотека изначально ориентирована на строгие стандарты (ISO, RFC, HTTP), но также предоставляет гибкий механизм пользовательского форматирования через токены.

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

Стандартные форматы Luxon

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

ISO 8601

ISO-формат является основным в Luxon и используется по умолчанию во многих методах.

import { DateTime } from "luxon";

const dt = DateTime.now();

dt.toISO();

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

  • Машиночитаемый формат
  • Поддерживает временные зоны
  • Используется в JSON, API и базах данных
  • Может включать миллисекунды и смещение

Дополнительные варианты ISO:

dt.toISODate();        // только дата: 2026-05-23
dt.toISOTime();        // только время: 14:32:10.123
dt.toISOWeekDate();    // неделя ISO
dt.toISOSeconds();     // без миллисекунд
dt.toISO()             // полный формат

RFC 2822

Формат, часто используемый в email-системах и старых веб-протоколах.

dt.toRFC2822();

Пример результата:

Sat, 23 May 2026 14:32:10 +0600

Характеристики:

  • Читаем человеком
  • Фиксированная структура
  • Поддержка временных смещений

HTTP-формат

Используется в заголовках HTTP (например, Last-Modified, Date).

dt.toHTTP();

Пример:

Sat, 23 May 2026 08:32:10 GMT

Особенность — всегда UTC/GMT.

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

Luxon предоставляет мощный механизм форматирования через метод toFormat(), основанный на токенах.

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

Пример результата:

23.05.2026 14:32

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

Форматирование в Luxon строится на наборе символов-токенов, каждый из которых отвечает за конкретную часть даты или времени.

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

Токен Значение Пример
yyyy год 2026
yy последние 2 цифры года 26
MM месяц (2 цифры) 05
M месяц (без ведущего нуля) 5
dd день месяца 23
d день без нуля 23

Токены времени

Токен Значение Пример
HH часы (24-часовой формат) 14
hh часы (12-часовой формат) 02
mm минуты 32
ss секунды 10
a AM/PM PM
S / SSS миллисекунды 123

Токены временной зоны

Токен Значение Пример
ZZ смещение +06:00
z название зоны Asia/Almaty
ZZZ сокращённое смещение +0600

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

Гибкость toFormat() позволяет строить любые пользовательские представления.

Базовые примеры

dt.toFormat("yyyy-MM-dd"); 
// 2026-05-23

dt.toFormat("dd/MM/yyyy");
// 23/05/2026

dt.toFormat("HH:mm:ss");
// 14:32:10

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

dt.toFormat("d LLLL yyyy, HH:mm");
// 23 May 2026, 14:32

Здесь LLLL выводит полное название месяца.

Локализованные формы

Luxon учитывает локаль при форматировании:

dt.setLocale("ru").toFormat("d LLLL yyyy");
// 23 мая 2026

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

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

Разбор строковых представлений

Luxon поддерживает обратное преобразование строк в DateTime через методы парсинга.

ISO-парсинг

DateTime.fromISO("2026-05-23T14:32:10.123+06:00");

Наиболее надёжный способ, так как ISO строго стандартизирован.

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

DateTime.fromFormat("23.05.2026 14:32", "dd.MM.yyyy HH:mm");

Важно:

  • шаблон должен точно соответствовать входной строке
  • любые отклонения приводят к невалидному объекту

Проверка валидности:

const dt = DateTime.fromFormat("23.05.2026", "dd.MM.yyyy");

dt.isValid;

RFC 2822 и HTTP

DateTime.fromRFC2822("Sat, 23 May 2026 14:32:10 +0600");

DateTime.fromHTTP("Sat, 23 May 2026 08:32:10 GMT");

Миллисекунды и Unix-время

DateTime.fromMillis(1716468730123);

DateTime.fromSeconds(1716468730);

Объектный способ

DateTime.fromObject({
  year: 2026,
  month: 5,
  day: 23,
  hour: 14,
  minute: 32
});

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

Влияние временной зоны на форматирование

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

const dt = DateTime.now().setZone("Asia/Almaty");

dt.toFormat("HH:mm ZZZZ");

Если зона не задана явно, используется системная.

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

  • ISO всегда сохраняет смещение
  • HTTP всегда конвертируется в UTC
  • пользовательские форматы зависят от установленной зоны

Локаль и культурные форматы

Локаль влияет не только на текстовые элементы, но и на порядок отображения компонентов даты.

DateTime.now()
  .setLocale("en")
  .toFormat("cccc, d LLLL");
// Saturday, 23 May

DateTime.now()
  .setLocale("ru")
  .toFormat("cccc, d LLLL");
// суббота, 23 мая

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

Некоторые символы в шаблоне могут быть интерпретированы как токены. Для их безопасного использования применяется экранирование:

dt.toFormat("'Дата:' dd.MM.yyyy");
// Дата: 23.05.2026

Правила:

  • текст в одинарных кавычках не интерпретируется
  • внутри кавычек токены игнорируются

Форматирование с условной логикой

Luxon не предоставляет встроенной условной логики в форматах, но её можно имитировать:

const formatted =
  dt.hour < 12
    ? dt.toFormat("dd.MM.yyyy 'утро' HH:mm")
    : dt.toFormat("dd.MM.yyyy 'вечер' HH:mm");

Сериализация в JSON

При работе с API часто используется автоматическая сериализация:

JSON.stringify(dt);

Luxon использует метод toJSON(), который возвращает ISO-строку:

"2026-05-23T14:32:10.123+06:00"

Преобразование форматов в цепочках

Форматы можно комбинировать с другими операциями DateTime:

dt
  .setZone("UTC")
  .toFormat("yyyy-MM-dd HH:mm");

Или:

dt.plus({ days: 2 }).toISODate();

Ошибки при работе с форматами

Основные причины невалидных результатов:

  • несоответствие шаблона и строки
  • использование неподдерживаемых токенов
  • отсутствие временной зоны при парсинге ISO-подобных строк
  • локаль не поддерживает используемые названия

Проверка всегда выполняется через:

result.isValid;
result.invalidReason;

Итоговые принципы работы с формами

  • ISO используется как базовый и универсальный формат
  • RFC и HTTP применяются для совместимости с протоколами
  • toFormat() обеспечивает гибкость отображения
  • fromFormat() требует строгого соответствия шаблону
  • локаль и временная зона напрямую влияют на результат
  • сериализация по умолчанию всегда возвращает ISO-представление
Оглавление