1. Web
  2. JavaScript
  3. 參考
  4. 標準內建物件
  5. Temporal
  6. Temporal.PlainMonthDay
  7. from()

Temporal.PlainMonthDay.from()

可用性有限

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

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

Temporal.PlainMonthDay.from() 靜態方法會從另一個 Temporal.PlainMonthDay 物件、一個具有月和日屬性的物件或一個 RFC 9557 字串建立一個新的 Temporal.PlainMonthDay 物件。

語法

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

引數

info

以下之一：

  • 一個 Temporal.PlainMonthDay 例項，這將建立該例項的一個副本。
  • 一個 RFC 9557 字串，包含一個日期和可選的日曆。如果日曆不是 iso8601，則年份是必需的。
  • 一個包含以下屬性的物件（按檢索和驗證的順序）
    calendar 可選

    一個字串，對應於 calendarId 屬性。預設為 "iso8601"。所有其他屬性都在此日曆系統中解釋（與 Temporal.PlainMonthDay() 建構函式不同，後者在 ISO 日曆系統中解釋值）。有關常用支援的日曆型別列表，請參閱 Intl.supportedValuesOf()。

    日

    一個整數，對應於 day 屬性。無論 overflow 選項如何，都必須為正數。

    era 和 eraYear

    一個字串和一個整數，可以用來代替 year。請參閱 PlainDate 的 era 和 eraYear。僅在日曆系統有紀元時使用。era 和 eraYear 必須同時提供。如果指定了 month，則必須提供 eraYear（與 era 一起）或 year 中的至少一個。如果同時提供了 era、eraYear 和 year，它們必須一致。

    月份

    一個正整數，可以用來代替 monthCode。請參閱 PlainDate 的 month。無論 overflow 選項如何，都必須為正數。如果提供了 month，並且日曆不是 iso8601，那麼還必須提供 year（或 eraYear 和 era 作為替代），因為在不同年份中，同一個 month 可能會對映到多個可能的 monthCode 值。month 或 monthCode 中至少要提供一個。如果同時提供了 month 和 monthCode，它們必須一致。

    monthCode

    對應於 monthCode 屬性。month 或 monthCode 中至少要提供一個。如果同時提供了 month 和 monthCode，它們必須一致。

    年

    一個整數，如果提供了 month，則用於消除歧義，因為對於某些日曆，同一個 month 在不同年份可能意味著不同的 monthCode。請參閱 PlainDate 的 year。如果提供了年份，那麼 overflow 選項會在給定的年份中驗證月-日，而不僅僅是任何一年。如果指定了 month，則必須提供 eraYear（與 era 一起）或 year 中的至少一個。如果同時提供了 era、eraYear 和 year，它們必須一致。

options 可選

包含以下屬性的物件

overflow 可選

一個字串，指定當日期元件超出範圍時（使用物件 info 時）的行為。可能的值有：

"constrain"（預設）

日期元件被限制在有效範圍內。

"reject"

如果日期元件超出範圍，則丟擲 RangeError。

返回值

一個新的 Temporal.PlainMonthDay 物件，表示由 info 在指定的 calendar 中指定的月和日。

每個 PlainMonthDay 內部儲存一個完整的 ISO 8601 日期，該日期在目標日曆中具有與所公開的相同的月-日。參考年份在使用 toString() 進行字串化時可見，它會輸出一個 ISO 日期。參考年份是任意但一致地選擇的（也就是說，每個 (monthCode, day) 對總是對映到同一個 ISO 參考年份）。它不使用輸入中提供的年份。相反，參考年份是透過查詢 1972 年 12 月 31 日之前在目標日曆中具有相同月-日的最新日期來選擇的，如果不存在這樣的日期，則選擇 1972 年 12 月 31 日之後的最早日期。

例如，對於源自公曆的日曆，參考年份是 1972 年。對於希伯來曆，參考年份是公曆的 1972 年，但如果月份是 Adar I (M05L)，這是一個閏月，則參考年份是 1970 年（希伯來曆的 5730 年），因為下一個閏年是 1973 年（希伯來曆的 5733 年），它在 1972 年之後。

這種參考年份的規範化確保了 equals() 可以直接比較底層的 ISO 日期，而無需額外的計算。

異常

TypeError

