Метод toLocaleString

Метод toLocaleString в библиотеке Luxon представляет собой инструмент форматирования даты и времени на основе локали пользователя и стандартов Intl. Он используется для получения человекочитаемой строки с учётом региональных настроек, языка и предпочтений отображения времени.

Общая концепция

toLocaleString опирается на встроенный механизм интернационализации JavaScript (Intl.DateTimeFormat). В отличие от низкоуровневого форматирования через шаблоны, метод автоматически адаптирует вывод под локаль и выбранные параметры.

Ключевая особенность заключается в том, что метод работает с объектом DateTime и возвращает строку, уже готовую для отображения без дополнительной обработки.

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

DateTime.toLocaleString(formatOpts?, options?)

Фактически метод вызывается у экземпляра:

dt.toLocaleString(formatOpts?, options?)

Параметры

formatOpts — предустановленный формат или объект конфигурации Luxon.

Поддерживаются:

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

options — объект, совместимый с Intl.DateTimeFormatOptions, либо расширения Luxon:

  • locale — принудительная локаль
  • numberingSystem — система нумерации
  • timeZone — временная зона

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

Luxon предоставляет набор стандартных форматов, упрощающих вывод дат без необходимости ручной настройки.

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

dt.toLocaleString(DateTime.DATE_SHORT)

Пример вывода:

24.05.2026

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

dt.toLocaleString(DateTime.DATE_MED)

Пример:

24 мая 2026 г.

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

dt.toLocaleString(DateTime.DATE_FULL)

Пример:

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

Полный формат даты и времени

dt.toLocaleString(DateTime.DATETIME_FULL)

Пример:

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

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

dt.toLocaleString(DateTime.TIME_SIMPLE)

Пример:

14:35

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

Локализация является ключевым аспектом метода. Luxon автоматически использует системную локаль, но её можно переопределить.

dt.toLocaleString(DateTime.DATE_FULL, {
  locale: 'en-US'
})

Результат:

Sunday, May 24, 2026

Для русской локали:

dt.toLocaleString(DateTime.DATE_FULL, {
  locale: 'ru'
})

Работа с временными зонами

Метод учитывает установленную временную зону объекта DateTime, но её можно переопределить через параметры.

dt.toLocaleString(DateTime.DATETIME_FULL, {
  timeZone: 'Europe/Moscow'
})

Это влияет на отображаемое время без изменения исходного значения объекта.

Использование Intl-опций

Вместо предустановленных форматов можно передать объект конфигурации Intl.DateTimeFormatOptions.

dt.toLocaleString({
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
})

Результат:

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

Такой подход позволяет строить полностью кастомные форматы без использования toFormat.

Комбинирование форматов

В реальных приложениях часто используется комбинация даты и времени через встроенные шаблоны Luxon.

dt.toLocaleString({
  ...DateTime.DATETIME_MED,
  locale: 'ru'
})

Однако приоритет имеет явный объект Intl-конфигурации, если он передан.

Отличие от toFormat

Метод toLocaleString отличается от toFormat принципом работы:

  • toLocaleString использует Intl и локаль системы
  • toFormat использует кастомные токены Luxon

Пример:

dt.toFormat('dd LLLL yyyy')

и

dt.toLocaleString(DateTime.DATE_FULL)

Первый вариант полностью контролируется разработчиком, второй — адаптируется к региону.

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

Если объект DateTime является некорректным (Invalid DateTime), метод возвращает строку:

Invalid DateTime

Это важно при работе с парсингом дат и внешними источниками данных.

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

Вывод даты публикации

article.createdAt.toLocaleString(DateTime.DATETIME_MED)

Формирование интерфейса календаря

event.start.toLocaleString({
  weekday: 'long',
  month: 'long',
  day: 'numeric'
})

Отображение времени в пользовательской локали

now.setZone(user.timeZone).toLocaleString(DateTime.TIME_SIMPLE)

Унифицированный вывод для API

dt.toLocaleString(DateTime.DATETIME_FULL, {
  locale: 'en-GB',
  timeZone: 'UTC'
})

Особенности поведения

  • Форматирование всегда возвращает строку
  • Не изменяет исходный объект DateTime
  • Полностью зависит от Intl API окружения
  • Поддерживает все стандартные локали ECMAScript
  • Может давать разные результаты в разных средах выполнения

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

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

dt.toLocaleString(DateTime.DATE_FULL)

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

Неверное ожидание строгого формата

Метод не гарантирует фиксированный формат строки. Например, порядок компонентов даты может отличаться:

  • RU: 24 мая 2026 г.
  • US: May 24, 2026

Смешивание с toFormat

Попытка использовать токены Luxon в toLocaleString приводит к некорректному выводу, так как метод не интерпретирует форматные строки.

Оглавление