Temporal.Duration.prototype.round()

語法

round(smallestUnit)
round(options)

引數

smallestUnit（最小單位）

表示 smallestUnit 選項的字串。這是一個便捷的過載，因此 round(smallestUnit) 等價於 round({ smallestUnit })，其中 smallestUnit 是一個字串。

options

一個包含以下部分或全部屬性的物件（按檢索和驗證的順序）：

largestUnit 可選

任何時間單位：“years”、“months”、“weeks”、“days”、“hours”、“minutes”、“seconds”、“milliseconds”、“microseconds”、“nanoseconds”，或者它們的單數形式；或者值“auto”，表示此持續時間的最大非零組成部分或 smallestUnit（取兩者中較大的一個）。預設為“auto”。結果不會包含比此更大的單位；例如，如果最大單位是“minutes”，那麼“1 hour 30 minutes”將變為“90 minutes”。

relativeTo 可選

一個帶時區或純日期(時間)，提供時間資訊和日曆資訊來解析日曆持續時間（請參閱連結瞭解此選項的一般解釋）。如果 this 或 other 是日曆持續時間，或者 smallestUnit 是日曆單位，則此引數必填。

roundingIncrement 可選

一個數字（截斷為整數），表示給定 smallestUnit 中的舍入增量。預設為 1。必須在 1 到 1e9（包括兩端）的範圍內。如果最小單位是小時、分鐘、秒、毫秒、微秒或納秒，則增量必須是該單位最大值的除數；例如，如果單位是小時，則增量必須是 24 的除數，並且不能是 24 本身，這意味著它可以是 1、2、3、4、6、8 或 12。

roundingMode 可選

一個字串，表示舍入模式，指定在各種情況下向上或向下舍入。請參閱 Intl.NumberFormat()。預設為 "halfExpand"。

smallestUnit 可選

任何時間單位：“years”、“months”、“weeks”、“days”、“hours”、“minutes”、“seconds”、“milliseconds”、“microseconds”、“nanoseconds”，或者它們的單數形式。預設為“nanoseconds”。對於大於“nanoseconds”的單位，smallestUnit 的小數部分將根據 roundingIncrement 和 roundingMode 設定進行舍入。必須小於或等於 largestUnit。必須提供 smallestUnit 和 largestUnit 至少一個。

返回值

一個新的 Temporal.Duration 物件，其最大單位不大於 largestUnit 選項，最小單位不小於 smallestUnit 選項。smallestUnit 的小數部分將根據 roundingIncrement 和 roundingMode 設定進行舍入。

異常

RangeError

如果任何選項無效，則丟擲。

描述

round() 方法執行兩個操作：舍入和平衡。它執行以下操作：

1. 它確保持續時間是平衡的。如果某個組成部分超過了其首選最大值（每天 24 小時，每小時 60 分鐘等），則多餘的部分將結轉到下一個更大的單位，直到達到 largestUnit。例如，如果 largestUnit 是“auto”，則“24 hours 90 minutes”變為“25 hours 30 minutes”；如果 largestUnit 是“days”，則變為“1 day 1 hour 30 minutes”。
2. 對於所有大於 largestUnit 的組成部分，它們將被向下結轉到 largestUnit；例如，如果 largestUnit 是“minutes”，則“2 hours 30 minutes”變為“150 minutes”。
3. 對於所有小於 smallestUnit 的組成部分，它們將被向上結轉到 smallestUnit 作為小數部分，然後根據 roundingIncrement 和 roundingMode 設定進行舍入。例如，如果 smallestUnit 是“hours”，則“1 hour 30 minutes”變為“1.5 hours”，然後使用預設設定舍入為“2 hours”。

日曆單位的長度不均勻。它們的長度是相對於起點解析的。例如，公曆中“2 年”的持續時間可能是 730 天或 731 天長，具體取決於它是否經過閏年。當舍入到日曆單位時，我們首先獲取 relativeTo + duration 所表示的精確日期時間，然後根據 smallestUnit 和 roundingIncrement 將其向下和向上舍入以獲得兩個候選值。然後，我們根據 roundingMode 設定選擇候選值，最後減去 relativeTo 以獲得最終持續時間。

示例

小單位的四捨五入

const duration = Temporal.Duration.from({ hours: 1, minutes: 30, seconds: 15 });
const roundedDuration = duration.round("minutes");
console.log(roundedDuration.toString()); // "PT1H30M"

避免更大的單位

const duration = Temporal.Duration.from({
  days: 3,
  hours: 1,
  minutes: 41,
  seconds: 5,
});
const roundedDuration = duration.round({ largestUnit: "hours" });
console.log(
  `Time spent on this problem: ${roundedDuration.toLocaleString("en-US", { style: "digital" })}`,
);
// Time spent on this problem: 73:41:05

舍入到整數小時

const duration = Temporal.Duration.from({ days: 1, hours: 1, minutes: 30 });
const roundedDuration = duration.round({
  largestUnit: "hours",
  smallestUnit: "hours",
  roundingMode: "floor",
});
console.log(roundedDuration.hours); // 25

以 15 分鐘為增量舍入

const duration = Temporal.Duration.from({ hours: 1, minutes: 17 });
const roundedDuration = duration.round({
  smallestUnit: "minutes",
  roundingIncrement: 15,
});
console.log(
  `The queue will take approximately ${roundedDuration.toLocaleString("en-US")}`,
);
// The queue will take approximately 1 hr, 15 min

解析日曆持續時間

如果初始持續時間或最大/最小單位包含日曆單位，則必須提供 relativeTo 選項來解析日曆持續時間。

const duration = Temporal.Duration.from({ months: 1, days: 1, hours: 1 });
const roundedDuration = duration.round({
  largestUnit: "days",
  smallestUnit: "days",
  relativeTo: Temporal.PlainDateTime.from("2022-01-01"),
});
console.log(roundedDuration); // "P32D"

規範

瀏覽器相容性

另見

• Temporal.Duration
• Temporal.Duration.prototype.total()