Humanizr/Humanizer · 上手攻略

• 仓库：Humanizr/Humanizer
• 链接：https://github.com/Humanizr/Humanizer
• 分类：.net-library · utility
• 作者：Tom
• 更新：2026-08-13

是什么

Humanizer 是一个久经沙场的 .NET 库，专门把程序里的各种值（字符串、枚举、日期、时间、时间跨度、数字、数量、字节大小、集合）转成人类可读的文本。它的 API 极其简洁——所有转换都以链式扩展方法形式附加在原生类型上，一行调用即完成转换。

这个库的最大特点不是"能做什么"，而是"做得有多好"：支持全球数十种文化（culture），转换结果随文化不同而变化，例如同样是 TimeSpan.FromMinutes(2).Humanize()，英语输出 "2 minutes"，德语输出 "2 Minuten"，俄语输出 "2 минуты"——无需额外代码，只要换个 CultureInfo。

NuGet 包名即 Humanizer，持续活跃维护，最新稳定版 3.x，文档站点 humanizr.net。

解决什么问题

在 .NET 应用里，数据库存的往往不是人类想看的东西：TimeSpan.FromDays(14) 存的是 14，但界面上显示"14 天"还是"两周"更友好？Gender.M 存的是枚举值，但通知文案里要写"他"还是"她"？1000000000 数字要显示成"1 Billion"还是中文的"10 亿"？这些问题每个都小，但每次手写格式化代码就是重复劳动。

Humanizer 把这些全部接管——一行代码搞定所有常见格式化需求，支持国际化，不用再维护一套自己的格式化工具类。

快速安装

# NuGet 包管理器
dotnet add package Humanizer

# 或 Package Manager Console
Install-Package Humanizer

# 或 Paket
paket add Humanizer

⚠️ 选择版本时需与 .NET 目标框架匹配：v3.x 支持 .NET 6+ / .NET Framework 4.6.1+ / .NET Standard 2.0+ / .NET Core 2.0+。v4.x（预览）引入了新的 SI/IEC 字节格式 API 和新的复数形式 API，与 v3 行为有差异。生产项目建议锁定 v3.x，升级前阅读 humanizr.net/docs/upgrading。

安装后直接 using：

using Humanizer;

核心用法

时间和时间跨度

using System.Globalization;

// 基本用法
TimeSpan.FromMinutes(2).Humanize();
// → "2 minutes"

TimeSpan.FromMilliseconds(1500).Humanize();
// → "1.5 seconds"

// 带精度的分数秒（v3 新 API）
TimeSpan.FromMilliseconds(1500).HumanizeWithFractionalSeconds(
    precision: 1,
    maxFractionalDigits: 3,
    roundingMode: MidpointRounding.ToEven,
    culture: CultureInfo.GetCultureInfo("en-US")
);
// → "1.5 seconds"

// 特定文化（德语与格）
var german = CultureInfo.GetCultureInfo("de-DE");
TimeSpan.FromDays(7).HumanizeWithCase(
    GrammaticalCase.Dative,
    culture: german
);
// → "in einer Woche"（一周后）

// 日期
DateTime.UtcNow.AddHours(-3).Humanize();
// → "3 hours ago"

数字和数量

// 英文
1234.Humanize();
// → "1,234"

1_000_000_000.ToWords();
// → "one billion"

// 印度计数制（Crore/Lakh）
1_000_000_000L.ToIndianWords(IndianScaleStyle.CroreBased);
// → "one hundred crore"

// 中文大写（需配合 Culture）
// ⚠️ Humanizer 本身不内置中文汉字转换，结合 .NET 的 CultureInfo("zh-CN") 使用

字节大小（v4 预览新 API）

using Humanizer;

// v4 预览引入：显式 SI / IEC 区分
var size = ByteSize.FromBytes(1_000_000);

size.Format(ByteSizeUnitSystem.DecimalSi);
// → "1 MB"  (1000-based, SI 标准)

size.Format(ByteSizeUnitSystem.BinaryIec);
// → "976.56 KiB"  (1024-based, IEC 标准)

// ⚠️ Legacy API（v3）使用固定换算规则，不区分 SI/IEC
ByteSize.FromKibibytes(1).ToString();
// → "1 kB"  ⚠️ 实际是 1024 字节，但 Legacy 用 kB 标签

⚠️ v4 预览 API 不稳定：SI/IEC 显式格式化和 TryPluralize/TrySingularize 新 API 仅在 v4 预览版中可用。生产代码建议在 v3 上等稳定版，或明确锁定预览版并在升级时重新测试。

枚举和字符串

// 枚举值转可读字符串（驼峰命名自动拆词）
enum PaymentTerm { Net30, Net60, CashOnDelivery }
PaymentTerm.Net30.Humanize();
// → "Net 30"

"SpecialFileFormat".Humanize();
// → "Special file format"

// 复数形式
"ox".Pluralize();
// → "oxen"

"fish".Pluralize();
// → "fish"（不变复数）

// 自定义复数规则（v4 预览）
var files = new PluralizationForms(
    singular: "plik",
    other: "pliku",
    few: "pliki",
    many: "plików"
);
files.TryPluralize(5m, CultureInfo.GetCultureInfo("pl"), out var noun);
// → "plików"

日期处理

// 相对日期（"3 hours ago" / "in 2 weeks"）
DateTime.Now.AddDays(-1).Humanize();
// → "yesterday"

DateTime.Now.AddMonths(2).Humanize();
// → "in 2 months"

// 具体日期格式化
new DateTime(2024, 12, 25).Humanize();
// → "Monday, 25 December 2024"

典型适用场景

• 日志和监控面板：把毫秒级时间戳转成 "3.2 seconds"、"2 hours ago"，比原始数字友好一百倍
• SaaS 通知文案：订单完成 "Your order will arrive in 3 days" 而非 "arrives in 259200 seconds"
• 国际化产品：同一套业务代码换 CultureInfo 就切换语言，无需重写格式化逻辑
• 电商和金融：金额大写、数量复数自动处理（如 "1 item" vs "2 items"）
• 数据导出报告：把数据库枚举值在 Excel/PDF 报告里显示成可读标签
• CLI 工具输出：给终端用户看的格式化输出，比直接 ToString() 专业得多

坑与注意

与同类对比

Humanizer 在 .NET 生态里没有真正同类竞品——它是唯一同时覆盖时间、数字、枚举、字节、复数且文化感知完整的格式化库。如果你的项目是 .NET，这是必装的基础设施包。

一句话推荐结论

Humanizer 是 .NET 开发者花最少力气让应用界面"更像人话"的不二之选——一个 NuGet 包、一行 using Humanizer，所有时间/数字/枚举/字节的格式化全部告别手写，尤其是做国际化产品时，CultureInfo 一切换就搞定全球语言，比自己维护格式化工具类省心十倍。

原始仓库：https://github.com/Humanizr/Humanizer · MIT License