Temporal.PlainDateTime.prototype.toZonedDateTime()

Метод toZonedDateTime() экземпляров Temporal.PlainDateTime возвращает новый экземпляр Temporal.ZonedDateTime, представляющий то же время и дату, что и этот простой объект времени и даты, но в указанном часовом поясе.

Синтаксис

toZonedDateTime(timeZone)
toZonedDateTime(timeZone, options)

Параметры

timeZone

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

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

Объект, содержащий следующее свойство:

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

Строка, указывающая, что делать, если это простое время соответствует нулю или более чем одному моменту времени в часовом поясе, обычно из-за переходов на летнее время. Возможные значения: "compatible", "earlier", "later" и "reject". По умолчанию используется "compatible". Для получения дополнительной информации об этих значениях см. неопределенность и пробелы при переходе от местного времени к времени UTC.

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

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

Исключения

RangeError

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

• Любая из опций недействительна.
• timeZone не является действительным идентификатором часового пояса.
• Время по настенным часам является неоднозначным в часовом поясе, а options.disambiguation установлено в "reject".

TypeError

Генерируется, если какой-либо из аргументов не соответствует ожидаемому типу.

Примеры

Использование toZonedDateTime()

const dt = Temporal.PlainDateTime.from("2021-08-01T12:34:56");
const zdt = dt.toZonedDateTime("America/New_York");
console.log(zdt.toString()); // '2021-08-01T12:34:56-04:00[America/New_York]'

const dt2 = Temporal.PlainDateTime.from("2021-01-01T12:34:56");
const zdt2 = dt2.toZonedDateTime("America/New_York");
console.log(zdt2.toString()); // '2021-01-01T12:34:56-05:00[America/New_York]'

Обработка неоднозначного времени

Ниже приведены два момента времени по настенным часам, которые мы хотим интерпретировать в часовом поясе America/New_York. Первый, dtNotExist, никогда не существовал из-за сдвига времени вперед при переходе на летнее время, поэтому нам нужно выбрать из моментов времени 01:05:00-05:00 или 03:05:00-04:00. Второй, dtAmbiguous, появился дважды из-за сдвига времени назад при переходе на летнее время, поэтому нам нужно выбрать из моментов времени 01:05:00-04:00 или 01:05:00-05:00. Для более подробного объяснения этой ситуации см. неопределенность и пробелы при переходе от местного времени к времени UTC.

const dtNotExist = Temporal.PlainDateTime.from("2024-03-10T02:05:00");
const dtAmbiguous = Temporal.PlainDateTime.from("2024-11-03T01:05:00");

// Default: compatible
console.log(dtNotExist.toZonedDateTime("America/New_York").toString());
// '2024-03-10T03:05:00-04:00[America/New_York]'
console.log(dtAmbiguous.toZonedDateTime("America/New_York").toString());
// '2024-11-03T01:05:00-04:00[America/New_York]'

// Use the earlier time for ambiguous times
console.log(
  dtNotExist
    .toZonedDateTime("America/New_York", { disambiguation: "earlier" })
    .toString(),
);
// '2024-03-10T01:05:00-05:00[America/New_York]'
console.log(
  dtAmbiguous
    .toZonedDateTime("America/New_York", { disambiguation: "earlier" })
    .toString(),
);
// '2024-11-03T01:05:00-04:00[America/New_York]'

// Use the later time for ambiguous times
console.log(
  dtNotExist
    .toZonedDateTime("America/New_York", { disambiguation: "later" })
    .toString(),
);
// '2024-03-10T03:05:00-04:00[America/New_York]'
console.log(
  dtAmbiguous
    .toZonedDateTime("America/New_York", { disambiguation: "later" })
    .toString(),
);
// '2024-11-03T01:05:00-05:00[America/New_York]'

// Throw an error for ambiguous times
dtNotExist.toZonedDateTime("America/New_York", { disambiguation: "reject" });
// RangeError: instant is ambiguous

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

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

См. также

• Temporal.PlainDateTime
• Temporal.ZonedDateTime
• Temporal.PlainDateTime.prototype.toPlainDate()
• Temporal.PlainDateTime.prototype.toPlainTime()
• Temporal.ZonedDateTime.prototype.toPlainDateTime()