Temporal.Instant

描述

Temporal.Instant 在語義上與 Date 相同。它們都封裝了一個時間點，但 Temporal.Instant 更精確，因為它儲存納秒而不是毫秒。Temporal.Instant 還避免了 Date 的陷阱，因為它不假設任何日曆或時區資訊——如果你想讀取任何日期或時間資訊（例如年份或月份），你需要首先使用 toZonedDateTimeISO() 將其轉換為 Temporal.ZonedDateTime。

你可以使用 Date.prototype.toTemporalInstant() 方法從 Date 轉換為 Temporal.Instant，該方法應優先於其他方法（例如 Temporal.Instant.fromEpochMilliseconds()），因為前者涉及的使用者程式碼更少，並且可能更最佳化。你也可以使用 Temporal.Instant 的紀元毫秒將其轉換為 Date，例如 new Date(instant.epochMilliseconds)。

RFC 9557 格式

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

YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm

YYYY

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

MM

一個從 01 到 12 的兩位數。

DD

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

T

日期-時間分隔符，可以是 T、t 或空格。

HH

一個兩位數字，從 00 到 23。

mm 可選

一個從 00 到 59 的兩位數。預設為 00。

ss.sssssssss 可選

一個從 00 到 59 的兩位數。可以選擇後跟 . 或 , 和一到九位數字。預設為 00。HH、mm 和 ss 部分可以用 : 分隔或不用。你可以只省略 ss 或同時省略 ss 和 mm，因此時間可以有三種形式：HH、HH:mm 或 HH:mm:ss.sssssssss。

Z/±HH:mm

UTC 指示符 Z 或 z，或以 + 或 - 形式表示的 UTC 偏移量，後跟與時間分量相同的格式。請注意，其他系統可能不支援分鐘以下的精度（:ss.sssssssss），該精度被接受但從不輸出。如果提供了偏移量，則時間將按指定的偏移量進行解釋。

作為輸入，你可以選擇性地包含時區識別符號和日曆，格式與 ZonedDateTime 相同，但它們將被忽略。其他 [key=value] 格式的註解也會被忽略，並且它們不能具有關鍵標誌。

序列化時，你可以配置小數秒位數和偏移量。

建構函式

Temporal.Instant() 實驗性

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

靜態方法

Temporal.Instant.compare() 實驗性

返回一個數字（-1、0 或 1），表示第一個瞬間是在第二個瞬間之前、相同還是之後。等同於比較兩個瞬間的 epochNanoseconds。

Temporal.Instant.from() 實驗性

從另一個 Temporal.Instant 物件或 RFC 9557 字串建立一個新的 Temporal.Instant 物件。

Temporal.Instant.fromEpochMilliseconds() 實驗性

從自 Unix 紀元（1970 年 1 月 1 日午夜，UTC）以來的毫秒數建立一個新的 Temporal.Instant 物件。

Temporal.Instant.fromEpochNanoseconds() 實驗性

從自 Unix 紀元（1970 年 1 月 1 日午夜，UTC）以來的納秒數建立一個新的 Temporal.Instant 物件。

例項屬性

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

Temporal.Instant.prototype.constructor

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

Temporal.Instant.prototype.epochMilliseconds 實驗性

返回一個整數，表示自 Unix 紀元（1970 年 1 月 1 日午夜，UTC）到此瞬間經過的毫秒數。相當於將 epochNanoseconds 除以 1e6 並向下取整。

Temporal.Instant.prototype.epochNanoseconds 實驗性

返回一個 BigInt，表示自 Unix 紀元（1970 年 1 月 1 日午夜，UTC）到此瞬間經過的納秒數。

Temporal.Instant.prototype[Symbol.toStringTag]

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

例項方法

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

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

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

如果此瞬間的值與另一個瞬間（可以由 Temporal.Instant.from() 轉換的形式）等效，則返回 true，否則返回 false。它們透過其紀元納秒進行比較。等同於 Temporal.Instant.compare(this, other) === 0。

Temporal.Instant.prototype.round() 實驗性

返回一個新的 Temporal.Instant 物件，表示此瞬間四捨五入到給定單位後的時間。

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

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

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

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

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

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

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

返回一個帶有此瞬間的語言敏感表示的字串。在支援 Intl.DateTimeFormat API 的實現中，此方法委託給 Intl.DateTimeFormat。

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

返回一個字串，表示此瞬間的 RFC 9557 格式，使用指定的時區。

Temporal.Instant.prototype.toZonedDateTimeISO() 實驗性

返回一個新的 Temporal.ZonedDateTime 物件，表示此瞬間在指定時區中，使用 ISO 8601 日曆系統。

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

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

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

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

規範

瀏覽器相容性

另見

• Temporal
• Temporal.Duration
• Temporal.ZonedDateTime