在以下情況之一中丟擲

  • info 不是物件或字串。
  • options 不是物件或 undefined。
  • 所提供的屬性不足以明確確定一個日期。你通常需要提供一個 year（或 era 和 eraYear）、一個 month 和一個 day，或者一個 monthCode 和一個 day。
RangeError

在以下情況之一中丟擲

  • 指定相同元件的提供的屬性不一致。
  • 提供的非數字屬性無效；例如，如果 monthCode 在此日曆中從未是有效的月份程式碼。
  • 提供的數字屬性超出範圍，並且 options.overflow 設定為 "reject"。
  • 該資訊不在 可表示範圍 內，該範圍是距 Unix 紀元 ±(108 + 1) 天，或大約 ±273,972.6 年。

示例

從物件建立 PlainMonthDay

js
// Month code + day
const md = Temporal.PlainMonthDay.from({ monthCode: "M05", day: 2 });
console.log(md.toString()); // 05-02

// Month + day (only for ISO calendar)
const md2 = Temporal.PlainMonthDay.from({ month: 7, day: 1 });
console.log(md2.toString()); // 07-01

// Year + month + day
const md3 = Temporal.PlainMonthDay.from({ year: 2021, month: 7, day: 1 });
console.log(md3.toString()); // 07-01

// Year + month + day in a different calendar (where year is required)
const md4 = Temporal.PlainMonthDay.from({
  year: 2021,
  month: 7,
  day: 1,
  calendar: "hebrew",
});
console.log(md4.toString()); // 1972-03-16[u-ca=hebrew]

// Month code + day in a different calendar
const md5 = Temporal.PlainMonthDay.from({
  monthCode: "M05L",
  day: 1,
  calendar: "hebrew",
});
console.log(md5.toString()); // 1970-02-07[u-ca=hebrew]

控制溢位行為

預設情況下，超出範圍的值會被約束到有效範圍內。一個沒有明確參考年份的月-日只要存在某一年份中它是有效的，它就是有效的，即使它不是每年都出現。如果年、月、日都給出，那麼對映到有效月-日的規則可能會很複雜且特定於每個日曆，但通常的行為是這樣的：

  • 如果 year/month 組合無效，month 會被約束以在該年份中獲得一個有效的 monthCode。
  • 如果 year/monthCode 組合無效，則會選擇一個不同的年份以保持 monthCode 不變。
  • day 在給定的年月中被約束以獲得一個有效的月-日。

這與通常的日期約束略有不同，後者更傾向於年份而不是月份程式碼。

js
// Month always out of range
const md1 = Temporal.PlainMonthDay.from({ month: 13, day: 1 });
console.log(md1.toString()); // 12-01

// Month out of range for the specific year: 5732 is not a Hebrew leap year,
// so month is clamped to 12 to resolve to a valid monthCode
const md2 = Temporal.PlainMonthDay.from({
  year: 5732,
  month: 13,
  day: 1,
  calendar: "hebrew",
});
console.log(md2.toLocaleString("en-US", { calendar: "hebrew" })); // 1 Elul
const underlyingDate = Temporal.PlainDate.from(md2.toString());
console.log(underlyingDate.year, underlyingDate.month); // 5732 12

// Month code exists but not for the specific year: 5731 is not a Hebrew leap year,
// so a different year is chosen to keep the monthCode as M05L
const md3 = Temporal.PlainMonthDay.from({
  year: 5731,
  monthCode: "M05L",
  day: 1,
  calendar: "hebrew",
});
console.log(md3.toLocaleString("en-US", { calendar: "hebrew" })); // 1 Adar I
const underlyingDate2 = Temporal.PlainDate.from(md3.toString());
console.log(underlyingDate2.year, underlyingDate2.monthCode); // 5730 M05L

// Day always out of range
const md4 = Temporal.PlainMonthDay.from({ month: 2, day: 30 });
console.log(md4.toString()); // 02-29

// Day out of range for the specific year-month
const md5 = Temporal.PlainMonthDay.from({ year: 2021, month: 2, day: 29 });
console.log(md5.toString()); // 02-28

你可以將此行為更改為丟擲錯誤

js
Temporal.PlainMonthDay.from(
  { year: 2021, month: 13, day: 1 },
  { overflow: "reject" },
);
// RangeError: date value "month" not in 1..12: 13

規範

規範
Temporal
# sec-temporal.plainmonthday.from

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

此頁最後修改於 ，由 MDN 貢獻者修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題
© . Content available under a Creative Commons license.