Temporal.ZonedDateTime.prototype.with()

可用性有限

此特性不是基線特性，因為它在一些最廣泛使用的瀏覽器中不起作用。

實驗性： 這是一項實驗性技術
在生產中使用此技術之前，請仔細檢查瀏覽器相容性表格。

Temporal.ZonedDateTime 例項的 with() 方法返回一個新的 Temporal.ZonedDateTime 物件，表示此日期時間，其中一些欄位被新值替換。由於所有 Temporal 物件都被設計為不可變的，因此此方法本質上充當日期時間欄位的設定器。

要替換 calendarId 屬性，請使用 withCalendar() 方法。要替換 timeZoneId 屬性，請使用 withTimeZone() 方法。

一個物件，包含至少一個由 Temporal.ZonedDateTime.from() 識別的屬性（calendar 和 timeZone 除外）：day、era 和 eraYear、hour、microsecond、millisecond、minute、month、monthCode、nanosecond、offset、second、year。未指定的屬性使用原始日期時間的值。你只需要提供 month 或 monthCode 中的一個，以及 era 和 eraYear 或 year 中的一個，另一個將相應更新。

options 可選

一個包含以下部分或全部屬性的物件（按檢索和驗證的順序）：

disambiguation 可選

如果給定本地日期時間在給定地區時區中不明確（存在多個具有此類本地時間的瞬間，或者本地時間不存在），則如何處理。可能的值包括 "compatible"、"earlier"、"later" 和 "reject"。預設為 "compatible"。有關這些值的更多資訊，請參閱從本地時間到 UTC 時間的歧義和間隙。

offset 可選

如果在 info 中明確提供了偏移量，但該偏移量對於給定本地時間中的給定地區時區無效，則如何處理。可能的值包括 "use"、"ignore"、"reject" 和 "prefer"。預設為 "prefer"。有關這些值的更多資訊，請參閱偏移量歧義。

overflow 可選

一個字串，指定當日期元件超出範圍時（使用物件 info 時）的行為。可能的值有：

"constrain"（預設）: 日期元件被限制在有效範圍內。
"reject": 如果日期元件超出範圍，則丟擲 RangeError。

返回值

一個新的 Temporal.ZonedDateTime 物件，其中 info 中指定且非 undefined 的欄位被相應的值替換，其餘欄位從原始日期時間複製。

異常

TypeError

在以下情況之一中丟擲

info 不是一個物件。
options 不是物件或 undefined。

RangeError

在以下情況之一中丟擲

指定相同元件的提供的屬性不一致。
提供的非數字屬性無效；例如，如果 monthCode 在此日曆中從未是有效的月份程式碼。
提供的數字屬性超出範圍，並且 options.overflow 設定為 "reject"。
所提供屬性表示的掛鐘時間在時區中不明確，並且 options.disambiguation 設定為 "reject"。
結果不在可表示範圍內，該範圍是距 Unix 紀元 ±10⁸ 天，或約 ±273,972.6 年。

示例

使用 with()

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56[America/New_York]",
);
const newZDT = zdt.with({ hour: 13 });
console.log(newZDT.toString()); // "2021-07-01T13:34:56-04:00[America/New_York]"

有關更多示例，請參閱可以使用 with() 設定的各個屬性的文件。

日期更改期間的偏移量

預設情況下，offset 選項設定為 "prefer"，這意味著如果原始偏移量（或 info 中提供的偏移量）有效，我們就會使用它，否則重新計算。這意味著如果你設定為由於夏令時轉換而具有不同偏移量的另一個日期，則偏移量將被重新計算。

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:00:00-04:00[America/New_York]",
);
const newZDT = zdt.with({ month: 12 });
// The offset is recalculated to -05:00
console.log(newZDT.toString()); // "2021-12-01T12:00:00-05:00[America/New_York]"

如果你將時間設定為夏令時轉換期間，則偏移量用於解決歧義。

const zdt = Temporal.ZonedDateTime.from(
  "2024-11-02T01:05:00-04:00[America/New_York]",
);
const newZDT = zdt.with({ day: 3 });
console.log(newZDT.toString()); // "2024-11-03T01:05:00-04:00[America/New_York]"

const zdt2 = Temporal.ZonedDateTime.from(
  "2024-11-04T01:05:00-05:00[America/New_York]",
);
const newZDT2 = zdt2.with({ day: 3 });
console.log(newZDT2.toString()); // "2024-11-03T01:05:00-05:00[America/New_York]"

如果你使用 offset: "use"，則偏移量將原樣用於首先獲取確切時間，然後重新計算偏移量。

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:00:00-04:00[America/New_York]",
);
const newZDT = zdt.with({ month: 12 }, { offset: "use" });
// The offset is recalculated to -05:00, but the wall-clock time changes
console.log(newZDT.toString()); // "2021-12-01T11:00:00-05:00[America/New_York]"

你還可以設定 offset: "reject"，如果原始偏移量無效，則會丟擲錯誤，強制指定一個明確的新偏移量。

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:00:00-04:00[America/New_York]",
);
zdt.with({ month: 12 }, { offset: "reject" });
// RangeError: date-time can't be represented in the given time zone
zdt.with({ month: 12, offset: "-05:00" }, { offset: "reject" }).toString();
// "2021-12-01T12:00:00-05:00[America/New_York]"