Макросы форматирования

Библиотека Luxon предоставляет два основных подхода к форматированию даты и времени:

  • форматирование через строковые токены;
  • форматирование через готовые макросы.

Макросы предназначены для быстрого получения локализованных строк даты и времени без необходимости вручную составлять шаблоны. Вместо сложных комбинаций вроде dd.MM.yyyy HH:mm:ss используются предопределённые наборы форматов.

Назначение макросов

Макросы решают несколько задач:

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

Пример:

import { DateTime } from "luxon";

const dt = DateTime.now();

console.log(dt.toLocaleString(DateTime.DATE_FULL));

Результат для русской локали:

24 мая 2026 г.

Для английской локали:

May 24, 2026

Один и тот же код адаптируется под язык и регион.

Метод toLocaleString

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

Общий синтаксис:

DateTime.toLocaleString(formatMacro)

Пример:

const dt = DateTime.now();

console.log(
  dt.toLocaleString(DateTime.TIME_SIMPLE)
);

Результат:

14:35

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

DATE_SHORT

Краткий формат даты.

const dt = DateTime.local(2026, 5, 24);

console.log(
  dt.toLocaleString(DateTime.DATE_SHORT)
);

Результат:

24.05.2026

Для en-US:

5/24/2026

DATE_MED

Средний формат даты.

console.log(
  dt.toLocaleString(DateTime.DATE_MED)
);

Результат:

24 мая 2026 г.

DATE_MED_WITH_WEEKDAY

Средний формат даты с днём недели.

console.log(
  dt.toLocaleString(DateTime.DATE_MED_WITH_WEEKDAY)
);

Результат:

вс, 24 мая 2026 г.

DATE_FULL

Полный формат даты.

console.log(
  dt.toLocaleString(DateTime.DATE_FULL)
);

Результат:

24 мая 2026 г.

Для некоторых локалей формат становится более подробным.

DATE_HUGE

Максимально подробный формат даты.

console.log(
  dt.toLocaleString(DateTime.DATE_HUGE)
);

Результат:

воскресенье, 24 мая 2026 г.

Макросы времени

TIME_SIMPLE

Краткое время.

console.log(
  dt.toLocaleString(DateTime.TIME_SIMPLE)
);

Результат:

14:35

TIME_WITH_SECONDS

Время с секундами.

console.log(
  dt.toLocaleString(DateTime.TIME_WITH_SECONDS)
);

Результат:

14:35:48

TIME_WITH_SHORT_OFFSET

Время с кратким часовым поясом.

console.log(
  dt.toLocaleString(DateTime.TIME_WITH_SHORT_OFFSET)
);

Результат:

14:35 GMT+6

TIME_WITH_LONG_OFFSET

Время с полным смещением.

console.log(
  dt.toLocaleString(DateTime.TIME_WITH_LONG_OFFSET)
);

Результат:

14:35 GMT+06:00

TIME_24_SIMPLE

24-часовой формат.

console.log(
  dt.toLocaleString(DateTime.TIME_24_SIMPLE)
);

Результат:

14:35

TIME_24_WITH_SECONDS

24-часовой формат с секундами.

console.log(
  dt.toLocaleString(DateTime.TIME_24_WITH_SECONDS)
);

Результат:

14:35:48

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

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

DATETIME_SHORT

console.log(
  dt.toLocaleString(DateTime.DATETIME_SHORT)
);

Результат:

24.05.2026, 14:35

DATETIME_SHORT_WITH_SECONDS

console.log(
  dt.toLocaleString(DateTime.DATETIME_SHORT_WITH_SECONDS)
);

Результат:

24.05.2026, 14:35:48

DATETIME_MED

console.log(
  dt.toLocaleString(DateTime.DATETIME_MED)
);

Результат:

24 мая 2026 г., 14:35

DATETIME_MED_WITH_SECONDS

console.log(
  dt.toLocaleString(DateTime.DATETIME_MED_WITH_SECONDS)
);

Результат:

24 мая 2026 г., 14:35:48

DATETIME_FULL

console.log(
  dt.toLocaleString(DateTime.DATETIME_FULL)
);

Результат:

24 мая 2026 г., 14:35 GMT+6

DATETIME_FULL_WITH_SECONDS

console.log(
  dt.toLocaleString(DateTime.DATETIME_FULL_WITH_SECONDS)
);

Результат:

24 мая 2026 г., 14:35:48 GMT+6

DATETIME_HUGE

console.log(
  dt.toLocaleString(DateTime.DATETIME_HUGE)
);

Результат:

воскресенье, 24 мая 2026 г., 14:35 GMT+6

DATETIME_HUGE_WITH_SECONDS

console.log(
  dt.toLocaleString(DateTime.DATETIME_HUGE_WITH_SECONDS)
);

Результат:

воскресенье, 24 мая 2026 г., 14:35:48 GMT+6

Локализация макросов

Макросы полностью зависят от локали.

Локаль задаётся методом setLocale().

Русская локаль

const dt = DateTime.now()
  .setLocale("ru");

console.log(
  dt.toLocaleString(DateTime.DATE_HUGE)
);

Результат:

воскресенье, 24 мая 2026 г.

