开发工具【免费下载链接】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 2.14.1 版本文档中的 Humanizer.On.July API 参考 为骨架深入讲解其 31 个日期属性与动态方法背后的实现原理、代码生成机制与实战用法。读完本文你将掌握如何在 .NET 代码中用On.July.The14th、On.July.The(5)这类自然语言风格调用构造出当前年份的某月某日的DateTime并能举一反三应用到其他月份与OnDateDateOnly变体上。On.July 类是什么On.July是 Humanizer 流式日期Fluent DateAPI 家族的一员位于Humanizer命名空间与On.January、On.February…On.December一起为 12 个月份分别提供了一套说人话的日期构造入口。官方 API 文档对其定位的描述是Provides fluent date accessors for July为七月提供流式日期访问器它继承自System.Object本身是一个静态成员组成的嵌套类声明形式为public class On.July所有成员返回的都是当前年份中七月的某个具体日期类型为System.DateTime。也就是说无论程序在哪一年运行On.July.The4th都等价于今年的 7 月 4 日年份自动取自DateTime.Now.Year。31 个 The* 属性每一天都是命名属性On.July为 7 月的每一天1 日到 31 日都预置了一个静态只读属性命名遵循英文序数词约定The1st、The2nd、The3rd、The4th依此类推到The31st。完整清单如下属性含义属性含义On.July.The1st当前年份 7 月 1 日On.July.The17th当前年份 7 月 17 日On.July.The2nd当前年份 7 月 2 日On.July.The18th当前年份 7 月 18 日On.July.The3rd当前年份 7 月 3 日On.July.The19th当前年份 7 月 19 日On.July.The4th当前年份 7 月 4 日On.July.The20th当前年份 7 月 20 日On.July.The5th当前年份 7 月 5 日On.July.The21st当前年份 7 月 21 日On.July.The6th当前年份 7 月 6 日On.July.The22nd当前年份 7 月 22 日On.July.The7th当前年份 7 月 7 日On.July.The23rd当前年份 7 月 23 日On.July.The8th当前年份 7 月 8 日On.July.The24th当前年份 7 月 24 日On.July.The9th当前年份 7 月 9 日On.July.The25th当前年份 7 月 25 日On.July.The10th当前年份 7 月 10 日On.July.The26th当前年份 7 月 26 日On.July.The11th当前年份 7 月 11 日On.July.The27th当前年份 7 月 27 日On.July.The12th当前年份 7 月 12 日On.July.The28th当前年份 7 月 28 日On.July.The13th当前年份 7 月 13 日On.July.The29th当前年份 7 月 29 日On.July.The14th当前年份 7 月 14 日On.July.The30th当前年份 7 月 30 日On.July.The15th当前年份 7 月 15 日On.July.The31st当前年份 7 月 31 日On.July.The16th当前年份 7 月 16 日每个属性的签名都是只读静态属性public static System.DateTime The10th { get; }典型调用using Humanizer; DateTime independenceDay On.July.The4th; // 今年的 7 月 4 日 DateTime midMonth On.July.The15th; // 今年的 7 月 15 日 DateTime lastDay On.July.The31st; // 今年的 7 月 31 日由于 7 月固定有 31 天这套属性从The1st到The31st恰好覆盖整个月份无需处理 28/29/30 天那种越界问题。The(int) 方法按数字动态取日除了 31 个预置属性On.July还提供了一个参数化方法用于以整数方式动态指定日期public static System.DateTime The(int dayNumber);参数dayNumber的类型为System.Int32表示7 月第几天返回值同样是System.DateTime。DateTime meetingDate On.July.The(14); // 等价于 On.July.The14th这套属性 方法的双轨设计覆盖了两种编程习惯写死的固定日期用带序数后缀的属性最直观由变量、配置或用户输入驱动的动态日期则交给The(int)。两者最终生成的日期值完全一致。源码实现一切归结为 DateTime 构造函数On.July的真实实现位于 On.Days.cs。以属性为例其实现极其简洁/// summary /// Provides fluent date accessors for July /// /summary public class July { /// summary /// The nth day of July of the current year /// /summary public static DateTime The(int dayNumber) new(DateTime.Now.Year, 7, dayNumber); /// summary /// The 1st day of July of the current year /// /summary public static DateTime The1st new(DateTime.Now.Year, 7, 1); /// summary /// The 14th day of July of the current year /// /summary public static DateTime The14th new(DateTime.Now.Year, 7, 14); // ... The2nd ~ The31st 依此类推 }可以提炼出的关键实现事实年份来源统一取DateTime.Now.Year因此这些 API 是运行时刻的日期不携带时区与具体时刻信息时刻为 00:00:00.000即当天零点月份固定7 月是写死的常量7底层构造每个成员都只是new DateTime(year, 7, day)的语法糖没有任何复杂的日期计算逻辑边界行为The(int dayNumber)对参数不加显式校验若传入非法值如0或32会抛出 .NETDateTime构造器自带的ArgumentOutOfRangeException这是从构造器语义推断的行为并非 Humanizer 自定义异常。代码生成On.Days.tt 模板驱动整个月份家族你可能会好奇12 个月、每家 31 个属性手写岂不枯燥答案是否定的。On.July所在的 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); // 生成月份类名 ... for (var day 1; day DateTime.DaysInMonth(leapYear, month); day) { var ordinalDay day.Ordinalize(); // 生成 The1st/The2nd/... 属性名 ... public static DateTime The# ordinalDay # new(DateTime.Now.Year, # month #, # day #); } }模板细节值得注意以2012 这个闰年为基准计算DateTime.DaysInMonth这样 2 月会生成 29 个属性其余月份按各自真实天数生成月份类名通过ToString(MMMM)得到本地化的月份英文名July属性名中的序数后缀1st、2nd、3rd、4th…由 Humanizer 自己的Ordinalize()扩展方法产生——这恰好是同一个库自产自销的典范。因此On.July的 31 个属性并非人工逐行编写而是由模板对月份 × 天数两层循环展开的结果这也解释了为何 12 个月类的结构完全同构、风格高度一致。测试验证同一机制的抽样覆盖仓库测试目录 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));虽然测试用例选取了 1 月、12 月与 2 月作为代表但由于 12 个月份类全部由同一套模板生成、实现模式完全一致这些断言对On.July.The*同样适用On.July.The4th与new(DateTime.Now.Year, 7, 4)恒等。测试同时覆盖了序数属性The23rd、The4th与动态方法The(11)两条路径。实战组合让 On.July 的结果真正可用On.July.The*返回的DateTime时刻为零点实际业务中往往需要叠加具体时间。可以借助 Humanizer 的介词扩展 PrepositionsExtensions.cs 实现链式调用using Humanizer; // 7 月 4 日下午 3 点 DateTime kickoff On.July.The4th.At(15); // 7 月 14 日中午 DateTime noon On.July.The14th.AtNoon(); // 7 月 1 日零点午夜 DateTime start On.July.The1st.AtMidnight(); // 把 7 月 4 日搬到指定年份如 2030 年 DateTime future On.July.The4th.In(2030);其中At(int hour, int min 0, int second 0, int millisecond 0)用于设定时刻AtNoon()/AtMidnight()是其便捷封装In(int year)则用于重设年份——三者都返回全新的DateTime不会修改原始值。如果你的项目基于 .NET 6 且偏好日期-only 语义Humanizer 还提供了对应的OnDate家族OnDate.July.The14th返回System.DateOnly实现见 OnDate.Days.cs与On.July的 API 形态完全对称。此外In.cs 中的In.TheYear(int year)可用来构造某年 1 月 1 日方便与On.July.The*( ).In(year)配合完成跨年份的日期编排。使用注意与适用范围当前年份语义所有On.July成员都绑定DateTime.Now.Year适合相对今天所在年份的场景如本年度内的排期、提醒若需要明确的绝对年份请配合In(year)扩展使用。无校验的动态参数The(int dayNumber)传入1 ~ 31之外的值会触发ArgumentOutOfRangeException调用方需自行保证参数合法。版本适用范围本文对应的 API 签名以 Humanizer 2.14.1 的版本化文档为准更高版本中该 API 形态保持稳定但建议以当前仓库 website/docs/api 下非版本化的最新 API 文档为最终依据。零开销设计从源码可见这些属性仅是DateTime构造器的一层薄封装无额外分配与复杂计算可放心在热路径中直接使用。延伸阅读完整 API 参考Humanizer.On.July实现源码On.Days.csOn.July 类、On.Days.ttT4 生成模板DateOnly变体OnDate.Days.cs配套扩展PrepositionsExtensions.csAt / AtNoon / AtMidnight / In测试用例OnTests.cs赞分享开发工具【免费下载链接】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 之 On.July用自然语言构造 7 月日期的完整指南Humanizer 流式日期 API 之 On.July用自然语言构造 7 月日期的完整指南 Humanizer 的 On.July 类是 FluentDat开发工具Humanizer On.February 流式日期 API 详解用自然语言构造 2 月日期Humanizer On.February 流式日期 API 详解用自然语言构造 2 月日期 Humanizer.On.February 是 .NET 库 H开发工具Humanizer 流式日期 API 详解On.July 七月日期访问器完整指南Humanizer 流式日期 API 详解On.July 七月日期访问器完整指南 本篇指南系统讲解 .NET 库 Humanizer 中 On.July 类的开发工具上一篇Wand-Enhancer免费解锁WeMod专业版功能的终极本地增强方案下一篇终极免费开源工具彻底解决腾讯游戏ACE-Guard卡顿问题的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考