开发工具【免费下载链接】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 的ByteSizeExtensions静态扩展类展开它是一组面向ByteSize值与各基础数值类型的扩展方法覆盖数值 → 字节量位/字节/KB/MB/GB/TB/PB/EB/PiB的工厂式转换、字节量 → 可读文本的人性化格式化支持格式字符串、本地化与多部分复合输出、显式单位制Legacy / DecimalSi / BinaryIec控制以及基于时间间隔的传输速率ByteRate计算。读完本文你将掌握 Humanizer 中字节处理的全部扩展 API 及其底层实现原理能够直接在 .NET 项目中把原始字节数优雅地展示为2 GB、10 KB 2 B、4 MB/s这类人类友好的文本。一、类概览ByteSizeExtensions 的设计定位在 Humanizer.ByteSizeExtensions.cs 中ByteSizeExtensions被定义为一个public static class继承自System.Object官方 API 文档Humanizer.ByteSizeExtensions.md对其的说明是Provides extension methods for ByteSize为 ByteSize 提供扩展方法它的方法可分为四大族方法族代表方法职责量值构造族Bits()、Bytes()、Kilobytes()…Exabytes()、Pebibytes()把基础数值类型包装为ByteSize值基础人性化Humanize()把ByteSize渲染为带最大合适单位的单段文本复合人性化HumanizeComposite()、HumanizeCompositeWithUnitSystem()按降序单位输出多段文本如10 KB 2 B显式单位制HumanizeWithUnitSystem()用明确指定的 SI/IEC/Legacy 单位制渲染速率计算Per()把字节量配以时间间隔构成ByteRate速率从源码结构看构造族方法全部是薄封装——它们直接委托给ByteSize的静态工厂方法如ByteSize.FromBits、ByteSize.FromTerabytes例如public static ByteSize Bits(this int input) ByteSize.FromBits(input); public static ByteSize Terabytes(this long input) ByteSize.FromTerabytes(input);二、量值构造族从数值到 ByteSizeByteSize是一个以字节为内部度量的结构体源码见 ByteSize.cs其Bits属性按long保存位总数Bytes以double保存字节数。构造族扩展方法让用数值直接写出大小成为可能。2.1 Bits把输入视为位Bits(this byte | sbyte | short | ushort | int | uint | long)共 7 个重载均返回ByteSize语义为将输入视为比特数public static ByteSize Bits(this byte input); public static ByteSize Bits(this int input); public static ByteSize Bits(this long input); // ... 其余为 sbyte / short / ushort / uint 重载注意Bits不提供double重载——位是离散单元一律走ByteSize.FromBits(long)其实现为new(value / (double)BitsInByte)即先换算成字节再向上取整存储Bits属性带Math.Ceiling因为位是整数单位。2.2 Bytes把输入视为字节Bytes(this byte | sbyte | short | ushort | int | uint | double | long)共 8 个重载语义为将输入视为字节数。它是唯一同时提供double重载的基础单位方法public static ByteSize Bytes(this double input); // 支持小数字节 public static ByteSize Bytes(this long input);2.3 倍数单位Kilobytes 到 ExabytesKilobytes()、Megabytes()、Gigabytes()、Terabytes()、Petabytes()、Exabytes()各自提供byte | sbyte | short | ushort | int | uint | double | long8 个重载。需要特别留意的是这些传统倍数单位在 Humanizer 中遵循混合换算规则见 ByteSize.cs 中的常量定义public const long BytesInKilobyte 1024; public const long BytesInMegabyte 1048576; // 1024² public const long BytesInGigabyte 1073741824; // 1024³ public const long BytesInTerabyte 1099511627776; // 1024⁴ public const long BytesInPetabyte 1000000000000000; // 1000⁵十进制 public const long BytesInExabyte 1000000000000000000; // 1000⁶十进制也就是说从 KB 到 TB 按 1024 进制实际是二进制换算而 PB、EB 按 1000 进制十进制换算。这正是ByteSizeUnitSystem.Legacy旧版兼容混合单位制的来历具体见后文显式单位制一节。2.4 二进制 IEC 单位PebibytesPebibytes()是构造族中唯一的 IEC 单位扩展提供 8 个重载对应ByteSize.FromPebibytesBytesInPebibyte 1125899906842624即 1024⁵。与之配套ByteSize内部还提供FromKibibytes/FromMebibytes/FromGibibytes/FromTebibytes等工厂以及Kibibytes/Mebibytes/Gibibytes/Tebibytes只读属性供需要严格二进制换算的场景使用。2.5 构造族的测试验证ByteSizeExtensionsTests.cs 对每个数值类型逐一验证构造族与工厂方法的等价性例如[Fact] public void IntTerabytes() { const int size 2; Assert.Equal(ByteSize.FromTerabytes(size), size.Terabytes()); }三、Humanize单段人性化格式化Humanize把ByteSize值渲染为最大合适单位 单位符号的单段文本例如2 GB。它有三个重载public static string Humanize(this ByteSize input, string? format null); public static string Humanize(this ByteSize input, IFormatProvider formatProvider); public static string Humanize(this ByteSize input, string? format, IFormatProvider? formatProvider);3.1 参数与默认行为format数字部分使用的 .NET 数值格式字符串可空默认null等价于通用格式G。也可以直接指定单位 token如KB、MB让输出强制停留在该单位而不自动升格。formatProvider用于本地化数字与单位文本的IFormatProvider可空传null时使用当前线程文化。源码实现非常直白见 ByteSizeExtensions.cspublic static string Humanize(this ByteSize input, string? format null) string.IsNullOrWhiteSpace(format) ? input.ToString() : input.ToString(format); public static string Humanize(this ByteSize input, IFormatProvider formatProvider) input.ToString(formatProvider); public static string Humanize(this ByteSize input, string? format, IFormatProvider? formatProvider) string.IsNullOrWhiteSpace(format) ? input.ToString(formatProvider) : input.ToString(format, formatProvider);也就是说Humanize本质是ByteSize.ToString的扩展包装未提供格式时直接调用无格式ToString()内部走GetLargestWholeNumberSymbol自动选择最大的整数值 ≥ 1单位依次考察 EB → PB → TB → GB → MB → KB → B → b见 ByteSize.cs 中GetLargestWholeNumberSymbol的实现并通过Configurator.GetFormatter(culture)获取当前文化的 formatter 完成单位词的本地化。3.2 单位本地化效果测试用例展示了同一数值在不同文化下的输出差异输入表达式文化输出2.Terabytes().Humanize()en2 TB2.Terabytes().Humanize()fr2 To2.Gigabytes().Humanize()fr2 Go2.Megabytes().Humanize()fr2 Mo2.Kilobytes().Humanize()fr2 Ko2.Bytes().Humanize()fr2 o可见单位符号随文化本地化法语中 TB→To、GB→Go、MB→Mo、KB→Ko、B→o而bits输出在法语中仍是b。3.3 格式字符串的实战用法测试 ByteSizeExtensionsTests.cs 给出了大量可复制的格式示例// 数字格式控制精度 2.123.Gigabytes().Humanize(#.##) // 2.12 GB 2.123.Gigabytes().Humanize(#) // 2 GB // 指定单位 token强制固定单位输出 2.Gigabytes().Humanize(MB) // 2048 MB2 GB 2048 MB 2.Megabytes().Humanize(KB) // 2048 KB 10000000.Bytes().Humanize(KB) // 9765.63 KB // 数字格式与单位 token 组合含千分位 10000000.Bytes().Humanize(#,##0 KB) // 9,766 KB 10000000.Bytes().Humanize(#,##0.# KB) // 9,765.6 KB // 位输入 12.Bits().Humanize(B) // 1.5 B 10000.Bits().Humanize(#.# KB) // 1.2 KB注意当仅传入数字格式无单位 token时Humanizer 仍会按数值大小自动选择最合适的单位当传入单位 token 时输出锁定为该单位。零值的默认输出为0 b即0.Bytes().Humanize()→0 b。四、HumanizeComposite多段降序复合输出HumanizeComposite把字节量拆分为从大到小、逐级降序的多段非零单位例如10 KB 2 Bpublic static string HumanizeComposite( this ByteSize input, int precision 2, IFormatProvider? formatProvider null, string separator , bool toWords false);4.1 参数语义参数类型默认值说明precisionint2最多返回的非零部分数量 1时抛ArgumentOutOfRangeExceptionformatProviderIFormatProvider?null格式化各数字部分的 providernull时使用当前文化separatorstring 各部分之间的分隔符传null时抛ArgumentNullExceptiontoWordsboolfalse为true时使用单位单词如bytes而非符号如B4.2 实现原理与输出规则从 ByteSizeExtensions.cs 的实现看算法按以下顺序逐个考察单位Exabyte → Petabyte → Terabyte → Gigabyte → Megabyte → Kilobyte → Byte → Bit用整数除法求出每段的数量并累减余数直到段数达到precision或余数为零。核心行为包括零值返回0 b或按toWords输出0 bit的本地化形式。非零单位才输出若某级商为 0 则跳过因此precision限制的是非零段数量而非固定段数。负值整个结果只带一个负号前缀且负号取自NumberFormatInfo.NegativeSign可通过自定义NumberFormatInfo覆盖例如把-换成~见HumanizesNegativeCompositeValuesWithOneLeadingSign测试。位余数精确保留剩余的 bit 数会被单独输出例如ByteSize.FromBits(81937).HumanizeComposite(3)→10 KB 2 B 1 b。4.3 实战示例来自测试用例10242.Bytes().HumanizeComposite(); // 10 KB 2 B 10242.Bytes().HumanizeComposite(separator: , , toWords: true); // 10 kilobytes, 2 bytes // precision 限制非零段数量 var input ByteSize.FromBytes(ByteSize.BytesInMegabyte ByteSize.BytesInKilobyte 1); input.HumanizeComposite(1); // 1 MB input.HumanizeComposite(2); // 1 MB 1 KB input.HumanizeComposite(3); // 1 MB 1 KB 1 B // 边界与本地化 1023.Bytes().HumanizeComposite(); // 1023 B 1024.Bytes().HumanizeComposite(); // 1 KB (-10242).Bytes().HumanizeComposite(); // -10 KB 2 B input.HumanizeComposite(3, new CultureInfo(fr)); // 1 Mo 1 Ko 1 o input.HumanizeComposite(3, separator: , , toWords: true); // 1 megabyte, 1 kilobyte, 1 byte // 异常验证 1.Bytes().HumanizeComposite(0); // ArgumentOutOfRangeExceptionprecision 1 1.Bytes().HumanizeComposite(-1); // ArgumentOutOfRangeException 1.Bytes().HumanizeComposite(separator: null!); // ArgumentNullException五、显式单位制ByteSizeUnitSystem 与两个 WithUnitSystem 方法5.1 ByteSizeUnitSystem 枚举定义见 ByteSizeUnitSystem.cs用于为显式解析与格式化 API 选择单位制成员值语义Legacy0Humanizer 传统混合单位KB–TB 按 1024 进制PB、EB 按 1000 进制DecimalSi1十进制 SI 单位相邻单位之间为 1000 倍kB、MB、GB、TB、PB、EBBinaryIec2二进制 IEC 单位相邻单位之间为 1024 倍KiB、MiB、GiB、TiB、PiB关于符号匹配枚举的 XML 文档明确说明对于DecimalSi和BinaryIecSI/IEC 前缀单位 token 按大小写不敏感匹配但bbit与Bbyte始终大小写敏感格式化输出统一使用规范符号大小写Legacy保留既有匹配行为。5.2 HumanizeWithUnitSystempublic static string HumanizeWithUnitSystem( this ByteSize input, ByteSizeUnitSystem unitSystem, string? format null, IFormatProvider? formatProvider null);语义使用明确指定的单位制把字节量渲染为单段人性化文本。实现为unitSystem ByteSizeUnitSystem.Legacy ? input.Humanize(format, formatProvider) // 传统行为 : input.Format(unitSystem, format, formatProvider); // SI/IEC 显式路径其中ByteSize.Format(unitSystem, format, formatProvider)见 ByteSize.cs 中Format与FormatWithUnitSystem的实现会先校验单位制合法性再在对应单位表中查找显式 tokenFindFormatUnit若未指定 token则按当前单位制的进制基数DecimalSi 为 1000BinaryIec 为 1024从低到高自动升级单位直到显示值小于进制基数。抛ArgumentOutOfRangeExceptionunitSystem不是已定义成员。抛FormatExceptionformat无效或选择的 token 不为所选非 Legacy 单位制支持。ByteSize.FromBytes(2048).HumanizeWithUnitSystem(ByteSizeUnitSystem.DecimalSi); // 2 kB1000 进制 ByteSize.FromBytes(2048).HumanizeWithUnitSystem(ByteSizeUnitSystem.BinaryIec); // 2 KiB1024 进制注意 DecimalSi 的小写k复合单位表中 DecimalSi 使用的符号是kBDecimalCompositeUnits数组中声明为kB而 BinaryIec 使用KiB。5.3 HumanizeCompositeWithUnitSystempublic static string HumanizeCompositeWithUnitSystem( this ByteSize input, ByteSizeUnitSystem unitSystem, int precision 2, IFormatProvider? formatProvider null, string separator , bool toWords false);语义使用一个明确的单位制输出多段复合文本。与HumanizeComposite的区别在于单位表Legacy 沿用 KB→TB1024混合 PB/EB1000的降序单位DecimalSi 使用EB → PB → TB → GB → MB → kBBinaryIec 使用PiB → TiB → GiB → MiB → KiB。toWords true时使用本地化的单位单词经由内置 formatter 的DataUnitHumanizeExact。异常规则与前面一致unitSystem未定义或precision 1→ArgumentOutOfRangeExceptionseparator为null→ArgumentNullException。零值在toWordsfalse时输出0 b。六、Per构建传输速率 ByteRatePer是 ByteSizeExtensions 中唯一的跨类型扩展public static ByteRate Per(this ByteSize size, TimeSpan interval);它将字节量 时间间隔组合为一个ByteRate对象源码见 ByteRate.cs支持IComparableByteRate/IEquatableByteRate比较与相等性均基于归一化后的每秒字节数BytesPerSecond并区分运行时类型。ByteSize.FromBytes(400).Per(TimeSpan.FromSeconds(1)).Humanize(); // 400 B/s ByteSize.FromBytes(4 * 1024).Per(TimeSpan.FromSeconds(1)).Humanize(); // 4 KB/s6.1 ByteRate.Humanize 的时间单位ByteRate.Humanize(TimeUnit timeUnit TimeUnit.Second)支持秒/分钟/小时三种显示时间单位TimeUnit.Minute输出min、TimeUnit.Hour输出h其他TimeUnit值如Millisecond、Day、Month、Week、Year会抛NotSupportedExceptionByteSize.FromMegabytes(1).Per(TimeSpan.FromSeconds(60)).Humanize(TimeUnit.Minute); // 1 MB/min ByteSize.FromMegabytes(1).Per(TimeSpan.FromSeconds(60*60)).Humanize(TimeUnit.Hour); // 1 MB/h另有Humanize(format, timeUnit, culture)重载支持数字格式与文化以及HumanizeWithUnitSystem(unitSystem, format, timeUnit, culture)支持显式单位制下的速率输出内部用BigInteger做有理数取整保证大位数值的精确缩放测试ExplicitUnitSystemsPreserveExactIdentityAndIntegralBitScaling验证了long.MaxValue位数的精确性。6.2 速率测试佐证ByteRateTests.cs 中的典型断言[InlineData(15 * 60 * 1024 * 1024, 60, 15 MB/s)] // 15 分钟传 15 MB → 15 MB/s [InlineData(4 * 1024, 0.1, 40 KB/s)] // 4 KB 用 0.1 秒 → 40 KB/s ByteSize.FromBytes(400).Per(TimeSpan.FromSeconds(1)).ToString(); // 400 B/s七、速查表ByteSizeExtensions 全部方法签名下表汇总本文涉及的公开方法完整签名与文档见 Humanizer.ByteSizeExtensions.md方法重载数量返回类型关键参数/默认值Bits(this byte/sbyte/short/ushort/int/uint/long)7ByteSize视输入为位Bytes(this byte/sbyte/short/ushort/int/uint/double/long)8ByteSize视输入为字节Kilobytes/Megabytes/Gigabytes/Terabytes/Petabytes/Exabytes(...)各 8ByteSize同上 8 种数值类型Pebibytes(...)8ByteSize1024⁵ 进制Humanize(this ByteSize, string? format null)1string单段格式化Humanize(this ByteSize, IFormatProvider)1string指定 providerHumanize(this ByteSize, string?, IFormatProvider?)1string格式 providerHumanizeWithUnitSystem(this ByteSize, ByteSizeUnitSystem, string? null, IFormatProvider? null)1string显式单位制HumanizeComposite(this ByteSize, int precision2, IFormatProvider?null, string separator , bool toWordsfalse)1string多段复合输出HumanizeCompositeWithUnitSystem(this ByteSize, ByteSizeUnitSystem, int precision2, IFormatProvider?null, string separator , bool toWordsfalse)1string显式单位制复合输出Per(this ByteSize, TimeSpan)1ByteRate构造传输速率八、实践建议与注意事项默认输出用Humanize()即可不传格式时自动选择最大整数单位并随当前文化本地化需要固定单位时传单位 token如MB但要注意它表达的是强制显示为该单位数值会被换算2.Gigabytes().Humanize(MB)→2048 MB。多段展示用HumanizeComposite适合下载大小、磁盘占用等希望同时看到大单位 余数的场景precision控制段数toWords控制符号/单词separator可自定义如中文环境用全角空格或顿号。严格单位制场景用HumanizeWithUnitSystem/HumanizeCompositeWithUnitSystemByteSizeUnitSystem.DecimalSi遵循 1000 进制、BinaryIec遵循 1024 进制适合对单位语义有明确规范的存储/网络产品Legacy用于保持与旧版本一致的输出。速率场景用PerByteRate支持秒/分/时三种展示单位Humanize()默认输出X/s形式。异常处理复合类方法在precision 1时抛ArgumentOutOfRangeExceptionseparator传null抛ArgumentNullException显式单位制方法在传入未定义的ByteSizeUnitSystem时抛ArgumentOutOfRangeException非法格式 token 抛FormatException。以上内容所引用的实现与测试均可在仓库对应文件中复核扩展方法实现见 ByteSizeExtensions.cs核心类型与格式化逻辑见 ByteSize.cs 与 ByteSizeUnitSystem.cs速率类型见 ByteRate.cs行为验证见 ByteSizeExtensionsTests.cs 与 ByteRateTests.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.ByteSize 完全指南.NET 字节数量的人性化格式化、解析与单位制选择Humanizer.ByteSize 完全指南.NET 字节数量的人性化格式化、解析与单位制选择 ByteSize 是 Humanizer 中用于表达字节数量开发工具深入理解 Humanizer 的 ByteSizeUnitSystem显式字节单位体系的解析与格式化指南深入理解 Humanizer 的 ByteSizeUnitSystem显式字节单位体系的解析与格式化指南 本文围绕 Humanizer 中 ByteSizeU开发工具NocoBase 模板打印时间间隔格式化:formatI 语法、单位换算与人性化输出完全指南NocoBase 模板打印时间间隔格式化:formatI 语法、单位换算与人性化输出完全指南 时间间隔时长格式化是业务单据打印中最高频的需求之一工单耗时低代码后端前端人工智能AI 应用工作流自动化上一篇如何快速找回加密压缩包密码终极自动化测试指南下一篇5分钟掌握StreamFX从直播小白到专业主播的蜕变之路创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考