JavaScript Intl.DurationFormat 怎样把时长对象格式化为本地文本

Intl.DurationFormat 接收由 hours、minutes、seconds 等字段构成的时长对象，再通过 format() 输出指定语言的文本。先用 new Intl.DurationFormat("zh-CN", { style: "long" }) 创建格式化器，随后把时长对象交给它即可；需要数字钟表式展示时可选择 digital 样式。

MDN 接口文档地址：https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat

先确认时长不是日期

任务用时两小时十七分钟九秒，表达的是一段长度，不是“今天几点”。因此不应把秒数塞进 Date 再借日期格式化器展示：那会引入起始日期、时区和跨日处理，而不是直接表达业务时长。

本例只处理小时、分钟和秒，输入为规范化的非负整数记录。格式化器负责显示，业务仍要决定原始秒数如何拆分、是否向上取整、超出一天是否继续显示小时。这些决策不由语言标签替代。

用语言和样式建立格式化器

// 输入描述时长，不是日期或时间戳。
const duration = { hours: 2, minutes: 17, seconds: 9 };
const textFormatter = new Intl.DurationFormat("zh-CN", { style: "long" });
const digitalFormatter = new Intl.DurationFormat("zh-CN", { style: "digital" });
console.log(textFormatter.format(duration));
console.log(digitalFormatter.format(duration));

这段代码为本文原创，未在制作过程中运行，未附固定输出作为实测结果。long 偏向完整单位文字，short 和 narrow 更紧凑，digital 偏向数字显示；具体分隔符与文字由语言数据和选项决定，见 构造器选项说明。

如果列表中每条任务都使用相同语言和样式，可以复用一个实例。不需要在每次更新秒数时重新构造相同的格式化器；更换语言或展示方案时，再更新实例配置。

把检测与降级放在同一入口

MDN 将这项特性列为 Baseline 2025，同时提醒旧设备和旧浏览器可能不支持。产品仍应检测当前运行时是否存在构造器，不仅凭浏览器名称判断。下面封装固定中文业务入口；降级只保证可读的中文单位，并不模拟完整本地化行为。

// 只在模块初始化时建立一次中文格式化器。
const durationFormatter =
  typeof Intl !== "undefined" && typeof Intl.DurationFormat === "function"
    ? new Intl.DurationFormat("zh-CN", { style: "long" })
    : null;

function formatTaskDuration(input) {
  if (input === null || typeof input !== "object" || Array.isArray(input)) {
    throw new TypeError("时长必须为对象");
  }
  const fields = ["hours", "minutes", "seconds"];
  // 本业务只接受三类字段，避免悄悄遗漏 days 等值。
  if (Object.keys(input).some((key) => !fields.includes(key))) {
    throw new TypeError("只支持 hours、minutes、seconds");
  }
  const duration = {};
  for (const field of fields) {
    const value = input[field] === undefined ? 0 : input[field];
    if (!Number.isSafeInteger(value) || value  59 || duration.seconds > 59) {
    throw new RangeError("本业务要求分钟和秒先规范到 0～59");
  }
  if (durationFormatter) {
    // 输入错误应显式处理，不能全部捕获后当成“不支持 API”。
    return durationFormatter.format(duration);
  }
  // 明确的简体中文降级，不冒充完整多语言实现。
  const units = [
    [duration.hours, "小时"],
    [duration.minutes, "分钟"],
    [duration.seconds, "秒"],
  ];
  return units
    .filter(([value]) => value !== 0)
    .map(([value, label]) => String(value) + label)
    .join("") || "0秒";
}

console.log(formatTaskDuration({ hours: 2, minutes: 17, seconds: 9 }));

这份封装有意比平台 API 更窄：只收三类单位，分钟与秒限定为 0～59，拒绝小数、负数和额外字段。它是任务用时展示的产品约束，不是宣称 Intl.DurationFormat 的所有字段都必须符合这份范围。若业务要支持天数和负时长，应扩展输入协议及降级实现。

特性检测失败才走这里的简化降级。数据不合法时应反馈输入错误；把所有异常都吞掉然后显示“0秒”，会把坏数据误显示成有效时长。对于真正的多语言产品，应选择满足目标语言和环境要求的兼容方案，不将中文拼接函数推广为通用 polyfill。

控制字段而不是硬编码结果字符串

平台 format 接受的时长字段使用整数，并要求符号一致。小数秒可以通过更小单位表达，而不是随意把非整数塞进秒字段。API 的对象语义由 ECMA-402 DurationFormat 规范 定义；本文示例采用非负值，避免同时引入符号展示与舍入策略。

返回字符串可能带非断行空格或方向控制字符，且同一语言在不同实现中也允许存在差异。不要用一个硬编码字符串判断接口是否正确，也不要靠 split(" ") 反向提取小时和分钟；这些输出边界见 format 方法说明。

显示层与业务数值分开保存，切换语言后才不需要重算任务用时。客户端和服务端渲染使用的语言数据不同也可能影响最终文本；项目应明确由哪一侧负责生成显示结果，而不是把不同字符串直接认定为时长数值不一致。

常见问题

接口会自动把总秒数转成小时分钟吗？

调用前应按业务规则构造时长字段。只有一份总秒数时，可以先按固定秒与分钟的关系拆分；是否保留小数、是否进位由业务决定。不要假定格式化函数同时承担日期运算。

可以用它计算两个日期相差几个月吗？

它是展示接口，不是日期差计算器。月份长度和时区规则需要日期计算逻辑，先确定时长记录，再考虑如何显示。

部署到旧 WebView 时该怎样处理？

保留运行时特性检测，为目标环境提供明确的兼容方案。本文的中文降级只适合限定的任务展示，不承诺所有语言、单位和格式都与原生一致。