Humanizer 格位（GrammaticalCase）枚举完全指南：为俄语、波兰语等屈折语言的日期与时长的格位感知输出

开发工具【免费下载链接】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 公开 API 中的GrammaticalCase枚举展开说明它如何在日期序数词ToOrdinalWords与时长文本HumanizeWithCase两类场景中按语法格位格选择正确的词形。读完本文你将掌握该枚举的全部成员语义、Humanizer 对其的校验与异常规则、以及它在俄语、丹麦语、罗马尼亚语、印地语、阿塞拜疆语等文化下的实际输出形态与适用边界。一、什么是 GrammaticalCase从 API 文档到源码定义在 version-3.0.1 的 API 文档 中GrammaticalCase被定义为Options for specifying the desired grammatical case for the output words即“用于指定输出词汇所需语法格位的选项”。它是 Humanizer 中一个public enum作用是告诉本地化层当某门语言的名词、形容词、序数词会随句子成分主语、宾语、领属者、介词宾语等发生**词形变化变格**时应该渲染成哪一种形态。对于俄语、波兰语、捷克语、德语、芬兰语等拥有格系统的语言这一参数直接决定输出词的正确写法而对于英语这类基本不发生名词变格的语言该参数通常不产生任何效果。当前仓库中的实际定义位于 src/Humanizer/GrammaticalCase.cs其完整枚举成员为28 个自动按序编号 029Causal为最后一个。而 v3.0.1 版本 API 文档只收录了前 6 个印欧语系核心格位编号 05后续版本在此基础上扩展出了更多区域性语言如芬兰-乌戈尔语系、达罗毗荼语系所需的格位。二、全部枚举成员与语义对照表以下表格整合了 API 文档 中记载的 6 个核心成员与 源码 中扩展的其余成员及其 XML 注释语义成员隐含数值语义对应源码 XML 注释典型使用语言推断Nominative0表示限定动词的主语subject of a finite verb俄语、德语、拉丁语等Genitive1表示另一名词的领属者possessor of another noun俄语、德语、丹麦语Dative2表示动词的间接宾语indirect object of a verb俄语、德语Accusative3表示动词的直接宾语direct object of a verb俄语、德语Instrumental4表示执行动作时使用的工具object used in performing an action俄语、波兰语Prepositional5表示介词宾语object of a preposition俄语Ablative6表示离开某名词的运动motion away from a noun拉丁语、芬兰语Comitative7表示伴随accompaniment芬兰语、爱沙尼亚语Ergative8表示作格结构中及物动词的施事agent of a transitive verb in an ergative construction巴斯克语Locative9表示位置location波兰语、捷克语Oblique10表示用在格标记后置词或后缀之前的形态form used before a case-marking postposition or suffix印地语、旁遮普语Partitive11表示部分或不定量partial or indefinite quantity芬兰语、爱沙尼亚语Vocative12表示直接称呼direct address波兰语、捷克语、乌克兰语Elative13表示从内部离开的运动motion out of or away from within芬兰语、爱沙尼亚语Illative14表示进入内部的运动motion into芬兰语、爱沙尼亚语Sociative15表示马拉雅拉姆语社会性格的关联或伴随association or accompaniment马拉雅拉姆语Terminative16表示端点或界限endpoint or limit爱沙尼亚语Translative17表示转变进入某种状态transition into a state芬兰语、爱沙尼亚语Absolutive18表示不及物动词的无标记主目或及物动词宾语unmarked argument of an intransitive verb or object of a transitive verb巴斯克语Additive19表示爱沙尼亚语短入格Estonian short illative form爱沙尼亚语Inessive20表示位于内部location within芬兰语、爱沙尼亚语Allative21表示朝上/朝某处的运动motion onto or toward芬兰语、爱沙尼亚语Adessive22表示位于某处/附着location on or at芬兰语、爱沙尼亚语Essive23表示临时状态或角色temporary state or role芬兰语、爱沙尼亚语Abessive24表示缺失或“没有”absence or being without芬兰语、爱沙尼亚语Equative25表示比较或等同comparison or equivalence格鲁吉亚语Directive26表示朝某方向的运动或趋向motion or direction toward部分高加索语言Lative27表示朝目的地的方向direction toward a destination芬兰语系部分语言Benefactive28表示预期受益者intended beneficiary部分语言Causal29表示原因或理由cause or reason芬兰语等说明数值为源码中按声明顺序的隐含编号前 6 项与 v3.0.1 API 文档 中标注的显式值Nominative0 … Prepositional5完全一致。三、GrammaticalCase 的两大消费入口Humanizer 中实际接收GrammaticalCase参数的公开 API 主要有两组均定义在扩展方法中可通过 Public API 快照 中的ToOrdinalWords(...grammaticalCase)与HumanizeWithCase(...grammaticalCase)签名得到印证。3.1 日期序数词ToOrdinalWords(input, GrammaticalCase)定义于 src/Humanizer/DateToOrdinalWordsExtensions.csDateTime.ToOrdinalWords(this DateTime input, GrammaticalCase grammaticalCase)DateOnly.ToOrdinalWords(this DateOnly input, GrammaticalCase grammaticalCase)仅 .NET 6.0 及以上。其实现直接委托给Configurator注册的IDateToOrdinalWordConverter/IDateOnlyToOrdinalWordConverter。从 DefaultDateToOrdinalWordConverter.cs 可以看到默认转换器的行为英语文化下输出形如22nd of December, 2020且Convert(DateTime date, GrammaticalCase grammaticalCase)直接忽略传入的格位参数并调用无格位版本——这正是“英语没有变格参数无效”的源码证据非英语文化则使用当前文化的短日期格式date.ToString(d, culture)并剥离希伯来/阿拉伯日历等输出中可能嵌入的方向性标记U200E、U200F、U061C保证嵌入更大序数短语时文本可读。源码目录src/Humanizer/Localisation/DateToOrdinalWords/下存放了 8 个区域性转换器实现可以推断俄语、波兰语等带格系统的语言各自实现了格位感知的序数词转换而 CoverageGapTests.cs 中Assert.Equal(February 22nd, 2024, date.ToOrdinalWords(GrammaticalCase.Genitive))的用例则从测试侧再次确认英语文化下无论传入哪个格位输出保持一致。3.2 时长文本HumanizeWithCase(TimeSpan, GrammaticalCase, …)定义于 src/Humanizer/TimeSpanHumanizeExtensions.cs提供两个重载public static string HumanizeWithCase( this TimeSpan timeSpan, GrammaticalCase grammaticalCase, int precision 1, CultureInfo? culture null, TimeUnit maxUnit TimeUnit.Week, TimeUnit minUnit TimeUnit.Millisecond, string? collectionSeparator , ) public static string HumanizeWithCase( this TimeSpan timeSpan, GrammaticalCase grammaticalCase, int precision, bool countEmptyUnits, CultureInfo? culture null, TimeUnit maxUnit TimeUnit.Week, TimeUnit minUnit TimeUnit.Millisecond, string? collectionSeparator , )参数说明依据源码 XML 注释grammaticalCase用于选择每个时间单位短语的格位precision最多返回的时间单位数量默认 1countEmptyUnits空时间单位是否计入precision前导空单位永不计数culture使用的文化null时取当前线程文化maxUnit/minUnit输出的最大/最小时间单位默认Week/MillisecondcollectionSeparator组合各时间分段的连接符传null时使用文化的默认集合格式化器。它内部先调用ValidateGrammaticalCase做参数校验再要求当前配置的ITimeSpanHumanizeStrategy必须实现IGrammaticalCaseTimeSpanHumanizeStrategy否则抛出NotSupportedException。默认策略 DefaultTimeSpanHumanizeStrategy.cs 实现了该接口并经由IGrammaticalCaseTimeSpanFormatter接口把格位请求转发给 DefaultFormatter.cs 中的TimeSpanHumanize(TimeUnit, int, GrammaticalCase)显式接口实现。四、源码级校验与异常语义Humanizer 对GrammaticalCase的校验横跨扩展方法与格式化器两层理解这些规则有助于规避运行时异常4.1 范围校验仅允许 ≤ Causal 的枚举值在 TimeSpanHumanizeExtensions.cs 的ValidateGrammaticalCase与 DefaultFormatter.cs 的接口实现中均采用无符号比较if ((uint)grammaticalCase (uint)GrammaticalCase.Causal) { throw new ArgumentOutOfRangeException( nameof(grammaticalCase), grammaticalCase, Unsupported grammatical case.); }即只要是枚举定义内的值029就通过校验若传入未定义的整数值如(GrammaticalCase)99则抛出ArgumentOutOfRangeException。4.2 文化级分类NotApplicable / UnsupportedDefaultFormatter的格位感知路径依赖源码生成器产出的LocaleDurationCaseTableCatalog生成输入定义见 src/Humanizer.SourceGenerators/Generators/ProfileCatalogs/LocaleDurationCaseTableCatalogInput.cs按LocaleDurationCaseClassification分三类处理Unsupported该文化具备格位系统但尚无经核验的时长短语形态——抛出NotSupportedExceptionNotApplicable该文化不支持格位时长短语如英语——抛出NotSupportedException正常分类通过table.TryGetCase(grammaticalCase, out var caseOverlay)查询若文化不支持所请求的特定格位同样抛出NotSupportedException。此外格位叠加层还按单位区分SameAsNominative退回主格形态、NotApplicable/Unsupported拒绝与常规短语渲染三种路径保证“某个格位对该单位不适用”时给出清晰失败信息而非错误词形。五、格位感知输出的真实形态固定用例验证测试 tests/Humanizer.Tests/Localisation/GeneratedLocaleData/CldrDurationCaseTests.cs 提供了大量“钉死”pinned的格位输出样例可直接作为行为参照文化格位单位数量期望输出da-DKGenitiveDay11 dagssv-SEGenitiveDay11 dygnsnn-NOGenitiveWeek11 vekesnb-NOGenitiveWeek11 ukesro-ROGenitiveDay1unei zileam-ETAccusativeDay1አንድ ቀንhi-INObliqueDay11 दिनpa-INObliqueWeek11 ਹਫ਼ਤੇazDativeDay11 günə可见丹麦语、瑞典语、挪威语的领属格会给名词加词尾如dag → dags、dygn → dygns罗马尼亚语属格甚至将单位渲染成独立的属格短语unei zile印地语与旁遮普语则使用Oblique形态后置词前的变格。同一测试文件还验证了阿拉伯语ar在Nominative/Genitive/Accusative下小时与天的双数、复数形态差异例如ساعة واحدة1 小时、ساعتان2 小时主格、ساعتين2 小时属格/宾格。测试中还包含“上下文相关失败”用例索马里语so对Nominative抛出包含does not apply的NotSupportedException验证了 4.2 节所述的单位级格位适用性检查。六、实战示例与注意事项using Humanizer; using System.Globalization; // 1) 日期序数词英语下格位参数被忽略 var en new DateTime(2024, 2, 22) .ToOrdinalWords(GrammaticalCase.Genitive); // February 22nd, 2024与 Nominative 相同 // 2) 时长短语丹麦语属格 var danish TimeSpan.FromDays(1).HumanizeWithCase( GrammaticalCase.Genitive, culture: new CultureInfo(da-DK), maxUnit: Humanizer.TimeUnit.Day, minUnit: Humanizer.TimeUnit.Day); // 1 dags // 3) 时长短语阿塞拜疆语与格 var azeri TimeSpan.FromDays(1).HumanizeWithCase( GrammaticalCase.Dative, culture: new CultureInfo(az), maxUnit: Humanizer.TimeUnit.Day, minUnit: Humanizer.TimeUnit.Day); // 1 günə使用要点先确认文化支持对无格系统的文化如en-US、zh-CN调用HumanizeWithCase会因LocaleDurationCaseClassification.NotApplicable抛出NotSupportedException并非所有语言都适用格位参数异常面较广除ArgumentOutOfRangeException非法枚举值外还可能在“文化无格位时长表”“文化不支持该格位”“该格位不适用于该单位”三种情况下抛出NotSupportedException生产代码应做好捕获或先探测支持范围默认参数即可满足多数场景precision默认 1、maxUnit默认Week、minUnit默认Millisecond与普通Humanize的默认行为一致通常只需显式传入grammaticalCase与cultureDateOnly 重载仅限 .NET 6DateOnly版本的ToOrdinalWords(input, grammaticalCase)带有#if NET6_0_OR_GREATER条件编译面向旧框架时只有DateTime重载可用。七、总结GrammaticalCase是 Humanizer 多语言本地化能力在“屈折语言”方向上的关键抽象它以 28 个成员覆盖印欧、乌拉尔、达罗毗荼、闪含等多个语系的格位系统通过ToOrdinalWords与HumanizeWithCase两个入口暴露给开发者底层则由源码生成器按文化产出格位时长表、由DefaultFormatter统一调度。理解其成员语义、文化分类与异常路径是正确使用 Humanizer 处理俄语、丹麦语、印地语等语言文本输出的前提。赞分享开发工具【免费下载链接】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 的 GrammaticalCase 枚举为多语言屈折输出精确指定语法格Humanizer 的 GrammaticalCase 枚举为多语言屈折输出精确指定语法格 本篇技术指南围绕 Humanizer https://link.g开发工具Humanizer GrammaticalCase 枚举参考语法格的完整定义与格感知时长输出实现Humanizer GrammaticalCase 枚举参考语法格的完整定义与格感知时长输出实现 本文以 Humanizer 2.13.14 版本文档站中的开发工具Humanizer 的 GrammaticalCase 枚举为多语言输出选择正确的语法格Humanizer 的 GrammaticalCase 枚举为多语言输出选择正确的语法格 GrammaticalCase 是 Humanizer 库中用于指定开发工具上一篇AO3 镜像站快速上手指南5 步拿到稳定访问地址下一篇智慧教育平台电子教材下载保姆级教程5分钟批量搞定电子课本PDF创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考