Temporal.Duration

描述

ISO 8601 持續時間格式

Duration 物件可以使用 ISO 8601 持續時間格式進行序列化和解析（帶有一些 ECMAScript 指定的擴充套件）。字串具有以下形式（空格僅用於可讀性，不應出現在實際字串中）

±P nY nM nW nD T nH nM nS

± 可選

一個可選的符號字元（+ 或 -），表示正或負持續時間。預設值為正。

P

文字字元 P 或 p，代表“週期”。

nY, nM, nW, nD, nH, nM, nS

一個數字後跟一個文字字元，分別表示年數（Y）、月數（M）、週數（W）、天數（D）、小時數（H）、分鐘數（M）或秒數（S）。除了最後一個存在的元件之外，所有元件都必須是整數。最後一個元件（如果它是時間元件，即小時、分鐘或秒）可以有一個 1 到 9 位的小數部分，由點或逗號引導，例如 PT0.0021S 或 PT1.1H。任何為零的元件都可以省略，但至少應存在一個元件（即使其值為零，在這種情況下持續時間為零）。

T

文字字元 T 或 t，用於分隔日期部分和時間部分，當且僅當其後至少有一個元件時才應存在。

以下是一些示例

序列化時，輸出會盡可能尊重儲存的元件，保留不平衡的元件。然而，亞秒級元件被序列化為單個小數秒，因此如果它們不平衡，其精確值可能會丟失。正持續時間的加號會被省略。零持續時間總是序列化為 PT0S。

日曆持續時間

日曆持續時間是指包含任何日曆單位：周、月和年的持續時間。非日曆持續時間是可移植的，無需任何日曆資訊即可參與日期/時間算術，因為它們明確地表示一個固定的時間量。然而，日曆持續時間不可移植，因為一個月或一年的天數取決於日曆系統和參考時間點。因此，嘗試對日曆持續時間執行任何算術運算都會丟擲錯誤，因為持續時間本身不跟蹤日曆。例如，如果我們在公曆五月，那麼“1 個月”是“31 天”，但如果我們在四月，那麼“1 個月”就變成了“30 天”。要新增或減去日曆持續時間，您需要將它們新增到日期中

const dur1 = Temporal.Duration.from({ years: 1 });
const dur2 = Temporal.Duration.from({ months: 1 });

dur1.add(dur2); // RangeError: for calendar duration arithmetic, use date arithmetic relative to a starting point

const startingPoint = Temporal.PlainDate.from("2021-01-01"); // ISO 8601 calendar
startingPoint.add(dur1).add(dur2).since(startingPoint); // "P396D"

其他操作，round()、total() 和 compare()，接受 relativeTo 選項來提供必要的日曆和參考時間資訊。此選項可以是 Temporal.PlainDate、Temporal.PlainDateTime、Temporal.ZonedDateTime，或者可以使用 Temporal.ZonedDateTime.from()（如果提供了 timeZone 選項或字串包含時區註釋）或 Temporal.PlainDate.from() 轉換的物件或字串。

請注意，從 天 到 小時 的轉換在技術上也是模糊的，因為一天的時間長度可能會因偏移量變化（例如夏令時）而異。您可以提供一個帶有時區的 relativeTo 來解釋這些變化；否則將假定為 24 小時一天。

持續時間平衡

表示同一持續時間的方式有很多種：例如，“1 分鐘 30 秒”和“90 秒”是等效的。然而，根據上下文，一種表示方式可能比另一種更合適。因此，通常情況下，Duration 物件會盡可能保留輸入值，以便在格式化時能按您預期的方式顯示。

持續時間的每個元件都有其最佳範圍；小時應在 0 到 23 之間，分鐘應在 0 到 59 之間，依此類推。當一個元件超出其最佳範圍時，多餘的部分可能會“進位”到下一個更大的元件。要進行進位，我們需要回答“一個 Y 中有多少個 X？”這個問題，對於日曆單位來說，這是一個複雜的問題，因此在這種情況下需要日曆。另請注意，預設情況下，天 直接進位到 月；只有在明確請求時才進位 周 單位。如果儘可能多地進位，所有元件都在其最佳範圍內的最終結果稱為“平衡”持續時間。不平衡持續時間通常以“頭重腳輕”的形式出現，其中最大單位不平衡（例如，“27 小時 30 分鐘”）；其他形式，例如“23 小時 270 分鐘”，很少見。

round() 方法總是將持續時間平衡為“頭重腳輕”的形式，直至 largestUnit 選項。使用足夠大的手動 largestUnit 選項，您可以完全平衡持續時間。同樣，add() 和 subtract() 方法將結果持續時間平衡到輸入持續時間的最大單位。

