Temporal.PlainYearMonth.prototype.add()
add() 方法用於 Temporal.PlainYearMonth 例項，返回一個新的 Temporal.PlainYearMonth 物件，該物件表示將此年月按給定持續時間（可以被 Temporal.Duration.from() 轉換）向前推移後的結果。
語法
js
add(duration)
add(duration, options)
引數
duration-
一個字串、一個物件或一個
Temporal.Duration例項，表示要新增到此年月的時間長度。它使用與Temporal.Duration.from()相同的演算法轉換為Temporal.Duration物件。 options可選-
包含以下屬性的物件
overflow可選-
一個字串，指定日期元件超出範圍時的行為。可能的值是
"constrain"（預設）-
日期元件被限制在有效範圍內。
"reject"-
如果日期元件超出範圍，則丟擲
RangeError。
返回值
一個表示原始 PlainYearMonth 指定的年月，加上持續時間後的新 Temporal.PlainYearMonth 物件。
異常
RangeError-
如果結果不在 可表示範圍 內，即距 Unix 紀元 ±(108 + 1) 天（約 ±273,972.6 年），則丟擲此錯誤。
描述
duration 的處理方式如下：
- 向前推移指定的年數，保持
monthCode不變。如果結果年份中的monthCode無效（對於公曆和 ISO 8601 不可能發生，但對於有閏月的日曆可能發生），我們將根據overflow選項進行調整：對於constrain，我們將根據該日曆使用者的文化慣例選擇另一個月份。例如，由於閏月通常被認為是另一個月份的重複，我們可能會選擇它是重複的那個月份。 - 向前推移指定的月數，必要時調整年份。
- 對於小於
months的所有單位（周、天、小時、分鐘、秒、毫秒、微秒、納秒），它們會被轉換為天數。所有常用支援的日曆都使用固定長度的周，因此週數會直接轉換為天數。如果規則更復雜，我們可能會採用類似於推移月份的方法。然後，我們向前推移該天數，從月份的第一天開始，必要時調整月份和年份。因此，小於當前月份長度的持續時間將不起作用。
內部參考日將選擇為月份的第一個有效日期，而不管原始參考日或持續時間的天數。對於公曆，不會發生溢位，因為每一年總是 12 個月，小於一個月的任何增量都會被忽略。
示例
在 ISO 8601 日曆中新增持續時間
js
const start = Temporal.PlainYearMonth.from("2021-01");
const end = start.add({ years: 1, months: 2, weeks: 3, days: 4 });
console.log(end.toString()); // 2022-03
const end2 = start.add({ years: -1, months: -2, weeks: -3, days: -4 });
console.log(end2.toString()); // 2019-11
const distance = Temporal.PlainYearMonth.from("2020-01").until("2021-01"); // 366 days
const end3 = start.add(distance);
console.log(end3.toString()); // 2022-01
在非 ISO 日曆中新增持續時間
js
const start = Temporal.PlainYearMonth.from("2021-02-01[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 11/2020
console.log(start.toString()); // 2021-01-13[u-ca=chinese]
const end = start.add({ months: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 12/2020
console.log(end.toString()); // 2021-02-12[u-ca=chinese]
// Adding an extra day has no effect at all
const end2 = start.add({ months: 1, days: 1 });
console.log(end2.toLocaleString("en-US", { calendar: "chinese" })); // 12/2020
// The reference day doesn't change, because it's always the first day of the Chinese month
console.log(end2.toString()); // 2021-02-12[u-ca=chinese]
// Start in a leap month
const start2 = Temporal.PlainYearMonth.from({
year: 5730,
monthCode: "M05L",
calendar: "hebrew",
});
console.log(start2.toLocaleString("en-US", { calendar: "hebrew" })); // Adar I 5730
// End in another leap month
const end3 = start2.add({ years: 3 });
console.log(end3.toLocaleString("en-US", { calendar: "hebrew" })); // Adar I 5733
新增帶有溢位的持續時間
如果我們推移幾年，而該年份中對應的月份無效，那麼我們將根據 overflow 選項調整月份。
js
// Start in a leap month
const start = Temporal.PlainYearMonth.from({
year: 5730,
monthCode: "M05L",
calendar: "hebrew",
});
// Hebrew leap years occur every 2 or 3 years, and 5731 is not a leap year
const end = start.add({ years: 1 });
console.log(end.toLocaleString("en-US", { calendar: "hebrew" })); // Adar 5731
console.log(end.monthCode); // M06
console.log(end.toString()); // 1971-02-26[u-ca=hebrew]
// Any further month additions are based on the clamped year-month
const end2 = start.add({ years: 1, months: 2 });
console.log(end2.monthCode); // M08
console.log(end2.toString()); // 1971-04-26[u-ca=hebrew]
// Compare with the same addition in a different order that results in no overflow:
const end3 = start.add({ months: 2 }).add({ years: 1 });
console.log(end3.monthCode); // M07
console.log(end3.toString()); // 1971-03-27[u-ca=hebrew]
請注意，以下情況不屬於溢位，因為年份可以簡單地增加。
js
const start = Temporal.PlainYearMonth.from("2021-01");
const end = start.add({ months: 100 });
console.log(end.toString()); // 2029-05
您也可以在日期元件超出範圍時丟擲錯誤。
js
const start = Temporal.PlainYearMonth.from({
year: 5730,
monthCode: "M05L",
calendar: "hebrew",
});
const end = start.add({ years: 1 }, { overflow: "reject" }); // RangeError: invalid "monthCode" calendar field: M05L
規範
| 規範 |
|---|
| Temporal # sec-temporal.plainyearmonth.prototype.add |
瀏覽器相容性
載入中…