Humanizer 流畅日期 API 详解：On.May 与 5 月日期访问器

开发工具【免费下载链接】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.10.1 的 API 参考文档为核心完整剖析On.May静态类——一个为 5 月提供流畅fluent日期访问器的工具类。你将掌握On.May.The1st至The31st全部 31 个属性与The(int)方法的签名、返回值语义、底层实现原理含 T4 模板生成机制以及如何在测试与业务代码中正确使用这些日期访问器。On.May 是什么一段可读的 5 月日期构造器On.May是 Humanizer 中On类On.Days.cs的嵌套类官方 API 参考将其描述为 Provides fluent date accessors for May为 5 月提供流畅日期访问器。它的核心价值在于用自然语言式的属性/方法调用代替晦涩的new DateTime(year, 5, day)构造让代码读起来就像在说5 月 1 日5 月 31 日。从类声明看public class On.May继承关系为 System.Object →May所有成员均为public static因此不需要实例化直接以On.May.The1st形式调用即可。Humanizer 为 12 个月份都生成了同名嵌套类On.January、On.February……On.DecemberOn.May只是其中之一本文聚焦 5 月这一实例展开。全部 31 个日期属性The1st 到 The31stOn.May为 5 月的每一天5 月有 31 天都提供了一个静态只读属性命名规则为The 英文序数词1st、2nd、3rd……31st。每个属性的语义完全一致返回当前年份DateTime.Now.Year中对应日期的System.DateTime。下表完整列出这 31 个属性与 API 参考文档一一对应未做任何删减属性返回的日期当年属性返回的日期当年The1st5 月 1 日The17th5 月 17 日The2nd5 月 2 日The18th5 月 18 日The3rd5 月 3 日The19th5 月 19 日The4th5 月 4 日The20th5 月 20 日The5th5 月 5 日The21st5 月 21 日The6th5 月 6 日The22nd5 月 22 日The7th5 月 7 日The23rd5 月 23 日The8th5 月 8 日The24th5 月 24 日The9th5 月 9 日The25th5 月 25 日The10th5 月 10 日The26th5 月 26 日The11th5 月 11 日The27th5 月 27 日The12th5 月 12 日The28th5 月 28 日The13th5 月 13 日The29th5 月 29 日The14th5 月 14 日The30th5 月 30 日The15th5 月 15 日The31st5 月 31 日The16th5 月 16 日所有属性的声明签名一致均为public static System.DateTime The10th { get; }以The10th为例官方描述为 The 10th day of May of the current year当前年份 5 月的第 10 天属性值类型为 System.DateTime。通用方法The(int dayNumber)除了 31 个预置属性On.May还提供一个方法用于访问第 n 天public static System.DateTime The(int dayNumber);参数dayNumber类型System.Int32表示 5 月中的某一天序号返回System.DateTime即当前年份 5 月dayNumber日的日期语义官方描述为 The nth day of May of the current year。这个方法是属性形式的通用版本适合在日期由运行时变量决定而非硬编码字面量的场景下使用。注意dayNumber的取值范围理论上受DateTime构造约束传入 0 或负数、超过 5 月实际天数31的值会导致参数异常实际编码时应自行保证输入在合法区间内。源码级原理T4 模板批量生成 当前年份注入On.May的代码并非手写 31 遍而是由 T4 文本模板 On.Days.tt 在构建期生成。模板核心逻辑如下节选for (var month 1; month 12; month) { var firstDayOfMonth new DateTime(leapYear, month, 1); var monthName firstDayOfMonth.ToString(MMMM); // 生成 public class {月份名} { ... } for (var day 1; day DateTime.DaysInMonth(leapYear, month); day) { var ordinalDay day.Ordinalize(); // 生成 public static DateTime The{序数} new(DateTime.Now.Year, {月}, {日}); } }从中可以读出三个关键实现事实月份名取自DateTime.ToString(MMMM)模板以 2012 年闰年用于保证 2 月 29 日的完整性为基准生成 12 个嵌套类5 月的类名May即来自英文区域设置下的长月份名属性名由Ordinalize()扩展方法生成day.Ordinalize()是 Humanizer 在 OrdinalizeExtensions.cs 中提供的序数词转换扩展把 1→1st、2→2nd、3→3rd、21→21st、22→22nd从而得到The1st、The2nd这样的规范命名年份动态取自DateTime.Now每个属性/方法体都是new(DateTime.Now.Year, 5, dayNumber)见 On.Days.cs 中May类的实际实现意味着调用时永远是当年的 5 月无需手工传入年份。以生成结果对照On.May实际位于 On.Days.cs 第 782 行起其中The(int dayNumber)实现为new(DateTime.Now.Year, 5, dayNumber)The1st实现为new(DateTime.Now.Year, 5, 1)依此类推。实际使用示例与调用注意点业务代码中的典型用法using Humanizer; // 属性形式硬编码的5月1日5月31日 DateTime laborDay On.May.The1st; // 当年 5 月 1 日 DateTime monthEnd On.May.The31st; // 当年 5 月 31 日 // 方法形式日期由变量决定 int scheduledDay GetScheduledDay(); // 例如 15 DateTime schedule On.May.The(scheduledDay); // 当年 5 月 15 日 // 与其他流畅 API 混用如5月1日的午夜 DateTime midnight On.May.The1st.At(0, 0, 0);需要注意的两个语义要点当前年份是调用时刻的年On.May.The1st在 2026 年调用返回 2026-05-01在 2027 年调用则返回 2027-05-01。跨年调度、历史数据回填等场景必须意识到这一点返回值是带时间部分的DateTime构造时未显式提供时分秒因此时间部分为00:00:00午夜可与At/AtNoon/AtMidnight等扩展组合得到更精确的时刻。测试中的验证方式Humanizer 自带测试 OnTests.cs 直接验证了这类访问器的行为[Fact] public void OnJanuaryThe23rd() Assert.Equal(new(DateTime.Now.Year, 1, 23), On.January.The23rd); [Fact] public void OnFebruaryThe() Assert.Equal(new(DateTime.Now.Year, 2, 11), On.February.The(11));对照On.May可写出等价断言Assert.Equal(new(DateTime.Now.Year, 5, 10), On.May.The10th)、Assert.Equal(new(DateTime.Now.Year, 5, 15), On.May.The(15))。测试与实现均使用DateTime.Now.Year因此断言天然随时间推移保持成立但要注意测试在跨年瞬间执行时理论上存在边界窗口。配套 API 与选择建议在 Humanizer 的 FluentDate 体系中On.May属于按月份取日期一族与以下 API 配套使用On其余月份类On.JanuaryOn.December结构与On.May完全一致同样由 On.Days.cs 生成适合表达某月某日OnDate在支持DateOnly的目标框架上提供对应无时间部分的日期访问器OnDate.May.The10th返回DateOnly而非DateTime见 OnDate.Days.cs适合仅关注日历日、不想携带午夜时间戳的场景In/InDate面向从现在起多少天后/月后或某年某月的相对/绝对构造例如In.AprilOf(2025)、In.TheYear(2026)与On形成互补见 In.cs。Humanizer 官方场景文档fluent-dates-and-time-spans.mdx将On.April.The3rd这类表达式定位为 readable constructors aroundDateTimeDateTime的可读构造函数。选型建议字面量日期优先用属性On.May.The1st比new DateTime(now.Year, 5, 1)更易读变量日期用The(int)仅需日期无需时间用OnDate需要指定任意年份则改用In.MayOf(year)一族。小结On.May以 31 个序数命名属性 1 个通用方法把当年 5 月的某一天封装成了近乎自然语言的 API。其背后是 T4 模板基于Ordinalize()与DateTime.DaysInMonth的批量生成以及DateTime.Now.Year的运行时年份注入——理解这三点你就掌握了 Humanizer 全部 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 详解On.May 五月份日期访问器全解析Humanizer 流式日期 API 详解On.May 五月份日期访问器全解析 本指南以 Humanizer 官方 API 参考文档 Humanizer.On开发工具Humanizer FluentDate API 详解On.September 类与 9 月流畅日期访问器Humanizer FluentDate API 详解On.September 类与 9 月流畅日期访问器 本篇技术指南围绕 Humanizer 2.10.1开发工具Humanizer 流式日期 API 详解On.July 七月日期访问器完整指南Humanizer 流式日期 API 详解On.July 七月日期访问器完整指南 本篇指南系统讲解 .NET 库 Humanizer 中 On.July 类的开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考