@giszhc/file-utils 0.0.4 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giszhc/file-utils",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "files": [
     "dist",
@@ -23,6 +23,9 @@
     "download"
   ],
   "homepage": "https://github.com/giszhc/file-utils#readme",
+  "dependencies": {
+    "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,16 @@ 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;

package/types/helpers.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 通用辅助工具方法
+ */
+/**
+ * 深拷贝方法
+ * 支持对象、数组、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;
+/**
+ * 数组求和
+ *
+ * @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;

package/types/index.d.ts

@@ -7,18 +7,23 @@
 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 { fileToBase64, base64ToBlob, blobToFile } from './convert';
+export { fileListToZip, downloadFileListAsZip } from './compress';
 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';
+export { deepClone, numberFixed, parseUrlParams, objectToFormData, omitKeys, generateUUID, arraySum, formatAmount, maskString, formatPhone } from './helpers';
+export { VerifyUtils, type IVerifyResult, type IVerifyMessages } from './verify';
 import { readFile, readTxtFile, readCsvFile, readJsonFile } from './read';
 import { downloadFile, downloadBlob, downloadBase64, downloadMultiple } from './download';
-import { fileToBase64, base64ToBlob } from './convert';
+import { fileToBase64, base64ToBlob, blobToFile } 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';
+import { deepClone, parseUrlParams, objectToFormData, omitKeys, generateUUID, arraySum, formatAmount, maskString, formatPhone } from './helpers';
+import { VerifyUtils } from './verify';
 declare const _default: {
     readFile: typeof readFile;
     readTxtFile: typeof readTxtFile;
@@ -30,6 +35,9 @@ declare const _default: {
     downloadMultiple: typeof downloadMultiple;
     fileToBase64: typeof fileToBase64;
     base64ToBlob: typeof base64ToBlob;
+    blobToFile: typeof blobToFile;
+    fileListToZip: (fileList: File[], filename: string) => Promise<File>;
+    downloadFileListAsZip: (fileList: File[], filename: string) => Promise<void>;
     copyToClipboard: typeof copyToClipboard;
     pasteFromClipboard: typeof pasteFromClipboard;
     generateTxtFile: typeof generateTxtFile;
@@ -44,5 +52,16 @@ declare const _default: {
     getFileExtension: typeof getFileExtension;
     getFileNameWithoutExtension: typeof getFileNameWithoutExtension;
     getFileInfo: typeof getFileInfo;
+    deepClone: typeof deepClone;
+    numberFixed: (number: number, fractionDigits?: number) => number;
+    parseUrlParams: typeof parseUrlParams;
+    objectToFormData: typeof objectToFormData;
+    omitKeys: typeof omitKeys;
+    generateUUID: typeof generateUUID;
+    arraySum: typeof arraySum;
+    formatAmount: typeof formatAmount;
+    maskString: typeof maskString;
+    formatPhone: typeof formatPhone;
+    VerifyUtils: typeof VerifyUtils;
 };
 export default _default;

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;