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()