@efs-dt/standard

当前阶段属于内部起步阶段。

一个轻量级的全栈标准工具库。

功能：

• 字节单位转换与网络速率计算工具类。
• ……待开发。

📦 安装

npm install @efs-dt/standard

🚀 快速开始

import { C_ByteUnit } from "@efs-dt/standard";

// 基本单位转换
const terabytes = Math.pow(1000, 4); // 1 TB (SI标准)
const formatted = C_ByteUnit.formatAuto({ bytes: terabytes });
console.log(formatted); // "1.00 TB"

// 网络速率转换
const speed = 100 * Math.pow(1000, 2); // 100 MBps
const speedFormatted = C_ByteUnit.formatSpeedAutoFromBytes(speed);
console.log(speedFormatted); // "100.00 MBps"

📖 C_ByteUnit 类 API 文档

核心方法列表

• bitsToBytes(bits): 将位（bit）转换为字节（Byte）
• bytesToBits(bytes): 将字节（Byte）转换为位（bit）
• isSiNorm(unit): 判断单位是否为 SI 标准（十进制）
• isIecNorm(unit): 判断单位是否为 IEC 标准（二进制）
• isNetBitsSpeed(unit): 判断速率单位是否为 bit 基准
• isNetBytesSpeed(unit): 判断速率单位是否为 Byte 基准
• isValidUnit(unit): 验证单位是否有效
• getAllUnits(): 获取所有有效的字节单位集合
• convertFromBytes(bytes, targetUnit): 将字节数转换为指定单位
• convertToBytes(value, sourceUnit): 从指定单位转换为字节数
• convert(value, sourceUnit, targetUnit): 任意字节单位间转换
• formatAuto(options): 自动选择最合适的单位进行格式化
• formatAs(bytes, targetUnit, toFixed): 格式化为指定单位
• parse(formatted): 解析格式化字符串为字节数
• parseSpeed(formatted): 解析格式化字符串为网络速率（字节/秒）
• percentage(used, usedUnit, total, totalUnit): 计算容量百分比（0~1）
• difference(value1, unit1, value2, unit2, resultUnit, toFixed): 计算两个容量之间的差值
• convertSpeedFromBits(bitsPerSecond, targetUnit): 从比特/秒转换为指定速率单位
• convertSpeedFromBytes(bytesPerSecond, targetUnit): 从字节/秒转换为指定速率单位
• convertSpeedToBits(value, sourceUnit): 任意速率单位转换为比特/秒
• convertSpeedToBytes(value, sourceUnit): 任意速率单位转换为字节/秒
• convertSpeed(value, sourceUnit, targetUnit): 任意速率单位间转换
• formatSpeedAutoFromBits(bitsPerSecond, preferBit): 从 bps 自动格式化速率
• formatSpeedAutoFromBytes(bytesPerSecond, preferBit, toFixed): 从 Bps 自动格式化速率
• formatSpeedAsFromBytes(bytesPerSecond, targetUnit, toFixed): 格式化为指定速率单位
• differenceSpeed(value1, unit1, value2, unit2, resultUnit, toFixed): 计算两个网络速率之间的差值

💡 6 个核心使用示例

import {C_ByteUnit} from "@efs-dt/standard";

// 基本单位转换
// 将 1024 字节转换为千字节（KB）
const result = C_ByteUnit.convertFromBytes(1024, "KB");
console.log(result); // 1.024 (SI标准，1 KB = 1000 Bytes)

// 智能格式化文件大小
const fileSize = 1536 * 1024 * 1024; // 1.5 GiB
const formatted = C_ByteUnit.formatAuto({
  bytes: fileSize,
});
console.log(formatted); // "1.500 GiB"

// 网络速率转换与格式化
// 将 100 Mbps 宽带速度转换为实际下载速度（MBps）
const broadbandMbps = 100;
const downloadSpeedBps = C_ByteUnit.convertSpeedToBytes(broadbandMbps, "Mbps");
const formattedSpeed = C_ByteUnit.formatSpeedAutoFromBytes(downloadSpeedBps);
const customUnitSpeed = C_ByteUnit.convertFromBytes(downloadSpeedBps, "MiB");
// 文件传输速度（MacOS）：12.500 MBps，文件传输速度（Windows）：11.921 MB/s
console.log(
  `文件传输速度（MacOS）：${formattedSpeed}，文件传输速度（Windows）：${customUnitSpeed.toFixed(3)} MB/s`,
);

// 解析用户输入的单位
const userInput = "2.5 GB";
const bytes = C_ByteUnit.parse(userInput);
// "2.5 GB 等于 2500000000 字节"
console.log(`${userInput} 等于 ${bytes} 字节`);

// 计算已用空间占总空间的百分比
const usedSpace = 150 * 1024 * 1024 * 1024; // 150 GiB
const totalSpace = 500 * 1024 * 1024 * 1024; // 500 GiB
const percentage = C_ByteUnit.percentage(usedSpace, "B", totalSpace, "B");
// "使用率: 30.00%"
console.log(`使用率: ${(percentage * 100).toFixed(2)}%`);

// 计算两个容量之间的差值
const total = 1; // 1 GB
const used = 500; // 500 MB
const remaining = C_ByteUnit.difference(total, "GB", used, "MB", "MB");
// "剩余空间: 500 MB"
console.log(`剩余空间: ${remaining} MB`);

📝 重要注意事项

1. SI 与 IEC 标准区别：

   • SI 标准（十进制）：1 KB = 1000 Bytes，用于硬盘厂商标称容量、网络传输
   • IEC 标准（二进制）：1 KiB = 1024 Bytes，一般用于操作系统内存管理、文件大小显示。
     • Windows 磁盘单位命名时采用 SI 标准，但计算时却采用 IEC 标准。
     • MacOS 磁盘单位命名与计算均采用 SI 标准。

2. bit 与 Byte 区别：

   • 1 Byte = 8 bits
   • 网络带宽通常用 bit/s（如 100 Mbps）
   • 文件传输速度通常用 Byte/s（如 12.5 MBps）

3. 精度处理：

   • 浮点数运算可能存在微小误差
   • 建议使用 toFixed() 参数控制显示的小数位数

📄 License

ISC

👤 Author

shadow-abyss