Humanizer 4 API 参考全览：从命名空间到类型清单的权威导览-平芜编程栈

开发工具

【免费下载链接】Humanizer

Humanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities

项目地址：https://gitcode.com/gh_mirrors/hu/Humanizer

点击查看免费下载

本篇指南围绕 Humanizer 4 官方 API 参考文档（website/docs/api/index.md）展开，系统梳理程序集Humanizer下全部公开类型的组织结构——类、结构体、接口与枚举——并结合仓库源码揭示各类型在实际调用链中的角色。读完本文，你将掌握 Humanizer 公开 API 的全貌，能根据索引快速定位某个类型或成员的详细说明页，并理解Configurator、StringHumanizeExtensions、NumberToWordsExtension等核心类型背后的实现原理。

这份 API 参考从何而来

Humanizer 的 API 参考页面不是手写的，而是由 Humanizer 4 的net10.0引用程序集（reference assembly）自动生成的。索引页开宗明义地说明："Generated from the Humanizer 4net10.0reference assembly."

这意味着：

索引页列出的类型、成员、签名、参数、返回值和 XML 文档注释，全部与当前仓库的公开 API 面保持一致；
你可以按类型名或成员名搜索当前版本，或直接浏览下方生成的索引；每个类型页面都会列出其签名、成员、参数、返回值和 XML 文档；
索引页对应一个独立的程序集命名空间清单页 assembly.md，其中唯一的命名空间就是Humanizer，对应命名空间总览页 Humanizer.md。

程序集与命名空间结构

整个 API 面集中在单一命名空间Humanizer之下，未拆分多个命名空间。全部公开类型分为四大类：

类型类别	数量与代表	说明
类（Classes）	约 80 个，如 StringHumanizeExtensions、Configurator	以扩展方法类为主，辅以策略实现、注册表与辅助类型
结构体（Structs）	1 个：ByteSize	字节大小的值类型
接口（Interfaces）	约 25 个，如 IFormatter、ITimeSpanHumanizeStrategy	定义本地化、转换与策略扩展点
枚举（Enums）	约 17 个，如 LetterCasing、TimeUnit	描述输出样式、单位与选项的常量集合

从源码结构看，这些类型与仓库中 src/Humanizer 目录下的源文件一一对应：扩展方法类位于根目录，策略类位于 DateTimeHumanizeStrategy 与 TimeSpanHumanizeStrategy 子目录，注册表类位于 Configuration 子目录。

类：按功能域拆解

字符串处理

字符串是人类化（Humanize）的核心入口，索引中的相关类包括：

StringHumanizeExtensions：将 PascalCase、camelCase、下划线字符串、连字符字符串转换为空格分隔、大小写恰当的人类可读文本；
StringDehumanizeExtensions：反人类化，将空格分隔文本还原为标识符；
CasingExtensions：ApplyCase方法，一键改变句子大小写；
TruncateExtensions 与 Truncator：字符串截断，后者是ITruncator的获取入口；
InflectorExtensions：复数化/单数化等词形变换；
Vocabulary 与 Vocabularies：自定义首字母缩略词大小写与复数/单数规则例外；目前仅支持单一词汇表Default，不支持多词汇表与删除既有规则；
EnglishArticle：移除、追加、前置冠词前缀，用于忽略冠词的排序；
To：通过IStringTransformer进行字符串变换的门户；
TupleizeExtensions：整数转命名元组字符串，1→"single"、2→"double" 等，仅 1–10、100、1000 有专属名称，其余返回 "n-tuple"；
DynamicNumberOfCharactersAndPreserveWordsTruncator：按字母/数字计数截断并保留完整单词的特殊截断器。

以StringHumanizeExtensions.Humanize为例，其源码（src/Humanizer/StringHumanizeExtensions.cs）揭示了文档中"按序应用多条规则"的底层实现：

若整个输入全大写（视为首字母缩略词），直接返回原值，除非命中已注册的缩略词（Vocabularies.ApplyAcronyms）；
处理游离的下划线/连字符（如"some _ string"）；
按下划线和连字符拆分（FromUnderscoreDashSeparatedWords）；
拆分 PascalCase 与 camelCase 文本（FromPascalCase，ASCII 路径走TryFromAsciiPascalCase快速通道，非 ASCII 走正则PascalCaseWordPartsPattern）；
在 PascalCase/camelCase 输入中把&保留为独立词元。

