Intl.DurationFormat() 构造函数

语法

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

参数

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.supportedValuesOf()；默认值取决于区域设置。此选项也可以通过 nu Unicode 扩展键设置；如果两者都提供，则此 options 属性优先。

style

格式化持续时间时使用的样式。此值用作所有其他单位选项的默认值，并且在连接持续时间单位列表时也对应于 Intl.ListFormat() 的 style 选项。可能的值有：

"long"

例如，1 小时 50 分钟

"short"（默认）

例如，1 小时，50 分钟

"narrow"

例如，1h 50m

"digital"

例如，1:50:00

years

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

yearsDisplay

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

months

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

monthsDisplay

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

weeks

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

weeksDisplay

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

days

格式化天数时使用的样式。可能的值为 "long"、"short" 和 "narrow"；默认值为 options.style（如果不是 "digital"），否则为 "short"。

daysDisplay

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

hours

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

secondsDisplay

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

milliseconds

格式化毫秒时使用的样式。

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

microsecondsDisplay

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

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

nanoseconds

格式化纳秒时使用的样式。

• 如果 microseconds 为 "numeric"，唯一可能的值是 "numeric"；默认值为 "numeric"。
• 否则，可能的值为 "long"、"short"、"narrow" 和 "numeric"；默认值为 options.style（如果不是 "digital"），否则为 "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() 构造函数

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
• Intl.supportedValuesOf()
• Intl