EvanHahn/HumanizeDuration.js · 上手攻略

• 仓库：EvanHahn/HumanizeDuration.js
• 链接：https://github.com/EvanHahn/HumanizeDuration.js
• 分类：JavaScript Utility · Humanize
• 作者：Tom
• 更新：2026-08-21

是什么

HumanizeDuration.js 是一个极简的 JavaScript 时间长度转人类可读字符串 工具库。输入毫秒数，输出如 "6 minutes, 1 second" 这样的自然语言描述。 NPM 包名 humanize-duration，常年稳居时间处理类工具下载量前列。

作者在 README 开篇就注明了它的核心定位：不增新功能，只维护现有功能稳定可用。这意味着它是那种「配置好之后永远不需要再动」的库——适合直接引入生产项目。

解决什么问题

// 你拿到了一个时间戳（毫秒）
const ms = 361000;

// 你想要："6 minutes, 1 second"
humanizeDuration(ms);

原生 Intl.DurationFormat（MDN）已经是现代浏览器的内置 API，如果你的目标环境支持，直接用它替代是更轻量的选择。但 HumanizeDuration.js 的优势在于：

• 支持更多语言：内置 20+ 种语言（含中文 zh，但需验证），并且可以自定义语言包
• 更细粒度的控制：最大单位数、保留小数位数、连接词/分隔符均可配置
• Node.js / 浏览器 / 打包工具全面兼容：UMD 格式，原生 <script> 标签也可用
• NPM 生态成熟：与 Modern JS 生态无缝集成（Webpack/Rollup/Vite）

快速安装

npm install humanize-duration
# 或
yarn add humanize-duration
# 或直接在浏览器引入
# <script src="humanize-duration.js"></script>

⚠️ npm 包名是 humanize-duration（连字符），不是 humanizeDuration。

核心用法

最基础用法

const humanizeDuration = require("humanize-duration");

humanizeDuration(12000);       // => "12 seconds"
humanizeDuration(3000);         // => "3 seconds"
humanizeDuration(2250);        // => "2.25 seconds"
humanizeDuration(97320000);     // => "1 day, 3 hours, 2 minutes"

指定语言

// 西班牙语
humanizeDuration(3000, { language: "es" });  // => "3 segundos"

// 韩语
humanizeDuration(5000, { language: "ko" });  // => "5 초"

// 语言不存在时回退到 fallback
humanizeDuration(3000, {
  language: "bad language",
  fallbacks: ["en"],
});  // => "3 seconds"

⚠️ 支持的语言完整列表在 npm 页面；中文 zh 是否完整支持需实际验证（部分库对中文复数形式支持有限）。

控制精度与格式

// 只显示最大 2 个单位
humanizeDuration(1000000000000, { largest: 2 });
// => "31 years, 8 months"

// 四舍五入到最近整数
humanizeDuration(1200, { round: true });    // => "1 second"
humanizeDuration(1600, { round: true });    // => "2 seconds"

// 控制小数位数（不四舍五入，只截断显示）
humanizeDuration(8123.456789, { maxDecimalPoints: 3 });
// => "8.123 seconds"

// 自定义分隔符和连接词
humanizeDuration(22140000, { delimiter: " and " });
// => "6 hours and 9 minutes"

// 自定义单位与数字之间的空格
humanizeDuration(260040000, { spacer: " whole " });
// => "3 whole days, 14 whole minutes"

限制单位种类

// 只使用指定的单位（必须按从大到小排列）
humanizeDuration(69000, { units: ["h", "m", "s", "ms"] });
// => "1 minute, 9 seconds"

// 只显示小时，不足一小时自动换算
humanizeDuration(3600000, { units: ["h"] });
// => "1 hour"

// 指定单位列表，即使超过范围也不自动换算
humanizeDuration(3600000, { units: ["d", "h"] });
// => "1 hour"

自定义 Humanizer（复用配置）

// 预置一个西班牙语、只显示"年/月/日"的 humanizer
const spanishHumanizer = humanizeDuration.humanizer({
  language: "es",
  units: ["y", "mo", "d"],
});

spanishHumanizer(71177400000);
// => "2 años, 3 meses, 2 días"

spanishHumanizer(71177400000, { units: ["d", "h"] });
// => "823 días, 19.5 horas"  （仍可覆盖默认参数）

数字替换 & 自定义单位换算

// 用英文单词替代阿拉伯数字
humanizeDuration(1234, {
  digitReplacements: ["Zero","One","Two","Three","Four","Five","Six","Seven","Eight","Nine"],
});
// => "One.TwoThreeFour seconds"

// 自定义单位换算基准（比如把"月"定义成精确30天）
humanizeDuration(2629800000, {
  unitMeasures: {
    y:  31557600000,
    mo: 30 * 86400000,   // 精确30天
    w:  604800000,
    d:  86400000,
    h:  3600000,
    m:  60000,
    s:  1000,
    ms: 1,
  },
});
// => "1 month, 10 hours, 30 minutes"

典型适用场景

1. 进度条 / 文件上传时间提示："预计剩余 3 分 22 秒" 比 "预计剩余 202000ms" 友好太多
2. 日志时间戳展示：审计日志里显示「任务耗时 2 hours, 15 minutes」比毫秒数更直观
3. 多语言产品国际化：英文 3 seconds、西班牙语 3 segundos，一行配置切语言
4. API 响应时间报告：非技术人员看的报告里将毫秒转为人类可读格式
5. 游戏/计时类 UI：技能冷却、Buff 持续时间等自然语言展示

坑与注意

1. 中文支持需验证：README 列出 zh 属于 supported languages，但实测中文复数形式（如「1 秒」vs「2 秒」）可能不精确，重要中文场景建议自行测试或做 fallback
2. 月份和年的默认长度是精确值：y: 31557600000（365.25 天）、mo: 2629800000（约 30.44 天），这与自然月的实际长度有偏差，如果涉及精确月份计算需要用 unitMeasures 自定义
3. 不处理负数：传入负数毫秒行为未定义，请自行做守卫
4. largest 与 units 联用可能踩坑：比如 largest: 2 + units: ["h", "m"] 时，1 年会被静默截断为小时，而非报错
5. 现代浏览器可直接用 Intl.DurationFormat：如果目标环境是 Chrome 78+/Firefox 100+，不一定需要引入这个库
6. Bower 已废弃：npm 安装是主流通道，Bower 仅做保留，新项目不要用 Bower

与同类对比

如果你只需要时间长度 → 人类可读字符串这单一功能，HumanizeDuration.js 是最轻量的选择，引入后几乎零维护成本。

一句话推荐结论

HumanizeDuration.js 是「写一次、用十年」型的前端工具——如果你只需要把毫秒转成「几分几秒」这种简单需求，它足够轻量；但如果你的场景涉及月份精确度或复杂多语言复数，建议先测后用，或者直接上浏览器原生的 Intl.DurationFormat。

• 原始 README：https://github.com/EvanHahn/HumanizeDuration.js
• NPM 包：https://www.npmjs.com/package/humanize-duration
• 官方 Intl.DurationFormat：https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat