@giszhc/file-utils 0.0.4 → 0.0.6

package/README.md

@@ -7,15 +7,99 @@
 - **文件读取**：支持读取文本、二进制数据、Data URL 等
 - **文件下载**：支持从 URL、Blob、Base64 等多种方式下载文件
 - **文件转换**：支持文件格式转换（如 Base64 转 Blob、File 转 Base64 等）
+- **文件压缩**：支持将多个文件打包为 ZIP 压缩包
 - **文件压缩**：支持图片压缩处理
 - **文件生成**：支持生成 TXT、CSV、JSON 格式文件，可选择返回 File 对象而不下载
 - **文件验证**：提供完整的文件验证和类型判断功能
 - **剪贴板操作**：支持一键复制文本到剪贴板，并支持成功/失败回调
+- **辅助工具**：提供深拷贝、UUID 生成、URL 参数解析、对象转 FormData 等实用工具
+- **正则验证**：提供邮箱、手机、URL、坐标等多种表单验证功能
 - **自动清理**：自动管理临时创建的 Blob URL，防止内存泄漏
 - **TypeScript**：完善的类型定义支持
 
 ------
 
+## 方法列表
+
+### 文件读取
+- `readFile` - 读取文件内容为文本、ArrayBuffer 或 DataURL
+- `readTxtFile` - 读取 TXT 文件内容
+- `readCsvFile` - 读取 CSV 文件并解析为对象数组
+- `readJsonFile` - 读取 JSON 文件并解析为 JavaScript 对象
+
+### 文件下载
+- `downloadFile` - 从 URL 下载文件
+- `downloadBlob` - 下载 Blob 对象
+- `downloadBase64` - 下载 Base64 编码的文件
+- `downloadMultiple` - 批量下载多个文件
+
+### 文件转换
+- `fileToBase64` - 将 File/Blob 转换为 Base64
+- `base64ToBlob` - 将 Base64 转换为 Blob
+- `blobToFile` - 将 Blob 转换为指定文件名的 File
+- `base64ToFile` - 将 Base64 转换为 File
+- `imageUrlToBase64` - 将图片 URL 转换为 Base64
+- `fileChangedImageDPI` - 修改图片的 DPI 分辨率
+- `compressImage` - 压缩图片
+
+### 文件压缩
+- `fileListToZip` - 将文件列表打包为 ZIP
+- `downloadFileListAsZip` - 下载文件列表的 ZIP 压缩包
+
+### 文件生成
+- `generateTxtFile` - 生成 TXT 文件
+- `generateCsvFile` - 生成 CSV 文件
+- `generateJsonFile` - 生成 JSON 文件
+
+### 文件验证
+- `checkFileType` - 检查文件类型
+- `checkFileSize` - 检查文件大小
+- `isImage` - 判断是否为图片
+- `getImageDimensions` - 获取图片尺寸
+- `validateFile` - 综合文件验证
+- `formatFileSize` - 格式化文件大小显示
+- `getFileNameSuffix` - 获取文件扩展名（不含点号）
+- `getFileNamePrefix` - 获取文件名（不含扩展名）
+- `getFileInfo` - 获取文件完整信息
+
+### 剪贴板操作
+- `copyToClipboard` - 复制文本到剪贴板
+- `pasteFromClipboard` - 从剪贴板读取文本
+
+### 辅助工具
+- `deepClone` - 深拷贝对象和数组
+- `numberFixed` - 数字保留指定小数位
+- `parseUrlParams` - 解析 URL 参数为对象
+- `objectToFormData` - 对象转换为 FormData
+- `omitKeys` - 从对象中移除指定的键
+- `generateUUID` - 生成 UUID（支持移除横杠）
+- `arraySum` - 数字数组求和
+- `formatAmount` - 格式化金额（千分位）
+- `maskString` - 字符串中间部分替换为星号
+- `formatPhone` - 格式化手机号码（隐藏中间 4 位）
+- `arrayStringFormatNumber` - 字符串数组转数值数组
+- `arrayCustomSort` - 自定义排序（按指定 id 顺序）
+- `jsonConvertTreeList` - 扁平数据转树形结构
+- `jsonConvertGeneralList` - 树形结构转扁平数据
+
+### 正则验证 (VerifyUtils)
+- `VerifyUtils.isEmail` - 邮箱验证
+- `VerifyUtils.isNumber` - 数字验证
+- `VerifyUtils.isPhone` - 手机号验证
+- `VerifyUtils.isUrl` - URL 链接验证
+- `VerifyUtils.isIP` - IP 地址验证
+- `VerifyUtils.isNoSpace` - 无空格验证
+- `VerifyUtils.isChinese` - 中文验证
+- `VerifyUtils.isPassword` - 密码强度验证
+- `VerifyUtils.isLongitude` - 经度验证
+- `VerifyUtils.isLatitude` - 纬度验证
+- `VerifyUtils.isInputCoordinates` - 坐标串验证
+- `VerifyUtils.isEmpty` - 空值检查
+- `VerifyUtils.getRule` - 生成表单验证规则
+- `VerifyUtils.validate` - 带错误消息的验证
+
+------
+
 ## 安装
 
 你可以通过 npm 安装该库：
