开发工具【免费下载链接】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点击查看免费下载导读本文围绕 Humanizer2.14.1 版本 API中Humanizer.Localisation.ResourceKeys.TimeSpanHumanize这个静态类展开讲解它如何为TimeSpan.Humanize()生成符合约定的资源键Resource Key如TimeSpanHumanize_SingleMinute并深入剖析该资源键在源码中与TimeUnit枚举、IFormatter接口和DefaultFormatter实现之间的调用关系。读完本文你将掌握 Humanizer 时长本地化的资源键命名约定、GetResourceKey(TimeUnit, int, bool)三个参数各自的作用与默认值以及如何通过自定义 Formatter 参与这一机制的扩展方式。ResourceKeys.TimeSpanHumanize 是什么在 Humanizer 2.14.1 的Humanizer.Localisation命名空间下存在一组用于按约定生成资源键的静态类ResourceKeys.TimeSpanHumanize是其中之一专门服务于TimeSpan.Humanize()时长人性化显示功能。对应 API 文档位于 Humanizer.Localisation.ResourceKeys.TimeSpanHumanize.md其定义如下public static class ResourceKeys.TimeSpanHumanize该类封装了获取 TimeSpan.Humanize 资源键所需的逻辑Encapsulates the logic required to get the resource keys for TimeSpan.Humanize本身继承自System.Object是一个不包含实例状态的静态工具类。与之并列的还有 ResourceKeys.DateHumanize服务于DateTime.Humanize()约定如DateHumanize_SingleMinuteAgo以及容器类 ResourceKeys。资源键在整个本地化架构中的位置从源码结构看资源键是 Humanizer 本地化管线中的中间产物调用方如TimeSpanHumanizeExtensions把时长拆解为时间单位 数量通过ResourceKeys.TimeSpanHumanize.GetResourceKey(...)之类的入口得到形如TimeSpanHumanize_SingleMinute的键名该键名再被映射到当前文化culture对应的本地化字符串minute、分钟 等。也就是说ResourceKeys系列类约定的是键的命名规范而实际文案则来自语言资源。这正是DefaultFormatter等 Formatter 实现所消费的数据——详见下文与 IFormatter 的协作一节。GetResourceKey(TimeUnit, int, bool) 方法签名与参数语义ResourceKeys.TimeSpanHumanize只公开了一个核心方法GetResourceKey完整签名如下public static string GetResourceKey(Humanizer.Localisation.TimeUnit unit, int count 1, bool toWords false);三个参数的含义均来自 API 文档原文分别是参数类型默认值语义unitTimeUnit无必填时间单位取自Humanizer.Localisation.TimeUnit枚举countSystem.Int321单位数量默认是 1OnetoWordsSystem.Booleanfalse结果是否以单词words形式呈现默认 false方法的返回值是System.String即资源键本身例如文档给出的示例TimeSpanHumanize_SingleMinute。TimeUnit可用的时间单位集合unit参数来自 TimeUnit.cs 中定义的枚举包含 8 个成员它们是 Humanizer 所有相对时间/时长格式化含DateHumanize与TimeSpanHumanize共用的单位体系public enum TimeUnit { Millisecond, // 一毫秒 Second, // 一秒 Minute, // 一分钟 Hour, // 一小时 Day, // 一天 Week, // 一周 Month, // 一个月 Year // 一年 }count 与 toWords 如何影响键的生成虽然GetResourceKey的文档没有给出完整的键名组合规则但从其示例键TimeSpanHumanize_SingleMinute可以推断出命名约定的三个组成部分前缀固定为TimeSpanHumanize_用于标识该键属于时长人性化输出数量形态count 1时使用Single段count ! 1复数场景时按约定应使用Multiple段对应资源中单复数两套文案单位名称直接采用TimeUnit枚举成员的名称如Minute、Hour、Day等。toWords参数则控制数量的呈现方式为false时数量以数字形式拼入文案如 1 minute为true时数量会以单词形式呈现如 one minute。这一开关会贯穿到 Formatter 的文案选择中下文结合DefaultFormatter的实现会看到SingleWordsVariant/MultipleWordsVariant这类单词变体资源的存在。从资源键到本地化文案DefaultFormatter 的实现印证在 2.14.1 的源码中资源键约定最终落实为IFormatter接口与DefaultFormatter实现的调用关系。接口 IFormatter.cs 中与时长相关的成员定义如下string TimeSpanHumanize_Zero(); // 零时长文案如 no time string TimeSpanHumanize(TimeUnit timeUnit, int unit, bool toWords false); string TimeSpanHumanize_Age(); // 年龄后缀格式接口方法名TimeSpanHumanize_Zero、TimeSpanHumanize_Age恰好延续了TimeSpanHumanize_前缀 语义段的键命名风格说明ResourceKeys的约定在整个 Formatter 层是前后一致的。在 DefaultFormatter.cs 中TimeSpanHumanize(TimeUnit, int, bool)的实现会查询当前文化对应的LocalePhraseTable由源码生成器从 Locales/*.yml 语言目录生成并依据单复数选择资源public virtual string TimeSpanHumanize(TimeUnit timeUnit, int unit, bool toWords false) TryFormatTimeSpanFromPhraseTable(timeUnit, unit, toWords, out var result) ? result : throw new InvalidOperationException(...);在FormatTimeSpanPhrase内部count 1时优先取phrase.Single若toWords true则优先取SingleWordsVariant否则取phrase.MultipletoWords时优先MultipleWordsVariant——这与GetResourceKey中count默认 1、toWords默认 false 的语义一一对应默认生成单数、数字形态的资源键只有显式传参才会切换到复数或单词形态。TimeSpan.Humanize 的调用链资源键的消费现场ResourceKeys.TimeSpanHumanize约定的键名最终服务于 TimeSpanHumanizeExtensions.cs 中的TimeSpan.Humanize()系列扩展方法。其核心调用链可以概括为拆解时长CreatePrecisionLimitedTimeParts遍历TimeUnit各成员TimeUnits数组把TimeSpan拆成单位 数量的元组并通过maxUnit/minUnit/precision参数限制输出范围见 TimeSpanHumanizeExtensions.cs获取 FormatterConfigurator.GetFormatter(culture)依据当前文化解析出对应的IFormatter实现生成文案调用cultureFormatter.TimeSpanHumanize(timeUnit, amount, toWords)见 TimeSpanHumanizeExtensions.cs当 Formatter 同时实现了IGrammaticalCaseTimeSpanFormatter且指定了语法格grammatical case时还会走caseFormatter.TimeSpanHumanize(...)的重载见 TimeSpanHumanizeExtensions.cs零值兜底当所有单位数量都为 0 且要求toWords输出时调用TimeSpanHumanize_Zero()返回如 no time 的零时长文案见 TimeSpanHumanizeExtensions.cs。可见GetResourceKey所体现的单位 数量 是否单词三元组正是整条时长人性化链路最核心的三个输入维度。扩展与自定义如何接入这套约定ResourceKeys.TimeSpanHumanize的价值不仅在于内置文案还在于它为自定义 Formatter提供了统一的键命名基线。基于源码结构可以给出两条可行的扩展路径自定义 IFormatter 实现实现 IFormatter.cs 中的TimeSpanHumanize等方法并通过Configurator的 Formatter 注册机制对应 Formatters 目录与FormatterRegistry按文化替换默认行为沿用资源键约定组织自己的文案表在自定义资源中让键名严格遵循TimeSpanHumanize_Single{Unit}/TimeSpanHumanize_Multiple{Unit}的命名{Unit}取TimeUnit枚举名即可与内置约定无缝对齐避免维护两套命名体系。版本演进提示需要说明的是ResourceKeys这类以Humanizer.Localisation命名空间暴露的类型是 2.x 时代的产物。根据仓库内的迁移文档 version-3-migration.mdx 记载Humanizer.Configuration与Humanizer.Localisation命名空间在 3.x 中被并入Humanizer而Resources/ResourceKeys在 3.0.10 之前仍保留其移除属于未来main/preview的迁移边界。因此如果你的项目仍停留在 2.14.1本文描述的Humanizer.Localisation.ResourceKeys.TimeSpanHumanize即为准确入口若升级到 3.x则相应类型会以Humanizer.ResourceKeys.TimeSpanHumanize的形式继续存在可对照 version-3.0.10 的 API 文档命名空间前缀发生了变化但键名约定与参数语义保持不变。小结ResourceKeys.TimeSpanHumanize.GetResourceKey(TimeUnit, int, bool)是 Humanizer 时长本地化的键名生成器它把时间单位、数量默认 1和是否单词输出默认 false三个维度编码进形如TimeSpanHumanize_SingleMinute的资源键中与TimeUnit枚举、IFormatter/DefaultFormatter的实现以及TimeSpan.Humanize()的完整调用链形成闭环。理解这套约定既能帮你读懂 Humanizer 的本地化源码也能指导你在自定义 Formatter 或资源文案时保持与官方命名体系的一致。赞分享开发工具【免费下载链接】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 资源键机制解析深入 ResourceKeys.TimeSpanHumanize 与 TimeSpan.Humanize 的本地化约定Humanizer 资源键机制解析深入 ResourceKeys.TimeSpanHumanize 与 TimeSpan.Humanize 的本地化约定 本篇开发工具Humanizer 资源键ResourceKeys机制解析TimeSpan.Humanize 本地化资源定位原理Humanizer 资源键ResourceKeys机制解析TimeSpan.Humanize 本地化资源定位原理 导读 Humanizer 的 TimeS开发工具Humanizer 本地化资源键机制解析ResourceKeys.TimeSpanHumanize 与 GetResourceKey 深入指南Humanizer 本地化资源键机制解析ResourceKeys.TimeSpanHumanize 与 GetResourceKey 深入指南 Resourc开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考