Свойство zoneName

В библиотеке Luxon работа с временными зонами построена вокруг двух ключевых понятий: самой зоны (zone) и её текстового идентификатора (zoneName). Свойство zoneName представляет собой строковое имя временной зоны, в которой интерпретируется конкретный объект DateTime.

Сущность zoneName

zoneName — это строковое представление текущей временной зоны объекта DateTime. Оно отражает идентификатор зоны в формате:

  • IANA-зон: "Europe/Berlin", "Asia/Almaty", "America/New_York"
  • фиксированных смещений: "UTC+3", "UTC-5"
  • специальных зон Luxon: "local", "utc"

Ключевая особенность

zoneName не является самостоятельным источником времени или смещения. Это только имя, связанное с объектом зоны (Zone), которое используется внутри Luxon для вычислений.

Получение значения zoneName

Свойство доступно у любого экземпляра DateTime.

import { DateTime } from "luxon";

const dt = DateTime.now();

dt.zoneName;

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

"Europe/Moscow"

или

"Asia/Almaty"

Связь с объектом zone

zoneName тесно связано с полем zone. Однако между ними есть различие:

  • zone — объект временной зоны (Zone)
  • zoneName — строковый идентификатор этой зоны
const dt = DateTime.now();

dt.zone;      // Zone instance
dt.zoneName;  // string

Важный момент

zoneName является производным значением от zone.id.

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

IANA-зоны

Для стандартных временных зон возвращается их полное имя:

DateTime.now().setZone("Asia/Tokyo").zoneName;

Результат:

"Asia/Tokyo"

UTC-зона

DateTime.utc().zoneName;

Результат:

"UTC"

Локальная зона

DateTime.local().zoneName;

Результат зависит от системы:

"Europe/Paris"

или другая системная зона.

Фиксированные смещения

При использовании фиксированных offset-зон:

DateTime.now().setZone("UTC+5").zoneName;

Результат:

"UTC+5"

Поведение при преобразованиях зон

При изменении зоны через setZone, значение zoneName меняется вместе с контекстом времени.

const dt = DateTime.now();

const shifted = dt.setZone("America/New_York");

shifted.zoneName;

Результат:

"America/New_York"

При этом сам момент времени остаётся тем же, меняется только интерпретация.

Отличие от offsetNameShort и offset

Свойство zoneName часто путается с другими временными метаданными.

zoneName

  • имя зоны
  • не зависит от текущего времени суток
  • строковый идентификатор

offset

  • числовое смещение в минутах
dt.offset; // например -180

offsetNameShort

  • человекочитаемое смещение
dt.offsetNameShort; // "GMT+3"

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

При форматировании даты zoneName может использоваться как дополнительная метаинформация:

const dt = DateTime.now().setZone("Asia/Almaty");

`${dt.toISO()} ${dt.zoneName}`;

Результат:

2026-05-23T14:30:00.000+05:00 Asia/Almaty

Неизменяемость значения

Экземпляры DateTime в Luxon являются иммутабельными. Это означает:

  • изменение зоны создаёт новый объект
  • zoneName всегда соответствует текущему состоянию объекта
const a = DateTime.now();
const b = a.setZone("UTC");

a.zoneName !== b.zoneName;

Поведение при отсутствии явной зоны

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

DateTime.fromMillis(0).zoneName;

Результат:

локальная системная зона

Использование в логике приложений

zoneName часто применяется для:

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

Пример хранения состояния:

const state = {
  timestamp: DateTime.now().toISO(),
  zone: DateTime.now().zoneName
};

Особенности поведения с системными зонами

В некоторых окружениях (например, Node.js или браузерах) zoneName может отличаться:

  • контейнеры могут использовать UTC
  • серверы — системную зону ОС
  • браузеры — локальную зону пользователя

Это делает значение zoneName зависимым от среды выполнения.

Ограничения

  • не содержит информации о летнем времени напрямую
  • не отражает текущий offset
  • не является вычисляемым временем
  • не заменяет полноценную работу с Zone объектом

Взаимодействие с сериализацией

При использовании toJSON() или toISO() zoneName не включается автоматически:

const dt = DateTime.now();

JSON.stringify(dt);

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

Для сохранения зоны требуется явное добавление:

{
  iso: dt.toISO(),
  zoneName: dt.zoneName
}
Оглавление