Английская локаль

const dt = DateTime.now()
  .setLocale("en");

console.log(
  dt.toLocaleString(DateTime.DATE_HUGE)
);

Результат:

Sunday, May 24, 2026

Немецкая локаль

const dt = DateTime.now()
  .setLocale("de");

console.log(
  dt.toLocaleString(DateTime.DATE_HUGE)
);

Результат:

Sonntag, 24. Mai 2026

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

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

const dt = DateTime.now()
  .setZone("Europe/Berlin")
  .setLocale("de");

console.log(
  dt.toLocaleString(DateTime.DATETIME_FULL)
);

Результат:

24. Mai 2026, 10:35 MESZ

Отличие макросов от toFormat

В Luxon существует два механизма форматирования:

Метод Назначение
toLocaleString() локализованные макросы
toFormat() ручные шаблоны

Пример с макросом

dt.toLocaleString(DateTime.DATE_SHORT);

Пример с токенами

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

Когда использовать макросы

Макросы особенно удобны:

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

Когда лучше использовать toFormat

Метод toFormat() предпочтительнее:

  • при строгом шаблоне;
  • при нестандартном формате;
  • при генерации файлов;
  • при интеграции с внешними API;
  • при необходимости полного контроля над строкой.

Пример:

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

Комбинирование макросов с настройками Intl

Метод toLocaleString() может принимать объект параметров Intl.DateTimeFormat.

Пример:

console.log(
  dt.toLocaleString({
    weekday: "long",
    month: "short",
    day: "numeric"
  })
);

Результат:

воскресенье, 24 мая

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

Макросы можно расширять дополнительными параметрами.

console.log(
  dt.toLocaleString(
    DateTime.DATE_FULL,
    {
      locale: "fr"
    }
  )
);

Результат:

24 mai 2026

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

Luxon поддерживает различные системы записи чисел.

const dt = DateTime.now().reconfigure({
  locale: "ar",
  numberingSystem: "arab"
});

console.log(
  dt.toLocaleString(DateTime.DATE_FULL)
);

Результат:

٢٤ مايو ٢٠٢٦

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

Поддерживаются альтернативные календари.

const dt = DateTime.now().reconfigure({
  locale: "ja",
  outputCalendar: "japanese"
});

console.log(
  dt.toLocaleString(DateTime.DATE_FULL)
);

Результат может выглядеть так:

令和8年5月24日

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

const utc = DateTime.utc();

console.log(
  utc.toLocaleString(
    DateTime.DATETIME_FULL
  )
);

Результат:

24 мая 2026 г., 08:35 UTC

Форматирование конкретной даты

const birthday = DateTime.local(1995, 12, 18);

console.log(
  birthday.toLocaleString(
    DateTime.DATE_HUGE
  )
);

Результат:

понедельник, 18 декабря 1995 г.

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

const dates = [
  DateTime.local(2026, 1, 1),
  DateTime.local(2026, 5, 9),
  DateTime.local(2026, 12, 31)
];

const result = dates.map(date =>
  date.toLocaleString(DateTime.DATE_FULL)
);

console.log(result);

Результат:

[
  '1 января 2026 г.',
  '9 мая 2026 г.',
  '31 декабря 2026 г.'
]

Частые ошибки

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

Ошибка:

dt.toFormat(DateTime.DATE_FULL);

toFormat() не работает с макросами.

Отсутствие локали

Без локали формат зависит от окружения:

dt.toLocaleString(DateTime.DATE_FULL);

На разных системах вывод может отличаться.

Путаница между 12-часовым и 24-часовым временем

DateTime.TIME_SIMPLE

может выводить:

2:35 PM

в английской локали.

Для принудительного 24-часового режима:

DateTime.TIME_24_SIMPLE

Практический пример интерфейса

import { DateTime } from "luxon";

const createdAt = DateTime.fromISO(
  "2026-05-24T14:35:48"
);

console.log(
  createdAt.toLocaleString(
    DateTime.DATETIME_MED
  )
);

Результат:

24 мая 2026 г., 14:35

Практический пример мультиязычного приложения

function formatDate(date, locale) {
  return date
    .setLocale(locale)
    .toLocaleString(DateTime.DATE_HUGE);
}

const dt = DateTime.now();

console.log(formatDate(dt, "ru"));
console.log(formatDate(dt, "en"));
console.log(formatDate(dt, "fr"));

Результат:

воскресенье, 24 мая 2026 г.
Sunday, May 24, 2026
dimanche 24 mai 2026

Сводная таблица макросов

Макрос Пример
DATE_SHORT 24.05.2026
DATE_MED 24 мая 2026 г.
DATE_FULL 24 мая 2026 г.
DATE_HUGE воскресенье, 24 мая 2026 г.
TIME_SIMPLE 14:35
TIME_WITH_SECONDS 14:35:48
DATETIME_SHORT 24.05.2026, 14:35
DATETIME_MED 24 мая 2026 г., 14:35
DATETIME_FULL 24 мая 2026 г., 14:35 GMT+6
DATETIME_HUGE воскресенье, 24 мая 2026 г., 14:35 GMT+6
Оглавление