@@ -239,15 +323,15 @@ console.log(file.size); // 文件大小（字节）
 ### 11. 获取文件扩展名和文件名
 
 ```ts
-import { getFileExtension, getFileNameWithoutExtension } from '@giszhc/file-utils';
+import { getFileNameSuffix, getFileNamePrefix } from '@giszhc/file-utils';
 
 const file = new File(['content'], 'document.pdf', { type: 'application/pdf' });
 
-// 获取扩展名
-const ext = getFileExtension(file); // ".pdf"
+// 获取扩展名（不含点号）
+const ext = getFileNameSuffix(file); // "pdf"
 
 // 获取文件名（不含扩展名）
-const name = getFileNameWithoutExtension(file); // "document"
+const name = getFileNamePrefix(file); // "document"
 ```
 
 ### 12. 文件类型验证
@@ -380,6 +464,161 @@ const text = await pasteFromClipboard();
 console.log('剪贴板内容:', text);
 ```
 
+### 21. 深拷贝对象
+
+```ts
+import { deepClone } from '@giszhc/file-utils';
+
+// 深拷贝对象
+const obj = { a: 1, b: { c: 2 }, d: [1, 2, 3] };
+const copy = deepClone(obj);
+copy.b.c = 3;
+console.log(obj.b.c); // 2 (原对象不受影响)
+
+// 支持 Date、RegExp 等特殊类型
+const data = {
+  date: new Date(),
+  regex: /test/g,
+  nested: { array: [1, 2, 3] }
+};
+const cloned = deepClone(data);
+```
+
+### 22. 数字保留小数位
+
+```ts
+import { numberFixed } from '@giszhc/file-utils';
+
+// 保留 2 位小数（默认）
+const num1 = numberFixed(3.14159); // 3.14
+
+// 自定义小数位数
+const num2 = numberFixed(10, 3); // 10
+const num3 = numberFixed(2.5678, 1); // 2.6
+```
+
+### 23. 解析 URL 参数
+
+```ts
+import { parseUrlParams } from '@giszhc/file-utils';
+
+// 解析当前页面 URL 参数
+const params = parseUrlParams();
+console.log(params.id); // 从当前 URL 获取 id 参数
+
+// 解析指定 URL 参数
+const url = 'https://example.com?name=John&age=30';
+const urlParams = parseUrlParams(url);
+// { name: 'John', age: '30' }
+```
+
+### 24. 对象转 FormData
+
+```ts
+import { objectToFormData } from '@giszhc/file-utils';
+
+// 简单对象转换
+const obj = { name: 'John', age: 30 };
+const formData = objectToFormData(obj);
+
+// 嵌套对象
+const user = {
+  name: 'John',
+  profile: {
+    email: 'john@example.com',
+    phone: '123456'
+  }
+};
+const fd = objectToFormData(user);
+
+// 包含文件
+const fileInput = document.querySelector('input[type="file"]');
+const data = {
+  avatar: fileInput.files[0],
+  description: 'User avatar'
+};
+const fdWithFile = objectToFormData(data);
+```
+
+### 25. 移除对象的特定键
+
+```ts
+import { omitKeys } from '@giszhc/file-utils';
+
+// 移除指定的键
+const obj = { a: 1, b: 2, c: 3, d: 4 };
+const result = omitKeys(obj, ['b', 'd']);
+// { a: 1, c: 3 }
+
+// 反向操作：只保留指定的键
+const filtered = omitKeys(obj, ['a', 'c'], true);
+// { a: 1, c: 3 }
+```
+
+### 26. 生成 UUID
+
+```ts
+import { generateUUID } from '@giszhc/file-utils';
+
+// 生成带横杠的 UUID（默认）
+const uuid1 = generateUUID();
+// "550e8400-e29b-41d4-a716-446655440000"
+
+// 生成不带横杠的 UUID
+const uuid2 = generateUUID(true);
+// "550e8400e29b41d4a716446655440000"
+
+// 使用场景：生成唯一 ID
+const userId = generateUUID();
+const requestId = generateUUID(true); // 无横杠版本用于数据库存储
+```
+
+### 27. 正则验证工具类
+
+```ts
+import { VerifyUtils } from '@giszhc/file-utils';
+
+// 基础验证
+VerifyUtils.isEmail('test@example.com'); // true
+VerifyUtils.isPhone('13800138000'); // true
+VerifyUtils.isUrl('https://example.com'); // true
+VerifyUtils.isNumber('123.45'); // true
+VerifyUtils.isNoSpace('hello'); // true
+VerifyUtils.isChinese('你好'); // true
+VerifyUtils.isPassword('Abc@1234'); // true
+
+// 经纬度验证
+VerifyUtils.isLongitude(116.4); // true
+VerifyUtils.isLatitude(39.9); // true
+
+// 坐标串验证（支持多级分隔符）
+VerifyUtils.isInputCoordinates('116.4,39.9'); // true
+VerifyUtils.isInputCoordinates('116.4,39.9;117.4,40.9'); // true
+VerifyUtils.isInputCoordinates('116.4,39.9|117.4,40.9'); // true
+
+// 空值检查
+VerifyUtils.isEmpty(''); // true
+VerifyUtils.isEmpty(null); // true
+VerifyUtils.isEmpty([]); // true
+VerifyUtils.isEmpty({}); // true
+
+// 生成 Element UI 表单验证规则
+const rules = {
+  email: [
+    { required: true, message: '请输入邮箱', trigger: 'blur' },
+    VerifyUtils.getRule('email', 'blur')
+  ],
+  phone: [
+    { required: true, message: '请输入手机号', trigger: 'blur' },
+    VerifyUtils.getRule('phone', 'blur')
+  ],
+  url: [VerifyUtils.getRule('url')]
+};
+
+// 获取错误提示语
+console.log(VerifyUtils.messages.email); // "请输入正确的邮箱地址"
+```
+
 ------
 
 ## 使用方法
@@ -519,6 +758,92 @@ const base64 = 'data:image/png;base64,iVBORw0KGgoAAAANS...';
 const blob = base64ToBlob(base64);
 ```
 
