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

Библиотека Luxon активно использует стандарт ISO 8601 как основной способ представления даты и времени. Этот формат универсален, поддерживается браузерами, серверными платформами, API и базами данных.

Типичная ISO-строка:

2025-03-15T14:30:00

Структура:

Часть Значение
2025 год
03 месяц
15 день
T разделитель даты и времени
14:30:00 часы, минуты, секунды

ISO 8601 поддерживает:

  • дату;
  • дату и время;
  • миллисекунды;
  • часовые пояса;
  • UTC-смещения;
  • сокращённые формы записи.

В Luxon ISO является наиболее удобным способом создания объектов времени.

Метод DateTime.fromISO()

Основной метод создания даты из ISO-строки:

DateTime.fromISO(isoString)

Пример:

import { DateTime } from "luxon";

const dt = DateTime.fromISO("2025-03-15T14:30:00");

console.log(dt.toString());

Результат:

2025-03-15T14:30:00.000+03:00

Метод возвращает объект DateTime.

Создание только даты

ISO может содержать только календарную дату:

const dt = DateTime.fromISO("2025-03-15");

console.log(dt.toISO());

Результат:

2025-03-15T00:00:00.000+03:00

Если время отсутствует:

  • часы становятся 00;
  • минуты и секунды тоже обнуляются.

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

Полная ISO-строка:

const dt = DateTime.fromISO("2025-03-15T18:45:10");

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

console.log(dt.year);
console.log(dt.month);
console.log(dt.day);

console.log(dt.hour);
console.log(dt.minute);
console.log(dt.second);

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

ISO поддерживает дробную часть секунд:

const dt = DateTime.fromISO(
  "2025-03-15T18:45:10.125"
);

console.log(dt.millisecond);

Результат:

125

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

Символ Z означает UTC-время:

const dt = DateTime.fromISO(
  "2025-03-15T18:45:10Z"
);

console.log(dt.zoneName);

Результат:

UTC

Такой формат особенно важен:

  • в API;
  • в серверных приложениях;
  • при хранении времени в базе данных;
  • при обмене между часовыми поясами.

ISO со смещением часового пояса

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

const dt = DateTime.fromISO(
  "2025-03-15T18:45:10+02:00"
);

console.log(dt.offset);

Результат:

120

Значение offset хранится в минутах.

Разница между Z и +03:00

UTC

2025-03-15T10:00:00Z

Абсолютное время UTC.

Offset

2025-03-15T10:00:00+03:00

Локальное время со смещением.

Luxon корректно интерпретирует оба варианта.

Опция setZone

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

Пример:

const dt = DateTime.fromISO(
  "2025-03-15T10:00:00+02:00"
);

console.log(dt.zoneName);

Если требуется сохранить оригинальную зону:

const dt = DateTime.fromISO(
  "2025-03-15T10:00:00+02:00",
  { setZone: true }
);

console.log(dt.zoneName);

Поведение без setZone

const dt = DateTime.fromISO(
  "2025-03-15T10:00:00+02:00"
);

Luxon:

  1. считывает offset;
  2. переводит время;
  3. преобразует объект в локальную зону.

Это может изменить отображаемые часы.

Поведение с setZone: true

const dt = DateTime.fromISO(
  "2025-03-15T10:00:00+02:00",
  { setZone: true }
);

Теперь:

  • зона сохраняется;
  • offset остаётся исходным;
  • объект продолжает работать в этой зоне.

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

Опция zone позволяет принудительно установить часовую зону.

const dt = DateTime.fromISO(
  "2025-03-15T10:00:00",
  { zone: "UTC" }
);

console.log(dt.toString());

Популярные значения zone

Значение Описание
UTC всемирное время
Europe/Moscow Москва
Asia/Almaty Алматы
America/New_York Нью-Йорк
local локальная зона

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

ISO допускает отдельное время:

const dt = DateTime.fromISO("10:30:15");

Luxon автоматически подставит текущую дату.

Создание даты недели ISO

ISO поддерживает week date:

const dt = DateTime.fromISO("2025-W12-6");

console.log(dt.toISODate());

Здесь:

  • W12 — 12 неделя года;
  • 6 — шестой день недели.

Ordinal date

Поддерживается ordinal формат:

const dt = DateTime.fromISO("2025-074");

Где:

  • 074 — 74-й день года.

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

Некорректная строка создаёт невалидный объект.

Пример:

const dt = DateTime.fromISO("invalid");

console.log(dt.isValid);

Результат:

false

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

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

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

unparsable
the input could not be parsed

Проверка перед использованием

Практика безопасной работы:

const dt = DateTime.fromISO(userInput);

