@zjlab-frontier/utils 使用说明文档

包名：@zjlab-frontier/utils
功能亮点：提供常用的工具函数集合，包括文件处理、日期格式化、深拷贝、防抖节流、验证函数等实用工具。

📦 安装

npm install @zjlab-frontier/utils

🚀 快速开始

1. 引入工具函数

import { formatFileSize, calculateFileHash, formatDate } from '@zjlab-frontier/utils';

2. 基本使用示例

// 格式化文件大小
const fileSize = formatFileSize(1024 * 1024 * 2.5); // 返回: "2.50 MB"

// 计算文件哈希
const fileInput = document.getElementById('fileInput') as HTMLInputElement;
fileInput.addEventListener('change', async (e) => {
  if (e.target.files && e.target.files[0]) {
    const hash = await calculateFileHash(e.target.files[0]);
    console.log('File hash:', hash);
  }
});

// 格式化日期
const formattedDate = formatDate(new Date(), 'YYYY-MM-DD'); // 返回当前日期，如: "2024-01-01"

📋 功能函数列表

文件相关

calculateFileHash(file: File): Promise<string>

• 功能：计算文件的MD5哈希值
• 参数：file - 要计算哈希的文件对象
• 返回值：Promise - 文件的MD5哈希值

formatFileSize(sizeInBytes: number, decimalPlaces?: number): string

• 功能：将文件大小从字节转换为合适的单位（B、KB、MB、GB、TB）
• 参数：
  • sizeInBytes - 文件大小（字节）
  • decimalPlaces - 保留的小数位数，默认为 2
• 返回值：转换后的文件大小字符串，如 "2.50 MB"

时间日期

formatDate(date: Date | number | string, format?: string): string

• 功能：格式化日期时间
• 参数：
  • date - 日期对象、时间戳或日期字符串
  • format - 格式化模板，默认为 'YYYY-MM-DD HH:mm:ss'
• 返回值：格式化后的日期时间字符串
• 支持的格式占位符：YYYY, MM, DD, HH, mm, ss

delay(ms: number): Promise<void>

• 功能：延迟指定毫秒数
• 参数：ms - 延迟毫秒数
• 返回值：Promise

对象处理

deepClone<T>(obj: T): T

• 功能：深拷贝对象
• 参数：obj - 要拷贝的对象
• 返回值：拷贝后的新对象
• 支持：普通对象、数组、Date对象

函数工具

throttle<T extends (...args: any[]) => any>(func: T, wait: number): ((...args: Parameters<T>) => void)

• 功能：节流函数 - 控制函数在指定时间内最多执行一次
• 参数：
  • func - 要节流的函数
  • wait - 等待时间（毫秒）
• 返回值：节流后的函数

debounce<T extends (...args: any[]) => any>(func: T, wait: number): ((...args: Parameters<T>) => void)

• 功能：防抖函数 - 延迟函数执行，直到一段时间内不再触发
• 参数：
  • func - 要防抖的函数
  • wait - 等待时间（毫秒）
• 返回值：防抖后的函数

随机数与验证

randomNumber(min: number, max: number): number

• 功能：生成指定范围的随机整数
• 参数：
  • min - 最小值（包含）
  • max - 最大值（包含）
• 返回值：随机整数

isValidEmail(email: string): boolean

• 功能：验证邮箱格式
• 参数：email - 邮箱字符串
• 返回值：是否为有效邮箱

isValidPhone(phone: string): boolean

• 功能：验证手机号格式（中国大陆）
• 参数：phone - 手机号字符串
• 返回值：是否为有效手机号

DOM相关

getCssVariable(name: string): string

• 功能：获取CSS变量的值
• 参数：name - CSS变量名（带或不带 -- 前缀）
• 返回值：CSS变量的字符串值

文本处理

truncateText(text: string, maxLength: number): string

• 功能：截断文本并添加省略号
• 参数：
  • text - 原始文本
  • maxLength - 最大长度
• 返回值：截断后的文本

🎯 使用场景示例

1. 表单验证

import { isValidEmail, isValidPhone } from '@zjlab-frontier/utils';

function validateForm(email: string, phone: string) {
  const errors: string[] = [];
  
  if (!isValidEmail(email)) {
    errors.push('请输入有效的邮箱地址');
  }
  
  if (!isValidPhone(phone)) {
    errors.push('请输入有效的手机号码');
  }
  
  return errors;
}

2. 性能优化（防抖/节流）

import { debounce, throttle } from '@zjlab-frontier/utils';

// 搜索框防抖处理
const handleSearch = debounce((query: string) => {
  // 执行搜索逻辑
  console.log('Searching for:', query);
}, 300);

// 滚动事件节流处理
const handleScroll = throttle(() => {
  // 执行滚动相关逻辑
  console.log('Scroll position:', window.scrollY);
}, 100);

window.addEventListener('scroll', handleScroll);

3. 文件上传处理

import { calculateFileHash, formatFileSize } from '@zjlab-frontier/utils';

async function handleFileUpload(file: File) {
  // 显示文件信息
  console.log('File name:', file.name);
  console.log('File size:', formatFileSize(file.size));
  
  // 计算文件哈希用于验证
  try {
    const hash = await calculateFileHash(file);
    console.log('File hash:', hash);
    // 执行上传逻辑...
  } catch (error) {
    console.error('Error calculating hash:', error);
  }
}

📜 许可证

MIT License

📝 注意事项

1. 浏览器兼容性：

   • 本库使用 ES6+ 语法，对于较旧的浏览器可能需要进行转译
   • getCssVariable 和 calculateFileHash 函数依赖于浏览器环境

2. TypeScript 支持：

   • 库提供完整的 TypeScript 类型定义
   • 建议在 TypeScript 项目中使用，以获得最佳的开发体验

3. 依赖说明：

   • 主要依赖 md5 用于文件哈希计算

✅ 本说明文档完整覆盖 @zjlab-frontier/utils 所有功能，可直接用于团队协作或用户文档。