Humanizer 流式日期 API 实战：On.March 类完整参考与源码实现解析

开发工具【免费下载链接】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 的流式日期FluentDateAPI 中On.March类展开系统讲解其全部成员签名、语义与源码实现。读者读完将掌握如何用On.March.The14th这类自然语言风格的访问器快速构造当前年份三月任意一天的System.DateTime理解其底层由 T4 模板生成、固定锚定DateTime.Now.Year的实现机制并能将其与.At()、.AtMidnight()等介词扩展组合成完整的时间表达式。概览On类与流式日期 APIHumanizer 在Humanizer命名空间下提供了一套流式日期FluentDateAPI用接近自然语言的方式表达日期。On是一个静态外层类其下按月份嵌套了 12 个内部类January至December每个内部类都暴露一组以序数词命名的静态属性。On.March就是其中针对三月的访问器集合官方 API 文档定义如下public class On.March继承关系System.Object→March。它既不继承自任何 Humanizer 自定义基类也不带任何接口是一个纯粹的组织型嵌套类所有成员均为static因此使用时无需实例化直接以On.March.xxx形式调用。构造函数与成员总览March() 构造函数public March();文档将其描述为Initializes a new instance of the March class。由于该类所有成员都是静态的构造函数在正常使用中几乎不会被直接调用其存在更多是 C# 嵌套类的默认形态。属性The1st The31stOn.March暴露了 31 个静态属性覆盖三月从 1 日到 31 日的每一天命名采用英文序数词形式属性语义属性语义The1st三月 1 日The17th三月 17 日The2nd三月 2 日The18th三月 18 日The3rd三月 3 日The19th三月 19 日The4th三月 4 日The20th三月 20 日The5th三月 5 日The21st三月 21 日The6th三月 6 日The22nd三月 22 日The7th三月 7 日The23rd三月 23 日The8th三月 8 日The24th三月 24 日The9th三月 9 日The25th三月 25 日The10th三月 10 日The26th三月 26 日The11th三月 11 日The27th三月 27 日The12th三月 12 日The28th三月 28 日The13th三月 13 日The29th三月 29 日The14th三月 14 日The30th三月 30 日The15th三月 15 日The31st三月 31 日The16th三月 16 日每个属性的完整签名形式为public static System.DateTime The10th { get; }文档对每个属性的描述统一为The {n}th day of March of the current year当前年份三月的第 n 天返回值均为System.DateTime。方法The(int dayNumber)public static System.DateTime The(int dayNumber);这是On.March唯一的实例无关方法用于按整数参数动态取日期参数dayNumberSystem.Int32表示三月的第几天返回值System.DateTime语义当前年份三月的第dayNumber天The nth day of March of the current year。与固定的 31 个属性相比The(int)适合在循环、用户输入或程序化计算场景中动态生成日期。源码实现T4 模板生成与固定年份语义打开 On.Days.cs可以看到March类从第 392 行开始。The(int)的实现极为简洁public static DateTime The(int dayNumber) new(DateTime.Now.Year, 3, dayNumber);而The14th等属性则逐一展开为public static DateTime The14th new(DateTime.Now.Year, 3, 14);从源码结构可以看出两个关键实现事实月份号硬编码March的所有成员构造DateTime时第二个参数固定为3月份这正是它代表三月的原因January、February等同类类分别对应1、2。年份取自DateTime.Now.Year即当前年份。这意味着 2026 年调用On.March.The14th得到的是2026-03-14 00:00:00跨年后调用会自然得到新一年三月的同一天且不依赖闰年判断——DateTime构造器本身会对非法日期如不存在 2 月 30 日抛ArgumentOutOfRangeException而三月固定有 31 天所以 131 全部合法。代码不是手写而是 T4 模板生成的On.Days.cs并不是手写文件而是由同目录下的 T4 文本模板 On.Days.tt 生成的。模板核心逻辑如下const int leapYear 2012; for (var month 1; month 12; month) { var firstDayOfMonth new DateTime(leapYear, month, 1); var monthName firstDayOfMonth.ToString(MMMM); // ... 生成 public class # monthName # ... for (var day 1; day DateTime.DaysInMonth(leapYear, month); day) { var ordinalDay day.Ordinalize(); // ... 生成 public static DateTime The# ordinalDay # ... } }这段模板揭示了两点深层设计模板以闰年2012作为生成基准用DateTime.DaysInMonth(2012, 3)得到 31从而确定三月生成 31 个属性闰年的二月则生成 29 个月份名通过ToString(MMMM)得到英文月份名序数属性名The1st、The2nd、The3rd、The21st……是由 Humanizer 自身的Ordinalize()扩展方法生成的这正是该项目用自己生成自己 API的典型自举式代码生成实践。实际使用示例与组合扩展基本用法using Humanizer; // 固定属性当前年份三月 14 日 DateTime piDay On.March.The14th; // 动态方法当前年份三月第 n 天 DateTime arbitrary On.March.The(25); // 验证2026 年调用上述代码分别得到 // 2026-03-14 00:00:00 与 2026-03-25 00:00:00与介词扩展组合成完整时刻On.March.xxx返回的是午夜零点时刻。若要表达三月某日的某个时刻可结合 PrepositionsExtensions.cs 中的扩展方法DateTime meeting On.March.The15th.At(14, 30); // 三月 15 日 14:30 DateTime midnight On.March.The1st.AtMidnight(); // 三月 1 日 00:00 DateTime noon On.March.The2nd.AtNoon(); // 三月 2 日 12:00 DateTime nextYear On.March.The3rd.In(2030); // 2030 年三月 3 日其中At(int hour, int min 0, int second 0, int millisecond 0)保留原日期、替换时分秒毫秒AtMidnight()等价于At(0)AtNoon()等价于At(12)In(int year)则只替换年份、保留原日期与时间分量。动态场景循环生成整月日期for (int day 1; day 31; day) { DateTime d On.March.The(day); Console.WriteLine(d.ToString(yyyy-MM-dd)); }测试验证仓库如何保证语义正确Humanizer 为On系列提供了专门的测试文件 OnTests.cs其断言方式与文档语义完全对应[Fact] public void OnJanuaryThe23rd() Assert.Equal(new(DateTime.Now.Year, 1, 23), On.January.The23rd); [Fact] public void OnDecemberThe4th() Assert.Equal(new(DateTime.Now.Year, 12, 4), On.December.The4th); [Fact] public void OnFebruaryThe() Assert.Equal(new(DateTime.Now.Year, 2, 11), On.February.The(11));这些测试直接以new(DateTime.Now.Year, month, day)与属性/方法返回值做相等断言验证了当前年份 指定月日的语义。三月虽然没有被单独列入测试但它与一月、二月、十二月共享同一套 T4 生成模板行为模式完全一致。此外InTests.cs 中On.January.The21st被作为基准日期参与在若干时间之后的断言展示了On系列在日期计算链中的典型用法。姊妹 APIDateOnly 版本的 OnDate.March自 .NET 6 起源码中以#if NET6_0_OR_GREATER条件编译Humanizer 还提供了返回DateOnly的平行 APIOnDate见 OnDate.Days.cs。其OnDate.March类与On.March结构完全同构只是所有属性与方法返回DateOnlypublic static DateOnly The(int dayNumber) new(DateTime.Now.Year, 3, dayNumber);在不需要时刻分量的纯日期业务如排期、日历中优先使用OnDate以避免携带无意义的零点时间。其 API 文档同样位于 website/docs/api 目录下如Humanizer.OnDate.March.md。注意事项与边界当前年份语义On.March.xxx与On.March.The(n)都锚定DateTime.Now.Year与调用时刻所在年份绑定因此表达式本身是今年三月某日而非固定年份合法取值范围The(int dayNumber)的dayNumber应在 131 之间。超出范围时DateTime构造器会抛出ArgumentOutOfRangeException这一点与手写new DateTime(year, 3, dayNumber)的行为完全一致跨午夜零时所有属性与方法返回的都是当天00:00:00如需具体时刻请配合.At()、.AtNoon()、.AtMidnight()等扩展命名规范属性名遵循英文序数规则1st/2nd/3rd/21st/22nd/23rd/31st由 Humanizer 的Ordinalize()生成使用时应严格按此拼写。总体而言On.March是 Humanizer 流式日期 API 的典型切片通过嵌套类 静态属性把构造当前年份三月某日这一机械操作包装成可读性极强的自然语言表达式配合 On.Days.tt 的代码生成机制同一套模式被一致地复制到全年 12 个月形成整齐划一、易于测试和扩展的日期构造入口。赞分享开发工具【免费下载链接】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 详解In.Nine 类完整参考与源码级解析Humanizer 流式日期 API 详解 In.Nine 类完整参考与源码级解析 本篇文章聚焦 Humanizer 流式日期FluentDateAPI开发工具Humanizer 流畅日期 API 详解In.One 类 1 秒至 1 年时间推算的完整参考Humanizer 流畅日期 API 详解 In.One 类 1 秒至 1 年时间推算的完整参考 本篇技术指南聚焦 Humanizer 的 FluentDat开发工具四步做出你的专属桌宠VPet 桌宠 MOD 定制新手免费教程四步做出你的专属桌宠VPet 桌宠 MOD 定制新手免费教程 盯着桌面看了很久你不想让某个小家伙眨眨眼、陪陪你吗VPet 是一个开源的虚拟桌宠模拟器在这开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考