1. Web
  2. JavaScript
  3. 参考
  4. 标准内置对象
  5. Temporal
  6. Temporal.ZonedDateTime
  7. from()

Temporal.ZonedDateTime.from()

可用性有限

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

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

Temporal.ZonedDateTime.from() 静态方法从另一个 Temporal.ZonedDateTime 对象、一个包含日期、时间及时区属性的对象或一个 RFC 9557 字符串创建一个新的 Temporal.ZonedDateTime 对象。

语法

js
Temporal.ZonedDateTime.from(info)
Temporal.ZonedDateTime.from(info, options)

参数

info

以下之一：

  • 一个 Temporal.ZonedDateTime 实例，用于创建该实例的副本。
  • 一个 RFC 9557 格式字符串，包含日期、可选的时间、可选的偏移量、时区注解以及可选的日历。
  • 一个包含 Temporal.PlainDate.from()（calendar、era、eraYear、year、month、monthCode、day）或 Temporal.PlainTime.from()（hour、minute、second、millisecond、microsecond、nanosecond）所接受属性的对象。info 应明确指定年份（作为 year 或 era 和 eraYear）、月份（作为 month 或 monthCode）和日期；其他属性是可选的，并将设置为其默认值。还应提供以下属性：
    timeZone

    一个字符串或 Temporal.ZonedDateTime 实例，表示要使用的时区。如果是 Temporal.ZonedDateTime 实例，则使用其时区。如果是字符串，它可以是命名时区标识符、偏移时区标识符，或者包含时区标识符或偏移量的日期时间字符串（有关更多信息，请参阅时区和偏移量）。时间属性将在此时区中解释。

    offset 可选

    一个偏移字符串，格式与 RFC 9557 偏移量相同，但秒和亚秒组件是可选的（±HH:mm:ss.sssssssss），表示与 UTC 的偏移量。如果省略，将根据时区和日期时间计算。不允许使用 "Z"。

options 可选

一个包含以下部分或全部属性的对象（按检索和验证的顺序）：

disambiguation 可选

如果本地日期时间在给定时间区域中存在歧义（有多个具有此类本地时间的瞬时，或者本地时间不存在），则采取何种操作。可能的值有 "compatible"、"earlier"、"later" 和 "reject"。默认为 "compatible"。有关这些值的更多信息，请参阅本地时间到 UTC 时间的歧义和间隙。

offset 可选

如果 info 中明确提供了偏移量，但该偏移量在给定本地时间的给定时间区域中无效，则采取何种操作。可能的值有 "use"、"ignore"、"reject" 和 "prefer"。默认为 "reject"。有关这些值的更多信息，请参阅偏移量歧义。

overflow 可选

一个字符串，指定当日期组件超出范围时（使用对象 info 时）的行为。可能的值有：

"constrain"（默认）

日期组件被限制在有效范围内。

"reject"

如果日期组件超出范围，则抛出 RangeError。

返回值

一个新的 Temporal.ZonedDateTime 对象，表示 info 在指定 calendar 和 timeZone 中指定的日期和时间。

异常

TypeError

在以下情况之一中抛出

  • info 不是对象或字符串。
  • options 不是对象或 undefined。
  • 提供的属性不足以明确确定日期。您通常需要提供 year（或 era 和 eraYear）、month（或 monthCode）和 day。
RangeError

在以下情况之一中抛出

  • 指定相同组件的提供的属性不一致。
  • 提供的非数字属性无效；例如，如果 monthCode 在此日历中从未是有效的月份代码。
  • 提供的数字属性超出范围，并且 options.overflow 设置为 "reject"。
  • 挂钟时间在时区中存在歧义，并且 options.disambiguation 设置为 "reject"。
  • 信息不在可表示范围内，即距离 Unix 纪元 ±108 天，或大约 ±273,972.6 年。

示例

从对象创建 ZonedDateTime