文档给出的行为示例可直接验证："PascalCaseInputString".Humanize()→"Pascal case input string"，"HTML".Humanize()→"HTML"，注册Vocabularies.Default.AddAcronym("iOS")后"IOS".Humanize()→"iOS"。

枚举处理

EnumHumanizeExtensions：枚举值转人类可读字符串，支持DescriptionAttribute、Flags位域枚举的逗号分隔输出；
EnumDehumanizeExtensions：反向映射回枚举值，无法匹配时抛出 NoMatchFoundException；
EnumHumanizeSource：指定枚举人类化的数据来源。

EnumHumanizeExtensions.Humanize<T>（src/Humanizer/EnumHumanizeExtensions.cs）的行为在 API 页中有明确示例：UserType.AnonymousUser.Humanize()→"Anonymous user"；带[Flags]的Permission.Read | Permission.Write→"Read, Write"（仅输出非零标志位）；带[Description("Currently active")]的成员直接返回描述文本。

日期与时间

DateHumanizeExtensions：将DateTime人类化为"多久以前/以后"的句子；
[DateTimeOffsetHumanizeExtensions] 对应DateTimeOffset类型（索引页中由 DateHumanizeExtensions 与四个策略类共同覆盖）；
TimeSpanHumanizeExtensions 与 TimeSpanDehumanizeExtensions：时间段的人类化与解析；
DateToOrdinalWordsExtensions：日期转序数词文本（ToOrdinalWords）；
TimeOnlyToClockNotationExtensions：TimeOnly转钟表记法；
PrepositionsExtensions：DateTime的空间/时间关系扩展（In、On系列）；
四个Default*HumanizeStrategy与四个Precision*HumanizeStrategy类：默认"时间距离→文字"计算器与精度版计算器，分别对应DateOnly、DateTime、DateTimeOffset、TimeOnly；
流畅日期访问器In/InDate/On/OnDate及其按月/按数的子类（如 In.Five、On.January），全部由 FluentDate 目录下的In.*.cs、On.Days.cs等 T4 模板生成文件实现。

数字与数量

NumberToWordsExtension：数字转本地化单词与序数词，输出受文化影响，包括en、en-GB、en-IN的英语族差异与地区级大数刻度名；
NumberToNumberExtensions：数字间转换；
NumberToTimeSpanExtensions：数值流畅转TimeSpan，如5.Seconds()、3.Hours()、2.Weeks()；
OrdinalizeExtensions：序数化扩展（1st、2nd 等）；
ToQuantityExtensions：单词按数量格式化；
RomanNumeralExtensions：ToRoman/FromRoman；
ChineseFinancialNumeralExtensions：整数转中文财务大写字符；
MetricNumeralExtensions：ToMetric/FromMetric公制表示；
WordsToNumberExtension 与 WordsToDecimalNumberExtension：本地化数字单词解析回数值，解析尊重区域继承；
FractionalizeExtensions：小数转常见分数；
HeadingExtensions：表示航向的数字转文字（如罗盘方向）。

NumberToWordsExtension的签名族非常庞大，API 页完整列出了每个重载：ToWords系列支持int/long、bool addAnd（是否在末尾组前加入区域连词）、WordForm（单词形式，如缩写）、GrammaticalGender（语法性别）与可选CultureInfo（null表示当前文化）。文档中的示例展示了性别与词形的实际效果：

// 西班牙语序数词 3.ToOrdinalWords(GrammaticalGender.Masculine, WordForm.Normal) // "tercero" 3.ToOrdinalWords(GrammaticalGender.Masculine, WordForm.Abbreviation) // "tercer" 3.ToOrdinalWords(GrammaticalGender.Feminine, WordForm.Normal) // "tercera" // 俄语/希伯来语性别差异 1.ToWords(GrammaticalGender.Masculine) // 俄语 "один" 1.ToWords(GrammaticalGender.Feminine) // 俄语 "одна" // 西班牙语以 1 结尾的数字随位置变形 21.ToWords(WordForm.Normal) // "veintiuno" 21.ToWords(WordForm.Abbreviation) // "veintiún"

