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