开发工具【免费下载链接】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点击查看免费下载IOrdinalizer是 Humanizer 中负责把数字转换为序数词如1st、2nd、3rd的本地化扩展点接口也是Ordinalize()扩展方法背后真正的执行者。本篇指南以该接口的 API 契约为骨架结合 接口定义、注册表 与 扩展方法入口 等源码讲解四个重载的语义差异、GrammaticalGender与WordForm的作用以及如何自定义或替换序数词实现帮助你在多语言场景下精确控制序数词输出。一、接口定位Ordinalize 的本地化后端Humanizer 的Ordinalize()扩展方法定义于 OrdinalizeExtensions.cs能把数字字符串或数值转换成序数词形式。默认情况下它输出英文规则1st、2nd、3rd、4th但在西班牙语、法语、意大利语、俄语等语言中序数词还要受语法性别grammatical gender甚至缩写/全写词形word form的制约。IOrdinalizer正是为了解决不同语言如何生成序数词这一本地化问题而设计的接口其官方注释明确说明它的职责是Localizes the ordinal form of a number本地化数字的序数形式。接口本身不包含任何实现逻辑只定义契约真正按语言路由到具体实现的是配置层Configurator.cs 暴露静态属性Ordinalizers类型为LocaliserRegistryIOrdinalizer并在 L83 提供便捷访问器Ordinalizer解析当前线程文化对应的实现OrdinalizerRegistry.cs 是注册表实现构造时以DefaultOrdinalizer作为兜底并调用OrdinalizerRegistryRegistrations.Register(this)批量注册各语言实现。因此IOrdinalizer是 Humanizer 序数词体系的插件契约内置实现全部实现该接口自定义实现也可以注册到同一注册表。二、接口契约四个 Convert 重载接口定义位于 IOrdinalizer.cs共声明 4 个方法重载签名如下public interface IOrdinalizer { // 使用默认语法形式将数字序数化 string Convert(int number, string numberString); // 使用区域特定的词形缩写 / 全写序数化 string Convert(int number, string numberString, WordForm wordForm); // 使用提供的语法性别序数化 string Convert(int number, string numberString, GrammaticalGender gender); // 同时使用语法性别与词形序数化 string Convert(int number, string numberString, GrammaticalGender gender, WordForm wordForm); }2.1 参数含义参数类型说明numberSystem.Int32正在被序数化的数值numberStringSystem.String该数字的基数cardinal文本表示即转换前的原始数字字符串genderHumanizer.GrammaticalGender语法性别仅在语言要求时生效如巴西葡萄牙语的1º/1ªwordFormHumanizer.WordForm词形用于区分缩写与全写如西班牙语1.ervs1.º返回值统一为System.String。接口注释特别指出numberString是数字的基数表示实现通常在其上追加后缀或做整体替换而不是重新把number格式化——这样既能保留调用方传入的原始文本如带千分位或本地化数字字符又能拿到数值做规则判断。2.2 四个重载的语义差异Convert(int, string)最基础的重载使用默认语法形式。例如英文下把1变成1st。Convert(int, string, WordForm)按词形输出。Humanizer 的WordForm枚举区分Normal正常词形与Abbreviation缩写词形。以西班牙语为例源码中的 XML 注释原例1.Ordinalize(WordForm.Abbreviation) - 1.er如 Vivo en el 1.er piso而1.Ordinalize(WordForm.Normal) - 1.º如 Fui el 1º de mi promoción。Convert(int, string, GrammaticalGender)按语法性别输出。典型场景是巴西葡萄牙语1.Ordinalize(GrammaticalGender.Masculine) - 1º1.Ordinalize(GrammaticalGender.Feminine) - 1ª。Convert(int, string, GrammaticalGender, WordForm)性别与词形组合的完整重载允许西班牙语等语言同时区分 1.er / 1.º / 1.ª。2.3 衍生接口 ILongOrdinalizer除IOrdinalizer外IOrdinalizer.cs 还定义了继承它的ILongOrdinalizer为 64 位整型补充了 4 个对应的Convert(long, string, ...)重载。注释明确说明注册自定义序数器时若需要支持超出int范围的值应实现ILongOrdinalizer已有的IOrdinalizer实现仍可继续用于 32 位数值。为什么需要单独扩展因为 OrdinalizeExtensions.cs 中的ConvertOrdinalizer辅助方法采用运行时类型判断若解析到的序数器是ILongOrdinalizer则调用其 64 位重载否则回退到 32 位重载并在数值超出int范围时抛出NotSupportedException。测试 OrdinalizeTests.cs 验证了大数值行为例如4294967297L.Ordinalize(new CultureInfo(fr-FR))输出4294967297ème说明法语实现已通过ILongOrdinalizer支持 64 位输入。三、扩展方法如何驱动接口完整调用链IOrdinalizer不会直接暴露给业务代码而是由 OrdinalizeExtensions.cs 中的一系列Ordinalize重载代理。理解调用链有助于判断自定义实现何时生效调用方执行1.Ordinalize(...)或1.Ordinalize(...)扩展方法解析文化culture ?? CultureInfo.CurrentCulture通过Configurator.Ordinalizers.ResolveForCulture(culture)按文化解析出IOrdinalizer实例调用对应重载的Convert(number, numberString, ...)实现内部按语言规则追加/替换后缀返回序数词。细节上OrdinalizeExtensions还做了两类预处理NormalizeOrdinalNumberString剔除输入字符串中的 UnicodeFormat类字符如零宽字符避免干扰后缀判断FormatOrdinalNumberString针对非不变文化如使用本地化数字字符或特殊负号规则的语言格式化数字字符串内置实现还按文化名对OrdinalNumberFormatting做了缓存OrdinalNumberFormattingCache。四、内置实现族从空操作到模板规则Localisation/Ordinalizers目录下共有 6 个实现文件构成了从什么都不做到模板化规则的完整谱系4.1 DefaultOrdinalizer默认实现DefaultOrdinalizer.cs 是注册表的兜底类型实现ILongOrdinalizer并标记所有方法为virtual。它的核心行为是原样返回numberStringL29-L30不做任何变换带性别/词形的重载只是逐级向下委托到无参形式如Convert(number, numberString, gender)委托给Convert(number, numberString)。它同时提供两个受保护的工具方法GetAbsoluteValue求绝对值正确处理long.MinValue的溢出和TryGetInt32Value安全的 int 范围检查供派生类复用。4.2 SuffixOrdinalizer 与 ModuloSuffixOrdinalizer后缀规则SuffixOrdinalizer最简单的后缀追加实现把固定后缀拼到数字字符串后面ModuloSuffixOrdinalizer.cs按取模规则选后缀Options支持DefaultSuffix、按精确数字的ExactSuffixes、按最后两位的LastTwoDigitSuffixes、按最后一位的LastDigitSuffixes以及可选的LastTwoDigitsRange闭区间规则与AbsoluteAtLeast/AbsoluteAtLeastSuffix阈值规则。其GetSuffix方法的规则优先级为后两位区间 精确数字 阈值 后两位 后一位 默认后缀典型用于英语11th/12th/13th这类特殊规则。4.3 TemplateOrdinalizer 与 WordFormTemplateOrdinalizer模板规则TemplateOrdinalizer.cs面向需要前缀后缀的语言。Options按GrammaticalGender提供三套PatternMasculine/Feminine/Neuter每个Pattern含Prefix、DefaultSuffix、ExactReplacements精确替换直接覆盖输入文本、ExactSuffixes与LastDigitSuffixes还支持ZeroAsPlainNumber、MinValueAsPlainNumber把0/int.MinValue当作纯数字输出与NegativeNumberMode负数处理策略AbsoluteInvariant模式用不变文化重排绝对值。WordFormTemplateOrdinalizer进一步把词形WordForm纳入模板维度让同一性别下缩写与全写可走不同模板支撑西班牙语1.er缩写与1.º全写的区分。4.4 NumberWordSuffixOrdinalizer词后缀对于序数词后缀附着在完整数字单词上的语言如印地语hi-IN使用该实现把序数词缀接到数字单词后面。测试 OrdinalizeTests.cs 的OrdinalizeLongNumberUsesNumberWordSuffixFallback即验证了此类回退行为。五、自定义序数器注册到 LocaliserRegistry要替换或扩展序数词行为核心入口是Configurator.OrdinalizersConfigurator.cs。以注册表模式工作// 1. 实现 IOrdinalizer或 ILongOrdinalizer public sealed class CustomOrdinalizer : IOrdinalizer { public string Convert(int number, string numberString) numberString º; // 示例统一追加后缀 public string Convert(int number, string numberString, WordForm wordForm) Convert(number, numberString); public string Convert(int number, string numberString, GrammaticalGender gender) Convert(number, numberString); public string Convert(int number, string numberString, GrammaticalGender gender, WordForm wordForm) Convert(number, numberString); } // 2. 注册到注册表并注册对应文化 Configurator.Ordinalizers.RegisterCustomOrdinalizer(new CultureInfo(xx-XX)); Configurator.Ordinalizers.RegisterDefaultCustomOrdinalizer();注册之后所有调用数字.Ordinalize()的代码都会经由 OrdinalizeExtensions.cs 解析到你的实现。需要注意若只实现IOrdinalizer而注册表恰好返回ILongOrdinalizer类型的实例ConvertOrdinalizer会优先调用 64 位重载反之long输入超过int范围时仅实现IOrdinalizer会抛NotSupportedException若需要完全自定义每种语言的规则可以参考TemplateOrdinalizer的Pattern/Options结构组织数据避免把规则散落在switch分支中注册表本身基于LocaliserRegistryIOrdinalizer支持按文化解析与默认回退具体见 OrdinalizerRegistry.cs。六、与相邻 API 的关系IOrdinalizer并非孤岛它与 Humanizer 序数词体系中的两个类型紧密协作GrammaticalGender枚举定义Masculine、Feminine、Neuter三个性别值作为Convert重载的入参仅在语言要求时被消费如巴西葡萄牙语、西班牙语、俄语WordForm枚举定义Normal与Abbreviation两种词形用于区分全写与缩写输出主要被西班牙语等场景使用。同时Ordinalize扩展方法还有无性别/词形的简洁版本以及按文化显式指定的版本完整重载清单见 OrdinalizeExtensions.cs其行为覆盖由 OrdinalizeTests.cs 的OrdinalizeNumberGenderIsImmaterial、OrdinalizeStringWithSpecifiedCultureInsteadOfCurrentCulture等用例验证。七、小结IOrdinalizer是 Humanizer 序数词能力的本地化契约层它用 4 个Convert重载覆盖基础形式、词形、语法性别、性别词形四种输出维度用ILongOrdinalizer扩展 64 位支持并由OrdinalizerRegistry按文化路由到DefaultOrdinalizer、SuffixOrdinalizer、ModuloSuffixOrdinalizer、TemplateOrdinalizer等内置实现。理解这个接口你就能解释1.Ordinalize(GrammaticalGender.Feminine)为何在葡萄牙语输出1ª判断为什么西班牙语WordForm.Abbreviation与Normal结果不同通过Configurator.Ordinalizers注册自定义实现为私有语言/业务场景定制序数词规则在大数值场景下正确选择实现ILongOrdinalizer以避免NotSupportedException。无论你是要深入理解 Humanizer 的本地化架构还是要定制自己的序数词输出IOrdinalizer都是最核心的起点。赞分享开发工具【免费下载链接】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 IOrdinalizer 接口详解自定义本地化序数词转换的扩展点Humanizer IOrdinalizer 接口详解自定义本地化序数词转换的扩展点 本篇技术指南以 Humanizer 仓库中 Humanizer.Loca开发工具Humanizer 的 IOrdinalizer 接口全解析本地化序数化扩展点与 Convert 方法族Humanizer 的 IOrdinalizer 接口全解析本地化序数化扩展点与 Convert 方法族 IOrdinalizer 是 Humanizer 中开发工具Humanizer 本地化序数词引擎IOrdinalizer 接口的契约、实现与扩展实战指南Humanizer 本地化序数词引擎IOrdinalizer 接口的契约、实现与扩展实战指南 Humanizer 是面向 .NET 的字符串、枚举、日期与数字开发工具上一篇以开发上下文约束 Agent 编码行为解读 ECC 的 Development Context 规范下一篇NativeScript-Vue 代码质量保障ESLint、Prettier 与 Git Hooks 配置创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考