@giszhc/file-utils 0.0.5 → 0.0.6

package/README.md

@@ -37,6 +37,9 @@
 - `fileToBase64` - 将 File/Blob 转换为 Base64
 - `base64ToBlob` - 将 Base64 转换为 Blob
 - `blobToFile` - 将 Blob 转换为指定文件名的 File
+- `base64ToFile` - 将 Base64 转换为 File
+- `imageUrlToBase64` - 将图片 URL 转换为 Base64
+- `fileChangedImageDPI` - 修改图片的 DPI 分辨率
 - `compressImage` - 压缩图片
 
 ### 文件压缩
@@ -55,8 +58,8 @@
 - `getImageDimensions` - 获取图片尺寸
 - `validateFile` - 综合文件验证
 - `formatFileSize` - 格式化文件大小显示
-- `getFileExtension` - 获取文件扩展名
-- `getFileNameWithoutExtension` - 获取文件名（不含扩展名）
+- `getFileNameSuffix` - 获取文件扩展名（不含点号）
+- `getFileNamePrefix` - 获取文件名（不含扩展名）
 - `getFileInfo` - 获取文件完整信息
 
 ### 剪贴板操作
@@ -74,6 +77,10 @@
 - `formatAmount` - 格式化金额（千分位）
 - `maskString` - 字符串中间部分替换为星号
 - `formatPhone` - 格式化手机号码（隐藏中间 4 位）
+- `arrayStringFormatNumber` - 字符串数组转数值数组
+- `arrayCustomSort` - 自定义排序（按指定 id 顺序）
+- `jsonConvertTreeList` - 扁平数据转树形结构
+- `jsonConvertGeneralList` - 树形结构转扁平数据
 
 ### 正则验证 (VerifyUtils)
 - `VerifyUtils.isEmail` - 邮箱验证
@@ -316,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. 文件类型验证
@@ -751,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>
 
 压缩图片文件。支持调整质量和最大尺寸。
@@ -941,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);
+// 可以发送到后端保存到数据库
+```
+
 ------
 
 ## 类型定义