图片解析工具库

这个工具库用于解析和提取各种格式文件的封面图。

文件结构

utils/
├── common.ts          # 公共方法和统一入口
├── parsePSD.ts        # PSD 文件解析器
├── parseTIFF.ts       # TIFF 文件解析器
├── parseImage.ts      # 常规图片解析器 (PNG, JPEG, WEBP, GIF, BMP)
├── index.ts           # 统一导出入口
└── README.md          # 说明文档

支持的文件格式

• PSD - 提取合成图像
• TIFF - 提取第一帧
• PNG - 原始图片
• JPEG - 原始图片
• WEBP - 原始图片
• GIF - 原始图片
• BMP - 原始图片

核心功能

1. 文件类型检测 (detectFileType)

通过读取文件头部的魔数（Magic Number）来识别文件的真实格式，不依赖文件扩展名。

import { detectFileType } from '@/utils'

const fileType = await detectFileType(file)
// 返回: 'PNG', 'PSD', 'TIFF' 等

2. 单文件解析 (parseFile)

解析单个文件并返回完整的图片信息。

import { parseFile } from 'qiuqiu1-image-parser-utils'

// 默认情况下不返回 File 对象，也不使用哈希命名
const resultDefault = await parseFile(file)
console.log(`文件名: ${resultDefault.fileName}, 原始名: ${resultDefault.originalFileName}`)

// 传入 { returnFile: true } 以获取 File 对象，但不使用哈希命名
const resultWithFile = await parseFile(file, { returnFile: true })
console.log(`文件名: ${resultWithFile.fileName}, 原始名: ${resultWithFile.originalFileName}, File 对象: ${resultWithFile.parsedFile?.name}`)

// 传入 { returnFile: true, useHashName: true } 以获取 File 对象并使用哈希命名 (默认 png 格式)
const resultWithHashedFile = await parseFile(file, { returnFile: true, useHashName: true })
console.log(`文件名: ${resultWithHashedFile.fileName}, 原始名: ${resultWithHashedFile.originalFileName}, 哈希名: ${resultWithHashedFile.hashedFileName}, File 对象: ${resultWithHashedFile.parsedFile?.name}`)

// 传入 { returnFile: true, useHashName: true, hashFileType: 'jpeg' } 以获取 File 对象并使用哈希命名 (指定 jpeg 格式)
const resultWithHashedJpegFile = await parseFile(file, { returnFile: true, useHashName: true, hashFileType: 'jpeg' })
console.log(`文件名: ${resultWithHashedJpegFile.fileName}, 原始名: ${resultWithHashedJpegFile.originalFileName}, 哈希名: ${resultWithHashedJpegFile.hashedFileName}, File 对象: ${resultWithHashedJpegFile.parsedFile?.name}`)

// result 包含:
// - file: 原始 File 对象 (始终存在)
// - originalFileName: 原始文件名 (始终存在)
// - fileName: 当前文件名 (可能是原始名或哈希名)
// - fileType: 文件类型
// - fileSize: 文件大小
// - width: 图片宽度
// - height: 图片高度
// - dataUrl: Base64 图片数据
// - parsedFile?: File // 转化后的 File 对象 (如果 returnFile 为 true)
// - hashedFileName?: string // 哈希后的文件名 (如果 useHashName 为 true)

3. 批量解析 (parseFiles)

批量解析多个文件，支持进度回调和实时回调。

import { parseFiles } from 'qiuqiu1-image-parser-utils'

// 传入 { returnFile: true, useHashName: true, hashFileType: 'jpeg' } 以获取 File 对象并使用哈希命名，指定输出为 jpeg
const { results, failedCount } = await parseFiles(
  files,
  // 进度回调
  (current, total) => {
    console.log(`进度: ${current}/${total}`)
  },
  // 实时回调：每解析完一张立即返回
  (result, current, total) => {
    console.log(`第 ${current}/${total} 张解析完成:`, result.fileName)
    console.log(`原始文件名: ${result.originalFileName}`)
    if (result.hashedFileName) {
      console.log(`哈希文件名: ${result.hashedFileName}`)
    }
    if (result.parsedFile) {
      console.log(`已生成 File 对象:`, result.parsedFile.name, result.parsedFile.size)
    }
    // 可以立即添加到界面显示
    displayImage(result)
  },
  { returnFile: true, useHashName: true, hashFileType: 'jpeg' } // 传入配置
)