請注意，由於 ISO 8601 持續時間格式將亞秒級元件表示為單個分數數字，因此在使用預設格式進行序列化時，無法保留不平衡的亞秒級元件。例如，“1000 毫秒”序列化為 "PT1S"，然後反序列化為“1 秒”。如果您需要保留亞秒級元件的量級，則需要手動將其序列化為 JSON 物件（因為預設情況下 toJSON() 方法以 ISO 8601 格式序列化持續時間）。

持續時間符號

由於持續時間是兩個時間點之間的差值，它可以是正的、負的或零。例如，如果您以相對時間顯示事件時間，則負持續時間可能表示過去的事件，正持續時間表示未來的事件。在我們使用時間元件組合的表示中，符號儲存在每個元件中：負持續時間的所有元件始終為負（或零），正持續時間的所有元件始終為正（或零）。構造具有混合符號元件的持續時間是無效的，並且將被建構函式或 with() 方法拒絕。add() 和 subtract() 方法將平衡結果持續時間以避免混合符號。

建構函式

Temporal.Duration() 實驗性

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

靜態方法

Temporal.Duration.compare() 實驗性

返回一個數字（-1、0 或 1），表示第一個持續時間是比第二個持續時間短、等於還是長。

Temporal.Duration.from() 實驗性

從另一個 Temporal.Duration 物件、具有持續時間屬性的物件或 ISO 8601 字串建立新的 Temporal.Duration 物件。

例項屬性

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

Temporal.Duration.prototype.blank 實驗性

返回一個布林值，如果此持續時間表示零持續時間，則為 true，否則為 false。等同於 duration.sign === 0。

Temporal.Duration.prototype.constructor

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

Temporal.Duration.prototype.days 實驗性

返回一個整數，表示持續時間中的天數。

Temporal.Duration.prototype.hours 實驗性

返回一個整數，表示持續時間中的小時數。

Temporal.Duration.prototype.microseconds 實驗性

返回一個整數，表示持續時間中的微秒數。

Temporal.Duration.prototype.milliseconds 實驗性

返回一個整數，表示持續時間中的毫秒數。

Temporal.Duration.prototype.minutes 實驗性

返回一個整數，表示持續時間中的分鐘數。

Temporal.Duration.prototype.months 實驗性

返回一個整數，表示持續時間中的月數。

Temporal.Duration.prototype.nanoseconds 實驗性

返回一個整數，表示持續時間中的納秒數。

Temporal.Duration.prototype.seconds 實驗性

返回一個整數，表示持續時間中的秒數。

Temporal.Duration.prototype.sign 實驗性

如果此持續時間為正，則返回 1；如果為負，則返回 -1；如果為零，則返回 0。

Temporal.Duration.prototype.weeks 實驗性

返回一個整數，表示持續時間中的週數。

Temporal.Duration.prototype.years 實驗性

返回一個整數，表示持續時間中的年數。

Temporal.Duration.prototype[Symbol.toStringTag]

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

例項方法

Temporal.Duration.prototype.abs() 實驗性

返回一個新的 Temporal.Duration 物件，其值為此持續時間的絕對值（所有欄位保持相同的量級，但符號變為正）。

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

返回一個新的 Temporal.Duration 物件，其值為此持續時間與給定持續時間（可以由 Temporal.Duration.from() 轉換的形式）之和。結果是平衡的。

Temporal.Duration.prototype.negated() 實驗性

返回一個新的 Temporal.Duration 物件，其值為此持續時間的負值（所有欄位保持相同的量級，但符號反轉）。

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

返回一個新的 Temporal.Duration 物件，其持續時間已四捨五入到給定最小單位並/或平衡到給定最大單位。

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

返回一個新的 Temporal.Duration 物件，其值為此持續時間與給定持續時間（可以由 Temporal.Duration.from() 轉換的形式）之間的差值。等同於新增其他持續時間的負值。

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

返回一個字串，表示此持續時間，其格式與呼叫 ISO 8601 格式的 toString() 相同。旨在由 JSON.stringify() 隱式呼叫。

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

返回一個字串，包含此持續時間的語言敏感表示。在支援 Intl.DurationFormat API 的實現中，此方法委託給 Intl.DurationFormat。

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

返回一個字串，表示此持續時間的ISO 8601 格式。

Temporal.Duration.prototype.total() 實驗性

返回一個數字，表示給定單位中的總持續時間。

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

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

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

返回一個新的 Temporal.Duration 物件，表示此持續時間，其中一些欄位已替換為新值。

規範

瀏覽器相容性

另見

• Temporal