Temporal.ZonedDateTime.prototype.with()

可用性有限

此特性不是基线特性，因为它在一些最广泛使用的浏览器中不起作用。

实验性： 这是一项实验性技术
在生产中使用此技术之前，请仔细检查浏览器兼容性表格。

Temporal.ZonedDateTime 实例的 with() 方法返回一个新的 Temporal.ZonedDateTime 对象，表示此日期时间，其中一些字段被新值替换。由于所有 Temporal 对象都被设计为不可变的，因此此方法本质上充当日期时间字段的设置器。

要替换 calendarId 属性，请使用 withCalendar() 方法。要替换 timeZoneId 属性，请使用 withTimeZone() 方法。

一个对象，包含至少一个由 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"。
结果不在可表示范围内，该范围是距 Unix 纪元 ±10⁸ 天，或约 ±273,972.6 年。

示例

使用 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]"