另有ToIndianWords(int/long, IndianScaleStyle)：NamedScales使用en-IN文化的命名刻度词汇表，CroreBased使用常见 crore 表述且不改变其他区域行为。

字节与速率

ByteSize：唯一的结构体，字节大小的值类型；
ByteSizeExtensions：ByteSize的扩展方法；
ByteRate：持有ByteSize与测量间隔以计算传输速率；
ByteSizeUnitSystem：显式解析/格式化 API 选择的单位系统。

集合

CollectionHumanizeExtensions：将IEnumerable人类化为可读列表；
ICollectionFormatter：按区域格式化集合的可读列表，具体实现位于 Localisation/CollectionFormatters。

配置与注册

Configurator：Humanizer 的全局配置点，详见下文专节；
LocaliserRegistry<TLocaliser>：本地化组件与区域关联的注册表泛型类，是Configurator各注册表属性的底层类型；
PluralizationForms：承载一个名词的单复数形式。

接口：扩展点与契约

接口定义了两类扩展能力：策略（Strategy）与转换器/格式化器（Converter/Formatter）。

策略接口（全部可挂在Configurator上替换）：IDateTimeHumanizeStrategy、IDateTimeOffsetHumanizeStrategy、IDateOnlyHumanizeStrategy、ITimeOnlyHumanizeStrategy、ITimeSpanHumanizeStrategy，以及支持小数秒的 IFractionalTimeSpanHumanizeStrategy、支持语法格的 IGrammaticalCaseTimeSpanHumanizeStrategy；
本地化格式化契约：IFormatter 本地化数字、日期、时长与单位格式；IFractionalTimeSpanFormatter 与 IGrammaticalCaseTimeSpanFormatter 为可选扩展——既有ITimeSpanHumanizeStrategy实现仍可用于既有时长 API，但无法服务HumanizeWithCase；
词形与序数契约：IOrdinalizer、ILongOrdinalizer、IDateToOrdinalWordConverter、IDateOnlyToOrdinalWordConverter、ITimeOnlyToClockNotationConverter；
数字转换契约：INumberToWordsConverter（数字转区域词、序数、元组名）、IWordsToNumberConverter、IWordsToDecimalNumberConverter；
字符串变换契约：IStringTransformer 与带文化参数的 ICulturedStringTransformer；截断契约 ITruncator。

这些接口的具体区域实现分布于 src/Humanizer/Localisation 下的 NumberToWords（40 个文件）、WordsToNumber（20 个文件）、Formatters（7 个文件）、Ordinalizers（7 个文件）等子目录，并由源码生成器（Humanizer.SourceGenerators）依据 Locales 下的 YAML 区域数据生成注册表，实现 100+ 区域的无缝本地化。

枚举：输出样式与选项常量

索引中的枚举决定了各类 API 的输出形态：

枚举	用途要点
LetterCasing	输出字符串的大小写样式（`AllCaps`/`LowerCase`/`Title`/`Sentence`等）
GrammaticalGender	输出词的语法性别（俄语、希伯来语、西班牙语等性别语言需要）
GrammaticalCase	期望的语法格
WordForm	单词形式（`Normal`/`Abbreviation`）
Plurality	单词单复数提示（单数/复数/未知）
TimeUnit	相对时间与时长格式化支持的时间单位，配合 TimeUnitToSymbolExtensions 输出符号（如`Year`→ "a"）
Tense	相对时间引用属于过去还是将来
TruncateFrom	截断位置（左侧/右侧）
ClockNotationRounding	钟表记法舍入选项
OnNoMatch	匹配失败时的处理方式，当前用于`DehumanizeTo`
ShowQuantityAs	单词转数量字符串的显示方式
DataUnit	数据大小格式化支持的数据单位
HeadingStyle	罗盘方向人类化的样式
IndianScaleStyle	`ToIndianWords`的大数词汇表选择
MetricNumeralFormats	公制数字表示的格式化标志（位标志）
EnumHumanizeSource	枚举人类化的来源

