Доступ к компонентам

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

Экземпляр DateTime инкапсулирует множество полей, отражающих как локальные календарные значения, так и параметры временной зоны:

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

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

import { DateTime } from "luxon";

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

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

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

Календарные свойства

Календарные компоненты отражают позицию даты в григорианском календаре и используются при построении интерфейсов, отчетов и вычислений:

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

Базовые элементы даты предоставляются напрямую:

dt.year;  // полный год
dt.month; // месяц (1–12)
dt.day;   // день месяца (1–31)

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

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

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

dt.ordinal;

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

День недели

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

dt.weekday; // 1 (понедельник) ... 7 (воскресенье)

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

Квартал года

Квартальная структура определяется через:

dt.quarter; // 1–4

Используется в финансовых и аналитических расчетах.

Временные компоненты

Временная часть DateTime представлена стандартными единицами измерения:

dt.hour;
dt.minute;
dt.second;
dt.millisecond;

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

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

Luxon предоставляет дополнительные свойства, вычисляемые на основе текущего состояния даты:

Количество дней в месяце

dt.daysInMonth;

Значение зависит от месяца и учитывает високосные годы.

Количество дней в году

dt.daysInYear;

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

Проверка високосного года

dt.isInLeapYear;

Используется для корректного построения календарных интервалов.

Временная зона и смещение

Каждый экземпляр DateTime содержит информацию о временной зоне и смещении относительно UTC:

dt.offset; // смещение в минутах
dt.zoneName; // идентификатор зоны

Смещение позволяет переводить локальное время в универсальное представление и обратно.

Локализация и культурные параметры

Компонент locale определяет форматирование и интерпретацию календарных значений:

dt.locale;

Он влияет на:

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

Проверка корректности значения

Любой экземпляр DateTime может находиться в валидном или невалидном состоянии:

dt.isValid;
dt.invalidReason;
dt.invalidExplanation;

При ошибках парсинга или некорректных входных данных объект сохраняется, но помечается как невалидный, что исключает необходимость выбрасывания исключений в большинстве сценариев обработки дат.

Получение всех компонентов одновременно

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

dt.toObject();

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

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

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

Доступ через форматированные представления

Хотя прямой доступ к компонентам осуществляется через свойства, Luxon предоставляет дополнительные способы извлечения значений через форматирование:

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

Форматирование не заменяет доступ к компонентам, но используется для их композиции в строковые представления.

Особенности модели доступа

Модель доступа в Luxon основана на неизменяемости:

  • любое изменение компонента возвращает новый объект
  • исходный DateTime не модифицируется
  • свойства доступны только для чтения

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

Сопоставление с UTC-представлением

При работе с локальными компонентами важно учитывать возможность преобразования в UTC-контекст:

dt.toUTC().hour;

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

Использование компонентов в вычислениях

Компоненты DateTime применяются напрямую в арифметике дат через создание новых экземпляров:

dt.plus({ days: 1 }).day;
dt.minus({ months: 1 }).month;

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

Оглавление