Temporal.Instant.prototype.add()

Метод add() экземпляров Temporal.Instant возвращает новый объект Temporal.Instant, представляющий этот момент времени, сдвинутый вперед на заданную длительность (в форме, конвертируемой Temporal.Duration.from()).

Синтаксис

add(duration)

Параметры

duration

Строка, объект или экземпляр Temporal.Duration, представляющий длительность, которую нужно добавить к этому моменту времени. Он конвертируется в объект Temporal.Duration, используя тот же алгоритм, что и Temporal.Duration.from().

Возвращаемое значение

Новый объект Temporal.Instant, представляющий добавление duration к этому моменту времени. Если duration положительное, то возвращаемый момент времени наступает позже этого момента; если duration отрицательное, то возвращаемый момент времени наступает раньше этого момента.

Исключения

RangeError

Выбрасывается в одном из следующих случаев:

• duration является календарной длительностью (имеет ненулевое значение years, months или weeks) или имеет ненулевое значение days, поскольку календарные длительности неоднозначны без календаря и ссылки на время.
• Результат выходит за пределы представимого диапазона, который составляет ±10⁸ дней, или примерно ±273 972,6 года, от Unix epoch.

Описание

По сути, метод add() сначала получает количество наносекунд, представленное duration, добавляет его к epochNanoseconds этого момента времени, а затем создает новый объект Temporal.Instant из результата. Следовательно, длительность должна однозначно представлять фиксированное количество времени.

Если вы хотите добавить календарную длительность, сложение должно выполняться в контексте календаря и часового пояса, чтобы учесть переменные длины месяцев, лет и дней (из-за перехода на летнее время). В этом случае преобразуйте момент времени в объект Temporal.ZonedDateTime, добавьте длительность, а затем преобразуйте результат обратно в момент времени.

Добавление длительности эквивалентно вычитанию ее отрицания.

Примеры

Добавление Temporal.Duration

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

Добавление объекта или строки

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

Добавление календарной длительности

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

Спецификации

Совместимость с браузерами

См. также

• Temporal.Instant
• Temporal.Duration
• Temporal.Instant.prototype.subtract()