核心类型深读：Configurator 全局配置点

Configurator 是 Humanizer 的全局配置入口，对应源码 src/Humanizer/Configuration/Configurator.cs。其公开成员分为两类：

注册表属性（只读，get-only）——均为LocaliserRegistry<TLocaliser>，负责按当前区域解析对应实现：

CollectionFormatters→LocaliserRegistry<ICollectionFormatter>（CollectionFormatterRegistry）
Formatters→LocaliserRegistry<IFormatter>（FormatterRegistry）
NumberToWordsConverters→LocaliserRegistry<INumberToWordsConverter>（NumberToWordsConverterRegistry）
Ordinalizers→LocaliserRegistry<IOrdinalizer>（OrdinalizerRegistry）
DateToOrdinalWordsConverters→LocaliserRegistry<IDateToOrdinalWordConverter>
DateOnlyToOrdinalWordsConverters、TimeOnlyToClockNotationConverters（NET6_0_OR_GREATER条件编译下可用）

策略属性（可读写）——每个都带同一组 Remarks："该属性应在应用启动期间、任何人类化操作发生之前仅设置一次；多线程场景下访问该属性应使用 volatile 读取或适当同步；生产应用中应避免在应用开始服务请求后更改"：

DateTimeHumanizeStrategy（默认DefaultDateTimeHumanizeStrategy）
DateTimeOffsetHumanizeStrategy（默认DefaultDateTimeOffsetHumanizeStrategy）
TimeSpanHumanizeStrategy（默认DefaultTimeSpanHumanizeStrategy）
DateOnlyHumanizeStrategy、TimeOnlyHumanizeStrategy（NET6_0_OR_GREATER条件编译）

方法：

IsCultureSupported(CultureInfo)：判断 Humanizer 是否为指定文化包含完整的生成区域支持。注意两点：只检查精确文化名清单，不沿CultureInfo.Parent向上回溯；调用方自建的LocaliserRegistry<TLocaliser>实例仍保留父文化回退。
UseEnumDescriptionPropertyLocator(Func<PropertyInfo, bool>)：为Enum.Humanize指定描述属性的定位谓词。源码显示默认定位器是p => p.Name == "Description"；该方法必须在任何Enum.Humanize调用之前调用（源码通过enumDescriptionPropertyLocatorHasBeenUsed标志校验，否则抛出异常提示移动到应用启动或ModuleInitializer）。

如何使用本索引定位 API

在索引页 website/docs/api/index.md 中按功能域（字符串、枚举、日期时间、数字、字节、集合、配置）定位类名；
点击进入对应类型页（如 Humanizer.DateHumanizeExtensions.md），页面会给出：类签名（含继承关系）、成员清单、每个方法的 C# 签名、参数说明、返回值、示例代码（Example节）与注意事项（Remarks节）；
需要确认底层行为时，回到源码：扩展方法类在 src/Humanizer 根目录，策略与注册表分别在 src/Humanizer/DateTimeHumanizeStrategy、src/Humanizer/TimeSpanHumanizeStrategy、src/Humanizer/Configuration，区域实现与 YAML 数据在 src/Humanizer/Localisation 与 src/Humanizer/Locales；
验证行为可参考测试项目 tests/Humanizer.Tests，其中StringHumanizeTests.cs、EnumHumanizeTests.cs、NumberToWordsTests.cs等与索引中的扩展类一一对应。

结语

Humanizer 4 的 API 参考索引是整个库的"地图"：它用一张类型表完整呈现了字符串、枚举、日期时间、数字、字节、集合与配置七大功能域的全部公开契约。结合仓库源码阅读时，索引页的类型摘要、示例与Remarks是理解实现意图的第一手材料——例如Humanize的多规则处理顺序、Configurator的策略替换时机限制、ToWords的性别与词形重载设计。当你需要为 .NET 应用引入 Humanizer 时，先浏览这份索引，再进入具体类型页，即可快速找到并正确使用所需的扩展方法或可扩展接口。