Intl.DurationFormat() 构造函数

¥Syntax

new Intl.DurationFormat()
new Intl.DurationFormat(locales)
new Intl.DurationFormat(locales, options)

注意：Intl.DurationFormat() 只能与 new 一起构建。尝试在没有 new 的情况下调用它会抛出 TypeError。

¥Note: Intl.DurationFormat() can only be constructed with new. Attempting to call it without new throws a TypeError.

¥Parameters

locales Optional

带有 BCP 47 语言标记或 Intl.Locale 实例的字符串，或此类区域设置标识符的数组。当传递 undefined 或不支持任何指定的区域设置标识符时，将使用运行时的默认区域设置。有关 locales 论证的一般形式和解释，请参阅 Intl 主页参数说明。

允许使用以下 Unicode 扩展键：

nu

参见 numberingSystem。

该键也可以通过 options 设置（如下所列）。当两者都设置时，options 属性优先。

options Optional

包含以下属性的对象，按检索顺序排列（所有属性都是可选的）：

localeMatcher

要使用的区域设置匹配算法。可能的值为 "lookup" 和 "best fit"；默认为 "best fit"。有关此选项的信息，请参阅 区域设置识别和协商。

numberingSystem

用于数字格式化的编号系统，例如 "arab"、"hans"、"mathsans" 等。有关支持的编号系统类型的列表，请参阅 Intl.Locale.prototype.getNumberingSystems()。该选项也可以通过 nu Unicode 扩展键设置；如果两者都提供，则此 options 属性优先。

style

格式化持续时间的样式。可能的值为：

"long"

例如 1 小时 50 分钟

"short"（默认）

例如，1 小时 50 分钟

"narrow"

例如，1 小时 50 米

"digital"

例如，1:50:00

years

格式化年份的样式。可能的值为 "long"、"short" 和 "narrow"；如果不是 "digital"，则默认为 options.style，否则默认为 "short"。

yearsDisplay

是否始终显示年份，或者仅在非零时显示。可能的值为 "always" 和 "auto"；如果未指定 years，则默认为 "auto"，否则为 "always"。

months

格式化月份的样式。可能的值为 "long"、"short" 和 "narrow"；如果不是 "digital"，则默认为 options.style，否则默认为 "short"。

monthsDisplay

是否始终显示月份，或者仅在非零时显示。可能的值为 "always" 和 "auto"；如果未指定 months，则默认为 "auto"，否则为 "always"。

weeks

格式化周的样式。可能的值为 "long"、"short" 和 "narrow"；如果不是 "digital"，则默认为 options.style，否则默认为 "short"。

weeksDisplay

是否始终显示周，或者仅在非零时显示。可能的值为 "always" 和 "auto"；如果未指定 weeks，则默认为 "auto"，否则为 "always"。

days

格式化日期的样式。可能的值为 "long"、"short" 和 "narrow"；如果不是 "digital"，则默认为 options.style，否则默认为 "short"。

daysDisplay

是否始终显示天数，或者仅在非零时显示。可能的值为 "always" 和 "auto"；如果未指定 days，则默认为 "auto"，否则为 "always"。

hours

格式化时间的样式。可能的值为 "long"、"short"、"narrow"、"numeric" 和 "2-digit"；如果不是 "digital"，则默认为 options.style，否则默认为 "numeric"。

hoursDisplay

是否始终显示小时，或者仅在非零时显示。可能的值为 "always" 和 "auto"；如果未指定 hours 并且 options.style 不是 "digital"，则默认值为 "auto"，否则默认为 "always"。

minutes

格式化会议记录的样式。

• 如果 hours 是 "numeric" 或 "2-digit"，则可能的值为 "numeric" 和 "2-digit"，并且 "numeric" 被归一化为 "2-digit"；默认为 "numeric"。
• 否则，可能的值为 "long"、"short"、"narrow"、"numeric" 和 "2-digit"；如果不是 "digital"，则默认为 options.style，否则默认为 "numeric"。

minutesDisplay

是否始终显示分钟，或者仅在非零时显示。可能的值为 "always" 和 "auto"；如果未指定 minutes 并且 options.style 不是 "digital"，则默认值为 "auto"，否则默认为 "always"。

seconds

格式化秒的样式。

• 如果 minutes 是 "numeric" 或 "2-digit"，则可能的值为 "numeric" 和 "2-digit"，并且 "numeric" 被归一化为 "2-digit"；默认为 "numeric"。
• 否则，可能的值为 "long"、"short"、"narrow"、"numeric" 和 "2-digit"；如果不是 "digital"，则默认为 options.style，否则默认为 "numeric"。