+### base64ToFile(base64: string, filename?: string, mimeType?: string): File
+
+将 Base64 编码转换为 File 对象。
+
+```ts
+import { base64ToFile } from '@giszhc/file-utils';
+
+// 转换带前缀的 Base64
+const base64 = 'data:image/png;base64,iVBORw0KGgoAAAANS...';
+const file = base64ToFile(base64, 'image.png');
+console.log(file.name); // "image.png"
+
+// 转换不带前缀的 Base64
+const pureBase64 = 'iVBORw0KGgoAAAANS...';
+const file2 = base64ToFile(pureBase64, 'image.png', 'image/png');
+```
+
+### imageUrlToBase64(imageUrl: string, mimeType?: string, quality?: number): Promise<string>
+
+将图片 URL 转换为 Base64 编码。使用 Canvas 将图片绘制后转换为 Base64。
+
+```ts
+import { imageUrlToBase64 } from '@giszhc/file-utils';
+
+// 转换远程图片
+const base64 = await imageUrlToBase64('https://example.com/image.jpg');
+console.log(base64); // data:image/png;base64,...
+
+// 转换为 JPEG 格式，80% 质量
+const jpegBase64 = await imageUrlToBase64(
+    'https://example.com/image.png',
+    'image/jpeg',
+    0.8
+);
+```
+
+### fileChangedImageDPI(source: string | Blob, dpi?: number): Promise<string | Blob>
+
+修改图片的分辨率 DPI（每英寸点数）。支持 Base64 字符串和 Blob 对象。返回 Promise。
+
+```ts
+import { fileChangedImageDPI } from '@giszhc/file-utils';
+
+// 修改 Base64 图片的 DPI 为 300（适合打印）
+const base64 = 'data:image/png;base64,iVBORw0KGgoAAAANS...';
+const highDpiBase64 = await fileChangedImageDPI(base64, 300);
+console.log('高分辨率图片:', highDpiBase64);
+
+// 修改 Blob 图片的 DPI
+const blob = new Blob([imageData], { type: 'image/png' });
+const newBlob = await fileChangedImageDPI(blob, 300);
+// newBlob 是修改后的 Blob 对象
+
+// 使用默认 DPI (96，屏幕显示标准)
+const defaultDpiResult = await fileChangedImageDPI(base64);
+
+// 设置为 72 DPI（网页优化）
+const webOptimized = await fileChangedImageDPI(base64, 72);
+
+// 结合其他方法使用
+import { fileToBase64, base64ToBlob, fileChangedImageDPI } from '@giszhc/file-utils';
+
+const handleImageUpload = async (file: File) => {
+    // 方式 1: 使用 Base64
+    const base64 = await fileToBase64(file);
+    const highResBase64 = await fileChangedImageDPI(base64, 300);
+    
+    // 方式 2: 直接使用 Blob
+    const highResBlob = await fileChangedImageDPI(file, 300);
+    const highResFile = base64ToFile(highResBase64, 'high-res.png');
+};
+```
+
+**应用场景：**
+- 🖼️ **打印前提升 DPI**：将网络图片的 DPI 从 72 提升到 300，获得更好的打印质量
+- 🌐 **网页优化**：降低 DPI 到 72，减少文件体积，加快网页加载速度
+- 📱 **设备适配**：根据不同设备的显示需求调整 DPI
+- 📄 **出版印刷**：满足专业印刷的 300 DPI 或更高要求
+
+**注意事项：**
+- 该方法仅修改图片元数据中的 DPI 值，不会改变图片的像素尺寸
+- DPI 值越高，打印时的物理尺寸越小，但细节越清晰
+- 标准屏幕显示通常使用 96 DPI，印刷品通常需要 300 DPI
+- 输入类型为 Base64 时返回 Base64，输入类型为 Blob 时返回 Blob
+- **该方法是异步函数，需要使用 await 调用**
+
 ### compressImage(file: File, quality?: number, maxWidth?: number, maxHeight?: number): Promise<Blob>
 
 压缩图片文件。支持调整质量和最大尺寸。
