Метод fromISO

В Luxon метод DateTime.fromISO() используется для преобразования строк формата ISO 8601 в полноценный объект DateTime. Этот метод является одним из базовых способов парсинга дат, поскольку ISO-строки считаются стандартом обмена датами в веб-разработке и API.

Метод fromISO() принимает строку даты и времени в формате ISO 8601 и возвращает объект DateTime, который уже содержит:

  • календарную дату
  • время
  • информацию о часовом поясе (если она присутствует)
  • дополнительные параметры локализации

Если строка не соответствует ISO-формату, результатом становится объект с состоянием Invalid.

Синтаксис

DateTime.fromISO(text, options)

Параметры

text (string) Строка в формате ISO 8601. Примеры:

  • "2026-05-23"
  • "2026-05-23T14:30:00"
  • "2026-05-23T14:30:00.000Z"
  • "2026-05-23T14:30:00+06:00"

options (Object, необязательный)

Основные параметры:

  • zone — принудительная установка временной зоны
  • setZone — использовать ли зону из строки (true/false)
  • includeOffset — сохранять ли смещение из строки
  • locale — локаль (например, "ru", "en")

Базовое использование

Только дата

import { DateTime } from "luxon";

const dt = DateTime.fromISO("2026-05-23");

console.log(dt.toString());

Результат интерпретируется как дата в локальной зоне окружения.

Дата и время

const dt = DateTime.fromISO("2026-05-23T14:30:00");

Здесь Luxon создаёт объект с точным временем, но без информации о часовом поясе в строке.

Дата, время и UTC

const dt = DateTime.fromISO("2026-05-23T14:30:00Z");

Символ Z означает UTC. Luxon интерпретирует это как всемирное координированное время.

Дата с часовым поясом

const dt = DateTime.fromISO("2026-05-23T14:30:00+06:00");

Смещение +06:00 сохраняется и учитывается при вычислениях.

Работа с часовыми поясами

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

const dt = DateTime.fromISO("2026-05-23T14:30:00", {
  zone: "Europe/Moscow"
});

Строка интерпретируется так, будто она принадлежит указанной зоне.

Отключение зоны из строки

const dt = DateTime.fromISO("2026-05-23T14:30:00+06:00", {
  setZone: false
});

В этом случае смещение из строки игнорируется, и время пересчитывается в текущую локальную зону.

includeOffset и его влияние

const dt = DateTime.fromISO("2026-05-23T14:30:00+06:00", {
  includeOffset: false
});

При includeOffset: false смещение не используется как источник истины, а дата приводится к локальному времени.

Особенности парсинга ISO 8601

Метод поддерживает широкий диапазон форматов:

Только дата

DateTime.fromISO("2026-05-23");

Секунды и миллисекунды

DateTime.fromISO("2026-05-23T14:30:00.123");

UTC

DateTime.fromISO("2026-05-23T14:30:00.123Z");

Смещение

DateTime.fromISO("2026-05-23T14:30:00.123+03:00");

Частичные и неполные значения

Luxon допускает неполные строки ISO:

DateTime.fromISO("2026-05");

или

DateTime.fromISO("2026");

В таких случаях недостающие компоненты заполняются минимальными значениями:

  • месяц → январь (1)
  • день → 1
  • время → 00:00:00

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

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

if (!dt.isValid) {
  console.log(dt.invalidReason);
}

Возможные причины invalidReason:

  • unparsable
  • invalid input
  • out of range

Влияние локали

const dt = DateTime.fromISO("2026-05-23T14:30:00", {
  locale: "ru"
});

Локаль влияет не на парсинг, а на последующее форматирование:

dt.toLocaleString(DateTime.DATETIME_FULL);

Отличие от JavaScript Date

DateTime.fromISO():

  • строго парсит ISO 8601
  • поддерживает временные зоны
  • сохраняет смещение
  • предоставляет богатые методы форматирования

new Date():

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

Типичные ошибки при использовании

1. Потеря часового пояса

DateTime.fromISO("2026-05-23T14:30:00");

Без Z или offset время считается локальным, что часто приводит к смещению при передаче данных между системами.

2. Неверное ожидание UTC

DateTime.fromISO("2026-05-23T14:30:00");

Это не UTC. Для UTC требуется:

DateTime.fromISO("2026-05-23T14:30:00Z");

3. Игнорирование isValid

const dt = DateTime.fromISO("2026-99-99");

console.log(dt.toString()); // некорректный результат

Без проверки isValid можно получить логически некорректные данные.

Использование в цепочках преобразований

const dt = DateTime
  .fromISO("2026-05-23T14:30:00Z")
  .setZone("Asia/Almaty")
  .plus({ days: 2 })
  .toISO();

Здесь:

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

Поведение при отсутствии времени

DateTime.fromISO("2026-05-23");

Luxon интерпретирует это как:

2026-05-23T00:00:00

в локальной временной зоне, если не указано иное.

Важные нюансы интерпретации строки

  • ISO без времени = начало суток
  • ISO без зоны = локальное время
  • ISO с Z = UTC
  • ISO с offset = смещённое время
  • setZone: true сохраняет оригинальную зону, если она есть

Роль метода в архитектуре приложений

fromISO() обычно используется:

  • при обработке API-ответов
  • при чтении данных из базы
  • при десериализации JSON
  • при обмене между микросервисами

ISO-формат выступает универсальным контрактом, а Luxon обеспечивает строгую и предсказуемую интерпретацию этих данных без неоднозначностей стандартного Date.

Оглавление