Temporal.PlainDate

描述

PlainDate 本質上是 Temporal.PlainDateTime 物件中的日期部分，去除了時間資訊。由於日期和時間資訊之間沒有太多互動，因此所有有關日期屬性的通用資訊都在這裡記錄。

RFC 9557 格式

PlainDate 物件可以使用 RFC 9557 格式進行序列化和解析，該格式是 ISO 8601 / RFC 3339 格式的擴充套件。字串形式如下（空格僅為可讀性而設，實際字串中不應包含空格）

YYYY-MM-DD [u-ca=calendar_id]

YYYY

一個四位數，或者一個帶 + 或 - 號的六位數。

MM

一個從 01 到 12 的兩位數。

DD

一個從 01 到 31 的兩位數。YYYY、MM 和 DD 部分可以用 - 分隔或不用。

[u-ca=calendar_id] 可選

將 calendar_id 替換為要使用的日曆。有關常用支援的日曆型別列表，請參閱 Intl.supportedValuesOf()。預設為 [u-ca=iso8601]。可以透過在鍵前加 ! 來新增關鍵標誌：例如 [!u-ca=iso8601]。這個標誌通常告訴其他系統，如果它們不支援它，就不能忽略它。如果註解包含兩個或多個日曆註解且其中一個是關鍵的，Temporal 解析器將丟擲錯誤。請注意，YYYY-MM-DD 始終被解釋為 ISO 8601 日曆日期，然後轉換為指定的日曆。

作為輸入，你可以選擇性地包含時間、偏移量和時區識別符號，格式與 PlainDateTime 相同，但它們將被忽略。[key=value] 格式的其他註解也將被忽略，且它們不得帶有關鍵標誌。

序列化時，你可以配置是否顯示日曆 ID，以及是否為其新增關鍵標誌。

無效日期校正

Temporal.PlainDate.from()、Temporal.PlainDate.prototype.with()、Temporal.PlainDate.prototype.add()、Temporal.PlainDate.prototype.subtract() 方法，以及其他 Temporal 物件中的對應方法，允許使用日曆特定屬性構造日期。日期元件可能超出範圍。在 ISO 日曆中，這總是溢位，例如月份大於 12 或日期大於天數，並且修復它只會涉及將值鉗制到允許的最大值。在其他日曆中，無效情況可能更復雜。使用 overflow: "constrain" 選項時，無效日期將按以下方式校正為有效日期

• 如果日期不存在但月份存在：選擇同一月份中最接近的日期。如果該月份中有兩個同樣接近的日期，則選擇較晚的日期。
• 如果月份是閏月，但在該年份不存在：根據該日曆使用者的文化習俗選擇另一個日期。通常，這會導致該閏月通常所屬的閏年中的前一個月或後一個月的相同日期。
• 如果月份因其他原因在該年份不存在：選擇在該年份內最接近的日期。如果該年份中有兩個同樣接近的日期，則選擇較晚的日期。
• 如果整個年份不存在：選擇在不同年份中最接近的日期。如果存在兩個同樣接近的日期，則選擇較晚的日期。

建構函式

Temporal.PlainDate() 實驗性

透過直接提供底層資料來建立新的 Temporal.PlainDate 物件。

靜態方法

Temporal.PlainDate.compare() 實驗性

返回一個數字（-1、0 或 1），指示第一個日期是早於、等於還是晚於第二個日期。等同於比較底層 ISO 8601 日期的年、月、日欄位。

Temporal.PlainDate.from() 實驗性

從另一個 Temporal.PlainDate 物件、具有日期屬性的物件或 RFC 9557 字串建立新的 Temporal.PlainDate 物件。

例項屬性

這些屬性在 Temporal.PlainDate.prototype 上定義，並由所有 Temporal.PlainDate 例項共享。

Temporal.PlainDate.prototype.calendarId 實驗性

返回一個字串，表示用於解釋內部 ISO 8601 日期的日曆。

Temporal.PlainDate.prototype.constructor

建立例項物件的建構函式。對於 Temporal.PlainDate 例項，初始值是 Temporal.PlainDate() 建構函式。

