Создание объекта DateTime

Библиотека Luxon предназначена для удобной работы с датой, временем, часовыми поясами и локализацией в JavaScript. Основным объектом библиотеки является DateTime.

Установка через npm:

npm install luxon

Подключение:

import { DateTime } from 'luxon'

Для CommonJS:

const { DateTime } = require('luxon')

Создание текущей даты и времени

Самый распространённый способ создания объекта — получение текущего момента времени.

const now = DateTime.now()

console.log(now)

Объект содержит:

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

Пример вывода:

DateTime {
  ts: 1716451200000,
  zone: UTC+3,
  locale: ru,
  ...
}

Создание объекта из ISO-строки

ISO 8601 — стандартный формат хранения даты и времени.

const dt = DateTime.fromISO('2025-06-15T14:30:00')

console.log(dt.toString())

Строка может содержать:

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

Только дата

const dt = DateTime.fromISO('2025-06-15')

Дата со временем

const dt = DateTime.fromISO('2025-06-15T14:30:00')

С часовым поясом

const dt = DateTime.fromISO('2025-06-15T14:30:00+02:00')

Создание объекта из отдельных компонентов

Метод fromObject() позволяет вручную указать части даты.

const dt = DateTime.fromObject({
  year: 2025,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30
})

Поддерживаемые поля объекта

fromObject() поддерживает большое количество параметров.

Основные поля

Поле Описание
year Год
month Месяц
day День
hour Час
minute Минута
second Секунда
millisecond Миллисекунда

Пример:

const dt = DateTime.fromObject({
  year: 2025,
  month: 12,
  day: 31,
  hour: 23,
  minute: 59,
  second: 45,
  millisecond: 120
})

Создание даты без времени

Если время не указано, Luxon автоматически устанавливает его в начало суток.

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

console.log(dt.toISO())

Результат:

2025-05-10T00:00:00.000+03:00

Создание времени без даты

Luxon всё равно создаёт полноценную дату, используя текущий день.

const dt = DateTime.fromObject({
  hour: 18,
  minute: 45
})

Использование часового пояса

Одно из главных преимуществ Luxon — встроенная работа с часовыми поясами.

const dt = DateTime.fromObject(
  {
    year: 2025,
    month: 6,
    day: 15,
    hour: 12
  },
  {
    zone: 'Europe/Moscow'
  }
)

Популярные идентификаторы зон

Зона Значение
UTC Всемирное время
Europe/Moscow Москва
Asia/Almaty Алматы
America/New_York Нью-Йорк
Europe/London Лондон
Asia/Tokyo Токио

Создание объекта в UTC

const dt = DateTime.utc()

console.log(dt.toString())

С указанием конкретной даты:

const dt = DateTime.utc(2025, 6, 15, 14, 30)

Разница между now() и utc()

DateTime.now()

Создаёт дату в локальной временной зоне системы.

const local = DateTime.now()

DateTime.utc()

Создаёт дату в UTC.

const utc = DateTime.utc()

Создание из JavaScript Date

Luxon умеет преобразовывать стандартный объект Date.

const jsDate = new Date()

const dt = DateTime.fromJSDate(jsDate)

Это особенно полезно при работе со старыми библиотеками и браузерным API.

Создание из timestamp

Timestamp — количество миллисекунд с 1 января 1970 года.

const dt = DateTime.fromMillis(1718456400000)

Создание из Unix timestamp

Unix timestamp хранится в секундах.

const dt = DateTime.fromSeconds(1718456400)

Отличие fromMillis() от fromSeconds()

Миллисекунды

DateTime.fromMillis(1718456400000)

Секунды

DateTime.fromSeconds(1718456400)

Ошибка в выборе метода приводит к неправильной дате.

Создание из SQL-формата

Luxon поддерживает SQL-представление даты.

const dt = DateTime.fromSQL('2025-06-15 14:30:00')

Создание из RFC2822

Формат часто используется в email-заголовках.

const dt = DateTime.fromRFC2822(
  'Tue, 15 Jun 2025 14:30:00 +0300'
)

Создание из HTTP-формата

const dt = DateTime.fromHTTP(
  'Sun, 15 Jun 2025 11:30:00 GMT'
)

Создание с локализацией

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

  • форматирование;
  • язык месяцев;
  • язык дней недели;
  • региональные настройки.
const dt = DateTime.fromObject(
  {
    year: 2025,
    month: 6,
    day: 15
  },
  {
    locale: 'ru'
  }
)

