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()