Метод fromObject

DateTime.fromObject создаёт объект даты и времени в Luxon на основе переданного структурированного объекта полей. Метод используется, когда значения времени уже разложены по компонентам (год, месяц, день и т. д.), либо когда требуется собрать DateTime без предварительного парсинга строки.

Формально:

DateTime.fromObject(obj: DateObjectUnits, opts?: DateTimeOptions): DateTime

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

Структура входного объекта

Первый аргумент метода — объект, содержащий календарные и временные поля. Эти поля интерпретируются как компоненты даты:

  • year — полный год
  • month — месяц (1–12)
  • day — день месяца (1–31)
  • hour — часы (0–23)
  • minute — минуты (0–59)
  • second — секунды (0–59)
  • millisecond — миллисекунды (0–999)

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

Пример частичного объекта:

DateTime.fromObject({
  year: 2025,
  month: 6
})

В таком случае Luxon автоматически подставляет:

  • day = 1
  • hour = 0
  • minute = 0
  • second = 0
  • millisecond = 0

Календарные единицы и нормализация

Luxon выполняет нормализацию входных значений. Это означает, что некорректные или выходящие за пределы значения не всегда приводят к ошибке, а приводятся к корректной дате.

Пример:

DateTime.fromObject({
  year: 2025,
  month: 13,
  day: 40
})

Поведение:

  • month: 13 интерпретируется как январь следующего года
  • day: 40 приводит к переходу на следующий месяц

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

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

Работа с временными зонами

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

DateTime.fromObject(
  {
    year: 2026,
    month: 1,
    day: 1,
    hour: 12
  },
  {
    zone: 'Europe/Paris'
  }
)

Ключ zone определяет, в каком часовом поясе будет интерпретирована дата.

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

  • Без указания zone используется системная временная зона окружения
  • Поддерживаются IANA-зоны (Europe/Paris, Asia/Almaty, UTC)
  • Перевод времени выполняется автоматически с учётом смещения

Локаль и дополнительные параметры

Второй аргумент также поддерживает:

  • locale — локаль (например, ru, en, de)
  • numberingSystem — система числового представления
  • outputCalendar — календарная система (григорианский, исламский и др.)

Пример:

DateTime.fromObject(
  {
    year: 2026,
    month: 5,
    day: 23
  },
  {
    locale: 'ru',
    numberingSystem: 'latn'
  }
)

Эти параметры не изменяют саму дату, но влияют на форматирование и интерпретацию при выводе.

Поведение при неполных данных

При отсутствии части полей Luxon использует стандартные значения:

Поле Значение по умолчанию
day 1
hour 0
minute 0
second 0
millisecond 0

Пример:

DateTime.fromObject({ year: 2024 })

Результат: 1 января 2024 года, 00:00:00.000

Обработка некорректных значений

Если входные данные полностью некорректны (например, отсутствует год), результатом будет Invalid DateTime.

const dt = DateTime.fromObject({
  month: 5,
  day: 10
})

dt.isValid // false

Luxon требует хотя бы базовую календарную основу для построения даты.

Границы и переполнение значений

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

Пример:

DateTime.fromObject({
  year: 2025,
  month: 1,
  day: 32
})

Результат будет интерпретирован как 1 февраля 2025 года.

Аналогично:

DateTime.fromObject({
  hour: 25
})

Превратится в +1 день и 1 час.

Такое поведение делает метод устойчивым к накопительным расчётам времени, но требует осторожности при строгой валидации.

Отличие от строкового парсинга

fromObject принципиально отличается от fromISO, fromFormat и других методов парсинга:

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

Пример сравнения:

DateTime.fromISO('2026-05-23T10:00')

DateTime.fromObject({
  year: 2026,
  month: 5,
  day: 23,
  hour: 10
})

Первый вариант ориентирован на строковые данные, второй — на программную генерацию.

Использование с системным временем

При необходимости базировать объект на текущем времени используется комбинирование с DateTime.now():

const now = DateTime.now()

const modified = DateTime.fromObject({
  year: now.year,
  month: now.month,
  day: now.day,
  hour: 12
})

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

Внутренняя интерпретация полей

Luxon использует календарную модель, в которой:

  • месяц начинается с 1 (январь = 1)
  • день месяца также 1-based
  • время представлено в 24-часовом формате

Это важно при миграции с систем, где используется 0-based индексация месяцев (например, JavaScript Date).

Пример ошибки переноса:

// JavaScript Date: месяц 0 = январь
// Luxon: месяц 1 = январь

DateTime.fromObject({
  year: 2026,
  month: 0
})

Результат будет интерпретирован как декабрь предыдущего года после нормализации.

Работа с миллисекундами и точностью

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

DateTime.fromObject({
  year: 2026,
  month: 5,
  day: 23,
  hour: 10,
  minute: 30,
  second: 15,
  millisecond: 250
})

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

Взаимодействие с объектом DateTime

Результатом fromObject всегда является экземпляр DateTime, который поддерживает цепочки преобразований:

const dt = DateTime.fromObject({
  year: 2026,
  month: 5,
  day: 23
})

dt.plus({ days: 5 }).set({ hour: 8 })

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

Оглавление