Temporal.ZonedDateTime.prototype.add()

語法

add(duration)
add(duration, options)

引數

duration

一個字串、一個物件或一個 Temporal.Duration 例項，表示要新增到此日期時間的持續時間。它使用與 Temporal.Duration.from() 相同的演算法轉換為 Temporal.Duration 物件。

options 可選

包含以下屬性的物件

overflow 可選

一個字串，指定日期元件超出範圍時的行為。可能的值是

"constrain"（預設）

日期元件被限制在有效範圍內。

"reject"

如果日期元件超出範圍，則丟擲 RangeError。

返回值

一個新的 Temporal.ZonedDateTime 物件，表示原始 ZonedDateTime 加上持續時間後的日期時間。

異常

RangeError

如果結果不在 可表示範圍 內（即距 Unix 紀元 ±10⁸ 天，或大約 ±273,972.6 年），則丟擲此錯誤。

描述

有關如何新增日曆持續時間，請參閱 Temporal.PlainDate.prototype.add()。

加減法根據 RFC 5545 (iCalendar) 中定義的規則執行

• 使用日曆算術新增/減去持續時間的日期部分；換句話說，使用 Temporal.PlainDateTime.prototype.add() 將日期部分新增到其 PlainDateTime，然後以相同的時區解釋結果。結果將使用此例項的 timeZone 欄位的規則自動調整夏令時。例如，2024-11-03T01:00:00-04:00[America/New_York] 加一天是 2024-11-04T01:00:00-05:00[America/New_York]，就好像這一天有 25 小時一樣。
  • 如果日期時間由於時區偏移轉換而模糊或無效，則使用 disambiguation: "compatible" 行為解決：對於時間跳過的轉換，將使用兩個可能瞬間中較晚的那個；對於時間重複的轉換，將使用兩個可能瞬間中較早的那個。例如，2024-03-09T02:05:00-05:00[America/New_York] 加一天本應是 2024-03-10T02:05:00-05:00[America/New_York]，但此時間不存在，因此返回一個小時後的掛鐘時間 2024-03-10T03:05:00-04:00[America/New_York]。
  • 如果偏移量模糊，則使用 offset: "prefer" 行為解決：如果偏移量對於時區和當地時間有效，則使用它，否則重新計算。例如，2024-11-02T01:00:00-04:00[America/New_York] 加一天是 2024-11-03T01:00:00-04:00[America/New_York]，而 2024-11-04T01:00:00-05:00[America/New_York] 減一天是 2024-11-03T01:00:00-05:00[America/New_York]。
  • 如果結果日期時間的元件超出範圍，則使用 overflow 選項解決。例如，2024-08-31 加一個月是 2024-09-31，這個日期不存在，因此預設情況下它被限制為 2024-09-30。
• 使用真實世界時間新增/減去持續時間的時間部分；換句話說，使用 Temporal.Instant.prototype.add() 將時間部分新增到其 Instant，然後以相同的時區解釋結果。例如，2024-11-03T01:00:00-04:00[America/New_York] 加一小時是 2024-11-03T01:00:00-05:00[America/New_York]。

這些規則使得 Temporal.ZonedDateTime 的算術運算“DST 安全”，這意味著結果最符合現實世界使用者和實現其他符合標準日曆應用程式的開發人員的期望。這些期望包括

• 新增或減去天數應在 DST 轉換期間保持時鐘時間一致。例如，如果您在週六下午 1:00 有一個約會，並要求將其重新安排到 1 天后，即使隔夜有 DST 轉換，您也會希望重新安排的約會仍然在下午 1:00。
• 新增或減去持續時間的時間部分應忽略 DST 轉換。例如，如果您遲到 1 小時或 3 小時，您要求在 2 小時後見面的朋友會感到惱火。應該有一個一致且相對不令人驚訝的操作順序。
• 如果結果在 DST 轉換時或附近，則應自動（不崩潰）和確定性地處理歧義。

新增持續時間等同於減去其負值。

示例

新增持續時間

const start = Temporal.ZonedDateTime.from(
  "2021-11-01T12:34:56-04:00[America/New_York]",
);
const end = start.add({
  years: 1,
  months: 2,
  weeks: 3,
  days: 4,
  hours: 5,
  minutes: 6,
  seconds: 7,
  milliseconds: 8,
});
console.log(end.toString()); // 2023-01-26T17:41:03.008-05:00[America/New_York]

有關更多示例，特別是不同日曆和 overflow 選項如何與日曆持續時間互動的示例，請參閱 Temporal.PlainDate.prototype.add()。

規範

瀏覽器相容性

另見

• Temporal.ZonedDateTime
• Temporal.Duration
• Temporal.ZonedDateTime.prototype.subtract()