Temporal.ZonedDateTime.from()

Статический метод Temporal.ZonedDateTime.from() создаёт новый объект Temporal.ZonedDateTime из другого объекта Temporal.ZonedDateTime, объекта со свойствами даты, времени и часового пояса или строки в формате RFC 9557.

Синтаксис

Temporal.ZonedDateTime.from(info)
Temporal.ZonedDateTime.from(info, options)

Параметры

info

Одно из следующего:

• Экземпляр Temporal.ZonedDateTime, который создаёт копию этого экземпляра.
• Строка в формате RFC 9557, содержащая дату, необязательно время и смещение, аннотацию часового пояса и необязательно календарь.
• Объект, содержащий свойства, допустимые для метода Temporal.PlainDate.from() (calendar, era, eraYear, year, month, monthCode, day) или Temporal.PlainTime.from() (hour, minute, second, millisecond, microsecond, nanosecond). В объекте info необходимо явно указать год (как year или как era и eraYear), месяц (как month или monthCode) и день; остальные значения необязательны и будут установлены по умолчанию. Также необходимо указать следующие свойства:

  timeZone

  Строка или экземпляр Temporal.ZonedDateTime, представляющий используемый часовой пояс. Если указана сущность Temporal.ZonedDateTime, используется её часовой пояс. Если указана строка, она может быть идентификатором именованного часового пояса, идентификатором часового пояса со смещением или строкой даты и времени, содержащей идентификатор часового пояса или смещение (подробнее см. в разделе Часовые пояса и смещения). Свойства времени интерпретируются в этом часовом поясе.

  offset Необязательно

  Строка смещения в том же формате, что и смещение RFC 9557, но с необязательными компонентами секунд и долей секунды (±HH:mm:ss.sssssssss), представляющая смещение относительно UTC. Если это свойство не указано, смещение вычисляется на основе часового пояса и даты и времени. Значение "Z" недопустимо.

options Необязательно

Объект, содержащий некоторые или все следующие свойства (в порядке их получения и проверки):

disambiguation Необязательно

Что делать, если локальные дата и время неоднозначны в указанном часовом поясе (существует несколько моментов времени с такими локальными значениями или такого локального времени не существует). Возможные значения: "compatible", "earlier", "later" и "reject". По умолчанию используется "compatible". Подробнее об этих значениях см. в разделе Неоднозначность и разрывы при преобразовании локального времени в время UTC.

offset Необязательно

Что делать, если смещение явно указано в info, но недопустимо для указанного часового пояса и локального времени. Возможные значения: "use", "ignore", "reject" и "prefer". По умолчанию используется "reject". Подробнее об этих значениях см. в разделе Неоднозначность смещения.

overflow Необязательно

Строка, задающая поведение в случае, если компонент даты выходит за допустимый диапазон (при использовании объекта info). Возможные значения:

"constrain" (по умолчанию)

Компонент даты ограничивается допустимым диапазоном.

"reject"

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

Возвращаемое значение

Новый объект Temporal.ZonedDateTime, представляющий дату и время, заданные с помощью info в указанном calendar и timeZone.

Исключения

TypeError

Выбрасывается в одном из следующих случаев:

• info не является объектом или строкой.
• options не является объектом или undefined.
• Указанных свойств недостаточно для однозначного определения даты. Обычно необходимо указать year (или era и eraYear), month (или monthCode) и day.

RangeError

Выбрасывается в одном из следующих случаев:

• Указанные свойства, задающие один и тот же компонент, противоречат друг другу.
• Указанные нечисловые свойства недопустимы; например, если monthCode никогда не является допустимым кодом месяца в этом календаре.
• Указанные числовые свойства выходят за допустимый диапазон, а для options.overflow задано значение "reject".
• Настенные часы показывают неоднозначное время в этом часовом поясе, а для options.disambiguation задано значение "reject".
• Значение info не входит в представимый диапазон: ±10⁸ дней, или примерно ±273 972,6 года от эпохи Unix.

Примеры

