Получение значений полей

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

Прямые свойства DateTime

Основной способ получения значений — доступ к свойствам экземпляра DateTime. Эти свойства возвращают уже нормализованные числовые значения.

Календарные поля

К базовым компонентам даты относятся:

  • year — год
  • month — месяц (1–12)
  • day — день месяца
  • hour — час (0–23)
  • minute — минуты
  • second — секунды
  • millisecond — миллисекунды
import { DateTime } from "luxon";

const dt = DateTime.local(2026, 5, 23, 14, 45, 30);

dt.year;        // 2026
dt.month;       // 5
dt.day;         // 23
dt.hour;        // 14
dt.minute;      // 45
dt.second;      // 30
dt.millisecond; // 0

Каждое значение извлекается уже с учётом текущей временной зоны объекта DateTime.

Производные календарные характеристики

Помимо базовых полей, Luxon предоставляет дополнительные вычисляемые свойства, связанные с календарём и локализацией.

День недели

Поле weekday возвращает числовое значение дня недели:

  • 1 — понедельник
  • 7 — воскресенье
dt.weekday; // например, 6 (суббота)

Порядковый день года

Поле ordinal показывает день в году от 1 до 365 (или 366 в високосный год):

dt.ordinal; // например, 143

Это значение полезно при расчётах сезонных или годовых интервалов.

Неделя года и год недели

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

  • weekNumber — номер недели в году
  • weekYear — год, к которому относится неделя
dt.weekNumber; // например, 21
dt.weekYear;   // может отличаться от year на границе года

Особенность заключается в том, что первая неделя года определяется по ISO-8601, а не по календарному принципу.

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

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

Название зоны

dt.zoneName;

Возвращает строковое представление временной зоны, например "UTC" или "Europe/Moscow".

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

dt.offset;

Значение выражается в минутах и показывает разницу с UTC:

  • 0 — UTC
  • 180 — UTC+3
  • -300 — UTC-5

Это поле особенно важно при низкоуровневой работе с временем и интеграции с внешними API.

Получение всех полей сразу

Для извлечения набора значений используется метод toObject(). Он возвращает структуру, содержащую основные компоненты даты.

dt.toObject();

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

{
  year: 2026,
  month: 5,
  day: 23,
  hour: 14,
  minute: 45,
  second: 30,
  millisecond: 0
}

Метод удобен при сериализации или передаче данных между слоями приложения.

Получение JavaScript Date

Luxon позволяет преобразовать объект в стандартный Date:

dt.toJSDate();

Этот метод возвращает нативный объект JavaScript, при этом все временные вычисления уже учтены на уровне Luxon.

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

Форматированное извлечение как альтернатива полям

Хотя основной акцент делается на свойства, иногда требуется получить значения в специфическом формате. Для этого используется toFormat():

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

Данный подход не извлекает поля напрямую, но опирается на них при формировании строки.

Особенности доступа к значениям

Поведение полей DateTime имеет несколько ключевых особенностей:

  • значения всегда нормализованы в рамках текущей временной зоны;
  • свойства являются вычисляемыми, а не хранимыми;
  • изменение зоны через setZone() влияет на все возвращаемые поля;
  • отсутствует необходимость в ручной конвертации UTC.
const utc = dt.setZone("utc");

utc.hour; // значение пересчитано относительно UTC

Различие между свойствами и методами преобразования

В Luxon важно различать:

  • прямые свойства (year, month, day)
  • агрегированные методы (toObject, toISO, toFormat)

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

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

Оглавление