Intl.DurationFormat 怎么本地化显示持续时间

页面要显示“1小时46分钟40秒”时，手工拼接 小时、分钟 和连接词，很快就会遇到英文复数、法语连接词以及阿拉伯语排版等问题。更稳妥的做法是把持续时间保留为结构化对象，交给 Intl.DurationFormat 根据 locale 和显示风格生成文本。

官方地址：https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat

准备 duration 对象并创建本地化格式器

Intl.DurationFormat 接收一个对象，常用字段包括 hours、minutes、seconds，也支持年、月、周、日以及更细的时间单位。它不负责把业务中的“总秒数”自动拆成小时和分钟，所以换算策略要放在业务层，格式化器只负责语言和展示。

const duration = {
  // 保持单位语义清楚，不把 6400 当作一个无法解释的数字传入
  hours: 1,
  minutes: 46,
  seconds: 40,
};

const formatter = new Intl.DurationFormat("zh-CN", {
  // long 适合详情页；卡片空间有限时可改成 short 或 narrow
  style: "long",
});

const text = formatter.format(duration);
console.log(text); // 例如：1小时46分钟40秒

同一份对象换一个 locale，单位名称、复数形式和连接词都会由国际化运行时决定。不要在 format() 之后再用正则替换“hour”或“分钟”，那会破坏其他语言的规则。

按展示空间选择 long、short 和 narrow

这三个风格不是三套业务逻辑，而是同一持续时间的不同文案密度。详情页需要清楚表达单位时用 long；列表或卡片常用 short；按钮、统计条等窄区域才考虑 narrow。最终输出仍由 locale 决定，不能把英文缩写硬编码成所有语言都适用的模板。

如果产品只允许展示某一组单位，先在数据层完成裁剪，再创建格式器。不要把“1小时60分钟”这样的未归一化输入交给页面层，也不要用 Date 代替 duration；日期时间和持续时间在跨日、跨月时不是同一种语义。

用 formatToParts 处理数值和单位的局部样式

直接使用 format() 最简单；当需要把数值加粗、给单位加颜色或插入无障碍标记时，使用 formatToParts() 更安全。它返回带有 type、value 等信息的对象数组，应用层只对已知类型做渲染，未知类型保留原值。

function renderDuration(duration, locale = "zh-CN") {
  // 先按用户语言格式化，再按 part 类型生成可控的 HTML
  const formatter = new Intl.DurationFormat(locale, { style: "short" });
  return formatter.formatToParts(duration).map((part) => {
    if (part.type === "integer" || part.type === "fraction") {
      // 数值可单独强调，但不改变本地化分隔符和单位顺序
      return `${part.value}`;
    }
    return part.value;
  }).join("");
}

const html = renderDuration({ minutes: 12, seconds: 8 }, "en-US");
console.log(html); // 只示意渲染结果，不代表固定的所有语言输出

把这段结果放入页面时仍要遵守项目的 HTML 安全策略；如果输入对象来自接口，不要把未经信任的用户文本直接拼进 innerHTML。更稳妥的做法是创建 DOM 节点并设置 textContent，或使用框架的安全模板语法。

能力检测、实际配置与兼容边界

MDN 将 Intl.DurationFormat 标为 Baseline 2025，并提示较旧设备或浏览器可能不可用。面向存量浏览器的页面不要直接假设构造函数存在，可以把能力检测放在国际化适配层。

function createDurationFormatter(locale) {
  // 旧环境没有构造函数时返回 null，由调用方选择降级文案
  if (typeof Intl.DurationFormat !== "function") {
    return null;
  }

  // supportedLocalesOf 用于判断运行时是否能直接支持目标 locale
  const supported = Intl.DurationFormat.supportedLocalesOf([locale]);
  const actualLocale = supported[0] || "en";
  return new Intl.DurationFormat(actualLocale, { style: "short" });
}

const formatter = createDurationFormatter("zh-CN");
if (formatter) {
  // resolvedOptions 可用于诊断实际采用的 locale 与 style
  console.log(formatter.resolvedOptions());
} else {
  console.log("当前环境需要降级或加载 polyfill");
}

这里的降级可以是产品已有的单位模板，也可以接入经过评估的 polyfill。降级文本要明确它只覆盖哪些单位和语言，避免在不支持的环境里静默显示错误结果。对于新页面，至少应在兼容性目标、打包策略和测试矩阵中记录这条边界。

常见问题

Intl.DurationFormat 能直接格式化毫秒时间戳吗？

不能直接把毫秒数字当作 duration 传入。先根据业务规则把总毫秒换算为明确的小时、分钟、秒等字段，再调用 format()。

为什么同一个 duration 在不同语言下长度不同？

locale 会影响单位名称、复数形式、连接词和顺序。布局应预留弹性宽度，不要把某一种语言的字符长度当成固定值。

formatToParts 适合解决什么问题？

它适合对本地化结果做局部渲染，例如强调数字或给单位添加语义属性；它不负责业务换算，也不能替代 HTML 安全处理。