Settings.defaultOutputCalendar

Общая роль настройки календарной системы

В библиотеке Luxon управление форматированием дат и времени основано на международном стандарте ICU и возможностях Intl.DateTimeFormat. Одним из ключевых аспектов локализации является календарная система, определяющая способ представления дат.

Settings.defaultOutputCalendar задаёт календарь по умолчанию, который используется при форматировании объектов DateTime, если календарь явно не указан.

Календарь влияет исключительно на отображение, не изменяя внутреннее представление времени (которое всегда хранится в UTC-основанной временной шкале).

Доступ к настройке

Настройка находится в глобальном объекте конфигурации Luxon:

import { Settings } from "luxon";

Settings.defaultOutputCalendar = "gregory";

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

Поддерживаемые календарные системы

Luxon опирается на Intl, поэтому список календарей соответствует ICU календарям:

  • gregory — григорианский календарь (по умолчанию)
  • buddhist — буддийский календарь
  • chinese — китайский лунно-солнечный календарь
  • hebrew — еврейский календарь
  • islamic — исламский календарь
  • indian — индийский национальный календарь
  • japanese — японская имперская система летоисчисления

Каждый из них влияет на отображение года, месяца и иногда структуры даты.

Механизм влияния на форматирование

Настройка применяется при использовании методов локализации:

  • toLocaleString()
  • toLocaleDateString()
  • toFormat() (в некоторых локализационных шаблонах через Intl)
  • любые методы, использующие Intl.DateTimeFormat под капотом

Пример:

import { DateTime, Settings } from "luxon";

const dt = DateTime.fromISO("2026-01-15T10:00:00");

Settings.defaultOutputCalendar = "gregory";

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

Вывод будет соответствовать григорианскому календарю.

Изменение календаря и влияние на результат

При смене календарной системы изменяется представление года и иногда структура даты.

import { DateTime, Settings } from "luxon";

const dt = DateTime.fromObject({
  year: 2026,
  month: 5,
  day: 23
});

Settings.defaultOutputCalendar = "gregory";
console.log(dt.toLocaleString(DateTime.DATE_FULL));

Settings.defaultOutputCalendar = "japanese";
console.log(dt.toLocaleString(DateTime.DATE_FULL));

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

Взаимодействие с Intl и локалью

Календарная система тесно связана с локалью (Settings.defaultLocale). При отсутствии явного указания календаря Luxon комбинирует:

  • локаль пользователя
  • системный календарь по умолчанию
  • Settings.defaultOutputCalendar

Пример:

import { Settings } from "luxon";

Settings.defaultLocale = "ar";
Settings.defaultOutputCalendar = "islamic";

В этом случае форматирование будет учитывать исламский календарь, если локаль поддерживает соответствующие настройки.

Отличие от setZone и других Settings

Settings.defaultOutputCalendar не влияет на:

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

Она влияет исключительно на визуальное представление даты.

Переопределение на уровне DateTime

Глобальная настройка может быть переопределена для конкретного объекта:

import { DateTime } from "luxon";

const dt = DateTime.now().reconfigure({
  outputCalendar: "buddhist"
});

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

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

Практическое влияние на приложения

Использование разных календарей важно в системах:

  • международных интерфейсов
  • государственных сервисов
  • религиозных календарей
  • образовательных платформ
  • локализованных CRM и ERP систем

Например, в интерфейсе для пользователей Таиланда может быть уместен буддийский календарь:

import { Settings } from "luxon";

Settings.defaultOutputCalendar = "buddhist";

Особенности работы с форматами

Некоторые форматы сильнее зависят от календаря:

  • полные даты (DATE_FULL)
  • расширенные локализованные строки
  • форматы с годом (year)

При этом низкоуровневые форматы (ISO):

  • toISO()
  • toUTC()

не зависят от календаря вообще, так как работают с абсолютным временем.

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

1. Ожидание изменения внутреннего времени

Календарь не изменяет timestamp:

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

Settings.defaultOutputCalendar = "islamic";

dt.toISO(); // останется прежним

2. Использование неподдерживаемого календаря

Если браузер или Node.js не поддерживает календарь через Intl, настройка будет проигнорирована.

3. Смешение локали и календаря

Некоторые комбинации локали и календаря дают неожиданный формат, если регион не ожидает такой системы.

Совместимость и ограничения

Поддержка календарей зависит от окружения:

  • Node.js использует ICU build
  • браузеры используют собственный ICU
  • минимальные сборки могут не включать все календари

Luxon не реализует календари самостоятельно, а полностью полагается на Intl.DateTimeFormat.

Поведение при отсутствии настройки

Если Settings.defaultOutputCalendar не задан, используется:

  • системный календарь окружения
  • либо "gregory" как стандарт ICU

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

Влияние на сериализацию и вывод

При преобразовании DateTime в строковые представления через локализацию:

  • календарь применяется автоматически
  • ISO-представления остаются неизменными
  • числовые поля year, month, day могут отображаться иначе в зависимости от календаря
const dt = DateTime.fromISO("2026-05-23");

Settings.defaultOutputCalendar = "chinese";

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

Архитектурная роль в Luxon

Settings.defaultOutputCalendar является частью глобального конфигурационного слоя, который включает:

  • defaultLocale
  • defaultZone
  • defaultOutputCalendar

Эти параметры формируют базовый контекст форматирования, на который опираются все экземпляры DateTime, если не задано иное.

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

Изменение настройки после создания объектов:

const dt = DateTime.now();

Settings.defaultOutputCalendar = "hebrew";

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

влияет только на последующее форматирование, но не на сам объект.

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

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

Settings.defaultLocale = "th";
Settings.defaultOutputCalendar = "buddhist";

или

Settings.defaultLocale = "ja";
Settings.defaultOutputCalendar = "japanese";

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

Взаимодействие с форматами Intl напрямую

Luxon передаёт календарь в Intl.DateTimeFormat:

new Intl.DateTimeFormat("en-US-u-ca-buddhist", {
  year: "numeric",
  month: "long",
  day: "numeric"
});

defaultOutputCalendar фактически влияет на параметр ca (calendar extension) в Unicode locale identifier.

Ограничения точности представления

Некоторые календари имеют отличную систему летоисчисления, что приводит к:

  • смещению года
  • специфическим эрам
  • нестандартным диапазонам дат

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

Оглавление