数字工具 (Number)

@pt/utils/modules/number 提供了数字处理相关的工具函数。

formatNumber

格式化数字（千分位）。

import { formatNumber } from '@pt/utils/modules/number';

formatNumber(1234567.89, {
  decimals: 2,
  decimalSeparator: '.',
  thousandsSeparator: ','
}); // '1,234,567.89'

formatCurrency

格式化货币。

import { formatCurrency } from '@pt/utils/modules/number';

formatCurrency(1234.56, {
  currency: 'CNY',
  locale: 'zh-CN',
  decimals: 2
}); // '¥1,234.56'

random

生成随机数。

import { random } from '@pt/utils/modules/number';

random(1, 10); // 生成1-10之间的整数
random(1, 10, false); // 生成1-10之间的浮点数

clamp

限制数字在指定范围内。

类型签名：

function clamp(num: number, min: number, max: number): number

参数：

• num: 要限制的数字
• min: 最小值
• max: 最大值

示例：

import { clamp } from '@pt/utils/modules/number';

clamp(5, 0, 10); // 5
clamp(-5, 0, 10); // 0
clamp(15, 0, 10); // 10
clamp(7.5, 0, 10); // 7.5

randomNum

生成指定范围内的随机整数。

类型签名：

function randomNum(min: number, max: number): number

参数：

• min: 最小值
• max: 最大值

示例：

import { randomNum } from '@pt/utils/modules/number';

randomNum(1, 100); // 生成 1-100 之间的随机整数

transformNumberUnit

将较大的数字转换为带单位的格式（K、M、B、T、P）。

类型签名：

function transformNumberUnit(data?: string | number): string

参数：

• data: 要转换的数字

单位说明：

• K: 千（1,000）
• M: 百万（1,000,000）
• B: 十亿（1,000,000,000）
• T: 万亿（1,000,000,000,000）
• P: 千万亿（1,000,000,000,000,000）

示例：

import { transformNumberUnit } from '@pt/utils/modules/number';

transformNumberUnit(0); // '0'
transformNumberUnit(999); // '999'
transformNumberUnit(1000); // '1K'
transformNumberUnit(1500); // '1.5K'
transformNumberUnit(1000000); // '1M'
transformNumberUnit(1234567); // '1.23M'
transformNumberUnit(1000000000); // '1B'

formatBytes

将字节数格式化为人类可读的文件大小格式。

类型签名：

function formatBytes(bytes: number, decimals?: number): string

参数：

• bytes: 字节数
• decimals: 小数位数，默认 2

示例：

import { formatBytes } from '@pt/utils/modules/number';

formatBytes(1024); // '1.00 KB'
formatBytes(1234); // '1.21 KB'
formatBytes(123456789); // '117.74 MB'
formatBytes(1234567890123456); // '1.10 PB'
formatBytes(1024, 0); // '1 KB'

transformFileSize

转换文件大小（简化版本）。

类型签名：

function transformFileSize(bytes?: number): string | number

参数：

• bytes: 字节数

返回值：

• 小于 1MB: 返回 KB 格式
• 1MB - 1GB: 返回 MB 格式
• 大于 1GB: 返回 GB 格式
• undefined: 返回 0

示例：

import { transformFileSize } from '@pt/utils/modules/number';

transformFileSize(512); // '0.50 KB'
transformFileSize(100); // '0.01 KB' (最小显示 0.01 KB)
transformFileSize(1024 * 1024); // '1.00 MB'
transformFileSize(1024 * 1024 * 1024); // '1.00 GB'
transformFileSize(undefined); // 0

使用场景示例

文件上传进度显示

import { formatBytes } from '@pt/utils/modules/number';

function showUploadProgress(loaded: number, total: number) {
  const progress = (loaded / total) * 100;
  const loadedSize = formatBytes(loaded);
  const totalSize = formatBytes(total);
  
  console.log(`上传进度: ${progress.toFixed(1)}% (${loadedSize} / ${totalSize})`);
  // 输出: 上传进度: 45.2% (452.34 MB / 1.00 GB)
}

数据统计展示

import { transformNumberUnit } from '@pt/utils/modules/number';

function showStatistics(views: number, likes: number) {
  return {
    views: transformNumberUnit(views),
    likes: transformNumberUnit(likes)
  };
}

showStatistics(1234567, 89012);
// { views: '1.23M', likes: '89.01K' }

价格显示

import { formatCurrency } from '@pt/utils/modules/number';

function displayPrice(price: number, currency: string = 'CNY') {
  return formatCurrency(price, { currency });
}

displayPrice(99.99); // '¥99.99'
displayPrice(99.99, 'USD'); // '$99.99'