Метод setZone

Метод setZone в библиотеке Luxon предназначен для изменения временной зоны у объекта DateTime без изменения самого момента времени или с его пересчётом — в зависимости от параметров. Ключевая особенность заключается в том, что объект DateTime в Luxon остаётся неизменяемым: любой вызов setZone возвращает новый экземпляр.

Основная задача метода — интерпретация уже существующего значения времени в другом часовом поясе.

Важно: поведение метода зависит от параметра сохранения локального времени, который определяет, будет ли изменена «абсолютная точка времени» или только её отображение.

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

dt.setZone(zone: string | Zone, { keepLocalTime?: boolean } = {}): DateTime

Параметры:

  • zone — строка IANA-таймзоны ("Europe/Paris", "Asia/Almaty") или объект Zone
  • keepLocalTime — логический флаг, управляющий стратегией преобразования времени

Возвращаемое значение — новый объект DateTime.

Поведение без сохранения локального времени

При keepLocalTime: false (значение по умолчанию) происходит пересчёт момента времени в новую зону.

Логика работы

  • исходный момент времени сохраняется как абсолютная точка UTC
  • отображение времени пересчитывается под новую зону
  • изменяются час, минута, дата при необходимости

Пример

import { DateTime } from "luxon";

const dt = DateTime.fromISO("2026-01-01T12:00:00", { zone: "UTC" });

const converted = dt.setZone("Asia/Tokyo");

converted.toISO();

Результат отражает тот же момент времени, но в часовом поясе Токио.

Поведение с сохранением локального времени

При keepLocalTime: true происходит иной сценарий: локальные значения времени остаются неизменными, но меняется их интерпретация.

Логика работы

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

Пример

const dt = DateTime.fromISO("2026-01-01T12:00:00", { zone: "UTC" });

const shifted = dt.setZone("Asia/Tokyo", { keepLocalTime: true });

shifted.toISO();

В этом случае 12:00 UTC начинает трактоваться как 12:00 Tokyo, что соответствует другому моменту времени.

Различие режимов поведения

Режим Что сохраняется Что изменяется
default (keepLocalTime: false) абсолютное время локальное отображение
keepLocalTime: true локальные компоненты абсолютное время

Ключевое различие: первый режим «переводит время», второй — «переназначает зону без сдвига цифр».

Работа с IANA-зонами

Метод поддерживает стандартные идентификаторы IANA:

  • Europe/London
  • Europe/Moscow
  • Asia/Almaty
  • America/New_York

При передаче некорректной зоны Luxon использует fallback на локальную систему или UTC, в зависимости от конфигурации окружения.

Иммутабельность DateTime

Каждый вызов setZone создаёт новый объект:

const original = DateTime.local();
const upd ated = original.setZone("UTC");

original === updated; // false

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

Взаимодействие с UTC и локальным временем

Метод тесно связан с другими функциями Luxon:

toUTC и toLocal

dt.setZone("UTC");
dt.toLocal();
  • setZone изменяет зону интерпретации
  • toUTC и toLocal выполняют специализированные преобразования

fromObject и zone

DateTime.fromObject({ zone: "Asia/Tokyo" });

setZone применяется уже к существующему объекту, тогда как fromObject задаёт зону при создании.

Поведение при цепочках вызовов

Метод хорошо комбинируется с форматированием и арифметикой времени:

const dt = DateTime.local()
  .plus({ days: 1 })
  .setZone("Europe/Paris")
  .se t({ hour: 10 });

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

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

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

Использование keepLocalTime: true без понимания последствий приводит к смещению абсолютного времени.

Неправильная интерпретация зоны

dt.setZone("UTC+3");

Подобный формат не является стандартным IANA-идентификатором и может давать непредсказуемый результат.

Предположение о мутабельности

dt.setZone("UTC");
console.log(dt.zoneName);

Исходный объект остаётся неизменным, что часто игнорируется при первом знакомстве с API.

Особенности внутренней работы

Luxon хранит момент времени в UTC и отдельно — информацию о временной зоне. setZone изменяет именно слой интерпретации:

  • timestamp остаётся базовым
  • зона перепривязывает отображение
  • при необходимости пересчитываются локальные компоненты

Применение в многозонных системах

В системах, работающих с несколькими регионами, setZone используется для:

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

Особенности при сериализации

После вызова setZone результат сериализации отражает новую зону:

dt.setZone("Asia/Tokyo").toJSON();

В строке ISO будет указана соответствующая временная зона или смещение.

Совместимость с форматированием

Метод влияет на все последующие операции форматирования:

dt.setZone("Europe/Paris").toFormat("HH:mm");

Вывод зависит от выбранной зоны, а не от исходной.

Поведение с относительными вычислениями

При добавлении или вычитании времени сначала выполняется пересчёт к UTC, затем применяется зона:

dt.setZone("UTC").plus({ hours: 5 });

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

Оглавление