Метод fromFormat

Метод DateTime.fromFormat в библиотеке Luxon предназначен для разбора строк даты и времени по строго заданному формату. В отличие от fromISO, который ожидает стандарт ISO 8601, fromFormat позволяет интерпретировать практически любой строковый формат при условии, что он явно описан через шаблон токенов.

Ключевая особенность метода — полный контроль над разбором строки. Это делает его незаменимым при работе с пользовательскими вводами, логами, внешними API и любыми нестандартными форматами даты.

Общая сигнатура метода

DateTime.fromFormat(text, format, options?)

Параметры

  • text — строка, содержащая дату и/или время
  • format — строка шаблона, описывающая структуру входных данных
  • options — объект конфигурации (необязательный)

Базовый принцип работы

Метод сопоставляет входную строку с набором токенов формата. Каждый токен описывает отдельную часть даты:

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

Если строка строго соответствует шаблону — возвращается корректный объект DateTime. Если нет — результатом будет Invalid DateTime.

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

import { DateTime } from "luxon";

const dt = DateTime.fromFormat("25-05-2026", "dd-MM-yyyy");

console.log(dt.toISODate());

В данном случае:

  • dd — день с ведущим нулём
  • MM — месяц
  • yyyy — четырёхзначный год

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

Год

  • y — год (1–4 цифры)
  • yy — две последние цифры года
  • yyyy — полный год

Пример:

DateTime.fromFormat("26", "yy");      // 2026 (в зависимости от pivot-логики)
DateTime.fromFormat("2026", "yyyy");  // 2026

Месяцы

  • M — месяц (1–12)
  • MM — месяц с ведущим нулём
  • MMM — сокращённое название месяца
  • MMMM — полное название месяца
DateTime.fromFormat("May", "MMMM", { locale: "en" });
DateTime.fromFormat("05", "MM");

Дни

  • d — день месяца
  • dd — день с ведущим нулём
DateTime.fromFormat("7", "d");
DateTime.fromFormat("07", "dd");

Время

  • H / HH — 24-часовой формат
  • h / hh — 12-часовой формат
  • m / mm — минуты
  • s / ss — секунды
  • a — AM/PM
DateTime.fromFormat("14:30", "HH:mm");
DateTime.fromFormat("02:30 PM", "hh:mm a");

Строгость разбора

fromFormat по умолчанию работает достаточно строго: строка должна соответствовать шаблону полностью.

Пример несовпадения

DateTime.fromFormat("2026/05/25", "dd-MM-yyyy");

Результат: Invalid DateTime, так как разделители и порядок не совпадают.

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

Один из ключевых аспектов fromFormat — зависимость от локали при разборе текстовых месяцев и дней недели.

DateTime.fromFormat("mai", "MMM", { locale: "fr" });

Без корректной локали строка может быть не распознана.

Разбор названий месяцев и дней недели

Месяцы

DateTime.fromFormat("février 2026", "MMMM yyyy", { locale: "fr" });

Дни недели

  • E — день недели (числовой)
  • EEE — сокращённое название
  • EEEE — полное название
DateTime.fromFormat("Monday", "EEEE", { locale: "en" });

Опция zone

Позволяет задать временную зону при парсинге:

DateTime.fromFormat("25-05-2026 10:00", "dd-MM-yyyy HH:mm", {
  zone: "Europe/Paris"
});

Если зона не указана, используется локальная зона окружения.

Опция setZone

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

DateTime.fromFormat("2026-05-25 10:00+03:00", "yyyy-MM-dd HH:mmZZ", {
  setZone: true
});

Обработка смещений часового пояса

Токен Z и его вариации:

  • Z — смещение вида +03:00
  • ZZ — более гибкий формат
  • ZZZ — сокращённые варианты
DateTime.fromFormat("2026-05-25 +0300", "yyyy-MM-dd ZZZZ");

Частичный парсинг

fromFormat позволяет извлекать не все компоненты сразу. Например, только дату без времени:

DateTime.fromFormat("25/05/2026", "dd/MM/yyyy");

В таком случае время устанавливается в 00:00:00.

Поведение при ошибках

Если строка не соответствует формату:

const dt = DateTime.fromFormat("invalid", "dd-MM-yyyy");

console.log(dt.isValid); // false
console.log(dt.invalidReason);

Основные причины:

  • mismatch (несоответствие формату)
  • unparsable (невозможность интерпретации токенов)
  • invalid input (некорректные значения)

Использование escape-символов

Если формат содержит литералы, совпадающие с токенами, используется экранирование:

DateTime.fromFormat("day 25", "'day' dd");

Кавычки ' фиксируют текст как литерал.

Сложные форматы

Комбинирование даты, времени и текста

DateTime.fromFormat(
  "Report generated: 25-05-2026 at 14:30",
  "'Report generated:' dd-MM-yyyy 'at' HH:mm"
);

Формат с миллисекундами

  • S, SS, SSS — миллисекунды
DateTime.fromFormat("14:30:12.345", "HH:mm:ss.SSS");

Поведение с двухзначными годами

При использовании yy Luxon применяет алгоритм интерпретации века:

  • значения интерпретируются относительно текущего века
  • возможны смещения в зависимости от контекста конфигурации
DateTime.fromFormat("26", "yy"); // может интерпретироваться как 2026

Сравнение с другими методами Luxon

fromISO

  • ожидает строгий ISO 8601
  • не требует шаблона

fromJSDate

  • принимает объект Date

fromFormat

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

Типичные сценарии использования

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

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

Обработка логов

DateTime.fromFormat(logLine, "yyyy/MM/dd HH:mm:ss");

Интеграция с внешними API

DateTime.fromFormat(apiDate, "MM-dd-yyyy HH:mm");

Особенности производительности

  • fromFormat медленнее fromISO
  • требует предварительного анализа токенов
  • локализация увеличивает стоимость парсинга

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

Несоответствие разделителей

DateTime.fromFormat("2026-05-25", "dd/MM/yyyy");

Игнорирование локали

DateTime.fromFormat("mai", "MMM"); // может не сработать без locale

Неверный порядок токенов

DateTime.fromFormat("05-2026-25", "dd-MM-yyyy"); // ошибка структуры

Практика построения устойчивых форматов

При проектировании формата для fromFormat рекомендуется:

  • избегать неоднозначных форматов (например, MM/dd/yyyy без контекста)
  • фиксировать разделители
  • явно задавать локаль при текстовых значениях
  • не смешивать разные порядки даты без необходимости

Работа с неполными данными

Если часть данных отсутствует, Luxon не заполняет их автоматически:

DateTime.fromFormat("25-05-2026", "dd-MM-yyyy"); // время = 00:00

Влияние календарной системы

Luxon использует григорианский календарь, и fromFormat интерпретирует входные данные в его рамках. Нестандартные календарные системы не поддерживаются напрямую через этот метод.

Оглавление