Humanizer 时间跨度人性化策略接口 ITimeSpanHumanizeStrategy 深度解析：方法签名、参数语义与自定义策略实战

开发工具【免费下载链接】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点击查看免费下载ITimeSpanHumanizeStrategy是 Humanizer 中负责把System.TimeSpan转换成人类可读文本的核心抽象。本文以该接口的 API 参考文档为主体结合 接口源码、默认实现、Configurator注册机制与测试用例完整讲解 9 个参数的语义、策略的接入与替换方式并给出自定义策略的实战写法帮助你掌握 Humanizer 时间跨度人性化能力的扩展点。接口定位策略模式下的 TimeSpan 人性化抽象Humanizer 把把TimeSpan变成人话这一行为抽象成了策略接口其设计意图在 ITimeSpanHumanizeStrategy.cs 的注释中写得很明确Defines a strategy for convertingTimeSpanvalues into human-readable text.接口定义本身非常精简只有一个方法namespace Humanizer; public interface ITimeSpanHumanizeStrategy { string Humanize( TimeSpan timeSpan, int precision, bool countEmptyUnits, CultureInfo? culture, TimeUnit maxUnit, TimeUnit minUnit, string? collectionSeparator, bool toWords, bool toSymbols); }之所以采用策略模式是因为人性化是一个高度可定制的行为同样的TimeSpan在不同文化culture、不同精度要求、不同输出风格数字/单词/符号下结果差异巨大。把算法封装进可替换的策略对象既保证了内置默认行为的稳定性又为使用方预留了完全自定义的扩展通道。Humanize 方法签名与 9 个参数详解接口的核心方法Humanize接收一个TimeSpan和 9 个控制参数返回人性化后的字符串。以下逐一说明每个参数的语义与 API 参考文档 一致并补充仓库源码中的默认值与取值范围。timeSpan待转换的时间跨度要人性化的TimeSpan值本身。正值、负值、零值都会进入策略处理逻辑。precision返回的最大时间单位个数类型int含义是最多返回多少个时间单位。默认值为 1即只返回最大单位。例如默认精度下new TimeSpan(2, 3, 4, 5)只输出类似2 days的结果把精度提高到 2才会追加到2 days 3 hours。countEmptyUnits空单位是否计入 precision类型bool。控制值为 0 的中间单位是否占用precision配额。这一点在 TimeSpanHumanizeExtensions.cs 的扩展方法文档中有更精确的表述Controls whether empty time units should be counted towards maximum number of time units. Leading empty time units never count.注意一个重要细节前导leading的空单位永远不计入countEmptyUnits只影响非前导位置的零值单位是否占用精度配额。仓库测试 TimeSpanWithPrecisionAndCountingEmptyUnits 专门覆盖了这一行为差异。culture本地化文化类型CultureInfo?。为null时使用当前线程文化current culture。传入明确文化例如new CultureInfo(zh-CN)或en-US可以让同一TimeSpan在不同语言环境下输出本地化的单位名称。测试 CanSpecifyCultureExplicitly 与 SymbolsUseTheRequestedCulture 验证了显式指定文化的效果。maxUnit 与 minUnit输出单位的上下界两者类型都是TimeUnit。TimeUnit枚举定义在 TimeUnit.cs共 8 个取值按数值从小到大排列枚举值含义Millisecond毫秒Second秒Minute分钟Hour小时Day天Week周Month月Year年maxUnit限定输出中允许出现的最大单位minUnit限定最小单位。TimeSpanHumanizeExtensions的默认值是maxUnit TimeUnit.Week、minUnit TimeUnit.Millisecond。扩展方法 XML 文档还补充了一个重要近似说明TimeSpanHumanizeExtensions.csThe default value isTimeUnit.Week. The time unitsTimeUnit.MonthandTimeUnit.Yearwill give approximations for time spans bigger 30 days by calculating with 365.2425 days a year and 30.4369 days a month.也就是说一旦把maxUnit放宽到Month或Year超过 30 天的跨度将按近似值换算一年按 365.2425 天、一个月按约 30.4369 天。这些常量定义在扩展类顶部const double DaysInAYear 365.2425; // 公历平均年长 const double DaysInAMonth DaysInAYear / 12;测试 Months、Years 与 MonthAndYearRangesIncludeWeeks 对这些换算行为做了大量断言。collectionSeparator多个时间部分的连接符类型string?。当结果包含多个时间单位例如2 days 3 hours时各部分之间用什么分隔。为null时回退到当前文化默认的 collection formatter。扩展方法层的默认值是, 。测试 TimeSpanWithPrecisionAndAlternativeCollectionFormatter 验证了自定义分隔符包括语言本地化分隔符的效果。toWords数字是否用单词呈现类型bool。为true时数字以单词形式输出例如one day而不是1 day。扩展方法文档示例即E.g. one day。测试 TimeSpanWithNumbersConvertedToWords 覆盖此路径。toSymbols单位是否用符号呈现类型bool。为true时时间单位渲染为本地化符号如d、h、m、s而非完整单词。该参数主要由HumanizeToSymbols系列扩展方法置为true传入。相关测试包括 CanUseLocalizedSymbolsWithPrecision、SymbolZeroUsesMinimumUnit 与 SymbolsUseTheRequestedCulture。返回值返回string即人性化后的时间跨度文本。各参数组合最终都会归结为这个字符串结果。派生类型从默认策略到语法格感知策略API 参考文档列出了两个派生关系它们在仓库源码中对应如下DefaultTimeSpanHumanizeStrategy内置默认实现定义在 DefaultTimeSpanHumanizeStrategy.cs是Configurator中注册的默认策略见下文。它的Humanize方法直接委托给扩展类内部的TimeSpanHumanizeExtensions.DefaultHumanize真正的算法核心在DefaultHumanizeCoreTimeSpanHumanizeExtensions.cs。此外该类还提供了HumanizeWithFractionalSeconds虚方法用于秒级以下小数位的输出。IGrammaticalCaseTimeSpanHumanizeStrategy语法格感知扩展定义在 IGrammaticalCaseTimeSpanHumanizeStrategy.cs它继承自ITimeSpanHumanizeStrategy额外增加一个带GrammaticalCase grammaticalCase参数的Humanize重载。其注释说明Optionally extends a time-span humanization strategy with grammatical-case support. ExistingITimeSpanHumanizeStrategyimplementations remain valid for existing duration APIs but cannot serviceHumanizeWithCase.GrammaticalCase枚举定义在 GrammaticalCase.cs包含Nominative、Genitive、Dative、Accusative、Instrumental、Prepositional、Ablative、Comitative、Ergative、Locative、Oblique、Partitive、Vocative等 30 余种语法格。这对于俄语、巴斯克语、芬兰语等格变化丰富的语言尤为重要——同一个时间单位在不同语法格下需要不同的词形。值得注意的两个实现细节DefaultTimeSpanHumanizeStrategy显式实现了IGrammaticalCaseTimeSpanHumanizeStrategy.Humanize且对非 Humanizer 程序集的自定义子类抛出NotSupportedExceptionDefaultTimeSpanHumanizeStrategy.cs要求自定义策略必须显式实现该接口才能获得语法格支持扩展方法HumanizeWithCase在Configurator.TimeSpanHumanizeStrategy不是IGrammaticalCaseTimeSpanHumanizeStrategy时同样抛出NotSupportedExceptionTimeSpanHumanizeExtensions.cs。策略接入点Configurator 注册与扩展方法调用链策略的注册中心是Configurator。在 Configurator.cs 中public static ITimeSpanHumanizeStrategy TimeSpanHumanizeStrategy { get; set; } new DefaultTimeSpanHumanizeStrategy();所有TimeSpanHumanizeExtensions的公开扩展方法Humanize、HumanizeToSymbols、HumanizeWithCase、HumanizeWithFractionalSeconds等最终都会路由到Configurator.TimeSpanHumanizeStrategy.Humanize(...)。以最常用的重载为例TimeSpanHumanizeExtensions.cspublic static string Humanize( this TimeSpan timeSpan, int precision 1, CultureInfo? culture null, TimeUnit maxUnit TimeUnit.Week, TimeUnit minUnit TimeUnit.Millisecond, string? collectionSeparator , , bool toWords false) Configurator.TimeSpanHumanizeStrategy.Humanize( timeSpan, precision, false, culture, maxUnit, minUnit, collectionSeparator, toWords, false);从调用链可以清晰看到公开重载与接口 9 参数签名之间的映射关系countEmptyUnits在无参版本固定为falsetoSymbols固定为false而HumanizeToSymbols则把toSymbols置为true。策略内部按maxUnit → minUnit从大到小分解时间跨度——TimeUnits静态数组正是Enum.GetValuesTimeUnit()的反转结果TimeSpanHumanizeExtensions.cs即从Year到Millisecond依次尝试。实战编写并注册自定义策略基于接口定义可以推断出自定义策略的标准实现骨架。例如实现一个把所有单位名统一转为小写的策略public sealed class LowercaseTimeSpanHumanizeStrategy : ITimeSpanHumanizeStrategy { public string Humanize( TimeSpan timeSpan, int precision, bool countEmptyUnits, CultureInfo? culture, TimeUnit maxUnit, TimeUnit minUnit, string? collectionSeparator, bool toWords, bool toSymbols) Humanizer.TimeSpanHumanizeExtensions .DefaultHumanize(timeSpan, precision, countEmptyUnits, culture, maxUnit, minUnit, collectionSeparator, toWords, toSymbols) .ToLowerInvariant(); }说明DefaultHumanize在仓库中标记为internalTimeSpanHumanizeExtensions.cs因此上面的示例是概念性骨架用于展示接口职责实际自定义策略时要么自行实现分解算法要么基于Configurator.TimeSpanHumanizeStrategy当前实例做包装委托。注册策略只需替换Configurator属性。仓库测试提供了标准的保存—替换—恢复模式参见 FractionalTimeSpanHumanizeTests.csvar originalStrategy Configurator.TimeSpanHumanizeStrategy; try { Configurator.TimeSpanHumanizeStrategy new MyCustomStrategy(); // 在此断言 Humanize 输出 } finally { Configurator.TimeSpanHumanizeStrategy originalStrategy; }注册之后所有TimeSpan扩展方法Humanize、HumanizeToSymbols、HumanizeWithCase等都会自动走新策略。需要特别留意的是如果你的自定义策略要支持HumanizeWithCase必须显式实现IGrammaticalCaseTimeSpanHumanizeStrategy接口若还需要支持HumanizeWithFractionalSeconds则应实现IFractionalTimeSpanHumanizeStrategy定义于 IFractionalTimeSpanHumanizeStrategy.cs扩展方法在 TimeSpanHumanizeExtensions.cs 处做了is IFractionalTimeSpanHumanizeStrategy的类型探测。由于策略是全局单点配置多线程场景下应避免在运行期频繁替换或在替换后尽快恢复。测试验证与行为保证仓库测试为策略行为提供了丰富的契约验证主要集中在 TimeSpanHumanizeTests.cs 与 FractionalTimeSpanHumanizeTests.cs值得关注的核心用例DefaultStrategyPreservesExistingOutputs默认策略必须保持既有输出不变防止回归TimeSpanWithPrecisionAndCountingEmptyUnits验证countEmptyUnits对精度配额的影响TimeSpanWithMinAndMaxUnits_DoesNotReportExcessiveTime验证单位上下界的约束GrammaticalCaseAppliesToEveryPart 与 BasqueUsesAbsolutiveAsItsCitationCase验证语法格作用于输出的每个部分FractionalTimeSpanHumanizeTests.cs 中的策略替换用例验证Configurator.TimeSpanHumanizeStrategy可替换、可恢复以及自定义策略与小数秒 API 的组合行为。这些测试既是自定义策略时的行为参照也是确认策略替换后扩展方法路由是否正确的可靠证据。小结ITimeSpanHumanizeStrategy是 Humanizer 时间跨度人性化能力的核心扩展点9 个参数完整覆盖了精度、空单位计数、文化、单位上下界、分隔符、数字/单词/符号输出等全部维度Configurator.TimeSpanHumanizeStrategy提供了全局替换入口DefaultTimeSpanHumanizeStrategy保证开箱即用的默认行为IGrammaticalCaseTimeSpanHumanizeStrategy与IFractionalTimeSpanHumanizeStrategy则在默认能力之上补充了语法格与小数秒的进阶支持。掌握这个接口就能在 Humanizer 的时间跨度人性化输出上实现任意自定义策略。相关源码与文档路径API 参考文档Humanizer.ITimeSpanHumanizeStrategy.md接口定义ITimeSpanHumanizeStrategy.cs默认实现DefaultTimeSpanHumanizeStrategy.cs语法格扩展接口IGrammaticalCaseTimeSpanHumanizeStrategy.cs公开扩展方法与核心算法TimeSpanHumanizeExtensions.cs策略注册中心Configurator.cs时间单位枚举TimeUnit.cs语法格枚举GrammaticalCase.cs行为测试TimeSpanHumanizeTests.cs、FractionalTimeSpanHumanizeTests.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 小数秒时间跨度人性化策略IFractionalTimeSpanHumanizeStrategy 接口深度解析与自定义实现指南Humanizer 小数秒时间跨度人性化策略IFractionalTimeSpanHumanizeStrategy 接口深度解析与自定义实现指南 导读 当 T开发工具Humanizer 中 IDateOnlyHumanizeStrategy 接口全解析自定义 DateOnly.Humanize 的人性化时间策略Humanizer 中 IDateOnlyHumanizeStrategy 接口全解析自定义 DateOnly.Humanize 的人性化时间策略 本篇指南围开发工具Humanizer 中 IDateTimeOffsetHumanizeStrategy 接口详解自定义 DateTimeOffset.Humanize 日期人性化策略Humanizer 中 IDateTimeOffsetHumanizeStrategy 接口详解自定义 DateTimeOffset.Humanize 日期人开发工具上一篇Improve YouTube!终极YouTube增强扩展90功能全面解析下一篇解剖 Claude Code 的 Plan 子代理提示词一个只读“软件架构师”如何产出实施计划创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考