Temporal.ZonedDateTime.prototype.add()

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

Синтаксис

add(duration)
add(duration, options)

Параметры

duration

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

options Необязательно

Объект, содержащий следующее свойство:

overflow Необязательно

Строка, определяющая поведение, когда компонент даты выходит за пределы диапазона. Возможные значения:

"constrain" (по умолчанию)

Компонент даты приводится к допустимому диапазону.

"reject"

Генерируется RangeError, если компонент даты выходит за пределы диапазона.

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

Новый объект Temporal.ZonedDateTime, представляющий дату и время, указанные исходным ZonedDateTime, плюс длительность.

Исключения

RangeError

Генерируется, если результат не входит в представимый диапазон, который составляет ±10⁸ дней, или около ±273 972,6 лет от эпохи Unix.

Описание

О том, как добавляются календарные длительности, см. Temporal.PlainDate.prototype.add().

Сложение и вычитание выполняются в соответствии с правилами, определенными в RFC 5545 (iCalendar):

• Добавление/вычитание части даты длительности с использованием календарной арифметики; другими словами, добавьте часть даты к ее PlainDateTime с помощью Temporal.PlainDateTime.prototype.add(), а затем интерпретируйте результат в том же часовом поясе. Результат будет автоматически скорректирован с учетом летнего времени с использованием правил поля 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]. Аналогично, как 2024-11-02T01:00:00-04:00[America/New_York] плюс один день, так и 2024-11-04T01:00:00-05:00[America/New_York] минус один день дают 2024-11-03T01:00:00-04:00[America/New_York], более ранний из двух возможных моментов времени.
  • Если компоненты полученной даты и времени выходят за границы, они разрешаются с использованием опции overflow. Например, 2024-08-31 плюс один месяц — это 2024-09-31, которого не существует, поэтому по умолчанию он приводится к 2024-09-30.
• Добавление/вычитание временной части длительности с использованием реального времени; другими словами, добавьте временную часть к ее Instant с помощью Temporal.Instant.prototype.add(), а затем интерпретируйте результат в том же часовом поясе. Например, 2024-11-03T01:00:00-04:00[America/New_York] плюс один час — это 2024-11-03T01:00:00-05:00[America/New_York].

Эти правила делают арифметику с Temporal.ZonedDateTime "безопасной для летнего времени" (DST-safe), что означает, что результаты наиболее точно соответствуют ожиданиям как реальных пользователей, так и разработчиков других календарных приложений, совместимых со стандартами. Эти ожидания включают:

• Добавление или вычитание дней должно обеспечивать согласованность времени по часам при переходах на летнее время. Например, если у вас назначена встреча в субботу в 13:00, и вы просите перенести ее на 1 день позже, вы ожидаете, что перенесенная встреча по-прежнему будет в 13:00, даже если ночью произошел переход на летнее время.
• Добавление или вычитание временной части длительности должно игнорировать переходы на летнее время. Например, друг, с которым вы договорились встретиться через 2 часа, будет раздражен, если вы появитесь через 1 час или через 3 часа. Должен быть последовательный и относительно не вызывающий удивления порядок операций.
• Если результаты находятся в момент перехода на летнее время или около него, неоднозначности должны обрабатываться автоматически (без сбоев) и детерминированно.

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

Примеры

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

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