Intl.DurationFormat() 构造函数

可用性有限

此功能不是基线功能，因为它在一些最广泛使用的浏览器中不起作用。

Intl.DurationFormat() 构造函数创建 Intl.DurationFormat 对象。

语法

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

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

参数

locales 可选

包含 BCP 47 语言标签的字符串或 Intl.Locale 实例，或此类语言环境标识符的数组。当传递 undefined 或未支持任何指定的语言环境标识符时，将使用运行时的默认语言环境。有关 locales 参数的一般形式和解释，请参阅 Intl 主页上的参数描述。

允许使用以下 Unicode 扩展键

nu

请参阅 numberingSystem。

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

options 可选

一个包含以下属性的对象，按检索顺序排列（所有属性均为可选）

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"

例如：1h 50m

"digital"

例如：1:50:00

years

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

yearsDisplay

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

months

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

monthsDisplay

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

weeks

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

weeksDisplay

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

days

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

daysDisplay

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

hours

格式化小时的样式。可能的值为 "long"、"short"、"narrow"、"numeric" 和 "2-digit"；如果 options.style 不是 "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"；如果 options.style 不是 "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"；如果 options.style 不是 "digital"，则默认为 options.style，否则默认为 "numeric"。
secondsDisplay

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

milliseconds

格式化毫秒的样式。

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

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

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

格式化纳秒的样式。

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

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

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

在输出中显示的小数秒位数。可能的值为 0 到 9；默认为 undefined（包含所有必要的小数位数）。

异常

RangeError

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

描述

对于每个时间段，都会在后台构建一个 Intl.NumberFormat 对象。它使用以下选项（有关详细信息，请参阅 Intl.NumberFormat()）

  • numberingSystem：options.numberingSystem 的值

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

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

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

  • minimumIntegerDigits：2

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

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

示例

使用 Intl.DurationFormat() 构造函数

js
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"

规范

规范
Intl.DurationFormat
# sec-intl-durationformat-constructor

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