Система вывода

В библиотеке Luxon каждый экземпляр DateTime имеет строго определённое стандартное строковое представление. При неявном преобразовании в строку используется ISO-формат, отражающий момент времени с учётом временной зоны объекта.

Стандартное поведение задаётся через toISO(), что делает ISO 8601 фундаментом системы вывода:

  • дата и время кодируются в унифицированной форме;
  • сохраняется информация о часовом поясе;
  • поддерживается высокая совместимость с внешними API и хранилищами данных.

При приведении к строке через String(DateTime) или конкатенацию с текстом используется тот же механизм ISO-представления.

ISO-форматы как основа сериализации

Luxon предоставляет набор методов для строгой сериализации даты и времени в различные варианты ISO 8601.

Полное ISO-представление

Метод:

  • toISO()

Формирует строку вида:

  • 2026-05-23T14:30:00.000+06:00

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

  • включение миллисекунд опционально;
  • всегда присутствует смещение временной зоны;
  • поддерживается строгая стандартизация.

Упрощённые варианты ISO

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

Каждый вариант используется в случаях, когда требуется минимальный объём данных без потери семантики.

RFC и HTTP-совместимые представления

Luxon поддерживает форматы, ориентированные на сетевые протоколы и заголовки HTTP.

RFC 2822

Метод:

  • toRFC2822()

Формат:

  • Sat, 23 May 2026 14:30:00 +0600

Используется в почтовых и устаревших веб-стандартах.

HTTP Date

Метод:

  • toHTTP()

Формат:

  • Sat, 23 May 2026 08:30:00 GMT

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

  • всегда преобразуется в UTC/GMT;
  • соответствует спецификации HTTP-заголовков.

Кастомное форматирование через токены

Основной механизм гибкого вывода реализован через метод:

  • toFormat(formatString)

Система основана на токенах, определяющих структуру строки.

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

  • yyyy — год
  • MM — месяц
  • dd — день
  • HH — часы (24-часовой формат)
  • mm — минуты
  • ss — секунды

Пример логики формирования:

DateTime.toFormat('yyyy-MM-dd HH:mm:ss')

Результат:

  • 2026-05-23 14:30:00

Разделители и текстовые элементы

Форматирование допускает свободное комбинирование:

  • дефисы, слэши, пробелы;
  • буквенные обозначения;
  • локализованные подписи.

Пример:

dd/MM/yyyy 'в' HH:mm

Результат:

  • 23/05/2026 в 14:30

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

Поддерживаются элементы календарной информации:

  • DDD — день года
  • W — неделя года
  • E — день недели
  • ZZ — смещение временной зоны

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

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

Luxon интегрируется с ECMAScript Internationalization API, обеспечивая локализованные форматы.

toLocaleString

Метод:

  • toLocaleString([formatOptions])

Поддерживает предустановленные форматы:

  • DateTime.DATE_FULL
  • DateTime.DATE_MED
  • DateTime.DATETIME_SHORT
  • DateTime.TIME_SIMPLE

Пример поведения:

  • форматирование даты зависит от локали объекта;
  • порядок элементов меняется автоматически;
  • числовые системы могут адаптироваться.

Локаль и культурные различия

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

  • порядок день/месяц/год;
  • название месяцев и дней недели;
  • формат времени (12/24 часа).

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

Временные зоны и их влияние на вывод

Система вывода тесно связана с понятием временной зоны.

setZone и отображение

При изменении зоны:

  • меняется интерпретация локального времени;
  • сохраняется абсолютный момент времени.

Пример поведения:

  • один и тот же timestamp отображается по-разному в разных зонах;
  • ISO-вывод всегда включает актуальное смещение.

UTC-режим

Метод:

  • toUTC()

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

  • смещение становится +00:00;
  • время пересчитывается.

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

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

toJSON

Метод:

  • toJSON()

Возвращает ISO-строку:

  • используется при JSON.stringify;
  • сохраняет стандартное представление даты.

valueOf

Метод:

  • valueOf()

Возвращает числовое значение:

  • количество миллисекунд с Unix-эпохи;
  • используется в арифметических операциях.

Форматы длительностей (Duration)

Система вывода распространяется и на Duration.

ISO-вывод длительности

Метод:

  • toISO()

Пример:

  • PT2H30M15S

Структура:

  • P — период
  • T — разделитель времени
  • H, M, S — компоненты

Кастомное форматирование Duration

Метод:

  • toFormat()

Позволяет задавать человекочитаемые формы:

  • часы, минуты, секунды;
  • произвольные шаблоны.

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

Интервалы и их представление

Объект Interval поддерживает сериализацию границ.

toString и toISO

  • toString() — человекочитаемое представление диапазона
  • toISO() — ISO-интервал вида:
2026-05-23T10:00:00+06:00/2026-05-23T12:00:00+06:00

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

  • строгое разделение начальной и конечной точек;
  • сохранение временных зон для каждой границы.

Приоритеты форматов вывода

Система Luxon определяет несколько уровней приоритета представления:

  1. Явно заданные методы (toISO, toFormat, toRFC2822)
  2. Локализованные методы (toLocaleString)
  3. Неявное приведение (valueOf, toString)
  4. JSON-сериализация (toJSON)

Такое разделение позволяет контролировать поведение объекта в разных контекстах — от логирования до сетевого обмена.

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

Разделение типов вывода основано на двух принципах:

  • строковое представление ориентировано на человека или протокол;
  • числовое представление ориентировано на вычисления.

В результате:

  • ISO и RFC форматы используются для обмена данными;
  • timestamp используется для арифметики времени;
  • локализованные строки применяются для интерфейсного слоя.

Влияние флагов конфигурации на вывод

Некоторые параметры объекта влияют на итоговую строку:

  • сохранённая временная зона;
  • локаль;
  • наличие или отсутствие смещения;
  • точность (миллисекунды).

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

Поведение при некорректных значениях

При отсутствии части данных система вывода:

  • заменяет отсутствующие компоненты нулями;
  • может исключать элементы строки (в зависимости от метода);
  • сохраняет валидность формата.

Например:

  • отсутствие секунд приводит к их опусканию в некоторых форматах;
  • отсутствие зоны заменяется на локальную по умолчанию.

Консистентность между методами

Все методы вывода согласованы между собой:

  • toISO() является базовым источником истины;
  • toFormat() строится поверх внутренних календарных значений;
  • toLocaleString() является отображением поверх Intl API;
  • toJSON() повторяет ISO-поведение.

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

Оглавление