Humanizer 命名空间 API 全览：从字符串、枚举到日期与数量的 .NET 人性化扩展

开发工具【免费下载链接】HumanizerHumanizer 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 是一个将字符串、枚举、日期、时间、时间跨度、数字、数量与集合转换为人类友好文本的 .NET 库。本篇以 2.10.1 版 API 参考文档为骨架逐一拆解Humanizer命名空间下的全部公开类型类、接口、枚举并结合仓库源码与测试用例说明每个核心扩展方法的能力边界与典型用法帮助你快速定位「哪种文本需求该调用哪个 API」。命名空间全景一张表看懂全部公开类型Humanizer命名空间是库的全部扩展方法的汇聚点。2.10.1 版 API 参考文档 Humanizer.md 将其划分为三大类类Classes、接口Interfaces与枚举Enums。从文档的类清单可以看出Humanizer 的公开面几乎全部是静态扩展类static classthis参数这是它「面向用法」的 API 设计你不需要构造任何对象直接对string、int、DateTime、IEnumerableT等调用扩展方法即可。类型说明源自 2.10.1 API 文档ByteSizeExtensions为ByteSize提供扩展方法CasingExtensions通过ApplyCase方法轻松改变句子的字母大小写CollectionHumanizeExtensions将IEnumerable人性化为可读列表DateHumanizeExtensions将DateTime人性化为可读句子DateToOrdinalWordsExtensions将DateTime人性化为可读句子序数词风格如 1st of JanuaryEnglishArticle提供移除、追加与前置冠词前缀的方法用于忽略冠词的字符串排序EnumDehumanizeExtensions将人性化的枚举字符串值还原为枚举EnumHumanizeExtensions人性化枚举HeadingExtensions将表示方向的数字转换为方向的文本表示InflectorExtensions词形变化复数化、单数化等扩展MetricNumeralExtensions数字到公制表示ToMetric与公制表示还原数字FromMetricNoMatchFoundException当字符串无法映射到目标枚举时由DehumanizeTo抛出NumberToNumberExtensions数字到数字扩展NumberToTimeSpanExtensions数字到TimeSpan扩展NumberToWordsExtension将数字转换为单词例如1 oneOrdinalizeExtensions序数化扩展PrepositionsExtensions与空间或时间关系相关的DateTime扩展RomanNumeralExtensions数字到罗马表示ToRoman与罗马表示还原数字FromRomanStringDehumanizeExtensions字符串反人性化扩展StringExtensionsString类型扩展方法StringHumanizeExtensions人性化字符串值TimeSpanHumanizeExtensions将TimeSpan人性化为可读形式To使用IStringTransformer进行字符串变换的入口ToQuantityExtensions将单词格式化为带数量的形式TruncateExtensions允许截断字符串Truncator获取ITruncator的工厂TupleizeExtensions将int转换为具名元组字符串1 - single、2 - double等仅 1-10、100、1000 有专名其余返回n-tuple字符串人性化StringHumanizeExtensions 的核心规则StringHumanizeExtensions 是使用频率最高的扩展类它把 PascalCase、camelCase、下划线、连字符混合的标识符转换成带空格的自然语句。从源码看Humanize(this string input)StringHumanizeExtensions.cs按顺序应用多条规则若整个输入全大写如HTML直接返回原样但会经过Vocabularies.ApplyAcronyms处理已注册的缩写调用Vocabularies.NormalizeAcronyms规范化已注册缩写如将IOS规范为iOS若存在两侧有空白的游离下划线/连字符HasFreestandingSpacingChar先替换为空格再走 PascalCase 分词否则按分隔符拆分或直接用正则PascalCaseWordPartsPattern对 PascalCase/camelCase 分词最终结果首字母大写并再次应用已注册缩写。文档注释中的典型结果PascalCaseInputString.Humanize() Pascal case input string Underscored_input_String_is_turned_INTO_sentence.Humanize() Underscored input String is turned INTO sentence dash-separated-string.Humanize() Dash separated string HTML.Humanize() HTML camelCaseText.Humanize() Camel case text RockRoll.Humanize() Rock roll对应的测试用例可在 StringHumanizeTests.cs 中找到例如PascalCaseInputStringIsTurnedIntoSentence→Pascal case input string is turned into sentence、HTMLIsTheLanguage→HTML is the language、HTML5→HTML 5。测试还验证了土耳其语等区域下的特殊行为如istanbul在tr-TR文化下被转为İstanbul说明人性化结果依赖当前文化的TextInfo。Humanize还支持LetterCasing重载StringHumanizeExtensions.cs本质是先Humanize()再调用CasingExtensions.ApplyCasePascalCaseInputString.Humanize(LetterCasing.AllCaps) PASCAL CASE INPUT STRING PascalCaseInputString.Humanize(LetterCasing.LowerCase) pascal case input string PascalCaseInputString.Humanize(LetterCasing.Title) Pascal Case Input String大小写与变换CasingExtensions、To 与转换器接口CasingExtensions 是大小写变换的统一点ApplyCase(this string input, LetterCasing casing)将LetterCasing枚举映射到 To 门户下的具体转换器To.TitleCase、To.LowerCase、To.UpperCase、To.SentenceCase非法枚举值会抛出ArgumentOutOfRangeExceptionsome string.ApplyCase(LetterCasing.Title) Some String SOME STRING.ApplyCase(LetterCasing.LowerCase) some string some string.ApplyCase(LetterCasing.AllCaps) SOME STRING some string.ApplyCase(LetterCasing.Sentence) Some stringTo类To.cs是「字符串变换门户」返回IStringTransformer实现。API 文档中与它配套的两个接口是IStringTransformer可变换字符串无文化参数ICulturedStringTransformer可在给定文化下变换字符串。具体实现位于 Transformer 目录ToTitleCase、ToSentenceCase、ToLowerCase、ToUpperCase对应测试见 TransformersTests.cs。枚举人性化与反人性化双向转换EnumHumanizeExtensions 的泛型HumanizeT(this T input)EnumHumanizeExtensions.cs按以下优先级输出若枚举成员带DescriptionAttribute等元数据则原样返回若枚举带[Flags]且多标志被置位则输出逗号分隔的人性化标志列表否则将成员名 PascalCase 转空格文本。源码示例enum UserType { AnonymousUser, RegisteredUser } UserType.AnonymousUser.Humanize() Anonymous user [Flags] enum Permission { None 0, Read 1, Write 2, Delete 4 } (Permission.Read | Permission.Write).Humanize() Read, Write enum Status { [Description(Currently active)] Active } Status.Active.Humanize() Currently activeHumanize的LetterCasing重载会对「由成员名派生的输出」应用大小写但对「作者书写的元数据文本」保持原样返回。反向操作由 EnumDehumanizeExtensions 承担DehumanizeToTTargetEnum(this string input)EnumDehumanizeExtensions.cs按「精确成员名 → 人性化成员名 →DisplayAttribute的 Name/Description/ShortName → 作者描述的DescriptionAttribute」顺序匹配匹配大小写不敏感无匹配时默认抛出 NoMatchFoundException也可通过 OnNoMatch 选择ReturnsNull。它还提供非泛型DehumanizeTo(Type, ...)重载供运行时才知枚举类型的场景使用反射类型安全弱于泛型版本。数字转单词与序数词NumberToWordsExtensionNumberToWordsExtension 提供ToWords、ToOrdinalWords、ToTuple、ToIndianWords等扩展。所有方法最终委托给Configurator.GetNumberToWordsConverter(culture)返回的区域化转换器INumberToWordsConverterculture参数为null时使用当前文化。基数词1.ToWords() one对支持词形变化的语言可传WordForm如西班牙语21.ToWords(WordForm.Abbreviation) veintiún对支持性别的语言可传GrammaticalGender俄语1.ToWords(GrammaticalGender.Masculine) один阴性为одна还可用addAnd控制末尾是否加连词。序数词1.ToOrdinalWords() first巴西葡萄牙语1.ToOrdinalWords(GrammaticalGender.Feminine) primeira西班牙语3.ToOrdinalWords(WordForm.Abbreviation) tercer。印度英语大数ToIndianWords支持IndianScaleStyle.NamedScales使用 en-IN 命名级与IndianScaleStyle.CroreBased使用 crore/lakh 表达的常用级两种词汇表后者对应的CroreBasedIndianScales常量定义在 NumberToWordsExtension.cs。元组名1.ToTuple() single仅 1-10、100、1000 有专名。区域化转换器实现位于 Localisation/NumberToWords40 个文件每种文化一个转换器类。数量词ToQuantityExtensions 与 ShowQuantityAsToQuantityExtensions 将单词与数量组合并自动单复数化ToQuantityExtensions.cs 中quantity为1或-1时调用Singularize否则调用Pluralize。ShowQuantityAs枚举决定数量如何显示None只输出变换后的单词不含数量Numeric以数字形式输出默认Words以单词形式输出如1200 one thousand two hundred。文档与源码示例request.ToQuantity(0) 0 requests request.ToQuantity(1) 1 request request.ToQuantity(2) 2 requests men.ToQuantity(2) 2 men process.ToQuantity(1200, ShowQuantityAs.Words) one thousand two hundred processes request.ToQuantity(10000, format: N0) 10,000 requests request.ToQuantity(0.2) 0.2 requestsint与long重载支持format标准或自定义数字格式字符串与formatProvider文化相关的格式提供者double重载会在数量为±1.0且为有限值时输出单数形式。集合人性化CollectionHumanizeExtensionsCollectionHumanizeExtensions 把IEnumerableT转成符合自然语言习惯的列表默认使用当前文化的分隔符英语通常为, 并在最后一项前加andnew[] { 1, 2, 3 }.Humanize() 1, 2 and 3 new[] { Alice, Bob, Charlie }.Humanize() Alice, Bob and Charlie new[] { single }.Humanize() single new string[] { }.Humanize() 它提供多种重载指定文化Humanize(new CultureInfo(en-GB))、自定义元素格式化函数people.Humanize(p p.Name)、自定义分隔符numbers.Humanize( | )输出1 | 2 | 3以及格式化函数 分隔符的组合。底层通过Configurator.CollectionFormatter与Configurator.CollectionFormatters.ResolveForCulture(culture)获取区域化格式器CollectionFormatters对应测试见 CollectionHumanizeTests.cs。日期人性化与流式日期DateHumanizeExtensions、In、OnDateHumanizeExtensions 将DateTime转成「多久之前/之后」的可读句子如 2 hours ago、in 3 days是构建动态时间显示消息时间戳、日志时间的常用工具。而In系列In.One、In.Two…In.Ten与On系列On.January…On.December提供流式日期访问器。In系列文档描述为空On系列文档则明确标注为 Provides fluent date accessors for …如 On.January其实现代码由 T4 模板生成位于 FluentDate/On.Days.cs 与 FluentDate/In.Months.cs模板源文件为对应的.tt文件。相关测试见 FluentDate。时间跨度人性化TimeSpanHumanizeExtensionsTimeSpanHumanizeExtensions 将TimeSpan人性化为可读形式。2.10.1 版已有若干策略类参与DefaultTimeSpanHumanizeStrategy、IFractionalTimeSpanHumanizeStrategy、IGrammaticalCaseTimeSpanHumanizeStrategy、ITimeSpanHumanizeStrategy实现位于 TimeSpanHumanizeStrategy。策略化设计意味着你可以通过Configurator替换默认的人性化策略例如启用带小数精度的输出相关测试见 TimeSpanHumanizeTests.cs 与 FractionalTimeSpanHumanizeTests.cs。截断与变换基础设施TruncateExtensions、Truncator、ITruncatorTruncateExtensions 允许按长度或单词数截断字符串Truncator 是获取ITruncator的工厂入口ITruncator 定义截断能力。截断实现位于 Truncation 目录FixedLengthTruncator、FixedNumberOfCharactersTruncator、FixedNumberOfWordsTruncator等并由 TruncateFrom 枚举指定从左侧还是右侧截断。测试见 TruncatorTests.cs。其余值得关注的类型RomanNumeralExtensionsToRoman()/FromRoman()实现见 RomanNumeralExtensions.cs测试见 RomanNumeralTests.cs。MetricNumeralExtensions与MetricNumeralFormats数字与公制前缀k、M、G 等互转。OrdinalizeExtensions数字序数化1.Ordinalize() 1st与NumberToWordsExtension的ToOrdinalWords互为补充数字后缀 vs 单词。NumberToNumberExtensions、NumberToTimeSpanExtensions前者提供数值之间的便捷转换后者如5.Days()、3.Hours()返回TimeSpan。InflectorExtensionsPluralize、Singularize、Pascalize、Camelize、Underscore、Dasherize等词形变换是ToQuantityExtensions单复数化的底层依赖。EnglishArticle与EnglishArticles忽略冠词的排序如把 The Beatles 按 Beatles 参与排序。HeadingExtensions与HeadingStyle罗盘方向数字转文本如 0/360 → North。NoMatchFoundExceptionDehumanizeTo无匹配时的默认异常类型。PrepositionsExtensions与空间或时间关系相关的DateTime扩展如In、On之外的前置词辅助。配套枚举与接口速查文档列出的Enums中除前文已涉及的ShowQuantityAs、OnNoMatch、LetterCasing、TruncateFrom、HeadingStyle、MetricNumeralFormats外还有EnglishArticles定冠词与不定冠词GrammaticalCase输出单词的期望语法格如主格、与格GrammaticalGender输出单词的期望语法性别阳性/阴性/中性Plurality向 Humanizer 提示单词是单数、复数还是未知。Interfaces仅有三个ICulturedStringTransformer、IStringTransformer、ITruncator它们与To门户、截断工厂共同构成库的两条可扩展点字符串变换、字符串截断。小结如何按需选择 API面对「文本需要更人性化」的需求可以按输入类型快速定位字符串Humanize()拆词ApplyCase(LetterCasing)大小写Truncate()截断Pluralize()/Singularize()单复数枚举Humanize()/DehumanizeToT()无匹配时用OnNoMatch.ReturnsNull或捕获NoMatchFoundException数字ToWords()/ToOrdinalWords()/Ordinalize()/ToRoman()/ToMetric()/ToTuple()数量word.ToQuantity(n, ShowQuantityAs.Numeric/Words)日期/时间DateTime.Humanize()、TimeSpan.Humanize()、流式的In/On系列集合IEnumerableT.Humanize()支持分隔符、格式化函数与文化参数。所有类型均可在 2.10.1 版 API 文档目录 中查看各自独立的参考页当前仓库主库源码位于 src/Humanizer测试位于 tests/Humanizer.Tests安装使用只需dotnet add package Humanizer见 readme.md。赞分享开发工具【免费下载链接】HumanizerHumanizer 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 命名空间全解析.NET 字符串、枚举、日期与数字人性化处理的 API 总览Humanizer 命名空间全解析.NET 字符串、枚举、日期与数字人性化处理的 API 总览 Humanizer 是一个把字符串、枚举、日期、时间、时长、数开发工具Humanizer 命名空间全解析从字符串、枚举到日期与数字的 API 全景图Humanizer 命名空间全解析从字符串、枚举到日期与数字的 API 全景图 导读 Humanizer 是一个面向 .NET 的人性化工具库其核心价值开发工具Humanizer 完全指南用 .NET 库把字符串、枚举、日期与数量变成人类可读文本Humanizer 完全指南用 .NET 库把字符串、枚举、日期与数量变成人类可读文本 Humanizer 是一个面向 .NET 的文本人性化库专门把字符串开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考