图片解析工具库

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

文件结构

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

支持的文件格式

• PDF - 提取第一页作为封面
• PSD - 提取合成图像
• TIFF - 提取第一帧
• PNG - 原始图片
• JPEG - 原始图片
• WEBP - 原始图片
• GIF - 原始图片
• BMP - 原始图片

核心功能

1. 文件类型检测 (detectFileType)

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

import { detectFileType } from '@/utils'

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

2. 单文件解析 (parseFile)

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

import { parseFile } from '@/utils'

const canvas = document.createElement('canvas')
const result = await parseFile(file, canvas)

// result 包含:
// - fileName: 文件名
// - fileType: 文件类型
// - fileSize: 文件大小
// - width: 图片宽度
// - height: 图片高度
// - dataUrl: Base64 图片数据

3. 批量解析 (parseFiles)

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

import { parseFiles } from '@/utils'

const canvas = document.createElement('canvas')
const { results, failedCount } = await parseFiles(
  files,
  canvas,
  // 进度回调
  (current, total) => {
    console.log(`进度: ${current}/${total}`)
  },
  // 实时回调：每解析完一张立即返回
  (result, current, total) => {
    console.log(`第 ${current}/${total} 张解析完成:`, result.fileName)
    // 可以立即添加到界面显示
    displayImage(result)
  }
)

4. 独立解析器

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

import { parsePDF, parsePSD, parseTIFF, parseImage } from '@/utils'

// 解析 PDF
const pdfDataUrl = await parsePDF(pdfFile, canvas)

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

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

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

使用示例

在组件中使用

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

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

<script setup lang="ts">
import { ref } from 'vue'
import { parseFiles, type ParsedImageInfo } from '@/utils'

const canvasRef = ref<HTMLCanvasElement | null>(null)
const parsedImages = ref<ParsedImageInfo[]>([])

const handleFileUpload = async (files: File[]) => {
  if (!canvasRef.value) return
  
  const { results, failedCount } = await parseFiles(
    files,
    canvasRef.value,
    // 进度回调
    (current, total) => {
      console.log(`正在处理 ${current}/${total}`)
    },
    // 实时回调：每解析完一张就立即显示
    (result, current, total) => {
      parsedImages.value.push(result)
    }
  )
  
  console.log(`成功: ${results.length}, 失败: ${failedCount}`)
}
</script>

方式2：批量显示

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

<script setup lang="ts">
import { ref } from 'vue'
import { parseFiles, type ParsedImageInfo } from '@/utils'

const canvasRef = ref<HTMLCanvasElement | null>(null)
const parsedImages = ref<ParsedImageInfo[]>([])

const handleFileUpload = async (files: File[]) => {
  if (!canvasRef.value) return
  
  const { results, failedCount } = await parseFiles(
    files,
    canvasRef.value,
    (current, total) => {
      console.log(`正在处理 ${current}/${total}`)
    }
  )
  
  // 所有图片解析完成后一起添加
  parsedImages.value.push(...results)
  console.log(`成功: ${results.length}, 失败: ${failedCount}`)
}
</script>

技术特点

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

依赖库

• pdfjs-dist - PDF 解析
• ag-psd - PSD 解析
• utif2 - TIFF 解析

注意事项

1. 所有解析方法都需要传入 Canvas 元素
2. Canvas 会被自动调整大小以匹配图片尺寸
3. 解析后的图片以 Base64 DataURL 格式返回
4. 建议在后台使用隐藏的 Canvas 进行解析
5. 大文件解析可能需要较长时间，建议显示加载状态

📦 发布到 npm

1. 前置条件

• npm 账号: 如果没有，请在 npm 官网 注册。
• npm 登录: 在终端中运行 npm login 并输入您的 npm 账号信息。

2. 构建库

在 src/utils 目录下运行：

cd src/utils
npm install
npm run build

这将会在 src/utils/dist 目录下生成编译后的 JavaScript 文件和类型声明文件 (.d.ts)。

3. 发布

在 src/utils 目录下运行：

npm publish --access public

• --access public 参数表示您的包是公开的，所有用户都可以使用。如果您有付费 npm 账号并希望发布私有包，则不需要这个参数。

4. 在其他项目中安装和使用

发布成功后，您可以在其他 Vue 3 + TypeScript 项目中安装：

npm install @your-scope/image-parser-utils

然后在您的组件中引入：

import { parseFiles, type ParsedImageInfo } from '@your-scope/image-parser-utils'

// ... 使用方法和之前在 CanvasBox.vue 中一致

5. 注意事项

• @your-scope/image-parser-utils: 请将 @your-scope 替换为您的 npm 账号的 scope 名称。如果没有设置 scope，可以直接使用 image-parser-utils 作为包名，但请确保包名是唯一的。
• 版本管理: 在 src/utils/package.json 中更新 version 字段，每次发布新版本时都需要递增版本号 (例如 0.1.0 → 0.1.1 → 0.2.0)，可以使用 npm version patch/minor/major 命令。
• 依赖: 确保 src/utils/package.json 中的 dependencies 和 devDependencies 正确配置。用户安装您的库时，dependencies 中的包也会被安装。
• 本地测试: 在发布之前，强烈建议在本地的其他项目中测试打包后的库，确保其功能正常。

📝 src/utils 目录现在被视为一个独立的 npm 包项目。

请注意，在实际的开发实践中，通常会将一个独立的 npm 包放在与主应用项目平行的独立文件夹中，而不是作为子目录。但为了在当前对话中方便修改和演示，我们暂时在 src/utils 内部进行了配置。