4. 独立解析器

每种格式都有独立的解析器，可以单独使用：

import { parsePSD, parseTIFF, parseImage } from 'qiuqiu1-image-parser-utils'

// 解析 PSD
const psdDataUrl = await parsePSD(psdFile)

// 解析 TIFF
const tiffDataUrl = await parseTIFF(tiffFile)

// 解析常规图片
const imageDataUrl = await parseImage(imageFile)

使用示例

在组件中使用

方式1：实时显示（推荐）

每解析完一张图片立即显示，用户体验更好：

<script setup lang="ts">
import { ref, onUnmounted } from 'vue'
import { parseFiles, type ParsedImageInfo, type ParseOptions } from 'qiuqiu1-image-parser-utils'

const parsedImages = ref<ParsedImageInfo[]>([])

// 在组件卸载时清理所有 Blob URL
onUnmounted(() => {
  parsedImages.value.forEach(image => {
    if (image.dataUrl.startsWith('blob:')) {
      URL.revokeObjectURL(image.dataUrl)
    }
  })
})

const handleFileUpload = async (files: File[]) => {
  const options: ParseOptions = { returnFile: true, useHashName: true, hashFileType: 'jpeg' } // 传入配置
  const { results, failedCount } = await parseFiles(
    files,
    // 进度回调
    (current, total) => {
      console.log(`正在处理 ${current}/${total}`)
    },
    // 实时回调：每解析完一张就立即显示
    (result, current, total) => {
      parsedImages.value.push(result)
    },
    options // 传递配置项
  )
  
  console.log(`成功: ${results.length}, 失败: ${failedCount}`)
}

// ... 其他功能（清空、下载等）需要自行实现 Blob URL 释放
</script>

方式2：批量显示

所有图片解析完成后一起显示：

<script setup lang="ts">
import { ref, onUnmounted } from 'vue'
import { parseFiles, type ParsedImageInfo, type ParseOptions } from 'qiuqiu1-image-parser-utils'

const parsedImages = ref<ParsedImageInfo[]>([])

// 在组件卸载时清理所有 Blob URL
onUnmounted(() => {
  parsedImages.value.forEach(image => {
    if (image.dataUrl.startsWith('blob:')) {
      URL.revokeObjectURL(image.dataUrl)
    }
  })
})

const handleFileUpload = async (files: File[]) => {
  const options: ParseOptions = { returnFile: true, useHashName: true, hashFileType: 'jpeg' } // 传入配置
  const { results, failedCount } = await parseFiles(
    files,
    (current, total) => {
      console.log(`正在处理 ${current}/${total}`)
    },
    undefined, // 不使用实时回调
    options // 传递配置项
  )
  
  // 所有图片解析完成后一起添加
  parsedImages.value.push(...results)
  console.log(`成功: ${results.length}, 失败: ${failedCount}`)
}

// ... 其他功能（清空、下载等）需要自行实现 Blob URL 释放
</script>

技术特点

1. 魔数检测: 通过文件头部特征识别真实格式，不受文件名影响
2. 原始尺寸: 保持图片原始尺寸和清晰度
3. 高质量输出: 使用最高质量（1.0）导出 PNG 格式
4. 模块化设计: 每个解析器独立，内部管理 Canvas
5. 类型安全: 完整的 TypeScript 类型定义
6. 错误处理: 完善的错误捕获和提示
7. 内存优化: 内部 Canvas 及时释放，Blob URL 显式回收

依赖库

本库的运行时依赖项包括 ag-psd 和 utif2。这些依赖项会在您安装 qiuqiu1-image-parser-utils 包时自动安装到您的项目中。

• ag-psd (用于 PSD 解析)
• utif2 (用于 tiff 解析)
• `