Создание ZonedDateTime из объекта

// Year + month + day + hour + minute + second
const zdt = Temporal.ZonedDateTime.from({
  timeZone: "America/New_York",
  year: 2021,
  month: 7,
  day: 1,
  hour: 12,
  minute: 34,
  second: 56,
});
console.log(zdt.toString()); // "2021-07-01T12:34:56-04:00[America/New_York]"

Создание ZonedDateTime из строки

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56-04:00[America/New_York]",
);
console.log(zdt.toLocaleString()); // "7/1/2021, 12:34:56 PM EDT" (assuming en-US locale)

// Time given as UTC, and converted to local
const zdt2 = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56Z[America/New_York]",
);
console.log(zdt2.toString()); // "2021-07-01T08:34:56-04:00[America/New_York]"

Создание ZonedDateTime из строки ISO 8601 / RFC 3339

Обратите внимание, что Temporal.ZonedDateTime.from() отклоняет строки ISO 8601, в которых не указан идентификатор часового пояса. Это гарантирует, что часовой пояс всегда известен и может использоваться для определения различных смещений при изменении локального времени.

Чтобы разобрать строку ISO 8601, сначала создайте объект Temporal.Instant, а затем преобразуйте его в объект Temporal.ZonedDateTime. Можно указать любой часовой пояс, даже если он не соответствует смещению, изначально указанному в строке; локальное время будет скорректировано соответствующим образом.

const isoString = "2021-07-01T12:34:56+02:00";
const instant = Temporal.Instant.from(isoString);
const zdt = instant.toZonedDateTimeISO("America/New_York");
console.log(zdt.toString()); // "2021-07-01T06:34:56-04:00[America/New_York]"

Разрешение неоднозначности локального времени

Введение в эту ситуацию см. в разделе Неоднозначность и разрывы при преобразовании локального времени в время UTC.

const localTimeNotExist = "2024-03-10T02:05:00[America/New_York]";
// For non-existent times, "compatible" is equivalent to "later"
const zdt = Temporal.ZonedDateTime.from(localTimeNotExist);
console.log(zdt.toString()); // "2024-03-10T03:05:00-04:00[America/New_York]"

const zdt2 = Temporal.ZonedDateTime.from(localTimeNotExist, {
  disambiguation: "earlier",
});
console.log(zdt2.toString()); // "2024-03-10T01:05:00-05:00[America/New_York]"

const localTimeAmbiguous = "2024-11-03T01:05:00[America/New_York]";
// For ambiguous times, "compatible" is equivalent to "earlier"
const zdt3 = Temporal.ZonedDateTime.from(localTimeAmbiguous);
console.log(zdt3.toString()); // "2024-11-03T01:05:00-04:00[America/New_York]"

const zdt4 = Temporal.ZonedDateTime.from(localTimeAmbiguous, {
  disambiguation: "later",
});
console.log(zdt4.toString()); // "2024-11-03T01:05:00-05:00[America/New_York]"

Разрешение неоднозначности смещения

Введение в эту ситуацию см. в разделе Неоднозначность смещения.

const offsetAmbiguous = "2019-12-23T12:00:00-02:00[America/Sao_Paulo]";

Temporal.ZonedDateTime.from(offsetAmbiguous);
// RangeError: date-time can't be represented in the given time zone
Temporal.ZonedDateTime.from(offsetAmbiguous, { offset: "use" }).toString();
// "2019-12-23T11:00:00-03:00[America/Sao_Paulo]"
Temporal.ZonedDateTime.from(offsetAmbiguous, { offset: "ignore" }).toString();
// "2019-12-23T12:00:00-03:00[America/Sao_Paulo]"

Другие примеры, в частности примеры с разными календарями и настройками переполнения, см. в разделах Temporal.PlainDate.from() и Temporal.PlainTime.from().

Спецификации

Совместимость с браузерами

См. также

• Temporal.ZonedDateTime
• Temporal.ZonedDateTime()
• Temporal.ZonedDateTime.prototype.with()