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 |
浏览器兼容性
加载中…