js
// Year + month + day + hour + minute + second
const zdt = Temporal.ZonedDateTime.from({
  timeZone: "America/New_York",
  year: 2021,
  month: 7,
  day: 1,
  hour: 12,
  minute: 34,
  second: 56,
});
console.log(zdt.toString()); // "2021-07-01T12:34:56-04:00[America/New_York]"

从字符串创建 ZonedDateTime

js
const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56-04:00[America/New_York]",
);
console.log(zdt.toLocaleString()); // "7/1/2021, 12:34:56 PM EDT" (assuming en-US locale)

// Time given as UTC, and converted to local
const zdt2 = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56Z[America/New_York]",
);
console.log(zdt2.toString()); // "2021-07-01T08:34:56-04:00[America/New_York]"

从 ISO 8601 / RFC 3339 字符串创建 ZonedDateTime

请注意，Temporal.ZonedDateTime.from() 拒绝不包含时区标识符的 ISO 8601 字符串。这是为了确保时区始终已知，并且可以用于在本地时间变化时推导不同的偏移量。

如果要解析 ISO 8601 字符串，请首先构造一个 Temporal.Instant 对象，然后将其转换为 Temporal.ZonedDateTime 对象。您可以提供任何时区，即使它与字符串中最初给定的偏移量不匹配，本地时间也会相应调整。

js
const isoString = "2021-07-01T12:34:56+02:00";
const instant = Temporal.Instant.from(isoString);
const zdt = instant.toZonedDateTimeISO("America/New_York");
console.log(zdt.toString()); // "2021-07-01T06:34:56-04:00[America/New_York]"

本地时间消歧

有关此情况的介绍，请参阅本地时间到 UTC 时间的歧义和间隙。

js
const localTimeNotExist = "2024-03-10T02:05:00[America/New_York]";
// For non-existent times, "compatible" is equivalent to "later"
const zdt = Temporal.ZonedDateTime.from(localTimeNotExist);
console.log(zdt.toString()); // "2024-03-10T03:05:00-04:00[America/New_York]"

const zdt2 = Temporal.ZonedDateTime.from(localTimeNotExist, {
  disambiguation: "earlier",
});
console.log(zdt2.toString()); // "2024-03-10T01:05:00-05:00[America/New_York]"

const localTimeAmbiguous = "2024-11-03T01:05:00[America/New_York]";
// For ambiguous times, "compatible" is equivalent to "earlier"
const zdt3 = Temporal.ZonedDateTime.from(localTimeAmbiguous);
console.log(zdt3.toString()); // "2024-11-03T01:05:00-04:00[America/New_York]"

const zdt4 = Temporal.ZonedDateTime.from(localTimeAmbiguous, {
  disambiguation: "later",
});
console.log(zdt4.toString()); // "2024-11-03T01:05:00-05:00[America/New_York]"

解决偏移量歧义

有关此情况的介绍，请参阅偏移量歧义。

js
const offsetAmbiguous = "2019-12-23T12:00:00-02:00[America/Sao_Paulo]";

Temporal.ZonedDateTime.from(offsetAmbiguous);
// RangeError: date-time can't be represented in the given time zone
Temporal.ZonedDateTime.from(offsetAmbiguous, { offset: "use" }).toString();
// "2019-12-23T11:00:00-03:00[America/Sao_Paulo]"
Temporal.ZonedDateTime.from(offsetAmbiguous, { offset: "ignore" }).toString();
// "2019-12-23T12:00:00-03:00[America/Sao_Paulo]"

有关更多示例，特别是关于不同日历和溢出设置的示例，请参阅Temporal.PlainDate.from() 和 Temporal.PlainTime.from()。

规范

规范
Temporal
# sec-temporal.zoneddatetime.from

浏览器兼容性

另见

帮助改进 MDN

了解如何贡献

此页面最后由 MDN 贡献者 在 修改。

在 GitHub 上查看此页面 • 报告此内容的问题
© . Content available under a Creative Commons license.