Метод toString и toLocaleString

В библиотеке Luxon объект DateTime представляет момент времени с учётом часового пояса, локали и внутренних настроек календаря. Метод toString() используется для получения строкового представления этого объекта, однако его поведение отличается от привычных методов форматирования дат в JavaScript.

Метод:

DateTime.toString(): string

возвращает стандартное ISO-подобное представление даты и времени. Фактически, это обёртка над toISO(), но с дополнительной семантикой, ориентированной на отладочные и диагностические сценарии.

Пример:

import { DateTime } from "luxon";

const dt = DateTime.local(2026, 5, 23, 14, 30);

console.log(dt.toString());

Результат будет примерно таким:

2026-05-23T14:30:00.000+03:00

Ключевые особенности:

  • формат основан на ISO 8601;
  • всегда включает информацию о временной зоне;
  • используется точное представление времени без локализации;
  • предназначен скорее для отладки, чем для отображения пользователю.

Важно учитывать, что toString() не предназначен для гибкой кастомизации. Любые попытки влиять на форматирование через локаль или настройки форматтеров не изменяют его поведение.

Семантика ISO-представления

В Luxon ISO-строка выполняет роль универсального формата обмена данными. Метод toString() фактически фиксирует объект DateTime в виде, который:

  • однозначно интерпретируется в разных системах;
  • сохраняет временную зону;
  • подходит для сериализации;
  • может быть обратно преобразован через DateTime.fromISO().

Пример обратимости:

const original = DateTime.local();
const serialized = original.toString();
const restored = DateTime.fromISO(serialized);

Такая модель делает toString() удобным в логировании и передаче данных между сервисами, но не для интерфейсов.

Метод toLocaleString() и локализованное форматирование

Метод toLocaleString() предназначен для отображения даты и времени в человеко-ориентированном формате с учётом локали и предустановленных шаблонов Luxon.

Сигнатура:

DateTime.toLocaleString(formatOpts?: DateTimeFormatOptions | Object): string

Этот метод использует либо встроенные пресеты Luxon, либо стандартные параметры Intl.DateTimeFormat.

Предустановленные форматы Luxon

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

  • DateTime.DATE_SHORT
  • DateTime.DATE_MED
  • DateTime.DATE_FULL
  • DateTime.DATE_HUGE
  • DateTime.TIME_SIMPLE
  • DateTime.TIME_WITH_SECONDS
  • DateTime.DATETIME_SHORT
  • DateTime.DATETIME_MED
  • DateTime.DATETIME_FULL
  • DateTime.DATETIME_HUGE

Пример:

const dt = DateTime.local(2026, 5, 23, 14, 30);

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

Возможный результат:

23 мая 2026 г., 14:30

Формат зависит от локали, установленной в среде или переданной в объекте DateTime.

Локаль и её влияние

Luxon активно использует локаль, заданную через параметр locale или системные настройки:

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

При этом toLocaleString() автоматически адаптирует:

  • порядок элементов даты;
  • названия месяцев;
  • формат времени (12/24 часа);
  • разделители.

Пример различий:

const dt = DateTime.local(2026, 5, 23, 14, 30);

console.log(dt.setLocale("en").toLocaleString(DateTime.DATETIME_MED));
console.log(dt.setLocale("ru").toLocaleString(DateTime.DATETIME_MED));

Результат:

May 23, 2026, 2:30 PM
23 мая 2026 г., 14:30

Использование кастомных параметров через Intl

Помимо пресетов, toLocaleString() принимает объект формата, аналогичный Intl.DateTimeFormatOptions.

Пример:

const dt = DateTime.local(2026, 5, 23, 14, 30);

console.log(
  dt.toLocaleString({
    weekday: "long",
    year: "numeric",
    month: "long",
    day: "2-digit",
    hour: "2-digit",
    minute: "2-digit"
  })
);

Результат будет зависеть от локали:

суббота, 23 мая 2026 г., 14:30

Этот режим даёт максимальную гибкость, позволяя строить форматирование уровня стандартного Intl.DateTimeFormat, но с удобным API Luxon.

Сравнение toString() и toLocaleString()

Оба метода возвращают строку, но их назначение принципиально различается.

toString()

  • машинно-ориентированный формат;
  • ISO 8601;
  • фиксированная структура;
  • независимость от локали;
  • пригоден для логов и сериализации.

toLocaleString()

  • человеко-ориентированный вывод;
  • зависит от локали;
  • поддерживает шаблоны и пресеты;
  • адаптируется к региональным стандартам;
  • используется в UI.

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

Luxon хранит информацию о временной зоне внутри DateTime. Оба метода учитывают её, но по-разному:

  • toString() всегда явно показывает смещение:
DateTime.local().toString();

пример:

2026-05-23T14:30:00.000+06:00
  • toLocaleString() обычно скрывает зону, если формат не требует её отображения:
DateTime.local().toLocaleString(DateTime.DATETIME_SHORT);

пример:

23.05.2026, 14:30

При необходимости можно включить отображение зоны через кастомный формат.

Поведение при некорректных датах

Если объект DateTime невалиден, оба метода ведут себя предсказуемо:

const dt = DateTime.fromObject({ year: 99999 });

console.log(dt.isValid); // false
console.log(dt.toString());
console.log(dt.toLocaleString());

Результат:

Invalid DateTime
Invalid DateTime

Luxon не выбрасывает исключение, а возвращает строку "Invalid DateTime", что упрощает обработку ошибок в цепочках данных.

Влияние внутренних настроек outputCalendar

Luxon поддерживает альтернативные календари (например, islamic, hebrew). Это влияет только на toLocaleString():

const dt = DateTime.local().reconfigure({ outputCalendar: "islamic" });

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

В результате дата будет отображаться в соответствующей календарной системе, тогда как toString() всегда остаётся в ISO-формате Григорианского календаря.

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

Разделение применения методов выстраивается по характеру данных.

toString() применяется при:

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

toLocaleString() применяется при:

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

Особенности поведения при цепочках методов

Luxon допускает последовательное преобразование объектов, при котором форматирование может зависеть от последнего этапа:

const dt = DateTime.local()
  .setZone("Europe/Paris")
  .setLocale("fr");

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

Здесь:

  • toLocaleString() учитывает и локаль, и часовой пояс;
  • toString() фиксирует момент времени в ISO без адаптации под региональные особенности.

Различие в стабильности формата

Одним из ключевых аспектов является стабильность:

  • toString() гарантирует одинаковый результат для одного и того же момента времени независимо от окружения;

  • toLocaleString() может давать разные результаты в зависимости от:

    • системной локали;
    • настроек браузера или Node.js;
    • версии ICU (International Components for Unicode).

Это различие критично при проектировании систем, где важна предсказуемость сериализации.

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

В архитектурных решениях Luxon метод toString() часто выступает как промежуточный слой между внутренним представлением времени и внешними системами. Он обеспечивает стабильную транспортировку данных.

toLocaleString() выполняет противоположную функцию — финальное представление, ориентированное на пользователя и контекст отображения.

Такое разделение формирует чёткую границу между:

  • доменной моделью времени;
  • слоем представления;
  • и слоем обмена данными.
Оглавление