The withTimeZone() method of Temporal.ZonedDateTime instances returns a new Temporal.ZonedDateTime object representing the same instant as this date-time but in the new time zone. Because all Temporal objects are designed to be immutable, this method essentially functions as the setter for the date-time's Temporal/ZonedDateTime/timeZoneId property.
To replace the date-time component properties, use the Temporal/ZonedDateTime/with method. To replace its calendar, use the Temporal/ZonedDateTime/withCalendar method.
Syntax
withTimeZone(timeZone)
Parameters
timeZone- : Either a string or a Temporal.ZonedDateTime instance representing the time zone to use. If a
Temporal.ZonedDateTimeinstance, its time zone is used. If a string, it can be a named time zone identifier, an offset time zone identifier, or a date-time string containing a time zone identifier or an offset (see time zones and offsets for more information).
- : Either a string or a Temporal.ZonedDateTime instance representing the time zone to use. If a
Return value
A new Temporal.ZonedDateTime object representing the same instant as this date-time but in the new time zone.
Exceptions
- TypeError
- : Thrown if
timeZoneis not a string or aTemporal.ZonedDateTimeinstance.
- : Thrown if
- RangeError
- : Thrown if the time zone name is invalid.
Examples
Using withTimeZone()
const meetingTime = Temporal.ZonedDateTime.from(
"2021-08-01T12:00[America/New_York]",
);
const meetingTimeInParis = meetingTime.withTimeZone("Europe/Paris");
console.log(meetingTimeInParis.toString()); // 2021-08-01T18:00:00+02:00[Europe/Paris]
Replacing the time zone while keeping the same wall-clock time
In the rare case where you want to keep the wall-clock time the same but change the time zone (and result in a different instant), convert it to a Temporal.PlainDateTime first:
const meetingTime = Temporal.ZonedDateTime.from(
"2021-08-01T12:00[America/New_York]",
);
const meetingTimeInParis = meetingTime
.toPlainDateTime()
.toZonedDateTime("Europe/Paris");
console.log(meetingTimeInParis.toString()); // 2021-08-01T12:00:00+02:00[Europe/Paris]
Specifications
Browser compatibility
See also
- Temporal.ZonedDateTime
- Temporal/ZonedDateTime/with
- Temporal/ZonedDateTime/withCalendar
- Temporal/ZonedDateTime/withPlainTime
- Temporal/ZonedDateTime/from
- Temporal/ZonedDateTime/timeZoneId
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