secondsDisplay

是否始终显示秒，或者仅在非零时显示秒。可能的值为 "always" 和 "auto"；如果未指定 seconds 并且 options.style 不是 "digital"，则默认值为 "auto"，否则默认为 "always"。

milliseconds

格式化毫秒的样式。

• 如果 seconds 是 "numeric" 或 "2-digit"，则唯一可能的值为 "numeric"；默认为 "numeric"。
• 否则，可能的值为 "long"、"short"、"narrow" 和 "numeric"；如果不是 "digital"，则默认为 options.style，否则默认为 "numeric"。

millisecondsDisplay

是否始终显示毫秒，或者仅在非零时显示。

• 如果 seconds 是 "numeric" 或 "2-digit"，则唯一可能的值为 "auto"；当未指定 milliseconds 时，仅默认为 "auto"。
• 否则，可能的值为 "always" 和 "auto"；如果未指定 milliseconds，则默认为 "auto"，否则为 "always"。

microseconds

格式化微秒的样式。

• 如果 milliseconds 是 "numeric"，则唯一可能的值为 "numeric"；默认为 "numeric"。
• 否则，可能的值为 "long"、"short"、"narrow" 和 "numeric"；如果不是 "digital"，则默认为 options.style，否则默认为 "numeric"。

microsecondsDisplay

是否始终显示微秒，或者仅在非零时显示。

• 如果 milliseconds 是 "numeric"，则唯一可能的值为 "auto"；当未指定 microseconds 时，仅默认为 "auto"。
• 否则，可能的值为 "always" 和 "auto"；如果未指定 microseconds，则默认为 "auto"，否则为 "always"。

nanoseconds

格式化纳秒的样式。

• 如果 microseconds 是 "numeric"，则唯一可能的值为 "numeric"；默认为 "numeric"。
• 否则，可能的值为 "long"、"short"、"narrow" 和 "numeric"；如果不是 "digital"，则默认为 options.style，否则默认为 "numeric"。

nanosecondsDisplay

是否始终显示纳秒，或者仅在非零时显示。

• 如果 microseconds 是 "numeric"，则唯一可能的值为 "auto"；当未指定 nanoseconds 时，仅默认为 "auto"。
• 否则，可能的值为 "always" 和 "auto"；如果未指定 nanoseconds，则默认为 "auto"，否则为 "always"。

fractionalDigits

在输出中显示多少个小数秒数字。可能的值是从 0 到 9；默认值为 undefined（根据需要包含尽可能多的小数位）。

¥Exceptions

RangeError

如果 locales 或 options 包含无效值，则抛出该异常。

¥Description

对于每个时间段，都会在底层构造一个 Intl.NumberFormat 对象。它使用以下选项（详细信息请参见 Intl.NumberFormat()）：

¥For each time segment, an Intl.NumberFormat object is constructed under the hood. It uses the following options (see Intl.NumberFormat() for details):

• numberingSystem：options.numberingSystem 的值

当 milliseconds、microseconds 或 nanoseconds 使用 "numeric" 样式时，还使用以下选项：

¥When milliseconds, microseconds, or nanoseconds uses the "numeric" style, the following options are also used:

• minimumFractionDigits：当 options.fractionalDigits 为 undefined 时为 0，否则为 options.fractionalDigits
• maximumFractionDigits：当 options.fractionalDigits 为 undefined 时为 9，否则为 options.fractionalDigits
• roundingMode："trunc"

当时间段使用 "2-digit" 样式时，还使用以下选项：

¥When the time segment uses the "2-digit" style, the following options are also used:

• minimumIntegerDigits：2

当时间段使用 "long"、"short" 或 "narrow" 样式时，还使用以下选项：

¥When the time segment uses the "long", "short", or "narrow" style, the following options are also used:

• style：当指定 "long"、"short" 或 "narrow" 时为 "unit"，否则为 undefined
• unit：当前格式化的单元（"years"、"days"、"nanoseconds" 等）
• unitDisplay：时间段样式的值（"long"、"short" 或 "narrow"）

¥Examples

¥Using the Intl.DurationFormat() constructor

const duration = {
  hours: 2,
  minutes: 20,
  seconds: 35,
};

console.log(new Intl.DurationFormat("pt", { style: "long" }).format(duration));
// "2 horas, 20 minutos e 35 segundos"

¥See also

• Intl.DurationFormat
• Intl.supportedValuesOf()
• Intl