大网数据广告活动
Web 标准与前端开发

Temporal.Instant.prototype.add()

· 52CE 我爱测

The **`add()`** method of Temporal.Instant instances returns a new `Temporal.Instant` object representing this instant moved forward by a given duration (in a form convertible by Temporal/Duration/from).

The add() method of Temporal.Instant instances returns a new Temporal.Instant object representing this instant moved forward by a given duration (in a form convertible by Temporal/Duration/from).

Syntax

add(duration)

Parameters

  • duration
    • : A string, an object, or a Temporal.Duration instance representing a duration to add to this instant. It is converted to a Temporal.Duration object using the same algorithm as Temporal/Duration/from.

Return value

A new Temporal.Instant object representing adding duration to this instant. If duration is positive, then the returned instant is later than this instant; if duration is negative, then the returned instant is earlier than this instant.

Exceptions

  • RangeError
    • : Thrown in one of the following cases:
      • duration is a calendar duration (it has a non-zero years, months, or weeks), or has a non-zero days, because calendar durations are ambiguous without a calendar and time reference.
      • The result is not in the representable range, which is ±10<sup>8</sup> days, or about ±273,972.6 years, from the Unix epoch.

Description

In essence, the add() method first gets the number of nanoseconds represented by duration, adds it to this instant's Temporal/Instant/epochNanoseconds, and then creates a new Temporal.Instant object from the result. Therefore, the duration must unambiguously represent a fixed amount of time.

If you want to add a calendar duration, the addition must be performed in the context of a calendar and a time zone to account for the variable lengths of months, years, and days (because of daylight saving time). In this case, convert the instant to a Temporal.ZonedDateTime object, add the duration, and then convert the result back to an instant.

Adding a duration is equivalent to subtracting its negation.

Examples

Adding a Temporal.Duration

const instant = Temporal.Instant.fromEpochMilliseconds(0);
const duration = Temporal.Duration.from("PT1S");
const newInstant = instant.add(duration);
console.log(newInstant.epochMilliseconds); // 1000

Adding an object or a string

const instant = Temporal.Instant.fromEpochMilliseconds(0);
const newInstant = instant.add({ seconds: 1 });
console.log(newInstant.epochMilliseconds); // 1000

const newInstant2 = instant.add("PT1S");
console.log(newInstant2.epochMilliseconds); // 1000

Adding a calendar duration

const instant = Temporal.Instant.fromEpochMilliseconds(1730610000000);
const duration = Temporal.Duration.from({ days: 1 });

// This instant is 2024-11-03T01:00:00-04:00[America/New_York],
// which is a DST transition day in the US.
const instant2 = instant
  .toZonedDateTimeISO("America/New_York")
  .add(duration)
  .toInstant();
console.log(instant2.epochMilliseconds); // 1730700000000

// The same instant is not a DST transition day in Paris.
const instant3 = instant
  .toZonedDateTimeISO("Europe/Paris")
  .add(duration)
  .toInstant();
console.log(instant3.epochMilliseconds); // 1730696400000

Specifications

Browser compatibility

See also

  • Temporal.Instant
  • Temporal.Duration
  • Temporal/Instant/subtract

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。