Temporal.ZonedDateTime.from()

可用性有限

此特性不是基線特性，因為它在一些最廣泛使用的瀏覽器中不起作用。

實驗性： 這是一項實驗性技術
在生產中使用此技術之前，請仔細檢查瀏覽器相容性表格。

Temporal.ZonedDateTime.from() 靜態方法從另一個 Temporal.ZonedDateTime 物件、一個包含日期、時間及時區屬性的物件或一個 RFC 9557 字串建立一個新的 Temporal.ZonedDateTime 物件。

語法

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 紀元 ±10⁸ 天，或大約 ±273,972.6 年。

示例

從物件建立 ZonedDateTime

// 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

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 物件。您可以提供任何時區，即使它與字串中最初給定的偏移量不匹配，本地時間也會相應調整。

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 時間的歧義和間隙。

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

解決偏移量歧義

有關此情況的介紹，請參閱偏移量歧義。

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 貢獻者在 2025 年 7 月 10 日修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題