Создание с несколькими настройками

const dt = DateTime.fromObject(
  {
    year: 2025,
    month: 6,
    day: 15,
    hour: 18
  },
  {
    zone: 'Asia/Almaty',
    locale: 'ru'
  }
)

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

Luxon не выбрасывает ошибку при невалидной дате. Вместо этого создаётся специальный объект.

const dt = DateTime.fromObject({
  year: 2025,
  month: 15,
  day: 40
})

console.log(dt.isValid)

Результат:

false

Получение причины ошибки

console.log(dt.invalidReason)
console.log(dt.invalidExplanation)

Пример:

unit out of range
you specified 15 (of type number) as a month...

Создание минималистичных объектов

Можно указывать только нужные части даты.

const dt1 = DateTime.fromObject({
  year: 2025
})

const dt2 = DateTime.fromObject({
  year: 2025,
  month: 10
})

Автоматическая нормализация значений

Luxon корректирует некоторые значения автоматически.

const dt = DateTime.fromObject({
  year: 2025,
  month: 6,
  day: 15,
  hour: 25
})

Однако не все ошибки исправляются автоматически. Для надёжной работы необходимо проверять isValid.

Создание объекта из пользовательского формата

Метод fromFormat() позволяет разбирать строки нестандартного формата.

const dt = DateTime.fromFormat(
  '15.06.2025 14:30',
  'dd.MM.yyyy HH:mm'
)

Основные токены формата

Токен Значение
dd День
MM Месяц
yyyy Год
HH Часы
mm Минуты
ss Секунды

Пример сложного формата

const dt = DateTime.fromFormat(
  '15 июня 2025 18:45',
  'dd LLLL yyyy HH:mm',
  {
    locale: 'ru'
  }
)

Использование setZone

По умолчанию Luxon может конвертировать дату в локальную зону. Чтобы сохранить исходную временную зону, используется setZone.

const dt = DateTime.fromISO(
  '2025-06-15T14:30:00+02:00',
  {
    setZone: true
  }
)

Иммутабельность объектов

DateTime является immutable-объектом. Это означает, что объект нельзя изменить после создания.

const dt1 = DateTime.now()

const dt2 = dt1.plus({ days: 1 })

dt1 останется неизменным.

Создание копии объекта

const original = DateTime.now()

const copy = original.set({})

Создание объекта с недельной датой

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

const dt = DateTime.fromObject({
  weekYear: 2025,
  weekNumber: 25,
  weekday: 3
})

Значения weekday

Значение День
1 Понедельник
2 Вторник
3 Среда
4 Четверг
5 Пятница
6 Суббота
7 Воскресенье

Создание из ordinal date

Ordinal date использует номер дня в году.

const dt = DateTime.fromObject({
  year: 2025,
  ordinal: 150
})

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

const dt = DateTime.local()

Метод аналогичен:

DateTime.now()

Создание локальной даты вручную

const dt = DateTime.local(
  2025,
  6,
  15,
  14,
  30
)

Порядок аргументов в local()

DateTime.local(
  year,
  month,
  day,
  hour,
  minute,
  second,
  millisecond
)

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

const dt = DateTime.fromObject({
  year: 2025,
  month: 6,
  day: 15,
  millisecond: 450
})

Создание объекта с nanosecond precision

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

Создание объекта для начала дня

const dt = DateTime.now().startOf('day')

Создание объекта для конца дня

const dt = DateTime.now().endOf('day')

Создание объекта для начала месяца

const dt = DateTime.now().startOf('month')

Создание объекта для начала года

const dt = DateTime.now().startOf('year')

Использование цепочек методов

const dt = DateTime.now()
  .setZone('UTC')
  .startOf('day')
  .plus({ days: 5 })

Типичная ошибка при создании DateTime

Неправильно:

const dt = DateTime.fromISO('15.06.2025')

Метод fromISO() ожидает ISO-формат.

Правильно:

const dt = DateTime.fromFormat(
  '15.06.2025',
  'dd.MM.yyyy'
)

Сравнение способов создания

Метод Назначение
now() Текущая дата
local() Локальная дата
utc() UTC-время
fromISO() ISO-строка
fromFormat() Пользовательский формат
fromObject() Создание из полей
fromJSDate() Из Date
fromMillis() Из timestamp
fromSeconds() Из Unix timestamp
fromSQL() SQL-формат
fromRFC2822() RFC2822
fromHTTP() HTTP-дата
Оглавление