@giszhc/file-utils 0.0.4 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giszhc/file-utils",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "files": [
     "dist",
@@ -23,6 +23,10 @@
     "download"
   ],
   "homepage": "https://github.com/giszhc/file-utils#readme",
+  "dependencies": {
+    "changedpi": "^1.0.4",
+    "jszip": "^3.10.1"
+  },
   "devDependencies": {
     "typescript": "~5.9.3",
     "vite": "^7.2.4"

package/types/compress.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 文件压缩相关方法
+ */
+/**
+ * 文件列表转 ZIP 压缩包
+ *
+ * @param fileList - 文件列表数组
+ * @param filename - ZIP 文件名（不含扩展名）
+ * @returns Promise<File> - 返回 ZIP 压缩包 File 对象
+ *
+ * @example
+ * const files = [file1, file2, file3];
+ * const zipFile = await fileListToZip(files, 'my-files');
+ * console.log(zipFile.name); // "my-files.zip"
+ */
+export declare const fileListToZip: (fileList: File[], filename: string) => Promise<File>;
+/**
+ * 下载文件列表的 ZIP 压缩包
+ *
+ * @param fileList - 文件列表数组
+ * @param filename - ZIP 文件名（不含扩展名）
+ * @returns Promise<void>
+ *
+ * @example
+ * const files = [file1, file2, file3];
+ * await downloadFileListAsZip(files, 'my-files');
+ */
+export declare const downloadFileListAsZip: (fileList: File[], filename: string) => Promise<void>;

package/types/convert.d.ts

@@ -35,3 +35,76 @@ export declare function fileToBase64(file: File | Blob): Promise<string>;
  * const blob = base64ToBlob(base64, 'image/png');
  */
 export declare function base64ToBlob(base64: string, mimeType?: string): Blob;
+/**
+ * 将 Blob 转换为指定文件名的 File 对象
+ *
+ * @param blob - Blob 对象
+ * @param filename - 文件名
+ * @returns File - 转换后的 File 对象
+ *
+ * @example
+ * const blob = new Blob(['Hello'], { type: 'text/plain' });
+ * const file = blobToFileName(blob, 'hello.txt');
+ * console.log(file.name); // "hello.txt"
+ */
+export declare function blobToFile(blob: Blob, filename: string): File;
+/**
+ * 将 Base64 编码转换为 File 对象
+ *
+ * @param base64 - Base64 编码的字符串（可以包含或不包含 data URL 前缀）
+ * @param filename - 文件名（可选），默认为 'file'
+ * @param mimeType - MIME 类型（可选），如果未指定且 base64 不包含前缀，默认为 'application/octet-stream'
+ * @returns File - 转换后的 File 对象
+ *
+ * @example
+ * // 转换带前缀的 Base64
+ * const base64 = 'data:image/png;base64,iVBORw0KGgoAAAANS...';
+ * const file = base64ToFile(base64, 'image.png');
+ *
+ * @example
+ * // 转换不带前缀的 Base64
+ * const base64 = 'iVBORw0KGgoAAAANS...';
+ * const file = base64ToFile(base64, 'image.png', 'image/png');
+ */
+export declare function base64ToFile(base64: string, filename?: string, mimeType?: string): File;
+/**
+ * 将图片 URL 转换为 Base64 编码
+ * 使用 Canvas 将图片绘制后转换为 Base64
+ *
+ * @param imageUrl - 图片 URL 地址
+ * @param mimeType - 输出的 MIME 类型（可选），默认为 'image/png'
+ * @param quality - 图片质量（可选），范围 0.0 - 1.0，默认为 1.0
+ * @returns Promise<string> - Base64 编码的字符串（包含 data URL 前缀）
+ *
+ * @example
+ * // 转换远程图片
+ * const base64 = await imageUrlToBase64('https://example.com/image.jpg');
+ * console.log(base64); // data:image/png;base64,iVBORw0KGgoAAAANS...
+ *
+ * @example
+ * // 转换为 JPEG 格式，80% 质量
+ * const base64 = await imageUrlToBase64('https://example.com/image.png', 'image/jpeg', 0.8);
+ */
+export declare function imageUrlToBase64(imageUrl: string, mimeType?: string, quality?: number): Promise<string>;
+/**
+ * fileChangedImageDPI 函数用于修改图片的分辨率 DPI
+ *
+ * @param source - 原图片，支持 Base64 字符串或 Blob 对象
+ * @param dpi - 需要设置的分辨率值，默认为 96
+ * @returns Promise<string | Blob> - 返回修改后的 DPI 图片（Base64 字符串或 Blob）
+ *
+ * @example
+ * // 修改 Base64 图片的 DPI
+ * const base64 = 'data:image/png;base64,iVBORw0KGgoAAAANS...';
+ * const newBase64 = fileChangedImageDPI(base64, 300);
+ *
+ * @example
+ * // 修改 Blob 图片的 DPI
+ * const blob = new Blob([imageData], { type: 'image/png' });
+ * const newBlob = await fileChangedImageDPI(blob, 300);
+ *
+ * @example
+ * // 使用默认 DPI (96)
+ * const result = await fileChangedImageDPI(base64);
+ */
+export declare function fileChangedImageDPI(source: string | Blob, dpi?: number): Promise<string | Blob>;

package/types/helpers.d.ts

@@ -0,0 +1,271 @@
+/**
+ * 通用辅助工具方法
+ */
+/**
+ * 深拷贝方法
+ * 支持对象、数组、Date、RegExp 等类型的深拷贝
+ *
+ * @param target - 需要拷贝的目标对象
+ * @returns T - 拷贝后的新对象
+ *
+ * @example
+ * const obj = { a: 1, b: { c: 2 } };
+ * const copy = deepClone(obj);
+ * copy.b.c = 3;
+ * console.log(obj.b.c); // 2 (原对象不受影响)
+ */
+export declare function deepClone<T>(target: T): T;
+/**
+ * 数字保留指定小数位数
+ *
+ * @param number - 需要处理的数字
+ * @param fractionDigits - 保留的小数位数，默认为 2
+ * @returns number - 处理后的数字
+ *
+ * @example
+ * numberFixed(3.14159, 2) // 3.14
+ * numberFixed(10, 3) // 10
+ */
+export declare const numberFixed: (number: number, fractionDigits?: number) => number;
+/**
+ * 解析 URL 参数为对象
+ *
+ * @param url - URL 字符串，默认为 location.href
+ * @returns Record<string, string> - 包含 URL 参数的对象
+ *
+ * @example
+ * parseUrlParams('https://example.com?name=John&age=30')
+ * // { name: 'John', age: '30' }
+ *
+ * @example
+ * parseUrlParams() // 解析当前页面 URL 参数
+ */
+export declare function parseUrlParams(url?: string): Record<string, string>;
+/**
+ * 将对象转换为 FormData
+ *
+ * @param obj - 需要转换的对象
+ * @param formData - 可选的 FormData 实例，用于追加数据
+ * @returns FormData - 转换后的 FormData 对象
+ *
+ * @example
+ * const obj = { name: 'John', age: 30 };
+ * const formData = objectToFormData(obj);
+ *
+ * @example
+ * // 嵌套对象
+ * const obj = { user: { name: 'John', email: 'john@example.com' } };
+ * const formData = objectToFormData(obj);
+ */
+export declare function objectToFormData(obj: Record<string, any>, formData?: FormData): FormData;
+/**
+ * 从给定对象中移除特定的键，返回新对象
+ *
+ * @param obj - 原始对象
+ * @param keys - 需要移除的键名数组
+ * @param reverse - 是否反向操作（即只保留指定的键），默认为 false
+ * @returns T - 移除指定键后的新对象
+ *
+ * @example
+ * omitKeys({ a: 1, b: 2, c: 3 }, ['b', c]) // { a: 1 }
+ *
+ * @example
+ * omitKeys({ a: 1, b: 2, c: 3 }, ['a'], true) // { a: 1 } (反向操作，只保留 a)
+ */
+export declare function omitKeys<T extends Record<string, any>>(obj: T, keys: (keyof T | string)[], reverse?: boolean): Partial<T>;
+/**
+ * 生成 UUID
+ *
+ * @param removeHyphens - 是否移除横杠，默认为 false（保留横杠）
+ * @returns string - 生成的 UUID 字符串
+ *
+ * @example
+ * generateUUID() // "550e8400-e29b-41d4-a716-446655440000"
+ *
+ * @example
+ * generateUUID(true) // "550e8400e29b41d4a716446655440000" (无横杠)
+ */
+export declare function generateUUID(removeHyphens?: boolean): string;
+/**
+ * 过滤对象中的空值
+ * 移除值为空字符串、null 或 undefined 的属性
+ *
+ * @param data - 需要过滤的对象
+ * @returns Record<string, any> - 过滤后的新对象
+ *
+ * @example
+ * const data = { a: 1, b: '', c: null, d: undefined, e: 'test' };
+ * const filtered = filterEmptyValue(data); // { a: 1, e: 'test' }
+ *
+ * @example
+ * const params = { name: 'John', age: null, email: '' };
+ * const validParams = filterEmptyValue(params); // { name: 'John' }
+ */
+export declare function filterEmptyValue(data: Record<string, any>): Record<string, any>;
+/**
+ * 数组求和
+ *
+ * @param arr - 数字数组
+ * @returns number - 数组元素的总和
+ *
+ * @example
+ * arraySum([1, 2, 3, 4, 5]) // 15
+ * arraySum([10, 20, 30]) // 60
+ */
+export declare function arraySum(arr: number[]): number;
+/**
+ * 格式化数字金额，使用逗号分隔（千分位）
+ *
+ * @param amount - 需要格式化的数字金额
+ * @param decimals - 小数位数，默认为 2
+ * @returns string - 格式化后的字符串（如：1,234,567.89）
+ *
+ * @example
+ * formatAmount(1234567.89) // "1,234,567.89"
+ * formatAmount(1000000, 0) // "1,000,000"
+ * formatAmount(999) // "999.00"
+ */
+export declare function formatAmount(amount: number, decimals?: number): string;
+/**
+ * 将字符串中间部分替换为星号（*）
+ * 常用于隐藏电话号码、身份证号等敏感信息
+ *
+ * @param str - 需要处理的字符串
+ * @param start - 开始保留的字符数（从左侧计数）
+ * @param end - 结束保留的字符数（从右侧计数）
+ * @param maskChar - 用于替换的字符，默认为 '*'
+ * @returns string - 处理后的字符串
+ *
+ * @example
+ * maskString('13800138000', 3, 4) // "138****8000"
+ * maskString('1234567890', 2, 2) // "12******90"
+ * maskString('abc', 1, 1) // "a*b"
+ */
+export declare function maskString(str: string, start?: number, end?: number, maskChar?: string): string;
+/**
+ * 格式化手机号码，隐藏中间 4 位
+ *
+ * @param phone - 手机号码
+ * @param maskChar - 用于替换的字符，默认为 '*'
+ * @returns string - 格式化后的手机号码（如：138****8000）
+ *
+ * @example
+ * formatPhone('13800138000') // "138****8000"
+ * formatPhone('13900139000', '#') // "139####9000"
+ */
+export declare function formatPhone(phone: string, maskChar?: string): string;
+/**
+ * arrayStringFormatNumber 函数用于将字符串数组转换为数值数组
+ *
+ * @param arrayList - 字符串数组
+ * @returns number[] - 返回格式化后的数值数组
+ *
+ * @example
+ * // 将字符串数字数组转换为数值数组
+ * const result = arrayStringFormatNumber(["0", "1", "2", "3", "4"]);
+ * console.log(result); // [0, 1, 2, 3, 4]
+ *
+ * @description
+ * 此方法将传入的字符串数组格式化为数值数组，并返回新的数组
+ */
+export declare function arrayStringFormatNumber(arrayList: string[]): number[];
+/**
+ * arrayCustomSort 函数用于根据给定的 id 顺序对数据列表进行排序。
+ *
+ * @param ids - 包含 id 的数组，定义排序的顺序。
+ * @param dataList - 需要排序的数据列表。
+ * @param cbA - 一个回调函数，用于从数据列表的每个元素中提取 id，用于排序。
+ * @param cbB - 一个回调函数，用于从数据列表的每个元素中提取 id，用于排序。
+ * @returns void - 直接修改原数组，不返回值
+ *
+ * @example
+ * ```typescript
+ * 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);
+ * // dataList 将被排序为 [
+ * //   { id: 'id1', name: 'Layer 1' },
+ * //   { id: 'id2', name: 'Layer 2' },
+ * //   { id: 'id3', name: 'Layer 3' }
+ * // ]
+ * ```
+ *
+ * @description
+ * cbA 和 cbB 允许对数据列表中的不同类型项进行单独的处理。
+ */
+export declare function arrayCustomSort(ids: string[], dataList: any[], cbA: (item: any) => any, cbB: (item: any) => any): void;
+/**
+ * jsonConvertTreeList 函数实现了把扁平的数据数组，按照父子节点的关系转换为树形结构。
+ *
+ * @param dataList - 输入的扁平数据数组，其中每个元素是一个对象，至少包含 id 和 pid 两个属性，表示自身的 ID 和其父节点的 ID。
+ * @returns any[] - 返回构建好的树形结构数组，其中每个节点包含 id，pid 和 children (如果有的话) 三个属性，children 属性是一个数组，里面包含其所有子节点。
+ *
+ * @example
+ * ```typescript
+ * 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: [] }
+ * //     ]
+ * //   }
+ * // ]
+ * ```
+ *
+ * @description
+ * 函数首先定义了一个递归的函数 buildChildren，用于构建指定节点的所有子节点。然后通过 filter 方法找出所有的根节点，对每个根节点调用 buildChildren 函数构建其子树。
+ * 最后返回包含所有子树的数组。
+ */
+export declare function jsonConvertTreeList(dataList: any[]): any[];
+/**
+ * jsonConvertGeneralList 函数是将嵌套的树形结构转换回扁平的数据数组。也可选择是否删除 children 属性。
+ *
+ * @param treeList - 输入的树形结构数组。
+ * @param delChildrenField - 可选，是否要删除每个节点的 children 字段，默认为 false，即默认不删除。
+ * @returns any[] - 返回扁平的数据数组。
+ *
+ * @example
+ * ```typescript
+ * const tree = [
+ *   {
+ *     id: 1,
+ *     pid: null,
+ *     name: '根节点',
+ *     children: [
+ *       { id: 2, pid: 1, name: '子节点 1', children: [] },
+ *       { id: 3, pid: 1, name: '子节点 2', children: [] }
+ *     ]
+ *   }
+ * ];
+ * const flat = jsonConvertGeneralList(tree);
+ * // 返回扁平数组：[
+ * //   { id: 1, pid: null, name: '根节点', children: [...] },
+ * //   { id: 2, pid: 1, name: '子节点 1', children: [] },
+ * //   { id: 3, pid: 1, name: '子节点 2', children: [] }
+ * // ]
+ * ```
+ *
+ * @description
+ * 函数首先定义了一个递归的函数 loop，用于处理每个节点和其子节点。然后对输入的树根节点调用 loop 函数。
+ * 如果设置了 delChildrenField 为 true，函数还会删除每个节点的 children 字段。
+ */
+export declare function jsonConvertGeneralList(treeList: any[], delChildrenField?: boolean): any[];

package/types/index.d.ts

@@ -5,44 +5,13 @@
  * 支持 Tree Shaking，按需引入
  */
 export type { ReadFileType, CompressOptions, DownloadOptions, CopyOptions, IFileInfo, IValidationResult, IFileValidationOptions } from './types';
-export { readFile, readTxtFile, readCsvFile, readJsonFile } from './read';
-export { downloadFile, downloadBlob, downloadBase64, downloadMultiple } from './download';
-export { fileToBase64, base64ToBlob } from './convert';
-export { copyToClipboard, pasteFromClipboard } from './copy';
-export { generateTxtFile, generateCsvFile, generateJsonFile } from './generate';
-export { checkFileType, checkFileSize, isImage, getImageDimensions, validateFile, formatFileSize } from './validators';
-export { getFileExtension, getFileNameWithoutExtension, getFileInfo } from './utils';
-import { readFile, readTxtFile, readCsvFile, readJsonFile } from './read';
-import { downloadFile, downloadBlob, downloadBase64, downloadMultiple } from './download';
-import { fileToBase64, base64ToBlob } from './convert';
-import { copyToClipboard, pasteFromClipboard } from './copy';
-import { generateTxtFile, generateCsvFile, generateJsonFile } from './generate';
-import { checkFileType, checkFileSize, isImage, getImageDimensions, validateFile, formatFileSize } from './validators';
-import { getFileExtension, getFileNameWithoutExtension, getFileInfo } from './utils';
-declare const _default: {
-    readFile: typeof readFile;
-    readTxtFile: typeof readTxtFile;
-    readCsvFile: typeof readCsvFile;
-    readJsonFile: typeof readJsonFile;
-    downloadFile: typeof downloadFile;
-    downloadBlob: typeof downloadBlob;
-    downloadBase64: typeof downloadBase64;
-    downloadMultiple: typeof downloadMultiple;
-    fileToBase64: typeof fileToBase64;
-    base64ToBlob: typeof base64ToBlob;
-    copyToClipboard: typeof copyToClipboard;
-    pasteFromClipboard: typeof pasteFromClipboard;
-    generateTxtFile: typeof generateTxtFile;
-    generateCsvFile: typeof generateCsvFile;
-    generateJsonFile: typeof generateJsonFile;
-    checkFileType: typeof checkFileType;
-    checkFileSize: typeof checkFileSize;
-    isImage: typeof isImage;
-    getImageDimensions: typeof getImageDimensions;
-    validateFile: typeof validateFile;
-    formatFileSize: typeof formatFileSize;
-    getFileExtension: typeof getFileExtension;
-    getFileNameWithoutExtension: typeof getFileNameWithoutExtension;
-    getFileInfo: typeof getFileInfo;
-};
-export default _default;
+export * from './read';
+export * from './download';
+export * from './convert';
+export * from './compress';
+export * from './copy';
+export * from './generate';
+export * from './validators';
+export * from './utils';
+export * from './helpers';
+export * from './verify';

package/types/utils.d.ts

@@ -3,33 +3,33 @@
  */
 import type { IFileInfo } from './types';
 /**
- * 获取文件扩展名（后缀）
+ * 获取文件扩展名（后缀，不含点号）
  *
  * @param file - File 对象或文件名
- * @returns string - 文件扩展名（包含点号，如 '.jpg'）
+ * @returns string - 文件扩展名（不含点号，如 'jpg'）
  *
  * @example
  * const file = new File(['content'], 'test.txt', { type: 'text/plain' });
- * const ext = getFileExtension(file); // ".txt"
+ * const ext = getFileNameSuffix(file); // "txt"
  *
  * @example
- * const ext = getFileExtension('image.png'); // ".png"
+ * const ext = getFileNameSuffix('image.png'); // "png"
  */
-export declare function getFileExtension(file: File | string): string;
+export declare function getFileNameSuffix(file: File | string): string;
 /**
- * 获取文件名（不含扩展名）
+ * 获取文件名（前缀，不含扩展名）
  *
  * @param file - File 对象或文件名
  * @returns string - 不含扩展名的文件名
  *
  * @example
  * const file = new File(['content'], 'test.txt', { type: 'text/plain' });
- * const name = getFileNameWithoutExtension(file); // "test"
+ * const name = getFileNamePrefix(file); // "test"
  *
  * @example
- * const name = getFileNameWithoutExtension('archive.tar.gz'); // "archive.tar"
+ * const name = getFileNamePrefix('archive.tar.gz'); // "archive.tar"
  */
-export declare function getFileNameWithoutExtension(file: File | string): string;
+export declare function getFileNamePrefix(file: File | string): string;
 /**
  * 获取文件信息
  *

package/types/verify.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 正则验证工具类 (增强版)
+ * 提供常用的表单验证功能，包括邮箱、手机、URL、坐标等
+ *
+ * @author 烟火里的尘埃 / AI 优化版
+ */
+/**
+ * 验证结果接口
+ */
+export interface IVerifyResult {
+    /** 是否通过验证 */
+    valid: boolean;
+    /** 错误消息 */
+    message?: string;
+}
+/**
+ * 提示语映射
+ */
+export interface IVerifyMessages {
+    email: string;
+    number: string;
+    phone: string;
+    url: string;
+    ip: string;
+    longitude: string;
+    latitude: string;
+    noSpace: string;
+    password: string;
+    empty: string;
+    chinese: string;
+    inputCoordinates: string;
+}
+/**
+ * 正则验证工具类 (增强版)
+ * 提供常用的表单验证功能，包括邮箱、手机、URL、坐标等
+ */
+export declare class VerifyUtils {
+    static messages: IVerifyMessages;
+    static isEmail: (val: string) => boolean;
+    static isNumber: (val: string) => boolean;
+    static isPhone: (val: string) => boolean;
+    static isUrl: (val: string) => boolean;
+    static isIP: (val: string) => boolean;
+    static isNoSpace: (val: string) => boolean;
+    static isChinese: (val: string) => boolean;
+    static isPassword: (val: string) => boolean;
+    /**
+     * 验证经度
+     * @param lng - 经度值
+     * @returns boolean - 是否在 -180 到 180 之间
+     */
+    static isLongitude(lng: number | string): boolean;
+    /**
+     * 验证纬度
+     * @param lat - 纬度值
+     * @returns boolean - 是否在 -90 到 90 之间
+     */
+    static isLatitude(lat: number | string): boolean;
+    /**
+     * 检查是否为空
+     * @param value - 需要检查的值
+     * @returns boolean - 是否为空
+     */
+    static isEmpty(value: any): boolean;
+    /**
+     * 验证输入坐标串 (递归平铺校验)
+     * 支持格式："lng,lat" 或 "lng,lat;lng,lat" 或 "lng,lat;lng,lat|lng,lat"
+     * @param latLngS - 坐标字符串
+     * @returns boolean - 坐标格式是否正确
+     */
+    static isInputCoordinates(latLngS: string): boolean;
+    /**
+     * 生成坐标数组 (支持多级分隔符)
+     * @param latLngS - 坐标字符串
+     * @returns any[] | null - 解析后的坐标数组
+     */
+    static generateCoordinates(latLngS: string): any[] | null;
+    /**
+     * 快速生成 Form 表单校验规则
+     * @param type - 对应 messages 的 key
+     * @param trigger - 触发方式 'blur' | 'change'
+     * @returns any - Element UI 表单验证规则对象
+     */
+    static getRule(type: string, trigger?: string): any;
+    /**
+     * 带错误消息的验证
+     * @param type - 验证类型
+     * @param value - 验证值
+     * @returns IVerifyResult - 验证结果
+     */
+    static validate(type: keyof typeof this.messages, value: any): IVerifyResult;
+}
+export default VerifyUtils;