if (dt.isValid) {
  console.log(dt.toISO());
} else {
  console.log("Ошибка даты");
}

Работа с пользовательским вводом

Частая ситуация:

const formValue = "2025-03-15";

const dt = DateTime.fromISO(formValue);

Особенно удобно при работе с:

  • <input type="date">;
  • REST API;
  • JSON;
  • GraphQL;
  • базами данных.

Парсинг серверных дат

Серверы часто возвращают ISO:

{
  "createdAt": "2025-03-15T10:20:30Z"
}

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

const created = DateTime.fromISO(data.createdAt);

Конвертация после создания

После парсинга доступны все методы Luxon.

Форматирование

dt.toFormat("dd.MM.yyyy")

Изменение зоны

dt.setZone("UTC")

Добавление времени

dt.plus({ days: 5 })

Вычитание

dt.minus({ hours: 2 })

Цепочки вызовов

const result = DateTime
  .fromISO("2025-03-15T10:00:00")
  .plus({ days: 1 })
  .setZone("UTC")
  .toFormat("yyyy-MM-dd HH:mm");

Сравнение ISO-дат

const a = DateTime.fromISO("2025-03-15");
const b = DateTime.fromISO("2025-03-20");

console.log(a < b);

Лучше использовать:

console.log(a.toMillis() < b.toMillis());

Преобразование в JavaScript Date

const dt = DateTime.fromISO(
  "2025-03-15T10:00:00"
);

const jsDate = dt.toJSDate();

Обратное преобразование в ISO

const dt = DateTime.fromISO(
  "2025-03-15T10:00:00"
);

console.log(dt.toISO());

Частичные ISO-форматы

Luxon понимает:

2025
2025-03
2025-03-15
2025-03-15T10
2025-03-15T10:30
2025-03-15T10:30:20

Разбор локального времени

const dt = DateTime.fromISO(
  "2025-03-15T10:00"
);

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

Проблемы с часовыми поясами

Ошибка:

DateTime.fromISO(
  "2025-03-15T10:00:00Z"
);

Без понимания UTC можно получить:

  • неожиданное смещение;
  • изменение времени при отображении;
  • ошибки синхронизации.

Практика хранения времени

Наиболее безопасный подход:

  1. хранить даты в UTC;
  2. передавать ISO;
  3. отображать в локальной зоне.

Пример:

const utcDate = DateTime.utc();

const iso = utcDate.toISO();

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

Отправка

fetch("/api", {
  method: "POST",
  body: JSON.stringify({
    createdAt: DateTime.now().toISO()
  })
});

Получение

const dt = DateTime.fromISO(
  response.createdAt
);

Работа с массивом ISO-строк

const dates = [
  "2025-03-15",
  "2025-03-16",
  "2025-03-17"
];

const parsed = dates.map(date =>
  DateTime.fromISO(date)
);

Сортировка дат

parsed.sort(
  (a, b) => a.toMillis() - b.toMillis()
);

Фильтрация невалидных значений

const validDates = parsed.filter(
  dt => dt.isValid
);

Типичные ошибки

Неправильный формат

15-03-2025

Это не ISO.

Правильно:

2025-03-15

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

Некоторые строки:

2025-03-15 10:00:00

могут работать нестабильно в разных окружениях.

Предпочтительно:

2025-03-15T10:00:00

Игнорирование зоны

2025-03-15T10:00:00Z

и

2025-03-15T10:00:00

— это разные значения времени.

Производительность

fromISO() оптимизирован для ISO-формата и работает быстрее многих универсальных парсеров.

Поэтому:

  • ISO — основной рекомендуемый формат;
  • fromISO() предпочтительнее ручного парсинга;
  • использование ISO уменьшает количество ошибок.

Сравнение fromISO() и fromFormat()

fromISO()

DateTime.fromISO("2025-03-15")

Используется для стандартных ISO-строк.

fromFormat()

DateTime.fromFormat(
  "15.03.2025",
  "dd.MM.yyyy"
);

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

Когда выбирать fromISO()

Метод особенно полезен при работе с:

  • серверными API;
  • JSON;
  • PostgreSQL;
  • MongoDB;
  • Firebase;
  • REST;
  • GraphQL;
  • временными метками;
  • браузерными формами;
  • международными системами обмена данными.

Полный пример

import { DateTime } from "luxon";

const source = "2025-03-15T10:30:00Z";

const dt = DateTime.fromISO(source);

if (!dt.isValid) {
  throw new Error(dt.invalidExplanation);
}

const result = dt
  .setZone("Asia/Almaty")
  .plus({ days: 3 })
  .toFormat("dd.MM.yyyy HH:mm");

console.log(result);
Оглавление