Temporal.ZonedDateTime.prototype.with()

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

Чтобы заменить свойство calendarId, используйте метод withCalendar(). Чтобы заменить свойство timeZoneId, используйте метод withTimeZone().

Синтаксис

with(info)
with(info, options)

Параметры

info

Объект, содержащий по крайней мере одно из свойств, распознаваемых Temporal.ZonedDateTime.from() (кроме calendar и timeZone): day, era и eraYear, hour, microsecond, millisecond, minute, month, monthCode, nanosecond, offset, second, year. Неуказанные свойства используют значения из исходной даты и времени. Вам нужно предоставить только одно из month или monthCode, и одно из era и eraYear или year, а другое будет обновлено соответствующим образом.

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

Объект, содержащий некоторые или все из следующих свойств (в порядке их извлечения и проверки):

disambiguation Необязательный

Что делать, если локальная дата и время неоднозначны в заданной временной зоне (существует более одного момента времени с таким локальным временем, или локальное время не существует). Возможные значения: "compatible", "earlier", "later" и "reject". По умолчанию используется "compatible". Для получения дополнительной информации об этих значениях см. неоднозначность и пробелы при преобразовании из локального времени в время UTC.

offset Необязательный

Что делать, если смещение явно указано в info, но оно недействительно для заданной временной зоны в заданном локальном времени. Возможные значения: "use", "ignore", "reject" и "prefer". По умолчанию используется "prefer". Для получения дополнительной информации об этих значениях см. неоднозначность смещения.

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

Строка, указывающая поведение, когда компонент даты выходит за пределы диапазона (при использовании объекта info). Возможные значения:

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

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

"reject"

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

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

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

Исключения

TypeError

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

• info не является объектом.
• options не является объектом или undefined.

RangeError

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

• Предоставленные свойства, задающие один и тот же компонент, противоречивы.
• Предоставленные нечисловые свойства недействительны; например, если monthCode никогда не является действительным кодом месяца в этом календаре.
• Предоставленные числовые свойства выходят за пределы диапазона, а options.overflow установлено в значение "reject".
• Время по настенным часам, представленное предоставленными свойствами, неоднозначно во временной зоне, а options.disambiguation установлено в значение "reject".
• Результат не находится в представимом диапазоне, который составляет ±10⁸ дней, или около ±273 972,6 лет, от эпохи Unix.

Примеры

Использование with()

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56[America/New_York]",
);
const newZDT = zdt.with({ hour: 13 });
console.log(newZDT.toString()); // "2021-07-01T13:34:56-04:00[America/New_York]"

Для получения дополнительных примеров см. документацию по отдельным свойствам, которые могут быть установлены с помощью with().

Смещение при изменении даты

По умолчанию опция offset установлена в "prefer", что означает, что мы используем исходное смещение (или смещение, предоставленное в info), если оно допустимо, и пересчитываем в противном случае. Это означает, что если вы устанавливаете другую дату, которая имеет другое смещение из-за перехода на летнее время, смещение будет пересчитано:

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:00:00-04:00[America/New_York]",
);
const newZDT = zdt.with({ month: 12 });
// The offset is recalculated to -05:00
console.log(newZDT.toString()); // "2021-12-01T12:00:00-05:00[America/New_York]"

И если вы устанавливаете время в пределах перехода на летнее время, смещение используется для разрешения неоднозначности:

const zdt = Temporal.ZonedDateTime.from(
  "2024-11-02T01:05:00-04:00[America/New_York]",
);
const newZDT = zdt.with({ day: 3 });
console.log(newZDT.toString()); // "2024-11-03T01:05:00-04:00[America/New_York]"

const zdt2 = Temporal.ZonedDateTime.from(
  "2024-11-04T01:05:00-05:00[America/New_York]",
);
const newZDT2 = zdt2.with({ day: 3 });
console.log(newZDT2.toString()); // "2024-11-03T01:05:00-05:00[America/New_York]"

Если вы используете offset: "use", то смещение будет использовано как есть для получения точного времени сначала, и затем смещение будет пересчитано:

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:00:00-04:00[America/New_York]",
);
const newZDT = zdt.with({ month: 12 }, { offset: "use" });
// The offset is recalculated to -05:00, but the wall-clock time changes
console.log(newZDT.toString()); // "2021-12-01T11:00:00-05:00[America/New_York]"

Вы также можете установить offset: "reject", чтобы вызвать ошибку, если исходное смещение недействительно, что требует явного указания нового смещения:

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:00:00-04:00[America/New_York]",
);
zdt.with({ month: 12 }, { offset: "reject" });
// RangeError: date-time can't be represented in the given time zone
zdt.with({ month: 12, offset: "-05:00" }, { offset: "reject" }).toString();
// "2021-12-01T12:00:00-05:00[America/New_York]"

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

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

См. также

• Temporal.ZonedDateTime
• Temporal.ZonedDateTime.prototype.withCalendar()
• Temporal.ZonedDateTime.prototype.withTimeZone()
• Temporal.ZonedDateTime.prototype.withPlainTime()
• Temporal.ZonedDateTime.from()
• Temporal.ZonedDateTime.prototype.add()
• Temporal.ZonedDateTime.prototype.subtract()