开发工具【免费下载链接】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 库中InDate.Five这一静态嵌套类完整剖析其 4 个属性Days、Weeks、Months、Years与 8 个方法DaysFrom、WeeksFrom、MonthsFrom、YearsFrom的DateOnly/DateTime重载的语义、底层实现、UTC 行为边界与测试验证方式并给出可直接运行的实操示例。读完本文你将掌握如何用人类可读的自然语言风格构造DateOnly日期以及在确定性代码中正确选择相对当前时刻属性与相对指定日期方法的准则。InDate.Five是 Humanizer 流畅日期 APIFluentDate在 .NET 6 上的DateOnly分支。它与In.Five返回DateTime一一对应是处理仅日历日期、无时间成分场景下的首选。本文以 version-2.11.10 的 API 参考文档 为骨架结合 InDate.SomeTimeFrom.cs 源码与 GeneratedFluentDateTests.cs 测试用例展开。一、InDate.Five 是什么InDate.Five是Humanizer.InDate的部分类public partial class InDate中嵌套的public static class Five全名Humanizer.InDate.Five。它是一组静态、无状态的日期工厂不持有任何实例状态全部成员均为static调用时直接返回一个System.DateOnly值。public static class InDate.Five与InDate.One至InDate.Ten构成同一族 API覆盖 110 的整数偏移。Five只是其中5这一档语义为从现在起 5 个时间单位之后或从指定日期起 5 个时间单位之后。二、成员全景4 个属性与 8 个方法InDate.Five提供 4 个属性、8 个方法全部返回System.DateOnly属性相对现在属性类型语义源码实现InDate.SomeTimeFrom.csDaysDateOnly从现在起 5 天DateOnly.FromDateTime(DateTime.UtcNow.AddDays(5))WeeksDateOnly从现在起 5 周DateOnly.FromDateTime(DateTime.UtcNow.AddDays(35))MonthsDateOnly从现在起 5 个月DateOnly.FromDateTime(DateTime.UtcNow.AddMonths(5))YearsDateOnly从现在起 5 年DateOnly.FromDateTime(DateTime.UtcNow.AddYears(5))方法相对指定日期每个单位都提供DateOnly与DateTime两种入参重载方法入参返回源码实现DaysFrom(DateOnly date)DateOnlyDateOnlydate.AddDays(5)DaysFrom(DateTime date)DateTimeDateOnlyDateOnly.FromDateTime(date.AddDays(5))WeeksFrom(DateOnly date)DateOnlyDateOnlydate.AddDays(35)WeeksFrom(DateTime date)DateTimeDateOnlyDateOnly.FromDateTime(date.AddDays(35))MonthsFrom(DateOnly date)DateOnlyDateOnlydate.AddMonths(5)MonthsFrom(DateTime date)DateTimeDateOnlyDateOnly.FromDateTime(date.AddMonths(5))YearsFrom(DateOnly date)DateOnlyDateOnlydate.AddYears(5)YearsFrom(DateTime date)DateTimeDateOnlyDateOnly.FromDateTime(date.AddYears(5))三、属性与方法的三层行为差异1. 时间基准UTC 还是本地时间四个属性全部基于DateTime.UtcNow计算再经DateOnly.FromDateTime截断为日期。这意味着结果是某一天而非某一时刻天然没有时区歧义中的时刻成分但今天由 UTC 时钟决定。若你的进程运行在非 UTC 时区在 UTC 日期与本地日期不一致的时间窗口内例如北京时间 08:00 之前InDate.Five.Days得到的5 天后可能与直觉上的本地日期相差一天。2. 输入类型DateOnly 与 DateTime 的重载差异DateOnly重载直接调用date.AddDays(...)纯日历运算、无任何转换DateTime重载则先对DateTime做偏移再DateOnly.FromDateTime转换。因此传入DateTime时时间成分被丢弃例如2025-01-20 09:00加 5 天得到2025-01-25时分秒不参与结果两种重载的结果等价性取决于DateTime的时区语义——DateOnly.FromDateTime按该DateTime的Kind直接取日期部分不做时区换算。3. 单位语义周是7 天的倍数从源码可见Weeks与WeeksFrom内部实现为AddDays(5 * 7)即 35 天不是AddWeeks。对日历运算而言 5 周恒等于 35 天结果一致这也说明 Humanizer 将周严格定义为固定天数偏移。四、日历运算的归一化月末与闰年MonthsFrom/YearsFrom委托给 .NET 原生的AddMonths/AddYears。官方场景文档 fluent-dates-and-time-spans.mdx 明确提醒月份与年份是日历大小的运算不是估算的TimeSpan时长结果遵循AddMonths/AddYears的归一化规则若目标月份不存在该日期如 2 月 30 日、非闰年的 2 月 29 日会自动折入当月最后一天。示例.NET的AddMonths语义Humanizer 原样继承var leapDay new DateOnly(2024, 2, 29); var fiveYearsLater InDate.Five.YearsFrom(leapDay); // 2029 年不是闰年 → 结果为 2029-02-28归一化同理InDate.Five.MonthsFrom(new DateOnly(2025, 8, 31))得到2026-01-31而InDate.Five.MonthsFrom(new DateOnly(2025, 10, 31))得到2026-03-313 月有 31 天不折叠。五、实操可运行的代码示例InDate.Five无需任何配置直接通过包引用使用。用InDate.Five表达5 个时间单位后using Humanizer; // 相对现在基于 UtcNow DateOnly inFiveDays InDate.Five.Days; // 今天 5 天 DateOnly inFiveWeeks InDate.Five.Weeks; // 今天 35 天 DateOnly inFiveMonths InDate.Five.Months; // 今天 5 个月日历运算 DateOnly inFiveYears InDate.Five.Years; // 今天 5 年日历运算 // 相对指定日期 DateOnly base new(2025, 1, 20); DateOnly due InDate.Five.DaysFrom(base); // 2025-01-25 DateOnly reminder InDate.Five.MonthsFrom(base); // 2025-06-20 // DateTime 输入时间成分被丢弃 DateOnly fromDateTime InDate.Five.DaysFrom(new DateTime(2025, 1, 20, 23, 59, 59)); // 2025-01-25时分秒不参与项目内的官方示例 scenarios-fluent-dates/Program.cs 展示了配套用法In.Two.MonthsFrom构造 2025-03-20其输出见 expected-output.txtTwo months later: 2025-03-20 09:00六、可测试性注入基准日期远离现在官方文档明确建议在需要可重复结果的代码或测试中应注入起始日期而非依赖现在。这正好对应InDate.Five的方法族——DaysFrom、WeeksFrom、MonthsFrom、YearsFrom才是确定性 API而四个属性读取UtcNow天然不可重复。测试代码 InDateTests.cs 正是这样验证的[Fact] public void InFiveDays() { var baseDate OnDate.January.The21st; var date InDate.Five.DaysFrom(baseDate); Assert.Equal(baseDate.AddDays(5), date); }GeneratedFluentDateTests.cs 则用反射批量断言InDateRelativeDatePropertiesReturnExpectedUtcOffsets遍历InDate下所有相对日期属性含Five.Days等在调用前后分别采样UtcNow断言返回值落在[before 偏移, after 偏移]区间内——这从测试层面证实了属性确实基于UtcNowInDateRelativeDateOnlyMethodsReturnExpectedOffsetsFromProvidedDate/InDateRelativeDateTimeMethodsReturnExpectedOffsetsFromProvidedDateTime分别验证DateOnly与DateTime两个重载的偏移正确性。七、设计溯源T4 模板生成InDate.Five并非手写代码而是由 T4 文本模板 InDate.SomeTimeFrom.tt 生成的。模板核心逻辑for (var i 1; i 10; i) // 生成 One ~ Ten 十个嵌套类 { // 每个类生成 4 属性 8 方法 // 类名i.ToWords().Dehumanize()即 5 → Five // Weeks 使用 AddDays(i * 7) }这也解释了为什么InDate.Five的类名是英文单词Five而非数字模板调用 Humanizer 自身的ToWords().Dehumanize()把数字 5 转为单词并反人类化去空格、驼峰化得到Five。整个InDate族的代码全部由同一模板驱动结构完全对称因此本文对Five的剖析可 1:1 迁移到OneTen其余九个类。另外InDate本身还有手写的TheYear(int year)方法InDate.cs返回new(year, 1, 1)用于某年 1 月 1 日的快速构造可与InDate.Five组合使用。八、适用前提与限制框架要求InDate系列含InDate.Five仅在NET6_0_OR_GREATER条件下编译源码以#if NET6_0_OR_GREATER包裹因为System.DateOnly自 .NET 6 引入。若目标框架为 .NET Framework 4.8 或 .NET Core 3.1应改用In.Five返回DateTime。文化差异所有成员返回纯DateOnly值不做任何格式化因此不涉及区域性但AddMonths/AddYears的归一化遵循 .NET 原生规则不选用特定文化的Calendar。不要将日历运算当作时长估算MonthsFrom/YearsFrom不是固定天数跨度随目标日期变化。九、延伸阅读同类 DateTime 版本Humanizer.In.Five返回DateTime时间成分保留月份构造器Humanizer.InDateJanuary~December属性与XxxOf(year)方法场景指南Compose dates and time spans fluently生成代码入口InDate.SomeTimeFrom.cs 与模板 InDate.SomeTimeFrom.tt赞分享开发工具【免费下载链接】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 InDate.Six 详解用 DateOnly 流畅表达「六天后 / 六周后 / 六月后 / 六年后」的日期计算Humanizer InDate.Six 详解用 DateOnly 流畅表达「六天后 / 六周后 / 六月后 / 六年后」的日期计算 导读 InDate.Si开发工具Humanizer InDate.Nine 全面解析用 DateOnly 表达 9 天/9 周/9 个月/9 年后的日期Humanizer InDate.Nine 全面解析用 DateOnly 表达 9 天/9 周/9 个月/9 年后的日期 导读 InDate.Nine 是 H开发工具Humanizer InDate.One 完整解析用 DateOnly 实现1 天后/周后/月后/年后的流畅日期计算Humanizer InDate.One 完整解析用 DateOnly 实现1 天后/周后/月后/年后的流畅日期计算 本文以 Humanizer 的 Fl开发工具上一篇WarcraftHelper让经典魔兽在新系统上焕发第二春的完整指南下一篇WarcraftHelper老铁们必装的魔兽终极兼容神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考