@@ -709,6 +1034,160 @@ if (!result.valid) {
 }
 ```
 
+### arrayStringFormatNumber(arrayList: string[]): number[]
+
+将字符串数组转换为数值数组。
+
+```ts
+import { arrayStringFormatNumber } from '@giszhc/file-utils';
+
+// 将字符串数字数组转换为数值数组
+const strArr = ["0", "1", "2", "3", "4"];
+const numArr = arrayStringFormatNumber(strArr);
+console.log(numArr); // [0, 1, 2, 3, 4]
+
+// 处理带小数点的字符串
+const decimalStrs = ["1.5", "2.7", "3.14"];
+const decimalNums = arrayStringFormatNumber(decimalStrs);
+console.log(decimalNums); // [1.5, 2.7, 3.14]
+```
+
+### arrayCustomSort(ids: string[], dataList: any[], cbA: Function, cbB: Function): void
+
+根据给定的 id 顺序对数据列表进行排序。
+
+```ts
+import { arrayCustomSort } from '@giszhc/file-utils';
+
+// 基本使用
+const ids = ['id1', 'id2', 'id3'];
+const dataList = [
+    { id: 'id3', name: 'Layer 3' },
+    { id: 'id1', name: 'Layer 1' },
+    { id: 'id2', name: 'Layer 2' }
+];
+
+arrayCustomSort(ids, dataList, item => item.id, item => item.id);
+// 排序后：[
+//   { id: 'id1', name: 'Layer 1' },
+//   { id: 'id2', name: 'Layer 2' },
+//   { id: 'id3', name: 'Layer 3' }
+// ]
+
+// 使用不同的回调函数处理不同类型的数据
+const orderIds = ['admin', 'user', 'guest'];
+const roles = [
+    { roleId: 'guest', roleName: '访客' },
+    { roleId: 'admin', roleName: '管理员' },
+    { roleId: 'user', roleName: '普通用户' }
+];
+
+arrayCustomSort(orderIds, roles, role => role.roleId, role => role.roleId);
+// 按指定顺序排序：管理员、普通用户、访客
+```
+
+### jsonConvertTreeList(dataList: any[]): any[]
+
+将扁平数据数组转换为树形结构。
+
+```ts
+import { jsonConvertTreeList } from '@giszhc/file-utils';
+
+// 扁平数据
+const flatData = [
+    { id: 1, pid: null, name: '根节点' },
+    { id: 2, pid: 1, name: '子节点 1' },
+    { id: 3, pid: 1, name: '子节点 2' },
+    { id: 4, pid: 2, name: '孙节点 1' }
+];
+
+const tree = jsonConvertTreeList(flatData);
+/*
+返回树形结构：
+[
+  {
+    id: 1,
+    pid: null,
+    name: '根节点',
+    children: [
+      {
+        id: 2,
+        pid: 1,
+        name: '子节点 1',
+        children: [
+          { id: 4, pid: 2, name: '孙节点 1' }
+        ]
+      },
+      {
+        id: 3,
+        pid: 1,
+        name: '子节点 2',
+        children: []
+      }
+    ]
+  }
+]
+*/
+
+// 应用场景：菜单生成、组织架构展示
+const menuData = [
+    { id: 1, pid: null, title: '系统管理' },
+    { id: 2, pid: 1, title: '用户管理' },
+    { id: 3, pid: 1, title: '角色管理' },
+    { id: 4, pid: 2, title: '用户列表' },
+    { id: 5, pid: 2, title: '用户新增' }
+];
+
+const menuTree = jsonConvertTreeList(menuData);
+```
+
+### jsonConvertGeneralList(treeList: any[], delChildrenField?: boolean): any[]
+
+将树形结构转换回扁平数据数组。
+
+```ts
+import { jsonConvertGeneralList } from '@giszhc/file-utils';
+
+// 树形结构
+const tree = [
+    {
+        id: 1,
+        pid: null,
+        name: '根节点',
+        children: [
+            {
+                id: 2,
+                pid: 1,
+                name: '子节点 1',
+                children: [
+                    { id: 4, pid: 2, name: '孙节点 1' }
+                ]
+            },
+            {
+                id: 3,
+                pid: 1,
+                name: '子节点 2',
+                children: []
+            }
+        ]
+    }
+];
+
+// 保留 children 字段
+const flatWithChildren = jsonConvertGeneralList(tree);
+console.log(flatWithChildren.length); // 4
+
+// 删除 children 字段
+const flatWithoutChildren = jsonConvertGeneralList(tree, true);
+console.log(flatWithoutChildren[0]); 
+// { id: 1, pid: null, name: '根节点' } (不含 children)
+
+// 应用场景：将树形菜单保存为扁平数据存储到数据库
+const menuTree = [...]; // 树形菜单
+const flatMenuData = jsonConvertGeneralList(menuTree, true);
+// 可以发送到后端保存到数据库
+```
+
 ------
 
 ## 类型定义