Temporal.PlainDate.prototype.add()
Temporal.PlainDate 例項的 add() 方法返回一個新的 Temporal.PlainDate 物件，該物件表示當前日期根據給定持續時間（以可由 Temporal.Duration.from() 轉換的形式）向前移動後的日期。
語法
js
add(duration)
add(duration, options)
引數
duration-
表示要新增到此日期的持續時間的字串、物件或
Temporal.Duration例項。它使用與Temporal.Duration.from()相同的演算法轉換為Temporal.Duration物件。 options可選-
包含以下屬性的物件
overflow可選-
一個字串，指定日期元件超出範圍時的行為。可能的值是
"constrain"（預設）-
日期元件被限制在有效範圍內。
"reject"-
如果日期元件超出範圍，則丟擲
RangeError。
返回值
一個新的 Temporal.PlainDate 物件，表示由原始 PlainDate 指定的日期加上持續時間後的日期。
異常
RangeError-
如果結果不在 可表示範圍 內，即距 Unix 紀元 ±(108 + 1) 天（約 ±273,972.6 年），則丟擲此錯誤。
描述
duration 的處理方式如下：
- 按年份數向前移動，保持
monthCode和day不變。如果monthCode在結果年份中無效（格里高利曆和 ISO 8601 不可能，但帶有閏月的日曆可能），我們根據overflow選項進行調整：對於constrain，我們根據該日曆使用者的文化習俗選擇另一個月份。例如，由於閏月通常被認為是另一個月份的複製品，我們可能會選擇它所複製的月份。 - 按月數向前移動，必要時調整年份，保持
day不變。如果day在結果月份中無效（例如 2 月 30 日），我們根據overflow選項進行調整：對於constrain，我們選擇最接近的有效日期（例如 2 月 28 日或 29 日）。 - 所有常用日曆都使用固定長度的周，因此週數只是轉換為天數。如果規則更復雜，我們可能會採取類似於月份偏移的方法。
- 對於所有非日曆單位（天、小時、分鐘、秒、毫秒、微秒、納秒），它們都轉換為天數。一天的分數部分將被忽略。然後，我們按該天數向前移動，必要時調整月份和年份。
示例
在 ISO 8601 日曆中新增持續時間
js
const start = Temporal.PlainDate.from("2021-01-01");
const end = start.add({ years: 1, months: 2, weeks: 3, days: 4 });
console.log(end.toString()); // 2022-03-26
const end2 = start.add({ years: -1, months: -2, weeks: -3, days: -4 });
console.log(end2.toString()); // 2019-10-07
const distance = Temporal.PlainDate.from("2020-01-01").until("2021-01-01"); // 366 days
const end3 = start.add(distance);
console.log(end3.toString()); // 2022-01-02
在非 ISO 日曆中新增持續時間
js
const start = Temporal.PlainDate.from("2021-01-01[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 11/18/2020
const end = start.add({ months: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 12/18/2020
帶溢位的持續時間新增
如果我們將日期移動幾個月，並且相應的天在該月中無效，那麼我們將根據 overflow 選項調整天。
js
const start = Temporal.PlainDate.from("2021-01-31");
const end = start.add({ months: 1 });
console.log(end.toString()); // 2021-02-28
// Any further day additions are based on the clamped month-day:
const end2 = start.add({ months: 1, days: 31 });
console.log(end2.toString()); // 2021-03-31
// Compare with the same addition in a different order that results in no overflow:
const end3 = start.add({ days: 31 }).add({ months: 1 });
console.log(end3.toString()); // 2021-04-03
對於不同年份有不同月份數的日曆（通常是由於閏月），月份也可能發生溢位。
js
const start = Temporal.PlainDate.from("2023-04-01[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 2bis/11/2023; "bis" means leap month
const end = start.add({ years: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 3/11/2024
// Compare:
const start = Temporal.PlainDate.from("2023-04-30[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 3/11/2023
const end = start.add({ years: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 3/11/2024; same day as above!
請注意，以下情況不是溢位，因為月份可以簡單地遞增
js
const start = Temporal.PlainDate.from("2021-01-01");
const end = start.add({ days: 100 });
console.log(end.toString()); // 2021-04-11
如果日期元件超出範圍，也可以丟擲錯誤
js
const start = Temporal.PlainDate.from("2021-01-31");
const end = start.add({ months: 1 }, { overflow: "reject" }); // RangeError: date value "day" not in 1..28: 31
const start = Temporal.PlainDate.from("2023-04-01[u-ca=chinese]");
const end = start.add({ years: 1 }, { overflow: "reject" }); // RangeError: invalid "monthCode" calendar field: M02L
新增時間持續時間
一天的分數部分將被忽略。
js
const start = Temporal.PlainDate.from("2021-01-01");
const end = start.add({ hours: 25 }); // Same as adding 1 day
console.log(end.toString()); // 2021-01-02
規範
| 規範 |
|---|
| Temporal # sec-temporal.plaindate.prototype.add |
瀏覽器相容性
載入中…