Temporal.PlainDate.prototype.day 實驗性

返回一個正整數，表示此日期在本月中的基於 1 的日期索引，這與你在日曆上看到的日期數字相同。依賴於日曆。通常從 1 開始並且是連續的，但並非總是如此。

Temporal.PlainDate.prototype.dayOfWeek 實驗性

返回一個正整數，表示該日期在星期中的基於 1 的日期索引。一週中的日期從 1 到 daysInWeek 依次編號，每個數字對映到其名稱。取決於日曆。通常，1 在日曆中表示星期一，即使使用該日曆的區域可能將不同的日期視為一週的第一天（請參閱 Intl.Locale.prototype.getWeekInfo()）。

Temporal.PlainDate.prototype.dayOfYear 實驗性

返回一個正整數，表示該日期在一年中的基於 1 的日期索引。該年份的第一天是 1，最後一天是 daysInYear。取決於日曆。

Temporal.PlainDate.prototype.daysInMonth 實驗性

返回一個正整數，表示此日期所在月份的天數。依賴於日曆。

Temporal.PlainDate.prototype.daysInWeek 實驗性

返回一個正整數，表示此日期所在星期中的天數。依賴於日曆。對於 ISO 8601 日曆，這總是 7，但在其他日曆系統中，每週可能不同。

Temporal.PlainDate.prototype.daysInYear 實驗性

返回一個正整數，表示此日期所在年份的天數。依賴於日曆。對於 ISO 8601 日曆，這是 365，閏年是 366。

Temporal.PlainDate.prototype.era 實驗性

返回一個日曆特定的小寫字串，表示此日期的紀元，如果日曆不使用紀元（例如 ISO 8601），則返回 undefined。era 和 eraYear 一起唯一地標識日曆中的一年，就像 year 一樣。依賴於日曆。對於格里高利曆，它是 "gregory" 或 "gregory-inverse"。

Temporal.PlainDate.prototype.eraYear 實驗性

返回一個非負整數，表示此日期在紀元內的年份，如果日曆不使用紀元（例如 ISO 8601），則返回 undefined。年份索引通常從 1（更常見）或 0 開始，一個紀元內的年份可以隨時間減少（例如格里高利曆的公元前）。era 和 eraYear 一起唯一地標識日曆中的一年，就像 year 一樣。依賴於日曆。

Temporal.PlainDate.prototype.inLeapYear 實驗性

返回一個布林值，指示此日期是否在閏年。閏年是指比平年有更多天數（由於閏日或閏月）的年份。依賴於日曆。

Temporal.PlainDate.prototype.month 實驗性

返回一個正整數，表示該日期在年份中的基於 1 的月份索引。該年份的第一個月是 1，最後一個月是 monthsInYear。取決於日曆。請注意，與 Date.prototype.getMonth() 不同，索引是基於 1 的。如果日曆有閏月，則具有相同 monthCode 的月份在不同年份中可能具有不同的 month 索引。

Temporal.PlainDate.prototype.monthCode 實驗性

返回一個日曆特定的字串，表示此日期的月份。依賴於日曆。通常是 M 加上一個兩位數的月份編號。對於閏月，它是上一個月的程式碼後跟 L。如果閏月是一年中的第一個月，程式碼是 M00L。

Temporal.PlainDate.prototype.monthsInYear 實驗性

返回一個正整數，表示此日期所在年份的月份數。依賴於日曆。對於 ISO 8601 日曆，這總是 12，但在其他日曆系統中可能會有所不同。

Temporal.PlainDate.prototype.weekOfYear 實驗性

返回一個正整數，表示該日期在 yearOfWeek 中的基於 1 的周索引，如果日曆沒有明確定義的周系統，則返回 undefined。年份的第一週是 1。取決於日曆。請注意，對於 ISO 8601，年份的頭幾天和最後幾天可能被歸入上一年或下一年的第一週。

Temporal.PlainDate.prototype.year 實驗性

返回一個整數，表示此日期的年份，相對於日曆特定的紀元開始年份。依賴於日曆。通常，第 1 年是最新紀元的第一年或 ISO 8601 的 0001 年。如果紀元在年中開始，該年在紀元開始日期前後將具有相同的值。

Temporal.PlainDate.prototype.yearOfWeek 實驗性

返回一個整數，表示與該日期的 weekOfYear 配對的年份，如果日曆沒有明確定義的周系統，則返回 undefined。取決於日曆。通常這是日期的年份，但對於 ISO 8601，年份的頭幾天和最後幾天可能歸屬於上一年或下一年的第一週，導致 yearOfWeek 相差 1。

Temporal.PlainDate.prototype[Symbol.toStringTag]

[Symbol.toStringTag] 屬性的初始值是字串 "Temporal.PlainDate"。此屬性在 Object.prototype.toString() 中使用。

例項方法

Temporal.PlainDate.prototype.add() 實驗性

返回一個新的 Temporal.PlainDate 物件，表示該日期按給定持續時間（以可由 Temporal.Duration.from() 轉換的形式）向前移動後的日期。

Temporal.PlainDate.prototype.equals() 實驗性

如果該日期在值上與另一個日期（以可由 Temporal.PlainDate.from() 轉換的形式）等效，則返回 true，否則返回 false。它們根據日期值和日曆進行比較。

Temporal.PlainDate.prototype.since() 實驗性

返回一個新的 Temporal.Duration 物件，表示從另一個日期（以可由 Temporal.PlainDate.from() 轉換的形式）到此日期的持續時間。如果另一個日期在此日期之前，則持續時間為正，如果在此日期之後，則為負。

Temporal.PlainDate.prototype.subtract() 實驗性

返回一個新的 Temporal.PlainDate 物件，表示該日期按給定持續時間（以可由 Temporal.Duration.from() 轉換的形式）向後移動後的日期。

Temporal.PlainDate.prototype.toJSON() 實驗性

返回一個字串，表示此日期的 RFC 9557 格式，與呼叫 toString() 相同。旨在由 JSON.stringify() 隱式呼叫。

Temporal.PlainDate.prototype.toLocaleString() 實驗性

返回此日期的語言敏感表示字串。

Temporal.PlainDate.prototype.toPlainDateTime() 實驗性

返回一個新的 Temporal.PlainDateTime 物件，表示此日期和在同一日曆系統中提供的某個時間。

Temporal.PlainDate.prototype.toPlainMonthDay() 實驗性

返回一個新的 Temporal.PlainMonthDay 物件，表示此日期在同一日曆系統中的 monthCode 和 day。

Temporal.PlainDate.prototype.toPlainYearMonth() 實驗性

返回一個新的 Temporal.PlainYearMonth 物件，表示此日期在同一日曆系統中的 year 和 month。

Temporal.PlainDate.prototype.toString() 實驗性

返回一個字串，表示此日期的 RFC 9557 格式。

Temporal.PlainDate.prototype.toZonedDateTime() 實驗性

返回一個新的 Temporal.ZonedDateTime 物件，表示此日期、提供的某個時間和提供的某個時區，在同一日曆系統中。

Temporal.PlainDate.prototype.until() 實驗性

返回一個新的 Temporal.Duration 物件，表示從此日期到另一個日期（以可由 Temporal.Instant.from() 轉換的形式）的持續時間。如果另一個日期在此日期之後，則持續時間為正，如果在此日期之前，則為負。

Temporal.PlainDate.prototype.valueOf() 實驗性

丟擲 TypeError，這會阻止 Temporal.PlainDate 例項在算術或比較操作中被 隱式轉換為原始值。

Temporal.PlainDate.prototype.with() 實驗性

返回一個新的 Temporal.PlainDate 物件，表示此日期，其中某些欄位已被新值替換。

Temporal.PlainDate.prototype.withCalendar() 實驗性

返回一個新的 Temporal.PlainDate 物件，表示此日期在新日曆系統中的解釋。

規範

瀏覽器相容性

另見

• Temporal
• Temporal.Duration
• Temporal.PlainDateTime
• Temporal.PlainMonthDay
• Temporal.PlainYearMonth
• Temporal.ZonedDateTime